ICustomPixel<TSelf> Interface

Defines a pixel type of the application that the library reads and writes through one of its built-in pixel formats, its storage format.

public interface ICustomPixel<TSelf> where TSelf : unmanaged, ICustomPixel<TSelf>

Type parameters

TSelf
The pixel type itself.

Remarks

An image always stores a built-in format (ICustomPixel<TSelf>.StorageFormat): every codec, kernel and conversion works on it. A custom pixel type gives the conversions of whole rows between its pixels and the bytes of that format, and the library calls them to import pixels (Image.ImportCustomPixelData), to copy the pixels of a frame of any format (ImageFrame.CopyCustomPixelDataTo, which converts them to the storage format first) and to edit the pixels of a frame of the storage format in place (ImageFrame.ProcessCustomPixelRows). Image<TPixel>, the decoders and the sequential readers and writers only take the built-in pixel types.

The members are static, so the calls are resolved when the generic code is compiled: no reflection is involved, and the type works with trimming and native AOT. The conversions must not keep the spans, and they are called with rows of the same number of pixels: width pixels of the storage format, width * PixelFormats.GetBytesPerPixel(StorageFormat) bytes in native endianness, laid out like the struct of the format (for example Rgba64).

Example

/// <summary>A pixel of 5-bit blue, green and red components packed in 16 bits (blue in the low bits), stored as <see cref="Rgb24"/>.</summary>
private readonly record struct Bgr555(ushort Packed) : ICustomPixel<Bgr555>
{
    public static PixelFormat StorageFormat => PixelFormat.Rgb24;

    public int Blue => Packed & 31;

    public int Green => (Packed >> 5) & 31;

    public int Red => (Packed >> 10) & 31;

    public static Bgr555 FromColor(int red, int green, int blue) => new((ushort)((red << 10) | (green << 5) | blue));

    public static void FromStorage(ReadOnlySpan<byte> source, Span<Bgr555> destination)
    {
        for (var i = 0; i < destination.Length; i++)
        {
            // The nearest 5-bit component of each 8-bit sample
            destination[i] = FromColor(((source[3 * i] * 31) + 127) / 255, ((source[(3 * i) + 1] * 31) + 127) / 255, ((source[(3 * i) + 2] * 31) + 127) / 255);
        }
    }

    public static void ToStorage(ReadOnlySpan<Bgr555> source, Span<byte> destination)
    {
        for (var i = 0; i < source.Length; i++)
        {
            destination[3 * i] = (byte)(((source[i].Red * 255) + 15) / 31);
            destination[(3 * i) + 1] = (byte)(((source[i].Green * 255) + 15) / 31);
            destination[(3 * i) + 2] = (byte)(((source[i].Blue * 255) + 15) / 31);
        }
    }
}

Properties

NameDescription
StorageFormatGets the built-in pixel format the pixels convert from and to.

StorageFormat

Gets the built-in pixel format the pixels convert from and to.

public static abstract PixelFormat StorageFormat { get; }

Property value

PixelFormat

Methods

NameDescription
FromStorage(ReadOnlySpan<byte>, Span<TSelf>)Converts a row of pixels of the storage format to pixels of this type.
ToStorage(ReadOnlySpan<TSelf>, Span<byte>)Converts a row of pixels of this type to pixels of the storage format.

FromStorage(ReadOnlySpan<byte>, Span<TSelf>)

Converts a row of pixels of the storage format to pixels of this type.

public static abstract void FromStorage(ReadOnlySpan<byte> source, Span<TSelf> destination)

Parameters

source ReadOnlySpan<byte>
The bytes of the pixels of ICustomPixel<TSelf>.StorageFormat.
destination Span<TSelf>
The pixels, as many as source holds.

ToStorage(ReadOnlySpan<TSelf>, Span<byte>)

Converts a row of pixels of this type to pixels of the storage format.

public static abstract void ToStorage(ReadOnlySpan<TSelf> source, Span<byte> destination)

Parameters

source ReadOnlySpan<TSelf>
The pixels.
destination Span<byte>
The bytes of the pixels of ICustomPixel<TSelf>.StorageFormat, as many as source holds.