Class GorgonImage

Holds raw data that is used to represent an image.

Inheritance

object

GorgonImage

Implements

IGorgonImage

IDisposable

IGorgonCloneable<IGorgonImage>

IGorgonImageInfo

IGorgonImageUpdateFluent

IGorgonImageUpdateFinalize

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.Graphics.Imaging

Assembly: Gorgon.Graphics.Imaging.dll

Syntax

public class GorgonImage : IGorgonImage, IDisposable, IGorgonCloneable<IGorgonImage>, IGorgonImageInfo, IGorgonImageUpdateFluent, IGorgonImageUpdateFinalize

Remarks

The GorgonImage object will hold a blob of data in native (unmanaged) memory 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.

Constructors

GorgonImage(GorgonImageInfo, ReadOnlySpan<byte>)

Initializes a new instance of the GorgonImage class.

Declaration

public GorgonImage(GorgonImageInfo info, ReadOnlySpan<byte> data = default)

Parameters

Type	Name	Description
GorgonImageInfo	info	A IGorgonImageInfo containing information used to create the image.
ReadOnlySpan<byte>	data	[Optional] A read only span of byte data that points to a blob of existing image data.

Remarks

If the data parameter is omitted, then a new, empty, image will be created, otherwise the data within the span will be copied into this image. The data passed to this image must be large enough to accomodate the size of the image described by info, otherwise an exception will be thrown. To determine how large the image size will be, in bytes, use the static CalculateSizeInBytes(IGorgonImageInfo, PitchFlags) method to determine the potential size of an image prior to creation.

important

The data, if not omitted, is copied, not wrapped. This ensures that the lifetime of the data passed in remains the responsibility of the caller and does not affect the image object integrity.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the info parameter is null.
GorgonException	Thrown when the image format is unknown or is unsupported.

GorgonImage(IGorgonImage)

Initializes a new instance of the GorgonImage class.

Declaration

public GorgonImage(IGorgonImage source)

Parameters

Type	Name	Description
IGorgonImage	source	The source image to copy.

Remarks

This is a copy constructor for an image object. The new object will contain a duplicate of all data provided by the source.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the source parameter is null.

Properties

ArrayCount

Property to return the total number of images there are in an image array.

Declaration

public int ArrayCount { get; }

Property Value

Type	Description
int

Remarks

This only applies to 1D and 2D images. This parameter will be set to a value of 1 for a 3D image.

Buffers

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

Declaration

public IGorgonImageBufferList Buffers { get; }

Property Value

Type	Description
IGorgonImageBufferList

Depth

Property to return the depth of an image, in pixels.

Declaration

public int Depth { get; }

Property Value

Type	Description
int

Remarks

This applies to 3D images only. This parameter will be set to a value of 1 for a 1D or 2D image.

Format

Property to return the pixel format for an image.

Declaration

public BufferFormat Format { get; }

Property Value

Type	Description
BufferFormat

FormatInfo

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

Declaration

public GorgonFormatInfo FormatInfo { get; }

Property Value

Type	Description
GorgonFormatInfo

HasPreMultipliedAlpha

Property to return whether the image data is using premultiplied alpha.

Declaration

public bool HasPreMultipliedAlpha { get; }

Property Value

Type	Description
bool

Remarks

Premultiplied alpha is used to display correct alpha blending. This flag indicates that the data in the image has already been transformed to use premultiplied alpha.

For more information see: Shawn Hargreaves Blog

Height

Property to return the height of an image, in pixels.

Declaration

public int Height { get; }

Property Value

Type	Description
int

Remarks

This applies to 2D and 3D images only. This parameter will be set to a value of 1 for a 1D image.

ImageData

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

Declaration

public GorgonPtr<byte> ImageData { get; }

Property Value

Type	Description
GorgonPtr<byte>

ImageType

Property to return the type of image data.

Declaration

public ImageType ImageType { get; }

Property Value

Type	Description
ImageType

IsPowerOfTwo

Property to return whether the size of the texture is a power of 2 or not.

Declaration

public bool IsPowerOfTwo { get; }

Property Value

Type	Description
bool

MipCount

Property to return the number of mip map levels in the image.

Declaration

public int MipCount { get; }

Property Value

Type	Description
int

SizeInBytes

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

Declaration

public int SizeInBytes { get; }

Property Value

Type	Description
int

Width

Property to return the width of an image, in pixels.

Declaration

public int Width { get; }

Property Value

Type	Description
int

Methods

BeginUpdate()

Function to begin updating the image.

Declaration

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

OTHER STUFF TO BE DONE HERE.

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.

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.

Exceptions

Type	Condition
NotSupportedException	Thrown if the image cannot be updated because of its format.
InvalidOperationException	Thrown if the image is already being edited.

See Also

EndUpdate(bool)

CalculateDepthSliceCount(int, int)

Function to return the number of depth slices for a 3D image with the given number of mip maps.

Declaration

public static int CalculateDepthSliceCount(int maximumSlices, int mipCount)

Parameters

Type	Name	Description
int	maximumSlices	The maximum desired number of depth slices to return.
int	mipCount	The number of mip maps to use.

Returns

Type	Description
int	The actual number of depth slices.

CalculateMaxMipCount(IGorgonImageInfo)

Function to return the maximum number of mip levels supported given the specified settings.

Declaration

public static int CalculateMaxMipCount(IGorgonImageInfo info)

Parameters

Type	Name	Description
IGorgonImageInfo	info	The IGorgonImageInfo used to describe the image.

Returns

Type	Description
int	The number of possible mip-map levels in the image.

CalculateMaxMipCount(int, int, int)

Function to return the maximum number of mip levels supported in for an image.

Declaration

public static int CalculateMaxMipCount(int width, int height, int depth)

Parameters

Type	Name	Description
int	width	Width of the proposed image.
int	height	Height of the proposed image.
int	depth	Depth of the proposed image.

Returns

Type	Description
int	The number of possible mip-map levels in the image.

CalculateSizeInBytes(IGorgonImageInfo, PitchFlags)

Function to return the size, in bytes, of an image with the given IGorgonImageInfo.

Declaration

public static int CalculateSizeInBytes(IGorgonImageInfo info, PitchFlags pitchFlags = PitchFlags.None)

Parameters

Type	Name	Description
IGorgonImageInfo	info	The IGorgonImageInfo used to describe the image.
PitchFlags	pitchFlags	[Optional] Flags to influence the size of the row pitch.

Returns

Type	Description
int	The number of bytes for the image.

Remarks

The pitchFlags parameter is used to compensate in cases where the original image data is not laid out correctly (such as with older DirectDraw DDS images).

Exceptions

Type	Condition
ArgumentException	Thrown when the format value of the info parameter is not supported.

CalculateSizeInBytes(ImageType, int, int, int, BufferFormat, int, PitchFlags)

Function to return the size of an image in bytes.

Declaration

public static int CalculateSizeInBytes(ImageType imageType, int width, int height, int arrayCountOrDepth, BufferFormat format, int mipCount = 1, PitchFlags pitchFlags = PitchFlags.None)

Parameters

Type	Name	Description
ImageType	imageType	The type of image.
int	width	Width of the image.
int	height	Height of the image.
int	arrayCountOrDepth	The number of array indices for Image1D or Image2D images, or the number of depth slices for a Image3D.
BufferFormat	format	Format of the image.
int	mipCount	[Optional] Number of mip-map levels in the image.
PitchFlags	pitchFlags	[Optional] Flags used to influence the row pitch of the image.

Returns

Type	Description
int	The number of bytes for the image.

Remarks

The pitchFlags parameter is used to compensate in cases where the original image data is not laid out correctly (such as with older DirectDraw DDS images).

Exceptions

Type	Condition
GorgonException	Thrown when the format is not supported.

CanConvertToFormat(BufferFormat)

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

Declaration

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

CanConvertToFormats(IReadOnlyList<BufferFormat>)

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

Declaration

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

Clone()

Function to make a clone of this image.

Declaration

public IGorgonImage Clone()

Returns

Type	Description
IGorgonImage	A new IGorgonImage that contains an identical copy of this image and its data.

Copy(IGorgonImage)

Function to copy an image into this image.

Declaration

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

Exceptions

Type	Condition
ArgumentNullException	Thrown when the image parameter is null.

See Also

IGorgonImageBuffer

Decompress(bool)

Function to decompress an image containing block compressed data.

Declaration

public IGorgonImageUpdateFluent Decompress(bool useBC1Alpha)

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 image with decompressed image data.

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.

Exceptions

Type	Condition
NotSupportedException	Thrown if the image data is not block compressed, or contains typeless data.
InvalidOperationException	Thrown if the image is already being edited.

See Also

Compress(BufferFormat, bool, BcCompressionQuality, bool)

BeginUpdate()

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

GetDepthCount(int)

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

Declaration

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

Implements

IGorgonImage

IDisposable

IGorgonCloneable<T>

IGorgonImageInfo

IGorgonImageUpdateFluent

IGorgonImageUpdateFinalize

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonImageTextureExtensions.ToTexture1D(IGorgonImage, GorgonGraphics, GorgonTextureLoadOptions)

GorgonImageTextureExtensions.ToTexture1DView(IGorgonImage, GorgonGraphics, GorgonTextureLoadOptions)

GorgonImageTextureExtensions.ToTexture2D(IGorgonImage, GorgonGraphics, GorgonTexture2DLoadOptions)

GorgonImageTextureExtensions.ToTexture2DView(IGorgonImage, GorgonGraphics, GorgonTexture2DLoadOptions)

GorgonImageTextureExtensions.ToTexture3D(IGorgonImage, GorgonGraphics, GorgonTextureLoadOptions)

GorgonImageTextureExtensions.ToTexture3DView(IGorgonImage, GorgonGraphics, GorgonTextureLoadOptions)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)