ImageConfiguration Class
Immutable configuration shared by an image and the operations performed on it.
public sealed class ImageConfigurationRemarks
An image captures the configuration it was created or loaded with; operations on the image use that snapshot. The configuration is immutable, so a single instance can be shared freely across threads.
Constructors
| Name | Description |
|---|---|
| ImageConfiguration() |
ImageConfiguration()
ImageConfiguration.cspublic ImageConfiguration()No documentation is available.
Properties
| Name | Description |
|---|---|
| BufferAllocator | Gets the allocator of the byte arrays of the images and operations of this configuration (pixels, decoders, encoders and scratch memory), or null (the default) for the process-wide pool, ImageBufferPool. |
| Codecs | Gets the codecs of the formats the library does not read or write itself, consulted before the built-in ones. Defaults to an empty list. |
| DecodingStrictness | Gets how the decoders treat files that deviate from their specification. Defaults to DecodingStrictness.Strict, which rejects them with an InvalidImageContentException. |
| Default | Gets the default configuration: ImageResourceLimits.Default limits and one worker. |
| Jpeg2000Decoding | Gets the options of the JPEG 2000 decoder: the quality layers it decodes. Defaults to Jpeg2000DecodingOptions.Default, which decodes every layer. |
| Limits | Gets the resource limits. Defaults to ImageResourceLimits.Default. |
| MaxDegreeOfParallelism | Gets the maximum number of workers an internal operation may use concurrently. Defaults to 1, meaning operations run on the calling thread only. |
| OpenExrDecoding | Gets the options of the OpenEXR decoder: the layer it decodes and the window the image covers. Defaults to OpenExrDecodingOptions.Default, which rejects the files with channels or pixels outside the image. |
BufferAllocator
ImageConfiguration.csGets the allocator of the byte arrays of the images and operations of this configuration (pixels, decoders, encoders and scratch memory), or null (the default) for the process-wide pool, ImageBufferPool.
public ImageBufferAllocator? BufferAllocator { get; init; }Property value
Remarks
The allocator replaces the pool for every image created, loaded, imported or cloned with this configuration, and for the readers, writers and operations that use it; the resource limits are charged as with the pool, before the allocator is asked for an array. The images an operation creates from an image (a clone, a conversion, a frame extraction) keep the configuration of their source. Image.WrapMemory wraps memory of the caller, which never comes from the allocator.
Codecs
ImageConfiguration.csGets the codecs of the formats the library does not read or write itself, consulted before the built-in ones. Defaults to an empty list.
public IReadOnlyList<CustomImageCodec> Codecs { get; init; }Property value
IReadOnlyList<CustomImageCodec>
Exceptions
ArgumentNullException- The value or one of its items is
null.
Remarks
The codecs are used by the entry points that receive this configuration: Image.Identify, Image.Load, their overloads and asynchronous variants, and Image.DetectFormatInfo; Image.Save selects their encoders from the file extension (CustomImageCodec.CreateEncoder) when the image has this configuration. A file is read by the first codec, in this order, whose CustomImageCodec.IsMatch accepts its first bytes; the built-in codecs are consulted after them, so that a registered codec also takes the files of a built-in format it recognizes. Sequential readers (ImageReader<TPixel>) reject the files of a custom codec with an UnsupportedImageFeatureException, and ImageCollection and AuxiliaryImageCollection only read the built-in formats.
The setter stores a copy of the list.
DecodingStrictness
ImageConfiguration.csGets how the decoders treat files that deviate from their specification. Defaults to DecodingStrictness.Strict, which rejects them with an InvalidImageContentException.
public DecodingStrictness DecodingStrictness { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
DecodingStrictness.
Remarks
DecodingStrictness.Lenient accepts the deviations that the reference decoders and the browsers accept, in identification, eager loads, sequential readers and collections alike. The resource limits are the same in both modes. Encoders and the other operations ignore the value.
Default
ImageConfiguration.csGets the default configuration: ImageResourceLimits.Default limits and one worker.
public static ImageConfiguration Default { get; }Property value
Jpeg2000Decoding
ImageConfiguration.csGets the options of the JPEG 2000 decoder: the quality layers it decodes. Defaults to Jpeg2000DecodingOptions.Default, which decodes every layer.
public Jpeg2000DecodingOptions Jpeg2000Decoding { get; init; }Property value
Exceptions
ArgumentNullException- The value is
null.
Remarks
Eager loads, sequential readers and collections read them alike. The other formats ignore them.
Limits
ImageConfiguration.csGets the resource limits. Defaults to ImageResourceLimits.Default.
public ImageResourceLimits Limits { get; init; }MaxDegreeOfParallelism
ImageConfiguration.csGets the maximum number of workers an internal operation may use concurrently. Defaults to 1, meaning operations run on the calling thread only.
public int MaxDegreeOfParallelism { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not positive.
Remarks
Currently, ImageProcessingExtensions.Resize, the transformations, ImageProcessingExtensions.Convolve, the blurs (ImageProcessingExtensions.GaussianBlur, ImageProcessingExtensions.BoxBlur, ImageProcessingExtensions.MedianBlur), ImageProcessingExtensions.Sharpen and ImageProcessingExtensions.DetectEdges use it: the output rows of a large frame (at least 65,536 output pixels and 32 rows per worker; nearest-neighbor resizing excepted) are split into at most this many bands processed concurrently, the calling thread included. The result is identical whatever the value. Each worker needs its own row scratch, charged to the image's ImageResourceLimits.MaxLiveAllocationBytes budget. The ImageProcessingExtensions.Pixelate, ImageProcessingExtensions.OilPaint and ImageProcessingExtensions.Flatten effects split the rows the same way (the bands of the pixelation start on a row of blocks, and those of the oil painting are at least as tall as its window). The comparisons of ImageSimilarity (SSIM, PSNR, SSIMULACRA 2 and Butteraugli) use the value of the image of the expected frame: their floating-point sums are made by bands of 64 rows, added in order, so their results do not depend on it either. The HEIC and AVIF decoders use it too: the tiles of a grid of at least 65,536 samples are decoded by up to this many workers, each holding the decoder and the picture of its tile, with the pixels and the errors of a decoding by one worker. The HEIC and AVIF encoders code the tiles of such a grid (HeicEncoder.GridTileSize, AvifEncoder.GridTileSize) by up to this many workers, each with encoders of its own, and write the same bytes as one worker. The AVIF decoder also runs the post-processing filters of an AV1 frame of at least 65,536 pixels (the loop filter, CDEF, the super-resolution upscaling and the loop restoration) by bands of rows, with the pixels of a decoding by one worker, unless the frame is a tile decoded alongside other tiles. They take about 25% to 40% of the decoding time of a 3840x2160 image that uses CDEF, which then decodes about 1.3 to 1.45 times faster with 8 workers. Each worker needs its own rows, about 140 bytes per pixel of the width of the frame, charged to ImageResourceLimits.MaxLiveAllocationBytes. The JPEG XL encoder, the JPEG XL decoder and JpegXlTranscoder use it as well: the groups of a frame of at least 65,536 pixels (squares of 256x256 pixels, which the format codes independently) are encoded or decoded by up to this many workers, each with its own working memory, and the restoration filters and the conversion of a decoded frame to its color space are split into row bands; the bytes, the pixels and the errors are those of one worker. The codecs of the other formats split the independent parts of a frame of at least 65,536 pixels the same way, with the bytes, the pixels and the errors of one worker: the JPEG decoder and encoder transform batches of MCU rows (the entropy coding stays on the calling thread), the TIFF decoder decompresses the LZW, Deflate and CCITT strips and tiles and the TIFF encoder compresses the LZW and Deflate strips, the OpenEXR decoder and encoder process the chunks, the JPEG 2000 decoder and encoder code the code-blocks and split the wavelet transforms, the AVIF decoder and encoder code the tiles of an AV1 frame that has several (unless the frame is a grid tile coded alongside other tiles), and the HEIC decoder decodes the tiles and the rows of the wavefront of a picture that start at entry points. Drawing uses it too: the rows of a shape, an image or a layer that may cover at least 131,072 pixels are composited by up to this many workers, by batches of rows, while the calling thread computes the coverages of the next rows; the pixels and the errors are those of one worker. Each worker needs about 128 KB and 40 bytes per pixel of the width of the canvas, charged to ImageResourceLimits.MaxLiveAllocationBytes. The other decoders (the HEVC in-loop filters included), the encoders and the other operations run on the calling thread.
Keep the default in services that already process several images concurrently: the bound applies per operation, so n concurrent operations may use up to n times this many threads.
OpenExrDecoding
ImageConfiguration.csGets the options of the OpenEXR decoder: the layer it decodes and the window the image covers. Defaults to OpenExrDecodingOptions.Default, which rejects the files with channels or pixels outside the image.
public OpenExrDecodingOptions OpenExrDecoding { get; init; }Property value
Exceptions
ArgumentNullException- The value is
null.
Remarks
Identification, eager loads, sequential readers and collections read them alike. The other formats ignore them.