Meziantou.FrameworkImageCollectionEntry Class
One entry of an ImageCollection: a page of a document or an alternative representation of a drawing.
public sealed class ImageCollectionEntryRemarks
An entry describes its image without decoding it: a loaded collection reads the directory structure of the file, not its pixels, so ImageCollectionEntry.Size, ImageCollectionEntry.PixelFormat and ImageCollectionEntry.Metadata are available for every entry of a 400-page document at the cost of a few kilobytes of reads. ImageCollectionEntry.Decode reads and decodes exactly one entry, and returns a normal, independently owned Image.
An entry is borrowed from its collection: it is valid until the collection is disposed, or until the entry is removed from it. The images it returns are not: they are owned by the caller, who disposes them.
Properties
| Name | Description |
|---|---|
| BitsPerComponent | Gets the precision of one encoded component, in bits. |
| ColorModel | Gets the color model of the encoded samples. |
| Hotspot | Gets the hotspot of a cursor representation, in pixels from the top-left corner of this entry, or null when the entry is not a cursor representation. |
| MayHaveTransparency | Gets a value indicating whether the entry can have transparent pixels. |
| Metadata | Gets the metadata of the entry. Entries of one collection have independent metadata. |
| PayloadFormat | Gets the format of the stored payload of the entry (ImageFormat.Png or ImageFormat.Bmp inside an icon, ImageFormat.Tiff for a page), or ImageFormat.Unknown for an entry that was added to the collection and not encoded yet. |
| PixelFormat | Gets the lossless working representation of the entry: the pixel format ImageCollectionEntry.Decode produces by default. |
| Size | Gets the size of the entry, in pixels. Entries of one collection may differ in size. |
BitsPerComponent
ImageCollectionEntry.csColorModel
ImageCollectionEntry.csGets the color model of the encoded samples.
public ImageColorModel ColorModel { get; }Property value
Hotspot
ImageCollectionEntry.csGets the hotspot of a cursor representation, in pixels from the top-left corner of this entry, or null when the entry is not a cursor representation.
public Point? Hotspot { get; }Property value
Remarks
A hotspot is cursor metadata, not a pixel offset: it never moves the image inside a canvas and is validated against the size of this entry only. A decoded entry carries it as the hotspot of its frame (FrameMetadata.Hotspot).
MayHaveTransparency
ImageCollectionEntry.csMetadata
ImageCollectionEntry.csGets the metadata of the entry. Entries of one collection have independent metadata.
public ImageMetadata Metadata { get; }Property value
PayloadFormat
ImageCollectionEntry.csGets the format of the stored payload of the entry (ImageFormat.Png or ImageFormat.Bmp inside an icon, ImageFormat.Tiff for a page), or ImageFormat.Unknown for an entry that was added to the collection and not encoded yet.
public ImageFormat PayloadFormat { get; }Property value
PixelFormat
ImageCollectionEntry.csGets the lossless working representation of the entry: the pixel format ImageCollectionEntry.Decode produces by default.
public PixelFormat PixelFormat { get; }Property value
Methods
| Name | Description |
|---|---|
| Decode(ImageDecodeOptions?) | Decodes the entry into a new image, in its default pixel format. |
| Decode(ImageDecodeOptions?, CancellationToken) | Decodes the entry into a new image, in its default pixel format, and can be canceled. |
| Decode<TPixel>(ImageDecodeOptions?) | Decodes the entry into a new image of the requested pixel type. |
| Decode<TPixel>(ImageDecodeOptions?, CancellationToken) | Decodes the entry into a new image of the requested pixel type, and can be canceled. |
Decode overloads
Decode(ImageDecodeOptions?)
ImageCollectionEntry.csDecodes the entry into a new image, in its default pixel format.
public Image Decode(ImageDecodeOptions? options)Parameters
optionsImageDecodeOptions?- The options, or
nullto decode with the configuration of the collection.
Returns
Image A new image owned by the caller. It is a still image: a page or a representation is never an animation.
Exceptions
ObjectDisposedException- The collection is disposed.
InvalidImageContentException- The data of the entry is malformed or truncated.
UnsupportedImageFeatureException- The entry uses a recognized but unsupported feature.
ImageResourceLimitException- A configured limit is exceeded.
IOException- An I/O error occurred.
Decode(ImageDecodeOptions?, CancellationToken)
ImageCollectionEntry.csDecodes the entry into a new image, in its default pixel format, and can be canceled.
public Image Decode(ImageDecodeOptions? options = null, CancellationToken cancellationToken = default)Parameters
optionsImageDecodeOptions?- The options, or
nullto decode with the configuration of the collection. cancellationTokenCancellationToken- The token to monitor for cancellation requests.
Returns
Image A new image owned by the caller. It is a still image: a page or a representation is never an animation.
Exceptions
ObjectDisposedException- The collection is disposed.
InvalidImageContentException- The data of the entry is malformed or truncated.
UnsupportedImageFeatureException- The entry uses a recognized but unsupported feature.
ImageResourceLimitException- A configured limit is exceeded.
IOException- An I/O error occurred.
OperationCanceledException- The operation was canceled.
Remarks
The decode runs synchronously on the calling thread. The token is checked before anything is read and then between bounded units of work of the decoder (rows, strips, tiles or blocks), never in the middle of one. A canceled decode returns no image, releases every buffer it allocated and leaves the collection usable: the entry can be decoded again. An entry that owns an image (added with ImageCollection.Add) is copied, which the token cannot interrupt.
Like the overload without a token, this method may be called from several threads at once on the entries of a loaded collection (see ImageCollection); each call observes its own token.
Decode<TPixel>(ImageDecodeOptions?)
ImageCollectionEntry.csDecodes the entry into a new image of the requested pixel type.
public Image<TPixel> Decode<TPixel>(ImageDecodeOptions? options) where TPixel : unmanagedType parameters
TPixel- The pixel type of the result.
Parameters
optionsImageDecodeOptions?- The options, or
nullto decode with the configuration of the collection.
Returns
Image<TPixel> A new image owned by the caller.
Exceptions
NotSupportedExceptionTPixelis not a built-in pixel struct.ObjectDisposedException- The collection is disposed.
UnsupportedImageFeatureException- The conversion would drop information without an explicit policy.
Decode<TPixel>(ImageDecodeOptions?, CancellationToken)
ImageCollectionEntry.csDecodes the entry into a new image of the requested pixel type, and can be canceled.
public Image<TPixel> Decode<TPixel>(ImageDecodeOptions? options = null, CancellationToken cancellationToken = default) where TPixel : unmanagedType parameters
TPixel- The pixel type of the result.
Parameters
optionsImageDecodeOptions?- The options, or
nullto decode with the configuration of the collection. cancellationTokenCancellationToken- The token to monitor for cancellation requests.
Returns
Image<TPixel> A new image owned by the caller.
Exceptions
NotSupportedExceptionTPixelis not a built-in pixel struct. Thrown before the token is checked.ObjectDisposedException- The collection is disposed.
UnsupportedImageFeatureException- The conversion would drop information without an explicit policy.
OperationCanceledException- The operation was canceled.
Remarks
The cancellation guarantees and the thread safety are those of ImageCollectionEntry.Decode.