Class MipChain

Namespace

Egami

Assembly

Egami.dll

A chain of ever-halved copies of an image, for making many smaller sizes fast: each resize starts from the smallest level that is still at least twice the target, so a gallery of thumbnail sizes reads each source pixel about once instead of once per size. Level 0 is the source itself; each next level halves the size, rounding up, by averaging 2 × 2 blocks of premultiplied pixels.

public sealed class MipChain : IDisposable

Inheritance

object

MipChain

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// A responsive image set: one chain, then each width from the smallest level at least twice its size.
using MipChain chain = MipChain.Build(photo);
foreach (int width in (int[])[320, 240, 160, 120, 80])
{
    using Raster thumbnail = chain.Fit(width, width, ResampleFilter.Lanczos2);
    thumbnail.Save($"egret-{width}.png");
}

Remarks

The levels together take a third more memory than the source. Every frame of an animation gets its levels. The chain does not copy or dispose the source, which must outlive it; disposing the chain frees the levels it made.

Properties

Levels

Gets the levels, from the source (level 0) down to 1 × 1.

public IReadOnlyList<Raster> Levels { get; }

Property Value

IReadOnlyList<Raster>

Exceptions

ObjectDisposedException

The chain has been disposed.

Methods

Build(Raster, ColorSpace)

Builds the chain for source, down to a 1 × 1 level.

public static MipChain Build(Raster source, ColorSpace colorSpace = ColorSpace.Encoded)

Parameters

source Raster

The image; it becomes level 0 as it is, so it must outlive the chain.

colorSpace ColorSpace

Where the levels and the resizes from them blend: the stored values (the default) or linear light.

Returns

MipChain

The chain. The caller must dispose it.

Exceptions

ArgumentNullException

source is null.

ArgumentOutOfRangeException

colorSpace is not defined.

LimitExceededException

The levels would break the context's MaxTotalBytes.

Dispose()

Frees the levels the chain made; the source is left alone.

public void Dispose()

Fit(int, int, ResampleFilter, bool)

Returns the image fitted inside width × height with its aspect ratio kept, the same size Fit(int, int, ResampleFilter, ColorSpace, bool) gives from the source, resized from the smallest level at least twice that size.

public Raster Fit(int width, int height, ResampleFilter filter = ResampleFilter.Bicubic, bool enlarge = true)

Parameters

width int

The box width, at least 1.

height int

The box height, at least 1.

filter ResampleFilter

The resampling kernel.

enlarge bool

Whether an image smaller than the box is scaled up; false returns it at its own size.

Returns

Raster

The new raster. The caller must dispose it.

Exceptions

ArgumentOutOfRangeException

A size is less than 1, or the filter is not defined.

ObjectDisposedException

The chain has been disposed.

Resize(int, int, ResampleFilter)

Returns the image resized to exactly width × height, from the smallest level at least twice that size in both directions (the source when there is none), as Resize(int, int, ResampleFilter, ColorSpace) would from the source.

public Raster Resize(int width, int height, ResampleFilter filter = ResampleFilter.Bicubic)

Parameters

width int

The width, at least 1.

height int

The height, at least 1.

filter ResampleFilter

The resampling kernel.

Returns

Raster

The new raster, with the source's pixel type and metadata. The caller must dispose it.

Exceptions

ArgumentOutOfRangeException

A size is less than 1, or the filter is not defined.

ObjectDisposedException

The chain has been disposed.