IcoEncoder Class

An icon file is a directory of alternative representations of one drawing, not an animation: use ImageCollection.Save on a collection of ImageCollectionKind.Representations to write several sizes, or Image.Save to write a single one. Animated images are rejected.

Output is conservative: every representation is written either as a still PNG or as a 32-bit BITMAPINFOHEADER DIB with straight alpha in the fourth byte and an all-zero AND mask (which is what the alpha channel makes redundant), selected by IcoEncoder.PayloadFormat. Indexed payloads, 1/4/8/16/24-bit DIBs and BI_BITFIELDS masks are decoded but never written. A DIB stores 8-bit samples, so pixels with 16-bit samples (PixelFormat.Rgba64, PixelFormat.Gray16) are written as a PNG by IconPayloadFormat.Auto whatever their size, and rejected with an UnsupportedImageFeatureException by IconPayloadFormat.Dib: precision is never reduced silently.

The container stores at most 256 pixels per side; a larger image is rejected with an UnsupportedImageFeatureException. The destination does not need to be seekable: a representation is at most 256x256, so its payload is encoded in memory and the directory is written before it.

IconKind.Cursor writes the hotspot of every entry (ImageCollectionEntry.Hotspot), or the hotspot of the frame for Image.Save (FrameMetadata.Hotspot), defaulting to the top-left corner when there is none; a cursor always has a hotspot, so it is written whatever ImageEncoder.MetadataHandling is. IconKind.Icon writes the conventional 1 color plane and the bit count instead, and a hotspot is metadata the format cannot store (rejected by default, see ImageEncoder.MetadataHandling).

Metadata (subject to ImageEncoder.MetadataHandling): an icon directory stores none. A resolution, an ICC profile, EXIF, XMP, text entries and an orientation other than ExifOrientation.TopLeft cannot be stored (rejected by default). A PNG payload is written without ancillary chunks.