JpegXlLayeredImage Class

A still JPEG XL image made of layers: images of any size, each at a position on the canvas, combined from the bottom one up with the blend modes of the format, and named. Image.Load reads the image the layers make, as a viewer shows it; this type reads and writes the layers themselves.

public sealed class JpegXlLayeredImage : IDisposable

Remarks

This type is separate from Image, whose frames are the full displayed frames of an animation, and from ImageCollection, whose entries are never blended: a layer is not shown on its own. Each layer is a frame of the file without duration, blended with the layers below it, which a decoder keeps in a reference slot: the last layer is the image.

JpegXlLayeredImage.Save writes every layer with the settings of a JpegXlEncoder (lossless by default, lossy alpha included), and JpegXlLayeredImage.Load reads the layers of any still JPEG XL file whose frames are such layers, whatever wrote it: a file with a single frame has one layer. A layer decoded from a lossy file has the samples a decoder blends: a lossless file gives the layers back exactly.

The images of the layers belong to the layered image, which disposes them. An instance supports one operation at a time.

Example

using (var document = new JpegXlLayeredImage(64, 48))
{
    // The bottom layer covers the canvas; a smaller layer is drawn over it at an offset, weighted by its alpha
    using var background = new Image<Rgba32>(64, 48, new Rgba32(255, 255, 255, 255));
    using var badge = new Image<Rgba32>(16, 16, new Rgba32(200, 0, 0, 255));
    document.AddLayer(background, name: "Background");
    document.AddLayer(badge, new Point(40, 4), JpegXlBlendMode.Blend, "Badge");
    document.Save(path);
}

// A viewer shows the image the layers make...
using (var image = Image.Load<Rgba32>(path))
{
    Assert.Equal(new Rgba32(200, 0, 0, 255), image.Frames[0][45, 10]);
    Assert.Equal(new Rgba32(255, 255, 255, 255), image.Frames[0][10, 10]);
}

// ...and the layers are read back, with their positions, blend modes and names
using (var document = JpegXlLayeredImage.Load(path))
{
    Assert.Equal(2, document.Layers.Count);
    Assert.Equal((new Point(40, 4), JpegXlBlendMode.Blend, "Badge"), (document.Layers[1].Offset, document.Layers[1].BlendMode, document.Layers[1].Name));
    Assert.Equal(new Size(16, 16), document.Layers[1].Image.Size);
}
Implements

Constructors

NameDescription
JpegXlLayeredImage(int, int, ImageConfiguration?)Initializes an image without layers, of a canvas size.

JpegXlLayeredImage(int, int, ImageConfiguration?)

JpegXlLayeredImage.cs

Initializes an image without layers, of a canvas size.

public JpegXlLayeredImage(int width, int height, ImageConfiguration? configuration = null)

Parameters

width int
The width of the canvas.
height int
The height of the canvas.
configuration ImageConfiguration?
The configuration of the layers and of the operations, or null for ImageConfiguration.Default.

Exceptions

ArgumentOutOfRangeException
width or height is not positive or is larger than JPEG XL allows (2^30).

Properties

NameDescription
ConfigurationGets the configuration of the layers and of the operations.
LayersGets the layers, from the bottom one up.
MetadataGets the metadata of the image: the color profile, CICP description or transfer function that describe the samples of every layer, the orientation, and the EXIF and XMP profiles.
SizeGets the size of the canvas: the size of the image the layers make.

Gets the configuration of the layers and of the operations.

public ImageConfiguration Configuration { get; }

Property value

ImageConfiguration

Gets the layers, from the bottom one up.

public IReadOnlyList<JpegXlLayer> Layers { get; }

Gets the metadata of the image: the color profile, CICP description or transfer function that describe the samples of every layer, the orientation, and the EXIF and XMP profiles.

public ImageMetadata Metadata { get; }

Property value

ImageMetadata

Remarks

The metadata of the images of the layers are not written. A layer whose image has another color profile, CICP description or transfer function than these is rejected by Save: its samples would be read in a color space they are not in.

Gets the size of the canvas: the size of the image the layers make.

public Size Size { get; }

Property value

Size

Methods

NameDescription
AddLayer(Image, Point, JpegXlBlendMode, string?)Adds a copy of an image as the top layer.
Dispose()Disposes the images of the layers.
InsertLayer(int, Image, Point, JpegXlBlendMode, string?)Inserts a copy of an image as a layer.
Load(Stream, ImageConfiguration?)Reads the layers of a still JPEG XL file from a stream, from its current position. The stream is left open.
Load(ReadOnlySpan<byte>, ImageConfiguration?)Reads the layers of a still JPEG XL file in memory.
Load(string, ImageConfiguration?)Reads the layers of a still JPEG XL file.
RemoveLayerAt(int)Removes a layer and disposes its image.
Save(Stream, JpegXlEncoder?)Writes the image to a stream, from its current position: each layer is a frame of the file. The stream is left open.
Save(string, JpegXlEncoder?)Writes the image to a file, published atomically: each layer is a frame of the file.

AddLayer(Image, Point, JpegXlBlendMode, string?)

JpegXlLayeredImage.cs

Adds a copy of an image as the top layer.

public JpegXlLayer AddLayer(Image image, Point offset = default, JpegXlBlendMode blendMode = JpegXlBlendMode.Replace, string? name = null)

Parameters

image Image
The pixels of the layer: a still image of one frame, of any size. It is copied: the caller keeps and disposes it.
offset Point
The position of the top-left corner of the layer on the canvas; it may be negative, and the layer may extend beyond the canvas.
blendMode JpegXlBlendMode
How the layer is combined with the layers below it.
name string?
The name of the layer, or null.

Returns

JpegXlLayer The layer.

Exceptions

ArgumentNullException
image is null.
ArgumentException
image has several frames or a poster frame, or name is longer than JpegXlLayer.MaxNameLength bytes in UTF-8.
ArgumentOutOfRangeException
offset or blendMode is not valid, or the image is larger than JPEG XL allows (2^30).
ObjectDisposedException
The layered image or image is disposed.

Disposes the images of the layers.

public void Dispose()

InsertLayer(int, Image, Point, JpegXlBlendMode, string?)

JpegXlLayeredImage.cs

Inserts a copy of an image as a layer.

public JpegXlLayer InsertLayer(int index, Image image, Point offset = default, JpegXlBlendMode blendMode = JpegXlBlendMode.Replace, string? name = null)

Parameters

index int
The index of the new layer, 0 being the bottom one.
image Image
The pixels of the layer: a still image of one frame, of any size. It is copied: the caller keeps and disposes it.
offset Point
The position of the top-left corner of the layer on the canvas; it may be negative, and the layer may extend beyond the canvas.
blendMode JpegXlBlendMode
How the layer is combined with the layers below it.
name string?
The name of the layer, or null.

Returns

JpegXlLayer The layer.

Exceptions

ArgumentNullException
image is null.
ArgumentException
image has several frames or a poster frame, or name is longer than JpegXlLayer.MaxNameLength bytes in UTF-8.
ArgumentOutOfRangeException
index, offset or blendMode is not valid, or the image is larger than JPEG XL allows (2^30).
ObjectDisposedException
The layered image or image is disposed.

Load overloads

Load(Stream, ImageConfiguration?)

JpegXlLayeredImage.cs

Reads the layers of a still JPEG XL file from a stream, from its current position. The stream is left open.

public static JpegXlLayeredImage Load(Stream stream, ImageConfiguration? configuration = null)
Parameters
stream Stream
The readable input.
configuration ImageConfiguration?
The configuration of the layers and of the decoding, or null for ImageConfiguration.Default.
Returns

JpegXlLayeredImage The layered image, which the caller disposes.

Exceptions
ArgumentNullException
stream is null.
ArgumentException
stream is not readable.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file, is an animation, or blends its frames in a way that is not a list of layers (with another reference frame than the layers below, or the alpha channel otherwise than the colors).
InvalidImageContentException
The file is malformed or truncated.
ImageResourceLimitException
A limit of the configuration is exceeded: each layer counts as a frame of its own size, charged before it is decoded.

Load(ReadOnlySpan<byte>, ImageConfiguration?)

JpegXlLayeredImage.cs

Reads the layers of a still JPEG XL file in memory.

public static JpegXlLayeredImage Load(ReadOnlySpan<byte> data, ImageConfiguration? configuration = null)
Parameters
data ReadOnlySpan<byte>
The file.
configuration ImageConfiguration?
The configuration of the layers and of the decoding, or null for ImageConfiguration.Default.
Returns

JpegXlLayeredImage The layered image, which the caller disposes.

Exceptions
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file, is an animation, or blends its frames in a way that is not a list of layers (with another reference frame than the layers below, or the alpha channel otherwise than the colors).
InvalidImageContentException
The file is malformed or truncated.
ImageResourceLimitException
A limit of the configuration is exceeded: each layer counts as a frame of its own size, charged before it is decoded.

Load(string, ImageConfiguration?)

JpegXlLayeredImage.cs

Reads the layers of a still JPEG XL file.

public static JpegXlLayeredImage Load(string path, ImageConfiguration? configuration = null)
Parameters
path string
The path of the file.
configuration ImageConfiguration?
The configuration of the layers and of the decoding, or null for ImageConfiguration.Default.
Returns

JpegXlLayeredImage The layered image, which the caller disposes.

Exceptions
ArgumentNullException
path is null.
ArgumentException
path is empty.
UnknownImageFormatException
The format of the input is not recognized.
UnsupportedImageFeatureException
The input is not a JPEG XL file, is an animation, or blends its frames in a way that is not a list of layers (with another reference frame than the layers below, or the alpha channel otherwise than the colors).
InvalidImageContentException
The file is malformed or truncated.
ImageResourceLimitException
A limit of the configuration is exceeded: each layer counts as a frame of its own size, charged before it is decoded.

RemoveLayerAt(int)

JpegXlLayeredImage.cs

Removes a layer and disposes its image.

public void RemoveLayerAt(int index)

Parameters

index int
The index of the layer, 0 being the bottom one.

Exceptions

ArgumentOutOfRangeException
index is not the index of a layer.
ObjectDisposedException
The layered image is disposed.

Save overloads

Save(Stream, JpegXlEncoder?)

JpegXlLayeredImage.cs

Writes the image to a stream, from its current position: each layer is a frame of the file. The stream is left open.

public void Save(Stream stream, JpegXlEncoder? encoder = null)
Parameters
stream Stream
The writable destination; it does not need to be seekable.
encoder JpegXlEncoder?
The settings of the frames, or null for the default ones (lossless). JpegXlEncoder.DurationRounding and JpegXlEncoder.OptimizeFrames do not apply to a still image.
Exceptions
ArgumentNullException
stream is null.
ArgumentException
stream is not writable.
InvalidOperationException
The image has no layer, its layers do not have the same pixel format, or the image of a layer has several frames or a poster frame.
UnsupportedImageFeatureException
A layer has floating-point samples without ImageEncoder.FloatingPointConversion, CMYK samples, or other color metadata than JpegXlLayeredImage.Metadata; or the metadata cannot be stored (see ImageEncoder.MetadataHandling).
ObjectDisposedException
The layered image is disposed.

Save(string, JpegXlEncoder?)

JpegXlLayeredImage.cs

Writes the image to a file, published atomically: each layer is a frame of the file.

public void Save(string path, JpegXlEncoder? encoder = null)
Parameters
path string
The destination path.
encoder JpegXlEncoder?
The settings of the frames, or null for the default ones (lossless). JpegXlEncoder.DurationRounding and JpegXlEncoder.OptimizeFrames do not apply to a still image.
Exceptions
ArgumentNullException
path is null.
ArgumentException
path is empty.
InvalidOperationException
The image has no layer, its layers do not have the same pixel format, or the image of a layer has several frames or a poster frame.
UnsupportedImageFeatureException
A layer has floating-point samples without ImageEncoder.FloatingPointConversion, CMYK samples, or other color metadata than JpegXlLayeredImage.Metadata; or the metadata cannot be stored (see ImageEncoder.MetadataHandling).
ObjectDisposedException
The layered image is disposed.
IOException
An I/O error occurred.