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 : IDisposableRemarks
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
| Name | Description |
|---|---|
| JpegXlLayeredImage(int, int, ImageConfiguration?) | Initializes an image without layers, of a canvas size. |
JpegXlLayeredImage(int, int, ImageConfiguration?)
JpegXlLayeredImage.csInitializes an image without layers, of a canvas size.
public JpegXlLayeredImage(int width, int height, ImageConfiguration? configuration = null)Parameters
widthint- The width of the canvas.
heightint- The height of the canvas.
configurationImageConfiguration?- The configuration of the layers and of the operations, or
nullforImageConfiguration.Default.
Exceptions
ArgumentOutOfRangeExceptionwidthorheightis not positive or is larger than JPEG XL allows (2^30).
Properties
| Name | Description |
|---|---|
| Configuration | Gets the configuration of the layers and of the operations. |
| Layers | Gets the layers, from the bottom one up. |
| Metadata | 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. |
| Size | Gets the size of the canvas: the size of the image the layers make. |
Configuration
JpegXlLayeredImage.csGets the configuration of the layers and of the operations.
public ImageConfiguration Configuration { get; }Property value
Layers
JpegXlLayeredImage.csGets the layers, from the bottom one up.
public IReadOnlyList<JpegXlLayer> Layers { get; }Property value
Metadata
JpegXlLayeredImage.csGets 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
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.
Methods
| Name | Description |
|---|---|
| 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.csAdds 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
imageImage- The pixels of the layer: a still image of one frame, of any size. It is copied: the caller keeps and disposes it.
offsetPoint- 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.
blendModeJpegXlBlendMode- How the layer is combined with the layers below it.
namestring?- The name of the layer, or
null.
Returns
JpegXlLayer The layer.
Exceptions
ArgumentNullExceptionimageisnull.ArgumentExceptionimagehas several frames or a poster frame, ornameis longer thanJpegXlLayer.MaxNameLengthbytes in UTF-8.ArgumentOutOfRangeExceptionoffsetorblendModeis not valid, or the image is larger than JPEG XL allows (2^30).ObjectDisposedException- The layered image or
imageis disposed.
Dispose()
JpegXlLayeredImage.csDisposes the images of the layers.
public void Dispose()InsertLayer(int, Image, Point, JpegXlBlendMode, string?)
JpegXlLayeredImage.csInserts 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
indexint- The index of the new layer, 0 being the bottom one.
imageImage- The pixels of the layer: a still image of one frame, of any size. It is copied: the caller keeps and disposes it.
offsetPoint- 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.
blendModeJpegXlBlendMode- How the layer is combined with the layers below it.
namestring?- The name of the layer, or
null.
Returns
JpegXlLayer The layer.
Exceptions
ArgumentNullExceptionimageisnull.ArgumentExceptionimagehas several frames or a poster frame, ornameis longer thanJpegXlLayer.MaxNameLengthbytes in UTF-8.ArgumentOutOfRangeExceptionindex,offsetorblendModeis not valid, or the image is larger than JPEG XL allows (2^30).ObjectDisposedException- The layered image or
imageis disposed.
Load overloads
Load(Stream, ImageConfiguration?)
JpegXlLayeredImage.csReads 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
streamStream- The readable input.
configurationImageConfiguration?- The configuration of the layers and of the decoding, or
nullforImageConfiguration.Default.
Returns
JpegXlLayeredImage The layered image, which the caller disposes.
Exceptions
ArgumentNullExceptionstreamisnull.ArgumentExceptionstreamis 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.csReads the layers of a still JPEG XL file in memory.
public static JpegXlLayeredImage Load(ReadOnlySpan<byte> data, ImageConfiguration? configuration = null)Parameters
dataReadOnlySpan<byte>- The file.
configurationImageConfiguration?- The configuration of the layers and of the decoding, or
nullforImageConfiguration.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.csReads the layers of a still JPEG XL file.
public static JpegXlLayeredImage Load(string path, ImageConfiguration? configuration = null)Parameters
pathstring- The path of the file.
configurationImageConfiguration?- The configuration of the layers and of the decoding, or
nullforImageConfiguration.Default.
Returns
JpegXlLayeredImage The layered image, which the caller disposes.
Exceptions
ArgumentNullExceptionpathisnull.ArgumentExceptionpathis 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.csRemoves a layer and disposes its image.
Parameters
indexint- The index of the layer, 0 being the bottom one.
Exceptions
ArgumentOutOfRangeExceptionindexis not the index of a layer.ObjectDisposedException- The layered image is disposed.
Save overloads
Save(Stream, JpegXlEncoder?)
JpegXlLayeredImage.csWrites 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
streamStream- The writable destination; it does not need to be seekable.
encoderJpegXlEncoder?- The settings of the frames, or
nullfor the default ones (lossless).JpegXlEncoder.DurationRoundingandJpegXlEncoder.OptimizeFramesdo not apply to a still image.
Exceptions
ArgumentNullExceptionstreamisnull.ArgumentExceptionstreamis 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 thanJpegXlLayeredImage.Metadata; or the metadata cannot be stored (seeImageEncoder.MetadataHandling). ObjectDisposedException- The layered image is disposed.
Save(string, JpegXlEncoder?)
JpegXlLayeredImage.csWrites the image to a file, published atomically: each layer is a frame of the file.
public void Save(string path, JpegXlEncoder? encoder = null)Parameters
pathstring- The destination path.
encoderJpegXlEncoder?- The settings of the frames, or
nullfor the default ones (lossless).JpegXlEncoder.DurationRoundingandJpegXlEncoder.OptimizeFramesdo not apply to a still image.
Exceptions
ArgumentNullExceptionpathisnull.ArgumentExceptionpathis 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 thanJpegXlLayeredImage.Metadata; or the metadata cannot be stored (seeImageEncoder.MetadataHandling). ObjectDisposedException- The layered image is disposed.
IOException- An I/O error occurred.