PixelBuffer

View Source Code

namespace VideoKit {
    /// <summary>
    /// View of pixel data in memory.
    /// </summary>
    readonly struct PixelBuffer : IDisposable { ... }
}

The PixelBuffer stores pixel data, supports different pixel formats, and provides properties for accessing pixel planes, metadata, and more.

Creating a Pixel Buffer

Pixel buffers are created from raw pixel data, along with data about the pixel layout:

From an Managed Buffer

/// <summary>
/// Create an interleaved pixel buffer from pixel data in managed memory.
/// </summary>
/// <param name="width">Pixel buffer width.</param>
/// <param name="height">Pixel buffer height.</param>
/// <param name="format">Pixel buffer format. This MUST be `RGBA8888`.</param>
/// <param name="data">Pixel data.</param>
/// <param name="rowStride">Pixel buffer row stride.</param>
/// <param name="timestamp">Pixel buffer timestamp.</param>
/// <param name="mirrored">Whether the pixel buffer is vertically mirrored.</param>
/// <returns>Created pixel buffer.</returns>
PixelBuffer (
    int width,
    int height,
    Format format,
    byte[] data,
    int rowStride = 0,
    long timestamp = 0L,
    bool mirrored = false
);

This constructor creates a PixelBuffer from interleaved pixel data in managed memory.

This overload makes a copy of the input buffer, so prefer using the other overloads instead.

From a Native Array

/// <summary>
/// Create an interleaved pixel buffer from pixel data.
/// </summary>
/// <param name="width">Pixel buffer width.</param>
/// <param name="height">Pixel buffer height.</param>
/// <param name="format">Pixel buffer format. This MUST be `RGBA8888`.</param>
/// <param name="data">Pixel data.</param>
/// <param name="rowStride">Pixel buffer row stride.</param>
/// <param name="timestamp">Pixel buffer timestamp.</param>
/// <param name="mirrored">Whether the pixel buffer is vertically mirrored.</param>
/// <returns>Created pixel buffer.</returns>
PixelBuffer (
    int width,
    int height,
    Format format,
    NativeArray<byte> data,
    int rowStride = 0,
    long timestamp = 0L,
    bool mirrored = false
);

This constructor creates a PixelBuffer from interleaved pixel data in a NativeArray<byte>.

You must ensure that the data native array is alive for the entire lifetime of the PixelBuffer.

From a Native Buffer

/// <summary>
/// Create an interleaved pixel buffer from pixel data in native memory.
/// </summary>
/// <param name="width">Pixel buffer width.</param>
/// <param name="height">Pixel buffer height.</param>
/// <param name="format">Pixel buffer format. This MUST be `RGBA8888`.</param>
/// <param name="data">Pixel data.</param>
/// <param name="rowStride">Pixel buffer row stride.</param>
/// <param name="timestamp">Pixel bufffer timestamp.</param>
/// <param name="mirrored">Whether the pixel buffer is vertically mirrored.</param>
/// <returns>Created pixel buffer.</returns>
unsafe PixelBuffer (
    int width,
    int height,
    Format format,
    byte* data,
    int rowStride = 0,
    long timestamp = 0L,
    bool mirrored = false
);

This constructor creates a PixelBuffer from interleaved pixel data in native memory.

You must ensure that the data buffer is alive for the entire lifetime of the PixelBuffer.

From a Texture

/// <summary>
/// Create a pixel buffer from a texture.
/// </summary>
/// <param name="texture">Input texture.</param>
/// <param name="timestamp">Pixel buffer timestamp.</param>
/// <returns>Created pixel buffer.</returns>
PixelBuffer (Texture2D texture, long timestamp = 0L);

This constructor creates a PixelBuffer from a Texture2D. The texture must have one of the following pixel formats:

`TextureFormat`	`PixelBuffer.Format`
`TextureFormat.RGBA32`	`Format.RGBA8888`
`TextureFormat.BGRA32`	`Format.BGRA8888`

Inspecting the Pixel Format

/// <summary>
/// Pixel buffer format.
/// </summary>
Format format { get; }

INCOMPLETE

/// <summary>
/// Pixel buffer format.
/// </summary>
enum Format : int {
    /// <summary>
    /// Unknown image format.
    /// </summary>
    Unknown = 0,
    /// <summary>
    /// Generic YUV 420 planar format.
    /// </summary>
    YCbCr420 = 1,
    /// <summary>
    /// RGBA8888.
    /// </summary>
    RGBA8888 = 2,
    /// <summary>
    /// BGRA8888.
    /// </summary>
    BGRA8888 = 3,    
}

Inspecting the Buffer Width

/// <summary>
/// Pixel buffer width.
/// </summary>
int width { get; }

INCOMPLETE

Inspecting the Buffer Height

/// <summary>
/// Pixel buffer height.
/// </summary>
int height { get; }

INCOMPLETE

Accessing Interleaved Pixel Data

INCOMPLETE

Accessing the Pixel Data

/// <summary>
/// Pixel data.
/// </summary>
NativeArray<byte> data { get; }

INCOMPLETE

Inspecting the Row Stride

/// <summary>
/// Pixel buffer row stride in bytes.
/// </summary>
int rowStride { get; }

INCOMPLETE

The rowStride is zero if the pixel format is planar.

Accessing Planar Pixel Data

/// <summary>
/// Pixel buffer planes for planar formats.
/// This is `null` for interleaved formats.
/// </summary>
IReadOnlyList<Plane> planes { get; }

INCOMPLETE

/// <summary>
/// Pixel buffer plane for planar formats.
/// </summary>
readonly struct Plane { ... }

Accessing the Pixel Data

/// <summary>
/// Pixel data.
/// </summary>
NativeArray<byte> Plane.data { get; }

INCOMPLETE

Inspecting the Plane Width

/// <summary>
/// Plane width.
/// </summary>
int Plane.width { get; }

INCOMPLETE

Inspecting the Plane Height

/// <summary>
/// Plane height.
/// </summary>
int Plane.height { get; }

INCOMPLETE

Inspecting the Plane Row Stride

/// <summary>
/// Row stride in bytes.
/// </summary>
int Plane.rowStride { get; }

INCOMPLETE

Inspecting the Plane Pixel Stride

/// <summary>
/// Pixel stride in bytes.
/// </summary>
int Plane.pixelStride { get; }

INCOMPLETE

Inspecting the Buffer Timestamp

/// <summary>
/// Pixel buffer timestamp in nanoseconds.
/// </summary>
long timestamp { get; }

INCOMPLETE

Inspecting the Vertical Mirroring

/// <summary>
/// Whether the pixel buffer is vertically mirrored.
/// </summary>
bool verticallyMirrored { get; }

INCOMPLETE

Inspecting the Buffer Metadata

/// <summary>
/// Pixel buffer metadata.
/// </summary>
IReadOnlyDictionary<string, object> metadata { get; }

INCOMPLETE

Copying Pixel Data

/// <summary>
/// Copy pixel data into a destination pixel buffer.
/// </summary>
/// <param name="destination">Destination pixel buffer.</param>
/// <param name="rotation">Rotation to apply when copying pixel data.</param>
void CopyTo (
    PixelBuffer destination,
    Rotation rotation = Rotation._0
);

INCOMPLETE

enum Rotation : int {
    /// <summary>
    /// No rotation.
    /// </summary>
    _0 = 0,
    /// <summary>
    /// Rotate 90 degrees counter-clockwise.
    /// </summary>
    _90 = 1,
    /// <summary>
    /// Rotate 180 degrees.
    /// </summary>
    _180 = 2,
    /// <summary>
    /// Rotate 270 degrees counter-clockwise.
    /// </summary>
    _270 = 3
}

Disposing the Pixel Buffer

/// <summary>
/// Dispose the pixel buffer and release resources.
/// </summary>
void Dispose ();

Because the PixelBuffer holds native resources, it must explicitly be disposed when it is no longer needed.