Interface IGorgonImage

Holds raw data that is used to represent an image.

Inherited Members
Namespace: Gorgon.Graphics.Imaging
Assembly: Gorgon.Graphics.Imaging.dll
Syntax
public interface IGorgonImage : IDisposable, IGorgonCloneable<IGorgonImage>, IGorgonImageInfo
Remarks

The GorgonImage object will hold a blob of data and represent that data as a series of pixels to be displayed, or manipulated. This image type is capable of representing standard 2D images, but can also represent 1D and 3D images. And, depending on the type of image, there is also support for mip map levels, and arrayed images.

Images can access their data directly through a GorgonNativeBuffer<T> interface that allows safe access to raw, unmanaged memory where the image data is stored. In cases where images have multiple parts like depth slices for a 3D image, or an array for 2D images, this object will provide access through a series of buffers that will point to the individual locations for depth slices, array indices, and mip map levels. These buffers will also provide their own GorgonNativeBuffer<T> that will allow safe and direct access to the native memory where the buffer is located.

Because this object stored data in native memory instead of on the heaps provided by .NET, this object should be disposed by calling its Dispose() method when it is no longer required. Failure to do so might cause a memory leak until the garbage collector can deal with it.

Properties

| Edit this page View Source

Buffers

Property to return the list of image buffers for this image.

Declaration
IGorgonImageBufferList Buffers { get; }
Property Value
Type Description
IGorgonImageBufferList
| Edit this page View Source

FormatInfo

Property to return information about the pixel format for this image.

Declaration
GorgonFormatInfo FormatInfo { get; }
Property Value
Type Description
GorgonFormatInfo
| Edit this page View Source

ImageData

Property to return the pointer to the beginning of the internal buffer.

Declaration
GorgonPtr<byte> ImageData { get; }
Property Value
Type Description
GorgonPtr<byte>
| Edit this page View Source

SizeInBytes

Property to return the number of bytes, in total, that this image occupies.

Declaration
int SizeInBytes { get; }
Property Value
Type Description
int

Methods

| Edit this page View Source

BeginUpdate()

Function to begin updating the image.

Declaration
IGorgonImageUpdateFluent BeginUpdate()
Returns
Type Description
IGorgonImageUpdateFluent

The fluent interface for editing the image.
Remarks

This begins an update to the current image instance by returning a fluent interface (IGorgonImageUpdateFluent) that will provide operations that can be performed on the image in place.

If the image data is compressed using block compression, this method will throw an exception. Check the FormatInfo property to determine if the image has block compressed image data. If the image data is block compressed, call the Decompress(bool) method instead.

Once done updating the image, call the EndUpdate(bool) method to apply or cancel the changes to the image data. This method must be called if BeginUpdate is to be called again. Calling BeginUpdate more than once without calling EndUpdate(bool) will throw an exception.

See Also
| Edit this page View Source

CanConvertToFormat(BufferFormat)

Function to determine if the pixel format for this image can be converted to another pixel format.

Declaration
bool CanConvertToFormat(BufferFormat format)
Parameters
Type Name Description
BufferFormat format

The pixel format to convert to.
Returns
Type Description
bool

true if the the current pixel format and the requested pixel format can be converted, false if not.
| Edit this page View Source

CanConvertToFormats(IReadOnlyList<BufferFormat>)

Function to determine if the source format can convert to any of the formats in the destination list.

Declaration
IReadOnlyList<BufferFormat> CanConvertToFormats(IReadOnlyList<BufferFormat> destFormats)
Parameters
Type Name Description
IReadOnlyList<BufferFormat> destFormats

List of destination formats to compare.
Returns
Type Description
IReadOnlyList<BufferFormat>

A list of formats that the source format can be converted into, or an empty array if no conversion is possible.
| Edit this page View Source

Copy(IGorgonImage)

Function to copy an image into this image.

Declaration
void Copy(IGorgonImage image)
Parameters
Type Name Description
IGorgonImage image

The image that will copied into this image.
Remarks

This will clone the image into this image. All information in the current image will be discarded and replaced with a duplicate of the data present in the source image. If copying parts of an image into a new image is required, then see the IGorgonImageBuffer.CopyTo(IGorgonImageBuffer, in Rectangle?, int, int) method.

| Edit this page View Source

Decompress(bool)

Function to decompress an image containing block compressed data.

Declaration
IGorgonImageUpdateFluent Decompress(bool useBC1Alpha = false)
Parameters
Type Name Description
bool useBC1Alpha

[Optional] true if the image is compressed with BC1 (DXT1) compression, and the contains alpha, false if no alpha is in the image.
Returns
Type Description
IGorgonImageUpdateFluent

The fluent interface for modifying the image.
Remarks

This method will decompress an image containing image data that has been compressed with one of the standard block compression formats. The BufferFormat enum contains 7 levels of block compression named BC1 - BC7. The features of each compression level are documented at .

The decompressed image data will result in 32 bit RGBA data in the format of R8G8B8A8_UNorm.

Block compression is, by nature, a lossy compression format. Thus some fidelity will be lost when the image data is compressed, it is recommended that images be compressed as a last stage in processing. Because block compression lays the image data out differently than standard image data, the functionality provided for modifying an image (e.g. Resize(int, int, int?, ImageFilter)) will not work and will throw an exception if used on block compressed data, this method will allow users to make alterations with the image modification functionality.

warning

Because block compressed data is lossy, it is not recommended that images be decompressed and compressed over and over as it will degrade the image fidelity severely.

If the image data was compressed with BC1 compression, optional 1-bit alpha channel data may be stored with the image data. The developer must specify whether to use the alpha data or not via the useBC1Alpha parameter.

This method returns the IGorgonImageUpdateFluent interface to allow users to modify the image modification after decompression. This means that this method calls BeginUpdate() implicitly after execution.

See Also
| Edit this page View Source

GetDepthCount(int)

Function to return the number of depth slices for a given mip map slice.

Declaration
int GetDepthCount(int mipLevel)
Parameters
Type Name Description
int mipLevel

The mip map level to look up.
Returns
Type Description
int

The number of depth slices for the given mip map level.
Remarks

For 1D and 2D images, the mip level will always return 1.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown when the mipLevel parameter exceeds the number of mip maps for the image or is less than 0.

Extension Methods