Interface IGorgonImageCodec

A codec to reading and/or writing image data.

Inherited Members

Namespace: Gorgon.Graphics.Imaging.Codecs

Assembly: Gorgon.Graphics.Imaging.dll

Syntax

public interface IGorgonImageCodec : IGorgonNamedObject

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 the following 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.

Properties

| Edit this page View Source

CanDecode

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

Declaration

bool CanDecode { get; }

Property Value

Type	Description
bool

Remarks

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

| Edit this page View Source

CanEncode

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

Declaration

bool CanEncode { get; }

Property Value

Type	Description
bool

Remarks

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

| Edit this page View Source

Codec

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

Declaration

string Codec { get; }

Property Value

Type	Description
string

| Edit this page View Source

CodecCommonExtensions

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

Declaration

IReadOnlyList<string> CodecCommonExtensions { get; }

Property Value

Type	Description
IReadOnlyList<string>

| Edit this page View Source

CodecDescription

Property to return the friendly description of the format.

Declaration

string CodecDescription { get; }

Property Value

Type	Description
string

| Edit this page View Source

SupportedPixelFormats

Property to return the pixel formats supported by the codec.

Declaration

IReadOnlyList<BufferFormat> SupportedPixelFormats { get; }

Property Value

Type	Description
IReadOnlyList<BufferFormat>

| Edit this page View Source

SupportsBlockCompression

Property to return whether the image codec supports block compression.

Declaration

bool SupportsBlockCompression { get; }

Property Value

Type	Description
bool

| Edit this page View Source

SupportsDepth

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

Declaration

bool SupportsDepth { get; }

Property Value

Type	Description
bool

| Edit this page View Source

SupportsMipMaps

Property to return whether the image codec supports mip maps.

Declaration

bool SupportsMipMaps { get; }

Property Value

Type	Description
bool

| Edit this page View Source

SupportsMultipleFrames

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

Declaration

bool SupportsMultipleFrames { get; }

Property Value

Type	Description
bool

Methods

| Edit this page View Source

FromFile(string)

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

Declaration

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.

| Edit this page View Source

FromStream(Stream, long?)

Function to load an image from a stream.

Declaration

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.

| Edit this page View Source

GetMetaData(Stream)

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

Declaration

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.

| Edit this page View Source

IsReadable(Stream)

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

Declaration

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

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

LoadFromFile(string)

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

Declaration

[Obsolete("Use FromFile(string) instead.")]
IGorgonImage LoadFromFile(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.

| Edit this page View Source

LoadFromStream(Stream, long?)

Function to load an image from a stream.

Declaration

[Obsolete("Use FromStream(Stream, long?) instead.")]
IGorgonImage LoadFromStream(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.

| Edit this page View Source

Save(IGorgonImage, Stream)

Function to persist a IGorgonImage to a stream.

Declaration

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.

Exceptions

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

| Edit this page View Source

Save(IGorgonImage, string)

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

Declaration

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.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `filePath`, or the `imageData` parameter is null.
ArgumentEmptyException	Thrown when the `filePath` is empty..
GorgonException	Thrown when the image data in the stream has a pixel format that is unsupported.

| Edit this page View Source

SaveToFile(IGorgonImage, string)

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

Declaration

[Obsolete("Use Save(IGorgonImage, string) instead.")]
void SaveToFile(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.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `filePath`, or the `imageData` parameter is null.
ArgumentEmptyException	Thrown when the `filePath` is empty..
GorgonException	Thrown when the image data in the stream has a pixel format that is unsupported.

| Edit this page View Source

SaveToStream(IGorgonImage, Stream)

Function to persist a IGorgonImage to a stream.

Declaration

[Obsolete("Use Save(IGorgonImage, string) instead.")]
void SaveToStream(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.

Exceptions

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

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)