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
| Name | Description |
|---|---|
| StorageFormat | Gets 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
Methods
| Name | Description |
|---|---|
| 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
sourceReadOnlySpan<byte>- The bytes of the pixels of
ICustomPixel<TSelf>.StorageFormat. destinationSpan<TSelf>- The pixels, as many as
sourceholds.
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
sourceReadOnlySpan<TSelf>- The pixels.
destinationSpan<byte>- The bytes of the pixels of
ICustomPixel<TSelf>.StorageFormat, as many assourceholds.