PeachImage
PeachImage
DecoderOptions Class
Base class for format-specific decode options. Format codecs derive their own options from this
(JpegDecoderOptions, PngDecoderOptions, etc.) to add format-specific knobs, but the base
class itself is directly constructible: when the only thing a caller needs is
TargetPixelFormat — the common case for a format-agnostic Load(Stream, DecoderOptions)
call, where the stream’s actual format isn’t known up front — construct a plain
new DecoderOptions { TargetPixelFormat = ... } rather than guessing at an arbitrary concrete
subtype. See TargetPixelFormat for the guarantee that makes this safe.
public class DecoderOptions
Inheritance System.Object → DecoderOptions
Derived
↳ AvifDecoderOptions
↳ BmpDecoderOptions
↳ CcittFaxDecoderOptions
↳ GifDecoderOptions
↳ Jbig2DecoderOptions
↳ JpegDecoderOptions
↳ Jpeg2000DecoderOptions
↳ JxlDecoderOptions
↳ PngDecoderOptions
↳ TiffDecoderOptions
↳ WebpDecoderOptions
| Properties | |
|---|---|
| AllowedFormats | The names of the formats Load(Stream, DecoderOptions) and Identify(Stream, DecoderOptions) may accept ("jpeg", "png", "gif", "webp", ...: the FormatName values of SupportedFormats, compared ignoring case). When null (the default) every format is allowed. |
| ApplyOrientation | When true, the decoded Image comes back upright: the EXIF orientation recorded in the file is applied to the pixels and reset in the image EXIF profile, as ApplyOrientation(ImageOrientation) does. Defaults to false, which leaves the pixels as stored (decoders never apply orientation by themselves). |
| FallbackCmykProfile | A CMYK profile to colour-manage CMYK pixels with when the image carries no usable profile of its own, for a TargetPixelFormat conversion of a CMYK JPEG or TIFF. null (the default) falls back to the profile-less formula R = 255 x (1 - C) x (1 - K) (likewise G and B), an approximation of how the inks would look. |
| MaxDegreeOfParallelism | The most threads one decode call may use. -1 (the default) leaves it to the library, which fans out over up to System.Environment.ProcessorCount workers; 1 decodes sequentially on the calling thread. The limit is per call, not global: concurrent calls each use up to this many, so a server decoding uploads should set a low value and/or share a TaskScheduler. Does not change the output. |
| MaxExpansionRatio | The most decoded bytes the image may declare per byte of its file, so a few hundred bytes of PNG, GIF or WebP cannot decode into gigabytes. The ratio is the decoded pixel bytes (width x height x bytes per pixel of the decoded pixel format) divided by the compressed bytes (the length of the stream from the image’s start). Checked from the header, before any pixel memory is allocated; a larger ratio throws ImageTooLargeException. When null (the default) there is no ratio limit. Use MaxExpansionRatios to give formats their own limits. |
| MaxExpansionRatios | Per-format overrides of MaxExpansionRatio, keyed by FormatName ("jpeg", "png", "webp", ..., compared ignoring case). A format with an entry uses it instead of MaxExpansionRatio; every other format falls back to MaxExpansionRatio, or is unlimited when that is null. The ratio is defined at MaxExpansionRatio. For example new Dictionary<string, double> { ["jpeg"] = 200, ["png"] = 30_000 }. |
| MaxPixels | The most pixels (width x height) an image may declare, checked from the header before any pixel memory is allocated: a larger image throws ImageTooLargeException. When null (the default) only each format’s own built-in ceiling applies. This is in addition to, never instead of, those built-in limits. |
| PreviewAvailable | Called, while the full image is still being decoded, with a lower-fidelity version of it: a JPEG XL preview frame, one per pass of an interlaced PNG, or one per scan of a progressive JPEG. Formats with no such intermediate (see HasPreview) never call it. |
| ScaleDenominator | Decodes at a reduced size: 1 (the default, full size), 2, 4 or 8 for 1/2, 1/4 or 1/8 of the width and height, rounded up (ceil(size / N)). Three formats reduce natively and save most of the decode work and memory: JPEG scales in the DCT domain (so a 24 megapixel photo at 1/8 never builds a full-size image), JPEG 2000 drops resolution levels (its wavelet low-pass differs from a box average, so expect larger differences from a resize), and JPEG XL decodes 1/8 from the DC image of a plain VarDCT still (1/2 and 1/4, and modular, lossless, alpha, animated and other feature-heavy files, decode at full size). Every other format decodes at full size and is then averaged down, so the result size is the same but nothing is saved. TargetSize, when set, chooses the denominator instead. |
| SkipMetadata | When true, the decoded Image carries no metadata profiles at all (EXIF, XMP, IPTC, ICC, text and the rest of Profiles), HasLocation is false, and the decoder and the location scan do not parse any of it. For a caller that only needs the pixels. Defaults to false. |
| TargetPixelFormat | The pixel format the caller wants the decoded Image to use, analogous to stb_image’s req_comp. When null, the decoder produces whatever format is most natural for the source data. |
| TargetSize | The size the caller is going to resize to. When set, the decoder reduces by the largest of 1/2, 1/4 and 1/8 that still leaves an image at least this wide and this tall (so a 6000x4000 JPEG with a target of 600x420 decodes at 750x500, 1/8). Decoding then costs a fraction of a full decode and a final Resize(int, int, ResizeOptions) to the target finishes the job. When null (the default) ScaleDenominator applies. With ApplyOrientation set, the target is compared against the upright (displayed) size, otherwise against the stored size. See ScaleDenominator for which formats reduce natively and how it interacts with the limits. |
| TaskScheduler | An optional scheduler the decoder’s parallel work runs on, so a host can share one limit across concurrent calls (for example the System.Threading.Tasks.ConcurrentExclusiveSchedulerPair.ConcurrentScheduler of a pair created with a bounded concurrency level). null (the default) uses the thread pool. |