OpenExrEncoder Class
Immutable settings for OpenEXR encoding (linear-light floating-point still images, lossless by default).
public sealed class OpenExrEncoder : ImageEncoderRemarks
The output is a single-part file whose data window and display window are the image: scan lines, or tiles with OpenExrEncoder.Tiling (and, if requested, resolution levels generated from the image). Floating-point pixels may have values outside [0, 1], infinities and samples that are not numbers (ImageEncoder.FloatingPointConversion does not apply). Integer pixels are stored as the floating-point values of the conversion of Image.CloneAs to RgbaFloat (v / max). Gray pixel formats are written as a luminance channel (Y), the formats with alpha with an A channel.
Colors are multiplied by the alpha that is written (rounded to the sample type) when it is not 0, and divided by it when decoded, as OpenEXR stores premultiplied colors and the library holds straight colors. Rounding and underflow can change them: lossless compression preserves the stored samples, not necessarily the source pixels (RgbaHalf pixels written as OpenExrPixelType.Float samples come back exactly), and lossy compression (OpenExrCompression.Pxr24 with float samples, OpenExrCompression.B44, OpenExrCompression.B44A, OpenExrCompression.Dwaa, OpenExrCompression.Dwab) changes the stored samples too. A zero alpha keeps its colors without multiplication. Alpha is not limited to [0, 1]: a finite color that the multiplication takes beyond the range of the sample type, or that an alpha that is not finite makes infinite or not a number, is rejected with UnsupportedImageFeatureException before anything is written.
By default, the samples are written as OpenExrPixelType.Half for RgbaHalf and 8-bit pixel formats, and as OpenExrPixelType.Float otherwise. Writing RgbaFloat or 16-bit pixels as half samples rounds them (nearest, ties to even) and requires OpenExrEncoder.AllowBitDepthReduction; a finite sample beyond ±65,504 (the largest half) is rejected.
OpenEXR samples are linear light: the image must be labeled ColorTransferFunction.Linear (the default of floating-point images), or have a CICP description with the linear transfer characteristics (8) and the primaries of BT.709, BT.2020, DCI-P3 or Display P3, which are written as the chromaticities attribute. Any other label (sRGB-encoded samples, an ICC profile), EXIF, XMP, an orientation other than ExifOrientation.TopLeft, a resolution or text entries follow ImageEncoder.MetadataHandling (rejected by default).
Compressed output needs a seekable destination: the table of the offsets of the chunks precedes them.
With ImageConfiguration.MaxDegreeOfParallelism above 1, the samples of an image of at least 65,536 pixels are checked, and its chunks converted and compressed, by up to that many workers; the file, and the error of a sample out of range, are those of a single worker. Each worker needs its own chunk buffers, charged to ImageResourceLimits.MaxLiveAllocationBytes.
- Inheritance
ImageEncoderOpenExrEncoder
Constructors
| Name | Description |
|---|---|
| OpenExrEncoder() |
OpenExrEncoder()
OpenExrEncoder.cspublic OpenExrEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AllowBitDepthReduction | Gets a value indicating whether RgbaFloat and 16-bit pixels may be written as half samples (OpenExrEncoder.PixelType set to OpenExrPixelType.Half), which rounds them. Defaults to false. |
| Compression | Gets the compression of the chunks. Defaults to OpenExrCompression.Zip (lossless); the lossy compressions are only used when they are chosen here. |
| DwaCompressionLevel | Gets the compression level of OpenExrCompression.Dwaa and OpenExrCompression.Dwab output: the larger, the smaller the file and the larger the errors (OpenEXR's dwaCompressionLevel; 0 keeps every DCT coefficient that a half value stores). Defaults to 45, the default of OpenEXR. Ignored by the other compressions. |
| Format | Gets the format produced by this encoder. |
| LineOrder | Gets the order of the chunks in the file. Defaults to OpenExrLineOrder.IncreasingY; OpenExrLineOrder.RandomY is only valid with OpenExrEncoder.Tiling, and an encoding of scan lines with it throws ArgumentException. |
| PixelType | Gets the type of the samples, or null (the default) for half samples of RgbaHalf and 8-bit pixels, float samples otherwise. Alpha conversion can round colors independently of this choice. |
| Tiling | Gets the tile size and the resolution levels of tiled output, or null (the default) for scan-line output. |
AllowBitDepthReduction
OpenExrEncoder.csGets a value indicating whether RgbaFloat and 16-bit pixels may be written as half samples (OpenExrEncoder.PixelType set to OpenExrPixelType.Half), which rounds them. Defaults to false.
public bool AllowBitDepthReduction { get; init; }Property value
Compression
OpenExrEncoder.csGets the compression of the chunks. Defaults to OpenExrCompression.Zip (lossless); the lossy compressions are only used when they are chosen here.
public OpenExrCompression Compression { get; init; }DwaCompressionLevel
OpenExrEncoder.csGets the compression level of OpenExrCompression.Dwaa and OpenExrCompression.Dwab output: the larger, the smaller the file and the larger the errors (OpenEXR's dwaCompressionLevel; 0 keeps every DCT coefficient that a half value stores). Defaults to 45, the default of OpenEXR. Ignored by the other compressions.
public float DwaCompressionLevel { get; init; }Format
OpenExrEncoder.csLineOrder
OpenExrEncoder.csGets the order of the chunks in the file. Defaults to OpenExrLineOrder.IncreasingY; OpenExrLineOrder.RandomY is only valid with OpenExrEncoder.Tiling, and an encoding of scan lines with it throws ArgumentException.
public OpenExrLineOrder LineOrder { get; init; }PixelType
OpenExrEncoder.csGets the type of the samples, or null (the default) for half samples of RgbaHalf and 8-bit pixels, float samples otherwise. Alpha conversion can round colors independently of this choice.
public OpenExrPixelType? PixelType { get; init; }Tiling
OpenExrEncoder.csGets the tile size and the resolution levels of tiled output, or null (the default) for scan-line output.
public OpenExrTiling? Tiling { get; init; }