Class RasterEncoder

Namespace

Egami

Assembly

Egami.dll

Creates a RasterEncoder<TPixel>, which writes an image a band of rows or a frame at a time.

public static class RasterEncoder

Inheritance

object

RasterEncoder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// A huge image written a band at a time: only the band is ever in memory.
const int Width = 8_000, Height = 6_000;
using Raster<Rgb8> band = Raster.Create<Rgb8>(Width, 64);
using RasterEncoder<Rgb8> encoder = RasterEncoder.Create<Rgb8>("big.png", Width, Height);
for (int top = 0; top < Height; top += band.Height)
{
    int rows = Math.Min(band.Height, Height - top);
    for (int y = 0; y < rows; y++)
    {
        band.Row(y).Fill(new Rgb8((byte)(top + y), 128, 200));
    }

    encoder.WriteRows(band, rows);
}

encoder.Complete(); // writes IEND; without it the file is deleted on dispose

Methods

Create<TPixel>(Stream, FormatInfo, int, int, WriterOptions?, RasterMetadata?, EgamiContext?)

Starts writing an image to a stream. A seekable stream lets BMP, TGA and PFM rows land bottom-up and an APNG's frame count be filled in at the end, as Save writes them; a stream that cannot seek gets top-down BMP and TGA rows, and an APNG needs FrameCount.

public static RasterEncoder<TPixel> Create<TPixel>(Stream stream, FormatInfo format, int width, int height, WriterOptions? options = null, RasterMetadata? metadata = null, EgamiContext? context = null) where TPixel : unmanaged, IPixelType<TPixel>

Parameters

stream Stream

Where to write, from its current position. It is left open.

format FormatInfo

The format.

width int

The image width, at least 1.

height int

The image height, at least 1.

options WriterOptions

The format's options, or null for its defaults.

metadata RasterMetadata

The metadata to write, or null for none.

context EgamiContext

The context, or null for Default.

Returns

RasterEncoder<TPixel>

The encoder.

Type Parameters

TPixel

The pixel type of the rows and frames to be written.

Examples

// An animation written a frame at a time, each frame from one reused canvas.
using Raster<Rgba8> canvas = Raster.Create<Rgba8>(120, 80);
using FileStream file = File.Create("spinner.gif");
using RasterEncoder<Rgba8> gif = RasterEncoder.Create<Rgba8>(file, GifFormat.Info, 120, 80);
for (int i = 0; i < 12; i++)
{
    for (int y = 0; y < canvas.Height; y++)
    {
        canvas.Row(y).Fill(new Rgba8(255, 255, 255, 255));
    }

    canvas.Row(40)[(i * 10)..((i * 10) + 10)].Fill(new Rgba8(200, 0, 0, 255));
    gif.WriteFrame(canvas, new Metadata.FrameMetadata { Delay = TimeSpan.FromMilliseconds(80) });
}

gif.Complete();

Exceptions

ArgumentNullException

stream or format is null.

ArgumentOutOfRangeException

width or height is less than 1.

UnsupportedFormatException

The format has no writer.

NotSupportedException

An option needs every pixel before the first byte, such as an automatic palette.

Create<TPixel>(string, int, int, WriterOptions?, RasterMetadata?, EgamiContext?)

Starts writing a file, choosing the format from the extension as Save(string, WriterOptions?) does. An existing file is replaced; if the encoder is disposed before Complete(), the partly written file is deleted.

public static RasterEncoder<TPixel> Create<TPixel>(string path, int width, int height, WriterOptions? options = null, RasterMetadata? metadata = null, EgamiContext? context = null) where TPixel : unmanaged, IPixelType<TPixel>

Parameters

path string

The file path.

width int

The image width, at least 1.

height int

The image height, at least 1.

options WriterOptions

The format's options, or null for its defaults.

metadata RasterMetadata

The metadata to write, such as EXIF, ICC and text, or null for none. It is given now because most formats write it before the image data.

context EgamiContext

The context, or null for Default.

Returns

RasterEncoder<TPixel>

The encoder, which owns the file.

Type Parameters

TPixel

The pixel type of the rows and frames to be written.

Examples

// A huge image written a band at a time: only the band is ever in memory.
const int Width = 8_000, Height = 6_000;
using Raster<Rgb8> band = Raster.Create<Rgb8>(Width, 64);
using RasterEncoder<Rgb8> encoder = RasterEncoder.Create<Rgb8>("big.png", Width, Height);
for (int top = 0; top < Height; top += band.Height)
{
    int rows = Math.Min(band.Height, Height - top);
    for (int y = 0; y < rows; y++)
    {
        band.Row(y).Fill(new Rgb8((byte)(top + y), 128, 200));
    }

    encoder.WriteRows(band, rows);
}

encoder.Complete(); // writes IEND; without it the file is deleted on dispose

Exceptions

ArgumentNullException

path is null.

ArgumentOutOfRangeException

width or height is less than 1.

UnsupportedFormatException

No registered format uses the extension, or it has no writer.

NotSupportedException

An option needs every pixel before the first byte, such as an automatic palette.

IOException

The file cannot be created.