Class PixelConvert

Namespace: Egami.Pixels

Assembly: Egami.dll

Converts spans of pixels from one pixel type to another.

public static class PixelConvert

Inheritance: object

PixelConvert

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Eight-bit, sixteen-bit and float pixels; every type converts to every other through PixelConvert.
Rgba8 orange = new(255, 128, 0, 255);
Bgr8 bgr = Bgr8.FromRgba8(orange);
Gray8 gray = Gray8.FromRgba8(orange);
GrayAlpha8 grayAlpha = new(gray.L, 128);
Gray16 deep = Gray16.FromRgba8(orange);
Rgba16 wide = new(65535, 32896, 0, 65535);
Rgb16 wideOpaque = Rgb16.FromRgba16(wide);           // exact: 16-bit to 16-bit never rounds
GrayAlpha16 deepMask = new(deep.L, 32768);
Argb8 alphaFirst = Argb8.FromRgba8(orange);             // bytes A, R, G, B
Alpha8 mask = Alpha8.FromRgba8(orange);                 // alpha only; reads back as black
RgbaF16 hdr = RgbaF16.FromScaled(new Vector4(4f, 2f, 0.5f, 1f)); // half floats keep values above 1
GrayF32 depth = new(12.5f);                              // floats hold any value until written to an integer type
Bgr565 packed = Bgr565.FromRgba8(orange);                // 5-6-5 levels in one ushort; rounds to the nearest level
Bgra5551 gdi16 = Bgra5551.FromRgba8(orange);             // 5-5-5 levels and a 1-bit alpha, the GDI+ 16-bit ARGB layout
Cmyk8 ink = Cmyk8.FromRgba8(orange);                     // inks by the plain formula: (0, 127, 255, 0)
PremulRgba8 glass = PremulRgba8.FromRgba8(new Rgba8(255, 128, 0, 128)); // stored (128, 64, 0, 128); converts back straight
RgbaF32 linear = RgbaF32.FromScaled(orange.ToScaled());

Rgba8[] row = [orange, Rgba8.Transparent];
Bgra8[] converted = new Bgra8[row.Length];
PixelConvert.Convert<Rgba8, Bgra8>(row, converted);

Methods

Convert<TFrom, TTo>(ReadOnlySpan<TFrom>, Span<TTo>)

Converts every pixel in source and writes the results to the start of destination.

public static void Convert<TFrom, TTo>(ReadOnlySpan<TFrom> source, Span<TTo> destination) where TFrom : unmanaged, IPixelType<TFrom> where TTo : unmanaged, IPixelType<TTo>

Parameters

source ReadOnlySpan<TFrom>: The pixels to convert.
destination Span<TTo>: Where to write the converted pixels. It must be at least as long as source.

Type Parameters

TFrom: The source pixel type.
TTo: The destination pixel type.

Remarks

Conversions between integer types where either side has 8-bit (or narrower packed) channels go through Rgba8, so they are exact: 8 to 16 bits multiplies by 257, and 16 to 8 bits rounds to the nearest value. Conversions between integer types wider than 8 bits go through Rgba16, also exact. All other conversions, including every one with a float or half-float side, go through red, green, blue and alpha scaled to 0..1.

Converting to a gray type takes the Rec. 709 luma of the color, weighted in linear light; gray colors keep their value. Converting to a type without alpha drops alpha, and converting from one gives every pixel full alpha.

Common pairs use SIMD: channel reordering between the 8-bit RGB layouts, 8 to 16 bits and back, and gray to RGB. Results are identical with and without SIMD.

The spans must not overlap unless both are the same type and start at the same address.

Exceptions

ArgumentException: destination is shorter than source.

Table of Contents