# Image formats

ALTO Image recognizes a stable set of image formats, but recognition does not
mean that the installed driver can decode or encode every one. Check the four
distinct capabilities before choosing a workflow:

- **Known** means `Format` represents the format and its common extensions and
  media type.
- **Detectable** means ALTO can identify and inspect a supported source header.
- **Readable** means the selected GD or Imagick build can decode its pixels.
- **Writable** means that build can encode a requested output.

Run the deployment's capability check for the authoritative read and write
lists:

```console
$ vendor/bin/image doctor
```

## Supported formats

| Format | Common input names | Alpha | Animation | Notes |
| --- | --- | --- | --- | --- |
| JPEG | `.jpg`, `.jpeg`, `.jpe`, `.jfif` | No | No | Widely readable and writable; quality is lossy. |
| PNG | `.png` | Yes | No | Lossless output; metadata support depends on the driver. |
| WebP | `.webp` | Yes | Yes | Build-dependent read and write support; only the first input frame is used. |
| AVIF | `.avif`, `.avifs` | Yes | Yes | Requires a matching GD build or ImageMagick delegate. |
| JPEG XL | `.jxl` | Yes | Yes | Known by ALTO; current driver support depends on installed delegates. |
| HEIC | `.heic`, `.heif`, `.hif` | Yes | Yes | Imagick only when its ImageMagick build has a HEIC delegate. |
| TIFF | `.tif`, `.tiff` | Yes | No | Imagick support depends on its ImageMagick delegates. |
| GIF | `.gif` | Yes | Yes | GD and Imagick use the first input frame. |
| BMP | `.bmp`, `.dib` | No | No | GD support depends on its build; Imagick depends on delegates. |
| SVG | `.svg`, `.svgz` | Yes | No | Vector source; Imagick rasterizes it at its declared size. GD refuses it. |

Animation in the table describes the file format, not multi-frame processing
by this package. ALTO Image currently renders the first frame and reports that
approximation. SVG can be detected and planned without implying that a raster
driver is available.

## Select a format

`Format::of()` accepts a format name, extension, or media type. It normalizes
aliases such as `jpg`, `.tiff`, and `image/svg+xml`:

```php
use Alto\Image\Format;

$format = Format::of('image/webp');

echo $format->extension(); // webp
echo $format->mime();      // image/webp
```

The enum also exposes `supportsAlpha()`, `supportsAnimation()`, `isVector()`,
`isLossy()`, and a format-specific `defaultQuality()`.

## Check the active driver

Driver capabilities are discovered at runtime. `Capabilities::$reads` and
`Capabilities::$writes` contain the exact `Format` cases available in that
installed build. A filename extension alone does not prove read or write
support.

Use [Drivers](https://altophp.com/image/drivers.md) to compare GD and Imagick.

## Encode output

Encoding selects the output format and its compression settings.

### Named formats

Use a named method for common settings:

```php
use Alto\Image\Effort;
use Alto\Image\Image;

$image = Image::open('photo.png')
    ->fit(1600, 1600)
    ->webp(quality: 82, effort: Effort::Best);
```

Available methods are `jpeg()`, `png()`, `webp()`, and `avif()`.

### Full configuration

Use `encode()` for byte limits, progressive JPEG, or lossless output:

```php
use Alto\Image\Format;
use Alto\Image\Image;

$image = Image::open('photo.png')->encode(
    format: Format::Webp,
    quality: 82,
    maxBytes: 200_000,
);
```

A byte limit can require several encoding passes. Use `encode()` with another
`Format` case when the selected [driver](https://altophp.com/image/drivers.md) reports it as writable
through `vendor/bin/image doctor`.

The complete encoding request includes the format, quality, effort, metadata
policy, byte limit, progressive mode, lossless mode, and driver-specific
options. The request remains immutable when one of these settings changes.