Table of Contents

Class Raster<TPixel>

Namespace
Egami
Assembly
Egami.dll

An image whose pixels are of type TPixel. Pixel access is by row span.

public sealed class Raster<TPixel> : Raster, IDisposable where TPixel : unmanaged, IPixelType<TPixel>

Type Parameters

TPixel

The pixel type.

Inheritance
Raster<TPixel>
Implements
Inherited Members
Extension Methods

Examples

// Decode straight into the type you want to work in.
using Raster<Rgba8> rgba = Raster.Load<Rgba8>("duck.png");

// Pixels are a row at a time: each row is a Span<Rgba8>.
for (int y = 0; y < rgba.Height; y++)
{
    Span<Rgba8> row = rgba.Row(y);
    for (int x = 0; x < row.Length; x++)
    {
        row[x].A = 128;
    }
}

// Convert a whole raster; the result is a new raster you dispose too.
using Raster<Gray8> gray = rgba.As<Gray8>();
gray.Save("duck-gray.png");

Properties

FrameCount

Gets the number of frames. Always at least 1.

public override int FrameCount { get; }

Property Value

int

Frames

Gets the frames. Frames[0] always exists.

public FrameList<TPixel> Frames { get; }

Property Value

FrameList<TPixel>

Layout

Gets the memory layout of the pixel type.

public override PixelLayoutInfo Layout { get; }

Property Value

PixelLayoutInfo

Methods

Apply(Action<RasterOps>, CancellationToken)

Runs a chain of operations on every frame, changing this raster in place. Steps that keep the size work on the existing pixels; steps that change it get new pixel memory, and the old memory is returned at once.

public void Apply(Action<RasterOps> build, CancellationToken cancellationToken = default)

Parameters

build Action<RasterOps>

Records the chain, for example ops => ops.Add(operation).

cancellationToken CancellationToken

Cancels between steps and between bands of rows.

Remarks

Arguments are checked while the chain is recorded, before any pixel changes. If a step fails or the chain is cancelled part way, the raster may be left partly changed. Spans from Row(int) taken before a size change become invalid.

Exceptions

ObjectDisposedException

The raster has been disposed.

LimitExceededException

A new plane would break MaxTotalBytes.

OperationCanceledException

The token was cancelled.

Copy()

Returns a deep copy of the raster: every frame and all metadata.

public Raster<TPixel> Copy()

Returns

Raster<TPixel>

The new raster. The caller must dispose it.

Exceptions

ObjectDisposedException

The raster has been disposed.

CopyFrame(int)

Returns a new one-frame raster with a copy of frame index and of the raster's metadata.

public Raster<TPixel> CopyFrame(int index)

Parameters

index int

The frame to copy.

Returns

Raster<TPixel>

The new raster. The caller must dispose it.

Exceptions

ArgumentOutOfRangeException

index is not a frame.

ObjectDisposedException

The raster has been disposed.

CopyPixelsFrom(ReadOnlySpan<byte>)

Overwrites the first frame's pixels from raw bytes laid out row by row with no gaps.

public void CopyPixelsFrom(ReadOnlySpan<byte> source)

Parameters

source ReadOnlySpan<byte>

The bytes. It must hold at least Width × Height × the pixel size bytes.

Exceptions

ArgumentException

source is too short.

ObjectDisposedException

The raster has been disposed.

CopyPixelsFrom(ReadOnlySpan<TPixel>)

Overwrites the first frame's pixels from source, which holds them row by row with no gaps.

public void CopyPixelsFrom(ReadOnlySpan<TPixel> source)

Parameters

source ReadOnlySpan<TPixel>

The pixels. It must hold at least Width × Height pixels.

Exceptions

ArgumentException

source is too short.

ObjectDisposedException

The raster has been disposed.

CopyPixelsTo(Span<byte>)

Copies the first frame's pixels as raw bytes, row by row with no gaps, to destination.

public void CopyPixelsTo(Span<byte> destination)

Parameters

destination Span<byte>

Where to copy. It must hold at least Width × Height × the pixel size bytes.

Exceptions

ArgumentException

destination is too short.

ObjectDisposedException

The raster has been disposed.

CopyPixelsTo(Span<TPixel>)

Copies the first frame's pixels, row by row with no gaps, to destination.

public void CopyPixelsTo(Span<TPixel> destination)

Parameters

destination Span<TPixel>

Where to copy. It must hold at least Width × Height pixels.

Exceptions

ArgumentException

destination is too short.

ObjectDisposedException

The raster has been disposed.

Derive(Action<RasterOps>, CancellationToken)

Runs a chain of operations and returns the result as a new raster, leaving this one untouched. The first step reads this raster directly, so no full-size copy is made first.

public Raster<TPixel> Derive(Action<RasterOps> build, CancellationToken cancellationToken = default)

Parameters

build Action<RasterOps>

Records the chain, for example ops => ops.Add(operation).

cancellationToken CancellationToken

Cancels between steps and between bands of rows.

Returns

Raster<TPixel>

The new raster, with a copy of this raster's metadata. The caller must dispose it.

Exceptions

ObjectDisposedException

The raster has been disposed.

LimitExceededException

A new plane would break MaxTotalBytes.

OperationCanceledException

The token was cancelled.

Dispose(bool)

Releases the frames' memory.

protected override void Dispose(bool disposing)

Parameters

disposing bool

true when called from Dispose().

ForEachRow(RowAction<TPixel>, CancellationToken)

Calls action once for every row of the first frame. Large rasters are processed in bands of rows on several threads, up to the context's MaxParallelism, so action may run concurrently for different rows.

public void ForEachRow(RowAction<TPixel> action, CancellationToken cancellationToken = default)

Parameters

action RowAction<TPixel>

The work to do on each row.

cancellationToken CancellationToken

Cancels between bands of rows.

Exceptions

ObjectDisposedException

The raster has been disposed.

OperationCanceledException

cancellationToken was canceled.

GetPixel(int, int)

Reads one pixel of the first frame. This is slow; use Row(int) for bulk access.

public TPixel GetPixel(int x, int y)

Parameters

x int

The column.

y int

The row.

Returns

TPixel

The pixel.

Exceptions

ArgumentOutOfRangeException

The position is outside the raster.

ObjectDisposedException

The raster has been disposed.

Row(int)

Returns one row of the first frame. Do not use the span after the raster is disposed or resized.

public Span<TPixel> Row(int y)

Parameters

y int

The row index, 0 to Height - 1.

Returns

Span<TPixel>

The row, exactly Width pixels long.

Exceptions

ArgumentOutOfRangeException

y is outside the raster.

ObjectDisposedException

The raster has been disposed.

SetPixel(int, int, TPixel)

Writes one pixel of the first frame. This is slow; use Row(int) for bulk access.

public void SetPixel(int x, int y, TPixel value)

Parameters

x int

The column.

y int

The row.

value TPixel

The pixel.

Exceptions

ArgumentOutOfRangeException

The position is outside the raster.

ObjectDisposedException

The raster has been disposed.

TryGetContiguous(out Span<TPixel>)

Gets all pixels of the first frame as one span, if they are contiguous in memory.

public bool TryGetContiguous(out Span<TPixel> pixels)

Parameters

pixels Span<TPixel>

All pixels, row by row, or an empty span.

Returns

bool

true if the pixels are contiguous.

Exceptions

ObjectDisposedException

The raster has been disposed.

Edit this page