Interface IGorgonImageBuffer

An image buffer containing data about a part of a IGorgonImage.

Namespace: Gorgon.Graphics.Imaging

Assembly: Gorgon.Graphics.Imaging.dll

Syntax

public interface IGorgonImageBuffer

Properties

ArrayIndex

Property to return the array this buffer represents.

Declaration

int ArrayIndex { get; }

Property Value

Type	Description
int

Remarks

For 3D images, this will always be 0.

Data

Property to return the native memory buffer holding the data for this image buffer.

Declaration

GorgonPtr<byte> Data { get; }

Property Value

Type	Description
GorgonPtr<byte>

Depth

Property to return the total depth for the IGorgonImage that this buffer is associated with.

Declaration

int Depth { get; }

Property Value

Type	Description
int

Remarks

This is only valid for 3D images.

DepthSliceIndex

Property to return the depth slice index.

Declaration

int DepthSliceIndex { get; }

Property Value

Type	Description
int

Remarks

For 1D or 2D images, this will always be 0.

Format

Property to return the format of the buffer.

Declaration

BufferFormat Format { get; }

Property Value

Type	Description
BufferFormat

FormatInformation

Property to return the format information for the buffer.

Declaration

GorgonFormatInfo FormatInformation { get; }

Property Value

Type	Description
GorgonFormatInfo

Height

Property to return the height for the current buffer.

Declaration

int Height { get; }

Property Value

Type	Description
int

Remarks

This is only valid for 2D and 3D images.

MipLevel

Property to return the mip map level this buffer represents.

Declaration

int MipLevel { get; }

Property Value

Type	Description
int

PitchInformation

Property to return information about the pitch of the data for this buffer.

Declaration

GorgonPitchLayout PitchInformation { get; }

Property Value

Type	Description
GorgonPitchLayout

Width

Property to return the width for the current buffer.

Declaration

int Width { get; }

Property Value

Type	Description
int

Methods

CopyTo(IGorgonImageBuffer, in Rectangle?, int, int)

Function to copy the image buffer data from this buffer into another.

Declaration

void CopyTo(IGorgonImageBuffer buffer, in Rectangle? sourceRegion = null, int destX = 0, int destY = 0)

Parameters

Type	Name	Description
IGorgonImageBuffer	buffer	The buffer to copy into.
Rectangle?	sourceRegion	[Optional] The region in the source to copy.
int	destX	[Optional] Horizontal offset in the destination buffer.
int	destY	[Optional] Vertical offset in the destination buffer.

Remarks

This method will copy the contents of this buffer into another buffer and will provide clipping to handle cases where the buffer or sourceRegion is mismatched with the destination size. If this buffer, and the buffer passed to buffer share the same pointer address, then this method will return immediately without making any changes.

Users may define an area on this buffer to copy by specifying the sourceRegion parameter. If null is passed to this parameter, then the entire buffer will be copied to the destination.

An offset into the destination buffer may also be specified to relocate the data copied from this buffer into the destination. Clipping will be applied if the offset pushes the source data outside of the boundaries of the destination buffer.

The destination buffer must be the same format as the source buffer. If it is not, then an exception will be thrown.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the buffer parameter is null.
ArgumentException	Thrown when the buffer is not the same format as this buffer.
ArgumentOutOfRangeException	Thrown when the source region does not fit within the bounds of this buffer.

Fill(byte)

Function to fill the entire buffer with the specified byte value.

Declaration

void Fill(byte value)

Parameters

Type	Name	Description
byte	value	The byte value used to fill the buffer.

GetRegion(in Rectangle)

Function to create a sub region from the current image data contained within this buffer.

Declaration

IGorgonImageBuffer GetRegion(in Rectangle clipRegion)

Parameters

Type	Name	Description
Rectangle	clipRegion	The region of the buffer to clip.

Returns

Type	Description
IGorgonImageBuffer	A new IGorgonImageBuffer containing the sub region of this buffer, or null if the clipped region is empty.

Remarks

This method is used to create a smaller sub region from the current buffer based on the clipRegion specified. This region value is clipped to the size of the buffer.

The resulting image buffer that is returned will share the same memory as the parent buffer (which, in turn, shares its buffer with the IGorgonImage it's created from). Because of this, the Format, MipLevel, ArrayIndex, DepthSliceIndex and the Depth will the be same as the buffer it was created from.

Because this buffer references a subsection of the same memory as the parent buffer, care must be taken when accessing the memory directly. Even though the GorgonNativeBuffer<T> object takes precautions to avoid out of bounds reads/writes on memory, it cannot address memory in a rectangular region like that of an image. If a write that extends beyond the width of the buffer occurs, it will appear on the parent buffer, but may not appear on the resulting buffer. To handle accessing memory properly, use of the values in PitchInformation is required so that data will be read and written within the region defined by the resulting buffer.

If the width and/or height of the clip region is 0, then the image is empty and this method will return null.

Please note that the returned buffer will not be appended to the list of Buffers in the IGorgonImage.

See Also

IGorgonImage

SetAlpha(float, GorgonRangeF?, Rectangle?)

Function to set the alpha channel for a specific buffer in the image.

Declaration

void SetAlpha(float alphaValue, GorgonRangeF? updateAlphaRange = null, Rectangle? region = null)

Parameters

Type	Name	Description
float	alphaValue	The value to set.
GorgonRangeF?	updateAlphaRange	[Optional] The range of alpha values in the buffer that will be updated.
Rectangle?	region	[Optional] The region in the buffer to update.

Remarks

This will set the alpha channel for the image data in the buffer> to a discrete value specified by alphaValue.

If the updateAlphaRange parameter is set, then the alpha values in the buffer will be examined and if the alpha value is less than the minimum range or greater than the maximum range, then the alphaValue will not be set on the alpha channel.

If the region is not specified, then the entire buffer is updated, otherwise only the values within the region are updated.

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GdiPlusExtensions.CopyTo(IGorgonImageBuffer, Bitmap)

GdiPlusExtensions.ToBitmap(IGorgonImageBuffer)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)