Class GorgonTexture3D

public sealed class GorgonTexture3D : GorgonGraphicsResource, IGorgonNativeResource, IGorgonTexture3DInfo, IGorgonTextureResource, IGorgonNamedObject, IGorgonGraphicsObject, IGorgonImageInfo, IDisposable

Constructors

| Edit this page View Source

GorgonTexture3D(GorgonGraphics, GorgonTexture3DInfo)

Initializes a new instance of the GorgonTexture3D class.

Declaration

public GorgonTexture3D(GorgonGraphics graphics, GorgonTexture3DInfo textureInfo)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The GorgonGraphics interface that created this texture.
GorgonTexture3DInfo	textureInfo	A IGorgonTexture3DInfo 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 ToTexture3D(IGorgonImage, GorgonGraphics, GorgonTextureLoadOptions) 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.

Properties

| 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

Depth

Property to return the depth of the texture, in slices.

Declaration

public int Depth { get; }

Property Value

Type	Description
int

| 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

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

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

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(IGorgonTexture3DInfo)

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

Declaration

public static int CalculateSizeInBytes(IGorgonTexture3DInfo info)

Parameters

Type	Name	Description
IGorgonTexture3DInfo	info	The IGorgonTexture3DInfo 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)

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

Declaration

public static int CalculateSizeInBytes(int width, int height, int depth, BufferFormat format, int mipCount)

Parameters

Type	Name	Description
int	width	The width of the texture.
int	height	The height of the texture.
int	depth	The depth of the texture.
BufferFormat	format	The format for the texture.
int	mipCount	The number of mip map levels.

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 sourceDepthSlice = 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	sourceDepthSlice	[Optional] The depth slice 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 `sourceDepthSlice`, `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 sourceDepthSlice, 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 a GorgonTexture2D.

Declaration

public void CopyTo(GorgonTexture2D destinationTexture, in Rectangle? sourceRectangle = null, int sourceDepthSlice = 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	sourceDepthSlice	[Optional] The depth slice 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 `sourceDepthSlice`, `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 sourceDepthSlice, 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?, GorgonRange?, int, int, int, int, int, CopyMode)

Function to copy this texture into a GorgonTexture3D.

Declaration

public void CopyTo(GorgonTexture3D destinationTexture, in Rectangle? sourceRectangle = null, GorgonRange? sourceDepthSliceRange = null, 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.
GorgonRange?	sourceDepthSliceRange	[Optional] The depth slice range 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, GorgonTextureLoadOptions)

Function to load a texture from a file..

Declaration

public static GorgonTexture3D FromFile(GorgonGraphics graphics, string filePath, IGorgonImageCodec codec, GorgonTextureLoadOptions 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.
GorgonTextureLoadOptions	options	[Optional] Options used to further define the texture.

Returns

Type	Description
GorgonTexture3D	A new GorgonTexture3D

Remarks

This will load an IGorgonImage from a file on disk and put it into a GorgonTexture3D 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?, GorgonTextureLoadOptions)

Function to load a texture from a Stream.

Declaration

public static GorgonTexture3D FromStream(GorgonGraphics graphics, Stream stream, IGorgonImageCodec codec, long? size = null, GorgonTextureLoadOptions 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.
GorgonTextureLoadOptions	options	[Optional] Options used to further define the texture.

Returns

Type	Description
GorgonTexture3D	A new GorgonTexture3D

Remarks

This will load an IGorgonImage from a stream and put it into a GorgonTexture3D 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

GetReadWriteView(BufferFormat, int, int, int)

Function to create a new GorgonTexture3DReadWriteView for this texture.

Declaration

public GorgonTexture3DReadWriteView GetReadWriteView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int startDepthSlice = 0, int depthSliceCount = 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	startDepthSlice	[Optional] The array index or depth slice to start viewing from.
int	depthSliceCount	[Optional] The number of array indices or depth slices to view.

Returns

Type	Description
GorgonTexture3DReadWriteView	A GorgonTexture3DReadWriteView 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 startDepthSlice and depthSliceCount parameters define the starting depth slice and the number of slices 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.
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.

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 GorgonRenderTarget3DView for this texture.

Declaration

public GorgonRenderTarget3DView GetRenderTargetView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int startDepthSlice = 0, int depthSliceCount = 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	startDepthSlice	[Optional] The depth index to start viewing from.
int	depthSliceCount	[Optional] The number of depth slices to view.

Returns

Type	Description
GorgonRenderTarget3DView	A GorgonTexture3DView 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 startDepthSlice and depthSliceCount parameters will define the starting depth slice and the number of depth slices to render into. If these values are left at 0, then the entire depth is used to receive rendering data.

Exceptions

Type Condition

Type	Condition
ArgumentException	Thrown when the `format` is typeless or cannot be determined from the this texture.
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 or cannot be determined from the this texture.

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)

Function to create a new GorgonTexture3DView for this texture.

Declaration

public GorgonTexture3DView GetShaderResourceView(BufferFormat format = BufferFormat.Unknown, int firstMipLevel = 0, int mipCount = 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.

Returns

Type	Description
GorgonTexture3DView	A GorgonTexture3DView 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 GorgonTexture3D GetStagingTexture()

Returns

Type	Description
GorgonTexture3D	A new GorgonTexture3D 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

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 destSlice = 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	destSlice	[Optional] The depth slice on the texture 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 and/or destSlice, then the data will be copied to the region in the texture specified by the first parameter and the depth slice specified by the second, 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/depth of the mip level (e.g. A 256x256x64 image at mip level 2 would be 64x64x16).

The destMipLevel defines which mip map level will receive the data. If omitted, the first mip level index is used. Like the destRectangle, this value is clipped against the MipLevels value.

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 GorgonTexture3D(graphics, new GorgonTexture3DInfo
{
   Width = image.Width,
   Height = image.Height,
   Format = image.Format,
   Depth = image.Depth,
   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 depth slice and mip level at the full size.
texture.SetData(image.Buffers[0]);

// Set the image to the 4th depth slice, 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), 3, 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

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

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? depthSlice = null)

Parameters

Type	Name	Description
int	mipLevel	The mip level in the texture to copy from.
int?	depthSlice	[Optional] The depthSlice 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 depthSlice is passed in, then only a single depth slice is created for the image. If it is omitted, then the entire slice for the mipLevel is returned.

Exceptions

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

| 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(Vector3)

Function to convert a texel coordinate into a pixel coordinate and a depth slice.

Declaration

public (Point, int) ToPixel(Vector3 texelCoordinates)

Parameters

Type	Name	Description
Vector3	texelCoordinates	The texel coordinates to convert.

Returns

Type	Description
(Point, int)	The pixel coordinates.

| Edit this page View Source

ToTexel(Point, int)

Function to convert a pixel coordinate into a texel coordinate.

Declaration

public Vector3 ToTexel(Point pixelCoordinates, int depthSlice)

Parameters

Type	Name	Description
Point	pixelCoordinates	The pixel coordinate to convert.
int	depthSlice	The depth slice to convert.

Returns

Type	Description
Vector3	The texel coordinates.

| 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(Vector3)

Function to convert a pixel coordinate into a texel coordinate.

Declaration

public Vector3 ToTexel(Vector3 pixelCoordinates)

Parameters

Type	Name	Description
Vector3	pixelCoordinates	The pixel coordinate to convert.

Returns

Type	Description
Vector3	The texel coordinates.

Implements

IGorgonNativeResource

IGorgonTexture3DInfo

IGorgonTextureResource

IGorgonNamedObject

IGorgonGraphicsObject

IGorgonImageInfo

IDisposable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)