Class GorgonTexture2D

public sealed class GorgonTexture2D : GorgonGraphicsResource, IGorgonTexture2DInfo, IGorgonTextureResource, IGorgonNamedObject, IGorgonGraphicsObject, IGorgonImageInfo, IDisposable, IGorgonSharedResource, IGorgonNativeResource

Constructors

| Edit this page View Source

GorgonTexture2D(GorgonGraphics, GorgonTexture2DInfo)

Initializes a new instance of the GorgonTexture2D class.

Declaration

public GorgonTexture2D(GorgonGraphics graphics, GorgonTexture2DInfo textureInfo)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The GorgonGraphics interface that created this texture.
GorgonTexture2DInfo	textureInfo	A IGorgonTexture2DInfo object describing the properties of this texture.

Remarks

This constructor creates an empty texture. Data may be uploaded to the texture at a later time if its Usage is not set to Immutable. If the Usage is set to Immutable with this constructor, then an exception will be thrown. To use an immutable texture, use the ToTexture2D(IGorgonImage, GorgonGraphics, GorgonTexture2DLoadOptions) extension method on the IGorgonImage type.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `graphics`, or the `textureInfo` parameter is null.
ArgumentException	Thrown when the Usage is set to `Immutable`.
GorgonException	Thrown when the texture could not be created due to misconfiguration.

| Edit this page View Source

GorgonTexture2D(GorgonGraphics, IGorgonImage, GorgonTexture2DLoadOptions)

Initializes a new instance of the GorgonTexture2D class.

Declaration

public GorgonTexture2D(GorgonGraphics graphics, IGorgonImage image, GorgonTexture2DLoadOptions options = null)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface used to create this texture.
IGorgonImage	image	The image to copy into the texture.
GorgonTexture2DLoadOptions	options	[Optional] The options to use when loading the texture.

Remarks

This constructor is used when converting an image to a texture.

Properties

| Edit this page View Source

ArrayCount

Property to return the number of array levels for a texture.

Declaration

public int ArrayCount { get; }

Property Value

Type	Description
int

Remarks

For textures with a IsCubeMap set to true, this this value will return a multiple of 6.

| Edit this page View Source

Binding

Property to return the flags to determine how the texture will be bound with the pipeline when rendering.

Declaration

public TextureBinding Binding { get; }

Property Value

Type	Description
TextureBinding

Remarks

If the Usage property is set to Staging, then the texture binding will a value of None as staging textures do not support bindings of any kind.

| Edit this page View Source

Format

Property to return the format of the texture.

Declaration

public BufferFormat Format { get; }

Property Value

Type	Description
BufferFormat

| Edit this page View Source

FormatInformation

Property to return the information about the format of the texture.

Declaration

public GorgonFormatInfo FormatInformation { get; }

Property Value

Type	Description
GorgonFormatInfo

| Edit this page View Source

Height

Property to return the height of the texture, in pixels.

Declaration

public int Height { get; }

Property Value

Type	Description
int

| Edit this page View Source

IsCubeMap

Property to return whether this 2D texture is a cube map.

Declaration

public bool IsCubeMap { get; }

Property Value

Type	Description
bool

Remarks

When this value returns true, then the texture is defined as a cube map using the ArrayCount as the number of faces. Because of this, the ArrayCount value will be a multiple of 6.

| Edit this page View Source

MipLevels

Property to return the number of mip-map levels for the texture.

Declaration

public int MipLevels { get; }

Property Value

Type	Description
int

Remarks

If the texture is multisampled, this value will return 1.

| Edit this page View Source

MultisampleInfo

Property to return the multisample quality and count for this texture.

Declaration

public GorgonMultisampleInfo MultisampleInfo { get; }

Property Value

Type	Description
GorgonMultisampleInfo

| Edit this page View Source

Name

Property to return the name of this object.

Declaration

public override string Name { get; }

Property Value

Type	Description
string

Overrides

GorgonGraphicsResource.Name

| Edit this page View Source

ResourceType

Property to return the type of data in the resource.

Declaration

public override GraphicsResourceType ResourceType { get; }

Property Value

Type	Description
GraphicsResourceType

Overrides

GorgonGraphicsResource.ResourceType

| Edit this page View Source

Shared

Property to return whether this texture can be shared with other graphics interfaces.

Declaration

public TextureSharingOptions Shared { get; }

Property Value

Type	Description
TextureSharingOptions

Remarks

Settings this flag to true allows the texture to be used with external graphics interfaces such as a Direct3D device. This is useful for providing interoperation between systems.

| Edit this page View Source

SizeInBytes

Property to return the size, in bytes, of the resource.

Declaration

public override int SizeInBytes { get; }

Property Value

Type	Description
int

Overrides

GorgonGraphicsResource.SizeInBytes

| Edit this page View Source

TextureID

Property to return the ID for this texture.

Declaration

public int TextureID { get; }

Property Value

Type	Description
int

| Edit this page View Source

Usage

Property to return the usage for the resource.

Declaration

public override ResourceUsage Usage { get; }

Property Value

Type	Description
ResourceUsage

Overrides

GorgonGraphicsResource.Usage

| Edit this page View Source

Width

Property to return the width of the texture, in pixels.

Declaration

public int Width { get; }

Property Value

Type	Description
int

Methods

| Edit this page View Source

CalculateSizeInBytes(IGorgonTexture2DInfo)

Function to calculate the size of a texture, in bytes with the given parameters.

Declaration

public static int CalculateSizeInBytes(IGorgonTexture2DInfo info)

Parameters

Type	Name	Description
IGorgonTexture2DInfo	info	The IGorgonTexture2DInfo used to define a texture.

Returns

Type	Description
int	The number of bytes for the texture.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `info` parameter is null.

| Edit this page View Source

CalculateSizeInBytes(int, int, int, BufferFormat, int, bool)

Function to calculate the size of a texture, in bytes with the given parameters.

Declaration

public static int CalculateSizeInBytes(int width, int height, int arrayCount, BufferFormat format, int mipCount, bool isCubeMap)

Parameters

Type	Name	Description
int	width	The width of the texture.
int	height	The height of the texture.
int	arrayCount	The number of array indices.
BufferFormat	format	The format for the texture.
int	mipCount	The number of mip map levels.
bool	isCubeMap	true if the texture is meant to be used as a cube map, or false if not.

Returns

Type	Description
int	The number of bytes for the texture.

| Edit this page View Source

CopyTo(GorgonTexture1D, GorgonRange?, int, int, int, int, int, int, CopyMode)

Function to copy this texture into a GorgonTexture1D.

Declaration

public void CopyTo(GorgonTexture1D destinationTexture, GorgonRange? sourceRange = null, int sourceY = 0, int sourceArrayIndex = 0, int sourceMipLevel = 0, int destX = 0, int destArrayIndex = 0, int destMipLevel = 0, CopyMode copyMode = CopyMode.None)

Parameters

Type	Name	Description
GorgonTexture1D	destinationTexture	The texture to copy into.
GorgonRange?	sourceRange	[Optional] The dimensions of the source area to copy.
int	sourceY	[Optional] The vertical position in the texture to copy.
int	sourceArrayIndex	[Optional] The array index of the sub resource to copy.
int	sourceMipLevel	[Optional] The mip map level of the sub resource to copy.
int	destX	[Optional] Horizontal offset into the destination texture to place the copied data.
int	destArrayIndex	[Optional] The array index of the destination sub resource to copy into.
int	destMipLevel	[Optional] The mip map level of the destination sub resource to copy into.
CopyMode	copyMode	[Optional] Defines how data should be copied into the texture.

Remarks

Use this method to copy a specific sub resource of this GorgonTexture2D to another sub resource of a GorgonTexture1D. The sourceRange coordinates must be inside of the destination, if it is not, then the source data will be clipped against the destination region. No stretching or filtering is supported by this method.

Limited format conversion will be performed if the two textures are within the same bit group (e.g. R8G8B8A8_SInt is convertible to R8G8B8A8_UNorm and so on, since they are both R8G8B8A8). If the bit group does not match, then an exception will be thrown.

When copying sub resources (e.g. mip levels, array indices, etc...), the mip levels and array indices must be different if copying to the same texture. If they are not, an exception will be thrown.

The destination texture must not have a Usage of Immutable.

The copyMode flag defines how data will be copied into this texture. See the CopyMode enumeration for a description of the values.

caution

For performance reasons, any exceptions thrown from this method will only be thrown when Gorgon is compiled as DEBUG.

Exceptions

Type Condition

Type	Condition
ArgumentNullException	Thrown when the texture parameter is null.
NotSupportedException	Thrown when the formats cannot be converted because they're not of the same group. -or- Thrown when the `destinationTexture` is the same as this texture, and the `sourceArrayIndex`, `destArrayIndex`, `sourceMipLevel` and the `destMipLevel` specified are pointing to the same subresource. -or- Thrown when this texture has a Usage of Immutable.

ArgumentNullException

Thrown when the texture parameter is null.

NotSupportedException

Thrown when the formats cannot be converted because they're not of the same group.

-or-

Thrown when the destinationTexture is the same as this texture, and the sourceArrayIndex, destArrayIndex, sourceMipLevel and the destMipLevel specified are pointing to the same subresource.

-or-

Thrown when this texture has a Usage of Immutable.

| Edit this page View Source

CopyTo(GorgonTexture2D, in Rectangle?, int, int, int, int, int, int, CopyMode)

Function to copy this texture into another GorgonTexture2D.

Declaration

public void CopyTo(GorgonTexture2D destinationTexture, in Rectangle? sourceRectangle = null, int sourceArrayIndex = 0, int sourceMipLevel = 0, int destX = 0, int destY = 0, int destArrayIndex = 0, int destMipLevel = 0, CopyMode copyMode = CopyMode.None)

Parameters

Type	Name	Description
GorgonTexture2D	destinationTexture	The texture to copy into.
Rectangle?	sourceRectangle	[Optional] The dimensions of the source area to copy.
int	sourceArrayIndex	[Optional] The array index of the sub resource to copy.
int	sourceMipLevel	[Optional] The mip map level of the sub resource to copy.
int	destX	[Optional] Horizontal offset into the destination texture to place the copied data.
int	destY	[Optional] Vertical offset into the destination texture to place the copied data.
int	destArrayIndex	[Optional] The array index of the destination sub resource to copy into.
int	destMipLevel	[Optional] The mip map level of the destination sub resource to copy into.
CopyMode	copyMode	[Optional] Defines how data should be copied into the texture.

Remarks

Use this method to copy a specific sub resource of this GorgonTexture2D to another sub resource of a GorgonTexture2D, or to a different sub resource of the same texture. The sourceRectangle coordinates must be inside of the destination, if it is not, then the source data will be clipped against the destination region. No stretching or filtering is supported by this method.

When copying sub resources (e.g. mip levels, array indices, etc...), the mip levels and array indices must be different if copying to the same texture. If they are not, an exception will be thrown.

The destination texture must not have a Usage of Immutable.

The copyMode flag defines how data will be copied into this texture. See the CopyMode enumeration for a description of the values.

caution

For performance reasons, any exceptions thrown from this method will only be thrown when Gorgon is compiled as DEBUG.

Exceptions

Type Condition

Type	Condition
ArgumentNullException	Thrown when the texture parameter is null.
NotSupportedException	Thrown when the formats cannot be converted because they're not of the same group. -or- Thrown when the `destinationTexture` is the same as this texture, and the `sourceArrayIndex`, `destArrayIndex`, `sourceMipLevel` and the `destMipLevel` specified are pointing to the same subresource. -or- Thrown when this texture has a Usage of Immutable.

ArgumentNullException

Thrown when the texture parameter is null.

NotSupportedException

Thrown when the formats cannot be converted because they're not of the same group.

-or-

Thrown when the destinationTexture is the same as this texture, and the sourceArrayIndex, destArrayIndex, sourceMipLevel and the destMipLevel specified are pointing to the same subresource.

-or-

Thrown when this texture has a Usage of Immutable.

| Edit this page View Source

CopyTo(GorgonTexture3D, in Rectangle?, int, int, int, int, int, int, CopyMode)

Function to copy this texture into a GorgonTexture3D.

Declaration

public void CopyTo(GorgonTexture3D destinationTexture, in Rectangle? sourceRectangle = null, int sourceArrayIndex = 0, int sourceMipLevel = 0, int destX = 0, int destY = 0, int destZ = 0, int destMipLevel = 0, CopyMode copyMode = CopyMode.None)

Parameters

Type	Name	Description
GorgonTexture3D	destinationTexture	The texture to copy into.
Rectangle?	sourceRectangle	[Optional] The dimensions of the source area to copy.
int	sourceArrayIndex	[Optional] The array index of the sub resource to copy.
int	sourceMipLevel	[Optional] The mip map level of the sub resource to copy.
int	destX	[Optional] Horizontal offset into the destination texture to place the copied data.
int	destY	[Optional] Vertical offset into the destination texture to place the copied data.
int	destZ	[Optional] Depth offset into the destination texture to place the copied data.
int	destMipLevel	[Optional] The mip map level of the destination sub resource to copy into.
CopyMode	copyMode	[Optional] Defines how data should be copied into the texture.

Remarks

Use this method to copy a specific sub resource of this GorgonTexture2D to another sub resource of a GorgonTexture3D. The sourceRectangle coordinates must be inside of the destination, if it is not, then the source data will be clipped against the destination region. No stretching or filtering is supported by this method.

When copying sub resources (e.g. mip levels, array indices, etc...), the mip levels and array indices must be different if copying to the same texture. If they are not, an exception will be thrown.

The destination texture must not have a Usage of Immutable.

The copyMode flag defines how data will be copied into this texture. See the CopyMode enumeration for a description of the values.

caution

For performance reasons, any exceptions thrown from this method will only be thrown when Gorgon is compiled as DEBUG.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the texture parameter is null.
NotSupportedException	Thrown when the formats cannot be converted because they're not of the same group. -or- Thrown when this texture has a Usage of Immutable.

Type

Condition

ArgumentNullException

Thrown when the texture parameter is null.

NotSupportedException

Thrown when the formats cannot be converted because they're not of the same group.

-or-

Thrown when this texture has a Usage of Immutable.

| Edit this page View Source

Dispose()

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

Declaration

public override void Dispose()

Overrides

GorgonGraphicsResource.Dispose()

| Edit this page View Source

FromFile(GorgonGraphics, string, IGorgonImageCodec, GorgonTexture2DLoadOptions)

Function to load a texture from a file..

Declaration

public static GorgonTexture2D FromFile(GorgonGraphics graphics, string filePath, IGorgonImageCodec codec, GorgonTexture2DLoadOptions options = null)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface that will own the texture.
string	filePath	The path to the file.
IGorgonImageCodec	codec	The codec that is used to decode the the data in the stream.
GorgonTexture2DLoadOptions	options	[Optional] Options used to further define the texture.

Returns

Type	Description
GorgonTexture2D	A new GorgonTexture2D

Remarks

This will load an IGorgonImage from a file on disk and put it into a GorgonTexture2D object.

If specified, the optionsparameter will define how Gorgon and shaders should handle the texture. The GorgonTextureLoadOptions type contains the following:

BindingWhen defined, will indicate the TextureBinding that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be ShaderResource.
UsageWhen defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to Default.
Multisample infoWhen defined (i.e. not null), defines the multisampling to apply to the texture. If omitted, then the default is NoMultiSampling.
ConvertToPremultipliedAlphaConverts the image to premultiplied alpha before uploading the image data to the texture.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `graphics`, `filePath`, or the `codec` parameter is null.
ArgumentEmptyException	Thrown when the `filePath` parameter is empty.

| Edit this page View Source

FromStream(GorgonGraphics, Stream, IGorgonImageCodec, long?, GorgonTexture2DLoadOptions)

Function to load a texture from a Stream.

Declaration

public static GorgonTexture2D FromStream(GorgonGraphics graphics, Stream stream, IGorgonImageCodec codec, long? size = null, GorgonTexture2DLoadOptions options = null)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface that will own the texture.
Stream	stream	The stream containing the texture image data.
IGorgonImageCodec	codec	The codec that is used to decode the the data in the stream.
long?	size	[Optional] The size of the image in the stream, in bytes.
GorgonTexture2DLoadOptions	options	[Optional] Options used to further define the texture.

Returns

Type	Description
GorgonTexture2D	A new GorgonTexture2D

Remarks

This will load an IGorgonImage from a stream and put it into a GorgonTexture2D object.

If the size option is specified, then the method will read from the stream up to that number of bytes, so it is up to the user to provide an accurate size. If it is omitted then the stream length - stream position is used as the total size.

If specified, the optionsparameter will define how Gorgon and shaders should handle the texture. The GorgonTextureLoadOptions type contains the following:

BindingWhen defined, will indicate the TextureBinding that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be ShaderResource.
UsageWhen defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to Default.
Multisample infoWhen defined (i.e. not null), defines the multisampling to apply to the texture. If omitted, then the default is NoMultiSampling.
ConvertToPremultipliedAlphaConverts the image to premultiplied alpha before uploading the image data to the texture.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the `graphics`, `stream`, or the `codec` parameter is null.
IOException	Thrown if the `stream` is write only.
EndOfStreamException	Thrown if reading the image would move beyond the end of the `stream`.

| Edit this page View Source

GetDepthStencilView(BufferFormat, int, int, int, DepthStencilViewFlags)

Function to create a new GorgonDepthStencil2DView for this texture.

Declaration

public GorgonDepthStencil2DView GetDepthStencilView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int arrayIndex = 0, int arrayCount = 0, DepthStencilViewFlags flags = DepthStencilViewFlags.None)

Parameters

Type	Name	Description
BufferFormat	format	[Optional] The format for the view.
int	firstMipLevel	[Optional] The first mip map level (slice) to start viewing from.
int	arrayIndex	[Optional] The array index to start viewing from.
int	arrayCount	[Optional] The number of array indices to view.
DepthStencilViewFlags	flags	[Optional] Flags to define how this view should be accessed by the shader.

Returns

Type	Description
GorgonDepthStencil2DView	A GorgonDepthStencil2DView used to bind the texture as a depth/stencil buffer.

Remarks

The depth/stencil views take a DepthStencilViewFlags parameter that determine how a shader can access the depth buffer when it is bound to the pipeline for reading. By specifying a single flag, the depth can write to the opposite plane (e.g. read only depth and write only stencil, write only depth and read only stencil) of the texture. This allows for multiple depth/stencil views to be bound to the pipeline for reading and writing.

If the Binding for the texture includes ShaderResource, then the format for the view and the Format for the texture must be specific values. These values are listed below:

Depth Format	Texture Format
D32_Float_S8X24_UInt	R32G8X24_Typeless
D24_UNorm_S8_UInt	R24G8_Typeless
D32_Float	R32_Typeless
D16_UNorm	R16_Typeless

Exceptions

Type Condition

Type	Condition
ArgumentException	Thrown when the `format` is not supported as a depth/stencil format.
GorgonException	Thrown when this texture does not have a TextureBinding of DepthStencil. -or- Thrown when this texture has a Usage of Staging. -or- Thrown if this texture has a Binding of ShaderResource, but the texture format is not a typeless format.

ArgumentException

Thrown when the format is not supported as a depth/stencil format.

GorgonException

Thrown when this texture does not have a TextureBinding of DepthStencil.

-or-

Thrown when this texture has a Usage of Staging.

-or-

Thrown if this texture has a Binding of ShaderResource, but the texture format is not a typeless format.

| Edit this page View Source

GetReadWriteView(BufferFormat, int, int, int)

Function to create a new GorgonTexture2DReadWriteView for this texture.

Declaration

public GorgonTexture2DReadWriteView GetReadWriteView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int arrayIndex = 0, int arrayCount = 0)

Parameters

Type	Name	Description
BufferFormat	format	[Optional] The format for the view.
int	firstMipLevel	[Optional] The first mip map level (slice) to start viewing from.
int	arrayIndex	[Optional] The array index to start viewing from.
int	arrayCount	[Optional] The number of array indices to view.

Returns

Type	Description
GorgonTexture2DReadWriteView	A GorgonTexture2DReadWriteView used to bind the texture to a shader.

Remarks

This will create an unordered access view that makes a texture accessible to shaders using unordered access to the data. This allows viewing of the texture data in a different format, or even a subsection of the texture from within the shader.

The format parameter is used present the texture data as another format type to the shader. If this parameter is omitted, then the format of the texture will be used.

The firstMipLevel parameter defines the starting mip level to allow access to within the shader. If this value falls outside of the range of available mip levels, then it will be clipped to the upper and lower bounds of the mip chain. If this value is left at 0, then only the first mip level is used.

The arrayIndex and arrayCount parameters define the starting array index and the number of array indices to allow access to within the shader. If these values are left at 0, then all array indices will be accessible.

Exceptions

Type Condition

Type	Condition
GorgonException	Thrown when this texture does not have a TextureBinding of ReadWriteView. -or- Thrown when this texture has a Usage of Staging. -or- Thrown if the this texture uses multisampling.
ArgumentException	Thrown when the `format` is typeless or is not a supported format for unordered access views.

GorgonException

Thrown when this texture does not have a TextureBinding of ReadWriteView.

-or-

Thrown when this texture has a Usage of Staging.

-or-

Thrown if the this texture uses multisampling.

ArgumentException

Thrown when the format is typeless or is not a supported format for unordered access views.

| Edit this page View Source

GetRenderTargetView(BufferFormat, int, int, int)

Function to create a new GorgonRenderTarget2DView for this texture.

Declaration

public GorgonRenderTarget2DView GetRenderTargetView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int arrayIndex = 0, int arrayCount = 0)

Parameters

Type	Name	Description
BufferFormat	format	[Optional] The format for the view.
int	firstMipLevel	[Optional] The first mip map level (slice) to start viewing from.
int	arrayIndex	[Optional] The array index start viewing from.
int	arrayCount	[Optional] The number of array indices to view.

Returns

Type	Description
GorgonRenderTarget2DView	A GorgonTexture2DView used to bind the texture to a shader.

Remarks

This will create a view that allows a texture to become a render target. This allows rendering into texture data in a different format, or even a subsection of the texture.

The format parameter is used present the texture data as another format type to the shader. If this value is left at the default of Unknown, then the format from the this texture is used. The format must be castable to the format of this texture. If it is not, an exception will be thrown.

The firstMipLevel parameter will be constrained to the number of mip levels for the texture should it be set to less than 0 or greater than the number of mip levels. If this value is left at 0, then only the top mip level is used.

The arrayIndex and arrayCount parameters will define the starting array index and the number of array indices to render into. If these values are left at 0, then the entire array is used to receive rendering data.

Exceptions

Type Condition

Type	Condition
ArgumentException	Thrown when the `format` is typeless.
GorgonException	Thrown when this texture does not have a TextureBinding of RenderTarget. -or- Thrown when this texture has a Usage of Staging.

ArgumentException

Thrown when the format is typeless.

GorgonException

Thrown when this texture does not have a TextureBinding of RenderTarget.

-or-

Thrown when this texture has a Usage of Staging.

| Edit this page View Source

GetShaderResourceView(BufferFormat, int, int, int, int)

Function to create a new GorgonTexture2DView for this texture.

Declaration

public GorgonTexture2DView GetShaderResourceView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int mipCount = 0, int arrayIndex = 0, int arrayCount = 0)

Parameters

Type	Name	Description
BufferFormat	format	[Optional] The format for the view.
int	firstMipLevel	[Optional] The first mip map level (slice) to start viewing from.
int	mipCount	[Optional] The number of mip map levels to view.
int	arrayIndex	[Optional] The array index to start viewing from.
int	arrayCount	[Optional] The number of array indices to view.

Returns

Type	Description
GorgonTexture2DView	A GorgonTexture2DView used to bind the texture to a shader.

Remarks

This will create a view that makes a texture accessible to shaders. This allows viewing of the texture data in a different format, or even a subsection of the texture from within the shader.

The firstMipLevel and mipCount parameters define the starting mip level and the number of mip levels to allow access to within the shader. If these values fall outside of the range of available mip levels, then they will be clipped to the upper and lower bounds of the mip chain. If these values are left at 0, then all mip levels will be accessible.

Exceptions

Type Condition

Type	Condition
ArgumentException	Thrown if the `format` is a typeless format.
GorgonException	Thrown when this texture does not have a TextureBinding of ShaderResource. -or- Thrown when this texture has a usage of Staging. -or- Thrown if the texture Format is not typeless, and the Binding is set to DepthStencil.

ArgumentException

Thrown if the format is a typeless format.

GorgonException

Thrown when this texture does not have a TextureBinding of ShaderResource.

-or-

Thrown when this texture has a usage of Staging.

-or-

Thrown if the texture Format is not typeless, and the Binding is set to DepthStencil.

| Edit this page View Source

GetStagingTexture()

Function to get a staging texture from this texture.

Declaration

public GorgonTexture2D GetStagingTexture()

Returns

Type	Description
GorgonTexture2D	A new GorgonTexture2D containing a copy of the data in this texture, with a usage of `Staging`.

Remarks

This allows an application to make a copy of the texture for editing on the CPU. The resulting staging texture, once edited, can then be reuploaded to the same texture, or another texture.

Exceptions

Type	Condition
GorgonException	Thrown when this texture has a Usage of `Immutable`.

| Edit this page View Source

ResolveTo(GorgonTexture2D, BufferFormat, int, int, int, int)

Function to resolve a multisampled 2D GorgonTexture2D into a non-multisampled GorgonTexture2D.

Declaration

public void ResolveTo(GorgonTexture2D destination, BufferFormat resolveFormat = BufferFormat.Unknown, int destArrayIndex = 0, int destMipLevel = 0, int srcArrayIndex = 0, int srcMipLevel = 0)

Parameters

Type	Name	Description
GorgonTexture2D	destination	The GorgonTexture2D that will receive the resolved texture.
BufferFormat	resolveFormat	[Optional] A format that will determine how to resolve the multisampled texture into a non-multisampled texture.
int	destArrayIndex	[Optional] Index in the array that will receive the resolved texture data.
int	destMipLevel	[Optional] The mip map level that will receive the resolved texture data.
int	srcArrayIndex	[Optional] The array index in the source to resolve.
int	srcMipLevel	[Optional] The source mip level to resolve.

Remarks

Use this method to resolve a multisampled texture into a non multisampled texture. This is most useful when transferring a multisampled render target pass as an input to a secondary pass.

The resolveFormat parameter is used to determine how to interpret the data in the texture. There are 3 ways this data may be interpreted:

If both textures have a typed format, then the resolve format must be the same as the format of the textures. Both textures must have the same format.
If one of the textures have a typeless format and one has a typed format, then the resolve format must be in the same group as the typed format.
If the textures both have a typeless format, then the resolve format must be in the same group as the typeless format.

Leaving the resolve format as Unknown will automatically use the format of the source texture.

Exceptions

Type Condition

ArgumentNullException

Thrown when the destination parameter is null.

ArgumentException

Thrown when the format of this texture, and the format destination texture are not typeless, and are not the same format.

-or-

Thrown when the format of both this texture and the destination texture are typeless, but the resolve format is not set to a bit group compatible format, or the textures do not have bit group compatible formats.

-or-

Thrown when either the format of this texture or the destination texture is typless, and the other is not, and the resolve format is not set to a bit group compatible format, or the textures do not have bit group compatible formats.

NotSupportedException

Thrown when the source texture is not multisampled or the destination texture is multisampled or has a non default usage.

| Edit this page View Source

SetData(IGorgonImageBuffer, in Rectangle?, int, int, CopyMode)

Function to update the texture, or a sub section of the texture with data from a IGorgonImageBuffer contained within a IGorgonImage.

Declaration

public void SetData(IGorgonImageBuffer imageBuffer, in Rectangle? destRectangle = null, int destArrayIndex = 0, int destMipLevel = 0, CopyMode copyMode = CopyMode.None)

Parameters

Type	Name	Description
IGorgonImageBuffer	imageBuffer	The image buffer that contains the data to copy.
Rectangle?	destRectangle	[Optional] The region on the texture to update.
int	destArrayIndex	[Optional] The array index to update.
int	destMipLevel	[Optional] The mip map level to update.
CopyMode	copyMode	[Optional] Flags to indicate how to copy the data.

Remarks

This will upload data from a IGorgonImageBuffer in a IGorgonImage to a sub section of the texture (e.g. a mip level, array index, etc...). The method will determine how to best upload the data depending on the Usage of the texture. For example, if the texture has a Usage of Default, then internally, this method will update to the GPU directly. Otherwise, if it is Dynamic, or Staging, it will use a locking pattern which uses the CPU to write data to the texture. The latter pattern is good if the texture has to change one or more times per frame, otherwise, the former is better where the texture is updated less than once per frame (i.e. Dynamic is good for multiple times per frame, Default is good for once per frame or less).

Users who wish to capture a smaller portion of the source imageBuffer can use the GetRegion(in Rectangle) method to extract a region from a buffer in a IGorgonImage.

If the user supplies a destRectangle, then the data will be copied to the region in the texture specified by the parameter, otherwise if the parameter is omitted, the full size of the texture (depending on mip level) is used. This value is clipped against the width/height of the mip level (e.g. A 256x256 image at mip level 2 would be 64x64).

The destMipLevel, and destArrayIndex define which mip map level, and/or array index will receive the data. If omitted, the first mip level and/or array index is used. Like the destRectangle, these values are clipped against the MipLevels and ArrayCount values respectively.

The copyMode parameter defines how the copy will be performed. If the texture has a Usage of Dynamic or Default and the copyMode is set to Discard then the contents of the texture are discarded before updating, if it is set to NoOverwrite, then the data will be copied to the destination if we know the GPU is not using the portion being updated. If the copyMode is set to None, then Discard is used. For textures created with a Usage of Staging, the CopyMode will be ignored and act as though None were passed.

Please note that no format conversion, or image manipulation (other than clipping against the destRectangle) is performed by this method. So it is up to the user to ensure that their source data is in the correct format and at the correct size.

caution

For performance reasons, any exceptions thrown from this method will only be thrown when Gorgon is compiled as DEBUG.

Examples

The following is an example showing how to upload an image into a texture using different techniques:

using DX = SharpDX;

IGorgonImage image = ... // Load an image from a source.
var texture = new GorgonTexture2D(graphics, new GorgonTexture2DInfo
{
   Width = image.Width,
   Height = image.Height,
   Format = image.Format,
   ArrayCount = 4,
   MipLevels = 4,
   // This will trigger a direct upload to the GPU, use Dynamic or Staging for CPU writable uploads.
   // Dynamic is useful if the texture needs updating once or more per frame.
   Usage = ResourceUsage.Default  
});

// Set the image to the first array and mip level at the full size.
texture.SetData(image.Buffers[0]);

// Set the image to the 3rd array index, and 2nd mip level, at position 10x10 on the texture, with a width and height of 50x50.
// Also, set it so that we're copying to another
texture.SetData(image.Buffers[0], new DX.Rectangle(10, 10, 50, 50), 2, 2, copyMode: CopyMode.NoOverwrite);

// Set a portion of the source image.
texture.SetData(image.Buffers[0].GetRegion(new DX.Rectangle(10, 10, 50, 50));

Exceptions

Type Condition

NotSupportedException

Thrown if this image has a usage of Immutable, is multisampled, or has a binding of DepthStencil.

ArgumentException

Thrown if the imageBuffer contains data in a BufferFormat that does not have the same size, in bytes, as the Format of this texture.

-or-

Thrown if the BufferFormat of the imageBuffer is compressed and the Format of this texture is not (or vice versa).

-or-

Thrown if the BufferFormat of the imageBuffer is packed and the Format of this texture is not (or vice versa).

ToImage()

Function to convert this texture to a IGorgonImage.

Declaration

public IGorgonImage ToImage()

Returns

Type	Description
IGorgonImage	A new IGorgonImage containing the texture data.

Exceptions

Type	Condition
GorgonException	Thrown when this texture has a Usage set to Immutable.

| Edit this page View Source

ToImage(int, int?)

Function to convert the texture data at the specified array index, and/or mip map level into a GorgonImage.

Declaration

public IGorgonImage ToImage(int mipLevel, int? arrayIndex = null)

Parameters

Type	Name	Description
int	mipLevel	The mip level in the texture to copy from.
int?	arrayIndex	[Optional] The array index in the texture to copy from.

Returns

Type	Description
IGorgonImage	A new IGorgonImage containing the data in the array index and mip level.

Remarks

If the arrayIndex is passed in, then only that array index will be copied to the resulting image. If it is omitted, then the entire array will be returned.

Exceptions

Type	Condition
GorgonException	Thrown when this texture has a Usage set to Immutable.

| Edit this page View Source

ToPixel(RectangleF)

Function to convert a texel rectangle into a pixel rectangle.

Declaration

public Rectangle ToPixel(RectangleF texelCoordinates)

Parameters

Type	Name	Description
RectangleF	texelCoordinates	The texel rectangle to convert.

Returns

Type	Description
Rectangle	The pixel rectangle.

| Edit this page View Source

ToPixel(Size2F)

Function to convert a texel size into a pixel size.

Declaration

public Size2 ToPixel(Size2F texelCoordinates)

Parameters

Type	Name	Description
Size2F	texelCoordinates	The texel size to convert.

Returns

Type	Description
Size2	The pixel size.

| Edit this page View Source

ToPixel(Vector2)

Function to convert a texel coordinate into a pixel coordinate.

Declaration

public Point ToPixel(Vector2 texelCoordinates)

Parameters

Type	Name	Description
Vector2	texelCoordinates	The texel coordinates to convert.

Returns

Type	Description
Point	The pixel coordinates.

| Edit this page View Source

ToTexel(Point)

Function to convert a pixel coordinate into a texel coordinate.

Declaration

public Vector2 ToTexel(Point pixelCoordinates)

Parameters

Type	Name	Description
Point	pixelCoordinates	The pixel coordinate to convert.

Returns

Type	Description
Vector2	The texel coordinates.

| Edit this page View Source

ToTexel(Rectangle)

Function to convert a pixel rectangle into a texel rectangle.

Declaration

public RectangleF ToTexel(Rectangle pixelCoordinates)

Parameters

Type	Name	Description
Rectangle	pixelCoordinates	The pixel rectangle to convert.

Returns

Type	Description
RectangleF	The texel rectangle.

| Edit this page View Source

ToTexel(Size2)

Function to convert a pixel size into a texel size.

Declaration

public Size2F ToTexel(Size2 pixelCoordinates)

Parameters

Type	Name	Description
Size2	pixelCoordinates	The pixel size to convert.

Returns

Type	Description
Size2F	The texel size.

| Edit this page View Source

ToTexel(Vector2)

Function to convert a pixel coordinate into a texel coordinate.

Declaration

public Vector2 ToTexel(Vector2 pixelCoordinates)

Parameters

Type	Name	Description
Vector2	pixelCoordinates	The pixel coordinate to convert.

Returns

Type	Description
Vector2	The texel coordinates.

Implements

IGorgonTexture2DInfo

IGorgonTextureResource

IGorgonNamedObject

IGorgonGraphicsObject

IGorgonImageInfo

IDisposable

IGorgonSharedResource

IGorgonNativeResource

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)