Class GorgonImageCodec<TEncOpt, TDecOpt>

A codec to reading and/or writing image data.

Inheritance

object

GorgonImageCodec<TEncOpt, TDecOpt>

GorgonCodecDds

GorgonCodecTga

GorgonCodecWic<TWicEncOpt, TWicDecOpt>

Implements

IGorgonImageCodec

IGorgonNamedObject

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.Graphics.Imaging.Codecs

Assembly: Gorgon.Graphics.Imaging.dll

Syntax

public abstract class GorgonImageCodec<TEncOpt, TDecOpt> : IGorgonImageCodec, IGorgonNamedObject where TEncOpt : class, IGorgonImageCodecEncodingOptions where TDecOpt : class, IGorgonImageCodecDecodingOptions

Type Parameters

Name	Description
TEncOpt	The type of the options object used to provide options when encoding an image. Must be a reference type and implement IGorgonImageCodecEncodingOptions.
TDecOpt	The type of the options object used to provide options when decoding an image. Must be a reference type and implement IGorgonImageCodecDecodingOptions.

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.

Currently, Gorgon supports the following codecs:

Format	File extension(s)	Read?	Write?	Limitations	Features
Jpeg	*.jpg; *.jpeg; *.jpe; *.jif; *.jfif; *.jfi	Yes	Yes	Only supports the first array index in an image array, the first mip slice in a mip map, and the first depth slice in a 3D image.	None
Png	*.png	Yes	Yes	Only supports the first array index in an image array, the first mip slice in a mip map, and the first depth slice in a 3D image.	None
Bmp	*.bmp; *.dib	Yes	Yes	24 bit only Only supports the first array index in an image array, the first mip slice in a mip map, and the first depth slice in a 3D image.	None
Gif	*.gif; *.dib	Yes	Yes	8 bit paletted images only. Color quantinization will reduce image quality. Only supports the first array index in an image array (for non-animated images), the first mip slice in a mip map, and the first depth slice in a 3D image.	Supports reading of animated gif files as an array of images.
Tga	*.tga; *.tpic	Yes	Yes	No color map support. Interleaved files are not supported. Only supports 8 bit grayscale, 16, 24 and 32 bit image formats. Can only write uncompressed image data. Only supports the first array index in an image array, the first mip slice in a mip map, and the first depth slice in a 3D image.	Can read RLE compressed and uncompressed formats.
Dds	*.dds	Yes	Yes	No support for typless formats or the following legacy Direct 3D 9 image formats: BumpDuDv D3DFMT_V8U8 D3DFMT_Q8W8V8U8 D3DFMT_V16U16 D3DFMT_A2W10V10U10 BumpLuminance D3DFMT_L6V5U5 D3DFMT_X8L8V8U8 FourCC "UYVY" D3DFMT_UYVY FourCC "YUY2" D3DFMT_YUY2 FourCC 117 D3DFMT_CxV8U8 ZBuffer D3DFMT_D16_LOCKABLE FourCC 82 D3DFMT_D32F_LOCKABLE No support for writing block compressed formats (BC1-BC7).	Supports the full array of image options like arrays, mip maps, 3D images and all Direct 3D 11 pixel formats.

While many of the image formats supplied will be useful out of the box, the system can read/write images via a GorgonImageCodecPlugIn if the supplied formats are too limited or do not support a necessary feature.

Constructors

GorgonImageCodec(TEncOpt, TDecOpt)

Initializes a new instance of the GorgonImageCodec<TEncOpt, TDecOpt> class.

Declaration

protected GorgonImageCodec(TEncOpt encodingOptions, TDecOpt decodingOptions)

Parameters

Type	Name	Description
TEncOpt	encodingOptions	Codec specific options to use when encoding image data.
TDecOpt	decodingOptions	Codec specific options to use when decoding image data.

Properties

CanDecode

Property to return whether the codec supports decoding of image data.

Declaration

public virtual bool CanDecode { get; }

Property Value

Type	Description
bool

Remarks

If this value is false, then the codec is effectively write only.

CanEncode

Property to return whether the codec supports encoding of image data.

Declaration

public virtual bool CanEncode { get; }

Property Value

Type	Description
bool

Remarks

If this value is false, then the codec is effectively read only.

Codec

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

Declaration

public abstract string Codec { get; }

Property Value

Type	Description
string

CodecCommonExtensions

Property to return the common file name extension(s) for a codec.

Declaration

public IReadOnlyList<string> CodecCommonExtensions { get; protected set; }

Property Value

Type	Description
IReadOnlyList<string>

CodecDescription

Property to return the friendly description of the format.

Declaration

public abstract string CodecDescription { get; }

Property Value

Type	Description
string

DecodingOptions

Property to return the decoding options for the codec.

Declaration

protected TDecOpt DecodingOptions { get; }

Property Value

Type	Description
TDecOpt

EncodingOptions

Property to return the encoding options for the codec.

Declaration

protected TEncOpt EncodingOptions { get; }

Property Value

Type	Description
TEncOpt

SupportedPixelFormats

Property to return the pixel formats supported by the codec.

Declaration

public abstract IReadOnlyList<BufferFormat> SupportedPixelFormats { get; }

Property Value

Type	Description
IReadOnlyList<BufferFormat>

SupportsBlockCompression

Property to return whether the image codec supports block compression.

Declaration

public abstract bool SupportsBlockCompression { get; }

Property Value

Type	Description
bool

SupportsDepth

Property to return whether the image codec supports a depth component for volume (3D) images.

Declaration

public abstract bool SupportsDepth { get; }

Property Value

Type	Description
bool

SupportsMipMaps

Property to return whether the image codec supports mip maps.

Declaration

public abstract bool SupportsMipMaps { get; }

Property Value

Type	Description
bool

SupportsMultipleFrames

Property to return whether the codec supports decoding/encoding multiple frames or not.

Declaration

public virtual bool SupportsMultipleFrames { get; }

Property Value

Type	Description
bool

Methods

FromFile(string)

Function to load an image from a file on the physical file system.

Declaration

public IGorgonImage FromFile(string filePath)

Parameters

Type	Name	Description
string	filePath	Path to the file to load.

Returns

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

Exceptions

Type	Condition
ArgumentNullException	Thrown when the filePath parameter is null.
ArgumentEmptyException	Thrown when the filePath parameter is empty.
ArgumentOutOfRangeException	Thrown when the size of the file is less than 1 byte.
GorgonException	Thrown when the image data in the file has a pixel format that is unsupported.

FromStream(Stream, long?)

Function to load an image from a stream.

Declaration

public IGorgonImage FromStream(Stream stream, long? size = null)

Parameters

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

Returns

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

Remarks

When the size parameter is specified, the image data will be read from the stream up to the amount specified. If it is omitted, then image data will be read up to the end of the stream.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.
ArgumentEmptyException	Thrown when the stream is write only.
ArgumentOutOfRangeException	Thrown when the size parameter is less than 1.
EndOfStreamException	Thrown when the amount of data requested exceeds the size of the stream minus its current position.
GorgonException	Thrown when the image data in the stream has a pixel format that is unsupported.

GetMetaData(Stream)

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

Declaration

public abstract 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 IGorgonImageInfo value.

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.

IsReadable(Stream)

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

Declaration

public abstract 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.

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 or an exception.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the stream parameter is null.
IOException	Thrown when the stream is write-only, or non-seekable.

OnDecodeFromStream(Stream, long)

Function to decode an image from a stream.

Declaration

protected abstract 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.

Remarks

A codec must implement this method in order to decode the image data.

Exceptions

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

Save(IGorgonImage, Stream)

Function to persist a IGorgonImage to a stream.

Declaration

public abstract 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.

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.

Save(IGorgonImage, string)

Function to persist a IGorgonImage to a file on the physical file system.

Declaration

public void Save(IGorgonImage imageData, string filePath)

Parameters

Type	Name	Description
IGorgonImage	imageData	A IGorgonImage to persist to the stream.
string	filePath	The path to the file that will hold the image data.

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 filePath, or the imageData parameter is null.
ArgumentEmptyException	Thrown when the filePath is empty..
NotSupportedException	Thrown when the image data in the stream has a pixel format that is unsupported by the codec.

ToString()

Returns a string that represents this instance.

Declaration

public override string ToString()

Returns

Type	Description
string	A string that represents this instance.

Overrides

object.ToString()

Implements

IGorgonImageCodec

IGorgonNamedObject

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)