Meziantou.FrameworkBmpEncoder Class
Immutable settings for BMP encoding (Windows bitmaps).
public sealed class BmpEncoder : ImageEncoderRemarks
By default the output is the most interoperable subset: uncompressed bottom-up rows padded to four bytes, either 24-bit BI_RGB in a BITMAPINFOHEADER or 32-bit BI_BITFIELDS in a BITMAPV4HEADER with an explicit alpha mask (BmpPixelLayout.Auto). BmpEncoder.PixelLayout also selects 1-, 4- and 8-bit indexed layouts and 16-bit 5-6-5 and 5-5-5 layouts, BmpEncoder.Compression run-length encodes the 4- and 8-bit indexed layouts, and BmpEncoder.RowOrder writes top-down rows. Embedded JPEG/PNG payloads and OS/2 headers are never written.
Nothing is lost silently. Gray pixel formats are written as gray RGB (R = G = B). Alpha is only preserved by BmpPixelLayout.Bgra32: every other layout requires BmpEncoder.BackgroundColor as soon as a pixel is not opaque. 16-bit pixel formats, and the 16-bit layouts, require BmpEncoder.AllowBitDepthReduction. An indexed layout stores the colors of the image exactly when its palette can hold them, and requires BmpEncoder.AllowColorReduction otherwise (see BmpEncoder.Quantization).
The indexed layouts read the frame twice (its colors, then its pixels) and keep one byte per pixel of working memory, charged to the resource limits; the other layouts keep one row.
BMP stores exactly one frame: animated images and images with a poster frame are rejected with an UnsupportedImageFeatureException; use ImageFrame.Save to save one frame explicitly.
Metadata (subject to ImageEncoder.MetadataHandling): only the resolution (biXPelsPerMeter/biYPelsPerMeter). An ICC profile, EXIF, XMP, an orientation other than ExifOrientation.TopLeft and text entries cannot be stored (rejected by default).
- Inheritance
ImageEncoderBmpEncoder
Constructors
| Name | Description |
|---|---|
| BmpEncoder() |
BmpEncoder()
BmpEncoder.cspublic BmpEncoder()No documentation is available.
Properties
| Name | Description |
|---|---|
| AllowBitDepthReduction | Gets a value indicating whether samples may be reduced to the precision of the layout (nearest rounding): 16-bit pixel formats to 8 bits per component, and any pixel format to the 5 or 6 bits per component of BmpPixelLayout.Bgr565 and BmpPixelLayout.Bgr555. Defaults to false. |
| AllowColorReduction | Gets a value indicating whether an indexed layout may reduce the colors of an image whose colors its palette cannot hold exactly (more distinct colors than the smaller of QuantizeOptions.MaxColors and the capacity of the layout, or colors that are not in QuantizeOptions.Palette). Defaults to false: such an image is rejected with an UnsupportedImageFeatureException. When true, the colors are reduced as BmpEncoder.Quantization says. An image whose colors fit is always stored exactly. Ignored by the other layouts. |
| BackgroundColor | Gets the opaque background color non-opaque pixels are composited over by the layouts that discard alpha (every layout but BmpPixelLayout.Bgra32), interpreted in the encoded color space of the image (sRGB when untagged), or null to reject non-opaque pixels. Fully opaque images never need it, and BmpPixelLayout.Bgra32 ignores it. |
| Compression | Gets the compression. Defaults to BmpCompression.None. BmpCompression.RunLength requires BmpPixelLayout.Indexed4 or BmpPixelLayout.Indexed8 and BmpRowOrder.BottomUp; saving fails with an ArgumentException otherwise. |
| Dithering | Gets the dithering applied when an indexed layout reduces colors: BmpEncoder.Quantization.QuantizeOptions.Dithering, which it sets. |
| Format | Gets the format produced by this encoder. |
| MaxColors | Gets the maximum number of palette entries of an indexed layout: BmpEncoder.Quantization.QuantizeOptions.MaxColors, which it sets. |
| PixelLayout | Gets the pixel layout. Defaults to BmpPixelLayout.Auto. |
| Quantization | Gets how an indexed layout reduces colors to its palette. Defaults to QuantizeOptions.Default: at most 256 entries, further limited to the capacity of the layout (2, 16 or 256), without dithering. Ignored by the other layouts. |
| RowOrder | Gets the order of the rows. Defaults to BmpRowOrder.BottomUp. |
AllowBitDepthReduction
BmpEncoder.csGets a value indicating whether samples may be reduced to the precision of the layout (nearest rounding): 16-bit pixel formats to 8 bits per component, and any pixel format to the 5 or 6 bits per component of BmpPixelLayout.Bgr565 and BmpPixelLayout.Bgr555. Defaults to false.
public bool AllowBitDepthReduction { get; init; }Property value
AllowColorReduction
BmpEncoder.csGets a value indicating whether an indexed layout may reduce the colors of an image whose colors its palette cannot hold exactly (more distinct colors than the smaller of QuantizeOptions.MaxColors and the capacity of the layout, or colors that are not in QuantizeOptions.Palette). Defaults to false: such an image is rejected with an UnsupportedImageFeatureException. When true, the colors are reduced as BmpEncoder.Quantization says. An image whose colors fit is always stored exactly. Ignored by the other layouts.
public bool AllowColorReduction { get; init; }Property value
BackgroundColor
BmpEncoder.csGets the opaque background color non-opaque pixels are composited over by the layouts that discard alpha (every layout but BmpPixelLayout.Bgra32), interpreted in the encoded color space of the image (sRGB when untagged), or null to reject non-opaque pixels. Fully opaque images never need it, and BmpPixelLayout.Bgra32 ignores it.
public Rgba64? BackgroundColor { get; init; }Compression
BmpEncoder.csGets the compression. Defaults to BmpCompression.None. BmpCompression.RunLength requires BmpPixelLayout.Indexed4 or BmpPixelLayout.Indexed8 and BmpRowOrder.BottomUp; saving fails with an ArgumentException otherwise.
public BmpCompression Compression { get; init; }Dithering
BmpEncoder.cs- Obsolete: Use Quantization.Dithering, which also selects other dithering modes.
Gets the dithering applied when an indexed layout reduces colors: BmpEncoder.Quantization.QuantizeOptions.Dithering, which it sets.
[Obsolete("Use Quantization.Dithering, which also selects other dithering modes.")]
public BmpDithering Dithering { get; init; }Format
BmpEncoder.csMaxColors
BmpEncoder.cs- Obsolete: Use Quantization.MaxColors.
Gets the maximum number of palette entries of an indexed layout: BmpEncoder.Quantization.QuantizeOptions.MaxColors, which it sets.
PixelLayout
BmpEncoder.csGets the pixel layout. Defaults to BmpPixelLayout.Auto.
public BmpPixelLayout PixelLayout { get; init; }Quantization
BmpEncoder.csGets how an indexed layout reduces colors to its palette. Defaults to QuantizeOptions.Default: at most 256 entries, further limited to the capacity of the layout (2, 16 or 256), without dithering. Ignored by the other layouts.
public QuantizeOptions Quantization { get; init; }Property value
Exceptions
ArgumentNullException- The value is
null.
Remarks
The palette is the exact colors of the image when they fit, otherwise a deterministic variance-based median cut of its colors (see PaletteBuilder), with the dithering of QuantizeOptions.Dithering; the colors are only reduced with BmpEncoder.AllowColorReduction. The palette only stores the entries it has (biClrUsed).
With QuantizeOptions.Palette, the pixels map to that palette, whose entries that are not opaque are composited over BmpEncoder.BackgroundColor first. Saving fails with an ArgumentException when an entry is not opaque without BmpEncoder.BackgroundColor, or when the palette has more colors than the layout holds.
RowOrder
BmpEncoder.csGets the order of the rows. Defaults to BmpRowOrder.BottomUp.
public BmpRowOrder RowOrder { get; init; }