Meziantou.FrameworkImageDecodeOptions Class
Immutable options for the eager Image.Load and Image.LoadAsync methods.
public sealed class ImageDecodeOptionsConstructors
| Name | Description |
|---|---|
| ImageDecodeOptions() |
ImageDecodeOptions()
ImageDecodeOptions.cspublic ImageDecodeOptions()No documentation is available.
Properties
| Name | Description |
|---|---|
| CmykConversion | Gets the color conversion applied to images whose samples are CMYK inks (four-component JPEG, separated TIFF), or null (the default) to reject them with an UnsupportedImageFeatureException. |
| Configuration | Gets the configuration of the loaded image (resource limits, parallelism). Defaults to ImageConfiguration.Default. |
| Conversion | Gets the options used when a typed load converts decoded samples to the requested pixel type. Defaults to PixelConversionOptions.Default. |
| Default | Gets the default options. |
| FrameLimit | Gets the maximum number of displayed frames to decode, or null to decode all frames. This is a deliberate prefix selection: decoding stops after the requested number of frames and the remaining data is not examined or validated. A separate poster frame is always preserved and is not counted. |
| Region | Gets the area of the image to decode, in pixels of the stored image at full resolution (before its orientation is applied), or null (the default) to decode the whole image. The decoded image holds the part of the area that is in the image. |
| ScaleDenominator | Gets the factor by which the decoder divides the width and the height of the image, a power of two. Defaults to 1: the image is decoded at full resolution. |
| TargetSize | Gets the smallest size the decoder needs to produce, or null (the default) to decode at full resolution. A file that can be decoded at a reduced resolution is decoded at the largest ImageDecodeOptions.ScaleDenominator it allows whose size is still at least this size in both dimensions; any other file is decoded at full resolution. |
CmykConversion
ImageDecodeOptions.csGets the color conversion applied to images whose samples are CMYK inks (four-component JPEG, separated TIFF), or null (the default) to reject them with an UnsupportedImageFeatureException.
public CmykConversionOptions? CmykConversion { get; init; }Property value
Remarks
No pixel format holds CMYK samples, so such an image can only be loaded by converting its colors. Like every color conversion it is explicit: set new CmykConversionOptions() to convert to sRGB. Other images are not affected.
Configuration
ImageDecodeOptions.csGets the configuration of the loaded image (resource limits, parallelism). Defaults to ImageConfiguration.Default.
public ImageConfiguration Configuration { get; init; }Conversion
ImageDecodeOptions.csGets the options used when a typed load converts decoded samples to the requested pixel type. Defaults to PixelConversionOptions.Default.
public PixelConversionOptions Conversion { get; init; }Default
ImageDecodeOptions.csFrameLimit
ImageDecodeOptions.csGets the maximum number of displayed frames to decode, or null to decode all frames. This is a deliberate prefix selection: decoding stops after the requested number of frames and the remaining data is not examined or validated. A separate poster frame is always preserved and is not counted.
public int? FrameLimit { get; init; }Region
ImageDecodeOptions.csGets the area of the image to decode, in pixels of the stored image at full resolution (before its orientation is applied), or null (the default) to decode the whole image. The decoded image holds the part of the area that is in the image.
public Rectangle? Region { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The area is empty or starts at a negative coordinate.
Remarks
A JPEG 2000 file only decodes the tiles that the area meets, in them the code-blocks whose coefficients reach it, and the wavelet transformation only rebuilds the samples the area needs: the samples of the area are those of a full decode, for less time and memory, even in an image of one tile. With ImageDecodeOptions.ScaleDenominator or ImageDecodeOptions.TargetSize, the area is divided like the image: its edges are rounded up, as the reference grid of the format does, and an area narrower than a pixel of the reduced image keeps the pixel that covers it.
The other formats cannot decode an area: a load with a region is an UnsupportedImageFeatureException, and so is an area that does not meet the image.
ScaleDenominator
ImageDecodeOptions.csGets the factor by which the decoder divides the width and the height of the image, a power of two. Defaults to 1: the image is decoded at full resolution.
public int ScaleDenominator { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a positive power of two.
ArgumentException- The value is not 1 and
ImageDecodeOptions.TargetSizeis set.
Remarks
The decoded image has ceil(width / ScaleDenominator) by ceil(height / ScaleDenominator) pixels, computed from fewer samples than a full decode, for less time and memory, by the formats that support it (see the format reference of the readme). The pixels are close to a resize of the full image, not equal to it. The metadata is the one of the file, like after a resize.
A file that cannot be decoded at this scale (a format that only decodes at full resolution, or a scale that the file does not allow) is an UnsupportedImageFeatureException. Set ImageDecodeOptions.TargetSize instead to get the smallest image the file allows without failing. The two properties cannot be set together.
TargetSize
ImageDecodeOptions.csGets the smallest size the decoder needs to produce, or null (the default) to decode at full resolution. A file that can be decoded at a reduced resolution is decoded at the largest ImageDecodeOptions.ScaleDenominator it allows whose size is still at least this size in both dimensions; any other file is decoded at full resolution.
public Size? TargetSize { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The width or the height of the value is zero.
ArgumentException- The value is not
nullandImageDecodeOptions.ScaleDenominatoris not 1.
Remarks
The size is compared with the stored dimensions of the image, before its orientation is applied. The decoded image is usually larger than the target: resize it afterwards to get an exact size. For a thumbnail, this is much faster than resizing a full decode, with nearly the same result.