OpenExrEncoder Class

Immutable settings for OpenEXR encoding (linear-light floating-point still images, lossless by default).

public sealed class OpenExrEncoder : ImageEncoder

Remarks

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
ImageEncoder OpenExrEncoder

Constructors

NameDescription
OpenExrEncoder()

OpenExrEncoder()

OpenExrEncoder.cs
public OpenExrEncoder()

No documentation is available.

Properties

NameDescription
AllowBitDepthReductionGets 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.
CompressionGets the compression of the chunks. Defaults to OpenExrCompression.Zip (lossless); the lossy compressions are only used when they are chosen here.
DwaCompressionLevelGets 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.
FormatGets the format produced by this encoder.
LineOrderGets 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.
PixelTypeGets 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.
TilingGets the tile size and the resolution levels of tiled output, or null (the default) for scan-line output.

AllowBitDepthReduction

OpenExrEncoder.cs

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.

public bool AllowBitDepthReduction { get; init; }

Property value

bool

Gets 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; }

Property value

OpenExrCompression

Exceptions

ArgumentOutOfRangeException
The value is not a defined OpenExrCompression.

DwaCompressionLevel

OpenExrEncoder.cs

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.

public float DwaCompressionLevel { get; init; }

Property value

float

Exceptions

ArgumentOutOfRangeException
The value is negative, infinite or not a number.

Gets the format produced by this encoder.

public override ImageFormat Format { get; }

Property value

ImageFormat

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.

public OpenExrLineOrder LineOrder { get; init; }

Property value

OpenExrLineOrder

Exceptions

ArgumentOutOfRangeException
The value is not a defined OpenExrLineOrder.

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.

public OpenExrPixelType? PixelType { get; init; }

Property value

OpenExrPixelType?

Exceptions

ArgumentOutOfRangeException
The value is not a defined OpenExrPixelType.

Gets the tile size and the resolution levels of tiled output, or null (the default) for scan-line output.

public OpenExrTiling? Tiling { get; init; }

Property value

OpenExrTiling?