Class GorgonCodecWic<TWicEncOpt, TWicDecOpt>

public abstract class GorgonCodecWic<TWicEncOpt, TWicDecOpt> : GorgonImageCodec<TWicEncOpt, TWicDecOpt>, IGorgonImageCodec, IGorgonNamedObject where TWicEncOpt : class, IGorgonWicEncodingOptions where TWicDecOpt : class, IGorgonWicDecodingOptions

Type Parameters

Name	Description
TWicEncOpt	The type of the options object used to provide options when encoding an image. Must be a reference type and implement IGorgonWicEncodingOptions.
TWicDecOpt	The type of the options object used to provide options when decoding an image. Must be a reference type and implement IGorgonWicDecodingOptions.

Remarks

A codec allows for reading and/or writing of data in an encoded format. Users may inherit from this object to define their own image formats, or use one of the predefined image codecs available in Gorgon.

Constructors

| Edit this page View Source

GorgonCodecWic(string, string, IReadOnlyList<string>, Guid, TWicEncOpt, TWicDecOpt)

Initializes a new instance of the GorgonCodecWic<TWicEncOpt, TWicDecOpt> class.

Declaration

protected GorgonCodecWic(string codec, string description, IReadOnlyList<string> extensions, Guid containerGUID, TWicEncOpt encodingOptions, TWicDecOpt decodingOptions)

Parameters

Type	Name	Description
string	codec	Codec name.
string	description	Description for the codec.
IReadOnlyList<string>	extensions	Common extension(s) for the codec.
Guid	containerGUID	GUID for the container format.
TWicEncOpt	encodingOptions	Options for encoding WIC images.
TWicDecOpt	decodingOptions	Options for decoding WIC images.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `codec` parameter is null.
ArgumentEmptyException	Thrown when the `codec` parameter is empty.

Properties

| Edit this page View Source

Codec

Property to return the abbreviated name of the codec (e.g. PNG).

Declaration

public override string Codec { get; }

Property Value

Type	Description
string

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.Codec

| Edit this page View Source

CodecDescription

Property to return the friendly description of the format.

Declaration

public override string CodecDescription { get; }

Property Value

Type	Description
string

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.CodecDescription

| Edit this page View Source

FrameOffsetMetadataNames

Property to return the list of names used to locate frame offsets in metadata.

Declaration

protected virtual IReadOnlyList<string> FrameOffsetMetadataNames { get; }

Property Value

Type	Description
IReadOnlyList<string>

Remarks

Implementors must put the horizontal offset name first, and the vertical name second. Failure to do so will lead to incorrect offsets.

| Edit this page View Source

SupportedFileFormat

Property to set or return the file format that is supported by this codec.

Declaration

protected Guid SupportedFileFormat { get; }

Property Value

Type	Description
Guid

| Edit this page View Source

SupportedPixelFormats

Property to return the supported pixel formats for this codec.

Declaration

public override IReadOnlyList<BufferFormat> SupportedPixelFormats { get; }

Property Value

Type	Description
IReadOnlyList<BufferFormat>

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.SupportedPixelFormats

| Edit this page View Source

SupportsBlockCompression

Property to return whether the image codec supports block compression.

Declaration

public override bool SupportsBlockCompression { get; }

Property Value

Type	Description
bool

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.SupportsBlockCompression

| Edit this page View Source

SupportsDepth

Property to return whether the image codec supports a depth component for volume textures.

Declaration

public override bool SupportsDepth { get; }

Property Value

Type	Description
bool

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.SupportsDepth

| Edit this page View Source

SupportsMipMaps

Property to return whether the image codec supports mip maps.

Declaration

public override bool SupportsMipMaps { get; }

Property Value

Type	Description
bool

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.SupportsMipMaps

Methods

| Edit this page View Source

GetCustomEncodingMetadata(int, IGorgonImageInfo)

Function to retrieve custom metadata when encoding an image frame.

Declaration

protected virtual IReadOnlyDictionary<string, object> GetCustomEncodingMetadata(int frameIndex, IGorgonImageInfo settings)

Parameters

Type	Name	Description
int	frameIndex	The index of the frame being encoded.
IGorgonImageInfo	settings	The settings for the image being encoded.

Returns

Type	Description
IReadOnlyDictionary<string, object>	A dictionary containing the key/value pair describing the metadata to write to the frame, or null if the frame contains no metadata.

| Edit this page View Source

GetFrameOffsets(Stream)

Function to retrieve the horizontal and vertical offsets for the frames in a multi-frame image.

Declaration

public IReadOnlyList<Point> GetFrameOffsets(Stream stream)

Parameters

Type	Name	Description
Stream	stream	The stream containing the image data.

Returns

Type	Description
IReadOnlyList<Point>	A list of `Point` values that indicate the offset within the image for each frame.

Remarks

For image codecs that support multiple frames, this reads a list of offset values for each frame so that the frame can be positioned correctly within the base image. If the image does not have multiple frames, or the codec does not support multiple frames, then an empty list is returned.

Exceptions

Type Condition

ArgumentNullException

Thrown when the stream parameter is null.

IOException

Thrown when the stream is write-only.

-or-

Thrown when the stream cannot perform seek operations.

EndOfStreamException

Thrown when an attempt to read beyond the end of the stream is made.

| Edit this page View Source

GetFrameOffsets(string)

Function to retrieve the horizontal and vertical offsets for the frames in a multi-frame image.

Declaration

public IReadOnlyList<Point> GetFrameOffsets(string fileName)

Parameters

Type	Name	Description
string	fileName	The path to the file to retrieve the offsets from.

Returns

Type	Description
IReadOnlyList<Point>	A list of `Point` values that indicate the offset within the image for each frame.

Remarks

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `fileName` parameter is null.
ArgumentEmptyException	Thrown when the `fileName` parameter is empty.
EndOfStreamException	Thrown when an attempt to read beyond the end of the stream is made.

| Edit this page View Source

GetMetaData(Stream)

Function to read the meta data for image data within a stream.

Declaration

public override IGorgonImageInfo GetMetaData(Stream stream)

Parameters

Type	Name	Description
Stream	stream	The stream containing the metadata to read.

Returns

Type	Description
IGorgonImageInfo	The image meta data as a GorgonImageInfo value.

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.GetMetaData(Stream)

Remarks

When overloading this method, the implementor should remember to reset the stream position back to the original position when they are done reading the data. Failure to do so may cause undesirable results.

Exceptions

Type	Condition
IOException	Thrown when the `stream` is write-only or if the stream cannot perform seek operations. -or- Thrown if the file is corrupt or can't be read by the codec.
ArgumentNullException	Thrown when the `stream` parameter is null.
IOException	Thrown when the `stream` is write-only or if the stream cannot perform seek operations.
EndOfStreamException	Thrown when an attempt to read beyond the end of the stream is made.

| Edit this page View Source

GetMetaData(Stream, IGorgonWicDecodingOptions)

Function to read file meta data.

Declaration

public IGorgonImageInfo GetMetaData(Stream stream, IGorgonWicDecodingOptions options)

Parameters

Type	Name	Description
Stream	stream	Stream used to read the meta data.
IGorgonWicDecodingOptions	options	Options used for decoding the meta data.

Returns

Type	Description
IGorgonImageInfo	The image meta data as a GorgonImageInfo value.

Exceptions

Type Condition

ArgumentNullException

Thrown when the stream parameter is null.

IOException

Thrown when the stream is write-only.

-or-

Thrown when the stream cannot perform seek operations.

EndOfStreamException

Thrown when an attempt to read beyond the end of the stream is made.

| Edit this page View Source

IsReadable(Stream)

Function to determine if this codec can read the image data within the stream or not.

Declaration

public override bool IsReadable(Stream stream)

Parameters

Type	Name	Description
Stream	stream	The stream that is used to read the image data.

Returns

Type	Description
bool	true if the codec can read the file, false if not.

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.IsReadable(Stream)

Remarks

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `stream` parameter is null.
IOException	Thrown when the `stream` is write-only or if the stream cannot perform seek operations.

| Edit this page View Source

OnDecodeFromStream(Stream, long)

Function to load an image from a stream.

Declaration

protected override IGorgonImage OnDecodeFromStream(Stream stream, long size)

Parameters

Type	Name	Description
Stream	stream	The stream containing the image data to read.
long	size	The size of the image within the stream, in bytes.

Returns

Type	Description
IGorgonImage	A IGorgonImage containing the image data from the stream.

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.OnDecodeFromStream(Stream, long)

Exceptions

Type	Condition
GorgonException	Thrown when the image data in the stream has a pixel format that is unsupported.

| Edit this page View Source

Save(IGorgonImage, Stream)

Function to persist a IGorgonImage to a stream.

Declaration

public override void Save(IGorgonImage imageData, Stream stream)

Parameters

Type	Name	Description
IGorgonImage	imageData	A IGorgonImage to persist to the stream.
Stream	stream	The stream that will receive the image data.

Overrides

GorgonImageCodec<TWicEncOpt, TWicDecOpt>.Save(IGorgonImage, Stream)

Remarks

When persisting image data via a codec, the image must have a format that the codec can recognize. This list of supported formats is provided by the SupportedPixelFormats property. Applications may convert their image data a supported format before saving the data using a codec.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `stream`, or the `imageData` parameter is null.
ArgumentEmptyException	Thrown when the `stream` is read only.
NotSupportedException	Thrown when the image data in the stream has a pixel format that is unsupported by the codec.

Implements

IGorgonImageCodec

IGorgonNamedObject

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)