Meziantou.FrameworkPixelConversionOptions Class
Immutable options controlling explicit conversions between pixel formats (typed loading and Image.CloneAs).
public sealed class PixelConversionOptionsRemarks
Conversions never silently discard alpha: converting non-opaque pixels to a format without alpha throws an UnsupportedImageFeatureException unless PixelConversionOptions.BackgroundColor is set. Converting fully opaque pixels never requires a background. Requesting a narrower pixel type (for example Rgba32 from 16-bit content) is an explicit precision reduction and uses nearest rounding.
Integer samples convert to floating-point ones as v / max: exactly for RgbaFloat, rounded to nearest for RgbaHalf (exactly from 8-bit samples). Floating-point samples convert to integer ones as round(v * max), to nearest; a sample that is not a number is always rejected, and a sample outside [0, 1] is rejected unless PixelConversionOptions.OutOfRangeSamples clips it or PixelConversionOptions.ToneMapping compresses the highlights first. Integer to RgbaFloat and back is exact for every integer pixel format, and so is 8-bit to RgbaHalf and back.
Layout conversion is not color management: no ICC transform is applied (use ImageProcessingExtensions.ConvertColorProfile to convert colors). A retained ICC profile whose color space is incompatible with the converted pixels (for example an RGB profile on grayscale pixels) causes an UnsupportedImageFeatureException unless PixelConversionOptions.DiscardIncompatibleColorProfile is true.
Constructors
| Name | Description |
|---|---|
| PixelConversionOptions() |
PixelConversionOptions()
public PixelConversionOptions()No documentation is available.
Properties
| Name | Description |
|---|---|
| BackgroundColor | Gets the opaque color used to flatten non-opaque pixels when the target pixel type has no alpha component, or null to reject non-opaque pixels. The color is interpreted in the encoded color space of the source pixels (sRGB when untagged); flattening is performed in that encoded space. |
| Default | Gets the default options: no background color, incompatible profiles are rejected. |
| DiscardIncompatibleColorProfile | Gets a value indicating whether an ICC profile incompatible with the converted pixels is removed instead of causing an error. |
| OutOfRangeSamples | Gets what happens to the floating-point samples that the destination pixel format cannot store: outside [0, 1] for an integer format, beyond ±65,504 for RgbaHalf. Defaults to OutOfRangeSampleHandling.Reject. |
| ToneMapping | Gets the tone mapping that brings the colors of floating-point pixels into [0, 1] when they are converted to an integer pixel format, or null (the default) to keep the colors as they are. |
BackgroundColor
PixelConversionOptions.csGets the opaque color used to flatten non-opaque pixels when the target pixel type has no alpha component, or null to reject non-opaque pixels. The color is interpreted in the encoded color space of the source pixels (sRGB when untagged); flattening is performed in that encoded space.
public Rgba64? BackgroundColor { get; init; }Default
PixelConversionOptions.csGets the default options: no background color, incompatible profiles are rejected.
public static PixelConversionOptions Default { get; }Property value
DiscardIncompatibleColorProfile
PixelConversionOptions.csOutOfRangeSamples
PixelConversionOptions.csGets what happens to the floating-point samples that the destination pixel format cannot store: outside [0, 1] for an integer format, beyond ±65,504 for RgbaHalf. Defaults to OutOfRangeSampleHandling.Reject.
public OutOfRangeSampleHandling OutOfRangeSamples { get; init; }Property value
Exceptions
ArgumentOutOfRangeException- The value is not a defined
OutOfRangeSampleHandling.
Remarks
It applies after PixelConversionOptions.ToneMapping, to what the curve leaves out of range (negative components, alpha).
ToneMapping
PixelConversionOptions.csGets the tone mapping that brings the colors of floating-point pixels into [0, 1] when they are converted to an integer pixel format, or null (the default) to keep the colors as they are.
public HdrToneMappingOptions? ToneMapping { get; init; }Property value
Remarks
The color components are linear light in units of the reference white (1 is the white), which is the meaning of the floating-point formats. The curve of HdrToneMappingOptions.Operator is applied to the largest of the three components and the three are scaled together, which keeps the hue. HdrToneMappingOptions.TargetWhiteLuminance gives the luminance of a component of 1 (the PQ values of the curve of Report ITU-R BT.2390 need it). The peak of the source is HdrToneMappingOptions.SourcePeakLuminance divided by that white when it is set, else the largest finite color component of the converted pixels (of every frame of an image), and at least 1. Light above the peak becomes the white, and so does an infinite component (the finite components of its pixel become 0).
The conversion does not change the transfer function label of the image. Alpha is not tone mapped, and negative components stay negative: PixelConversionOptions.OutOfRangeSamples decides about what is still out of range. The option is ignored for the other conversions.