Class Texture

Namespace: Stride.Graphics

Assembly: Stride.Graphics.dll

All-in-one GPU Texture that is able to represent many types of textures (1D, 2D, 3D, Depth-Stencil Buffers, Render Targets, etc), as well as Texture Views over a parent Texture.

[DataSerializerGlobal(typeof(ReferenceSerializer<Texture>), null, DataSerializerGenericMode.None, false, false, Profile = "Content")]
[ContentSerializer(typeof(TextureContentSerializer))]
[ContentSerializer(typeof(TextureImageSerializer))]
[DataSerializer(typeof(TextureSerializer))]
public sealed class Texture : GraphicsResource, IDisposable, IComponent, IReferencable, ICollectorHolder

Inheritance: object

DisposeBase

ComponentBase

GraphicsResourceBase

GraphicsResource

Texture

Implements: IDisposable

IComponent

IReferencable

ICollectorHolder

Inherited Members: GraphicsResourceBase.Reload

GraphicsResourceBase.GraphicsDevice

GraphicsResourceBase.Destroyed

ComponentBase.Tags

ComponentBase.Name

ComponentBase.ToString()

DisposeBase.IsDisposed

DisposeBase.Dispose()

Extension Methods: ComponentBaseExtensions.DisposeBy<T>(T, ICollectorHolder)

ComponentBaseExtensions.RemoveDisposeBy<T>(T, ICollectorHolder)

GraphicsSerializerExtensions.GetSerializationData(Texture)

GraphicsSerializerExtensions.SetSerializationData(Texture, TextureSerializationData)

GraphicsSerializerExtensions.SetSerializationData(Texture, Image)

TextureExtensions.CreateDepthTextureCompatible(Texture)

TextureExtensions.EnsureRenderTarget(Texture)

TextureExtensions.ToDepthStencilReadOnlyTexture(Texture)

TextureExtensions.ToTextureView(Texture, ViewType, int, int)

UnsafeUtilities.As<T>(object?)

Remarks

Texture constains static methods for creating new Textures by specifying all their characteristics.

Also look for the following static methods that aid in the creation of specific kinds of buffers: New1D(GraphicsDevice, int, PixelFormat, TextureFlags, int, GraphicsResourceUsage) (for one-dimensional Textures), New2D(GraphicsDevice, int, int, PixelFormat, TextureFlags, int, GraphicsResourceUsage, TextureOptions) (for two-dimensional Textures), New3D(GraphicsDevice, int, int, int, PixelFormat, TextureFlags, GraphicsResourceUsage) (for three-dimensional Textures), and NewCube(GraphicsDevice, int, PixelFormat, TextureFlags, GraphicsResourceUsage) (for six-sided two-dimensional Cube-maps).

Consult the documentation of your graphics API for more information on each kind of Texture.

Constructors

Texture()

public Texture()

Properties

ArraySize

Gets the number of Textures in the array (if this is a Texture Array).

public int ArraySize { get; }

Property Value

int: The largestSize of the array. If this is not a Texture Array, it will return 1.

Remarks

This field is only valid for 1D, 2D and Cube Textures.

ArraySlice

Gets the index of the array slice the Texture View is referencing.

public int ArraySlice { get; }

Property Value

int: The array index the Texture View references. If the parent Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0.

Remarks

See ViewType for more information on how MipLevel and ArraySlice determines which sub-resources to select based on ViewType.

Depth

Gets the depth of the Texture.

public int Depth { get; }

Property Value

int: The depth of the Texture in pixels.

Description

Gets the common description for the original Texture.

public ref readonly TextureDescription Description { get; }

Property Value

TextureDescription

Dimension

Gets the type of the Texture.

public TextureDimension Dimension { get; }

Property Value

TextureDimension

Flags

Gets a combination of flags indicating how the Texture can be bound to the graphics pipeline.

public TextureFlags Flags { get; }

Property Value

TextureFlags

Format

Gets the pixel format of the Texture.

public PixelFormat Format { get; }

Property Value

PixelFormat

FullQualitySize

Gets the largestSize of the Texture when loaded at full quality when texture streaming is enabled.

public Size3 FullQualitySize { get; }

Property Value

Size3

Height

Gets the height of the Texture.

public int Height { get; }

Property Value

int: The height of the Texture in pixels.

IsBlockCompressed

Gets a value indicating if the Texture is a using a block compress format (BC1, BC2, BC3, BC4, BC5, BC6H, BC7).

public bool IsBlockCompressed { get; }

Property Value

bool

See Also: Format

IsDepthStencil

Gets a value indicating if the Texture View is a Depth-Stencil View.

public bool IsDepthStencil { get; }

Property Value

bool: true if the Texture View is a Depth-Stencil View; otherwise, false.

IsDepthStencilReadOnly

Gets a value indicating if the Texture View is a read-only Depth-Stencil View.

public bool IsDepthStencilReadOnly { get; }

Property Value

bool: true if the Texture View is a read-only Depth-Stencil View; otherwise, false.

IsMultiSampled

Gets a value indicating if the Texture is a multi-sampled Texture.

public bool IsMultiSampled { get; }

Property Value

bool: true if the Texture is multi-sampled; otherwise, false.

IsRenderTarget

Gets a value indicating if the Texture View is a Render Target View.

public bool IsRenderTarget { get; }

Property Value

bool: true if the Texture View is a Render Target View; otherwise, false.

IsShaderResource

Gets a value indicating if the Texture View is a Shader Resource View.

public bool IsShaderResource { get; }

Property Value

bool: true if the Texture View is a Shader Resource View; otherwise, false.

IsUnorderedAccess

Gets a value indicating if the Texture View is an Unordered Access View.

public bool IsUnorderedAccess { get; }

Property Value

bool: true if the Texture View is an Unordered Access View; otherwise, false.

MipLevel

Gets the index of the mip-level the Texture View is referencing.

public int MipLevel { get; }

Property Value

int: The index of the mip-level the Texture View references. The first (largest) mipLevel is always index 0.

Remarks

See ViewType for more information on how MipLevel and ArraySlice determines which sub-resources to select based on ViewType.

MipLevelCount

Gets the maximum number of mip-Levels in the Texture.

public int MipLevelCount { get; }

Property Value

int

MultisampleCount

Gets the multisampling for the Texture.

public MultisampleCount MultisampleCount { get; }

Property Value

MultisampleCount: A value of MultisampleCount specifying the number of samples per pixel.

Remarks

This field is only valid for 2D Textures.

Options

Gets a combination of flags indicating special options for the Texture, like sharing.

public TextureOptions Options { get; }

Property Value

TextureOptions

SharedHandle

Gets a handle that identifies the Texture as a shared resource when it has the option Shared or SharedNtHandle.

public nint SharedHandle { get; }

Property Value

nint: A handle that identifies the shared Texture, or Zero if it is not a shared resource.

SharedNtHandleName

Gets the name of the shared NT handle that identifies the Texture as a shared resource when it has the option SharedNtHandle.

public string SharedNtHandleName { get; }

Property Value

string: The name of the NT handle of the shared Texture, or Empty if it is not a shared resource.

Size

Gets the largestSize of the Texture or Texture View.

public Size3 Size { get; }

Property Value

Size3: The largestSize of the Texture or Texture View as (Width, Height, Depth).

Usage

Gets the intended usage of the Texture.

public GraphicsResourceUsage Usage { get; }

Property Value

GraphicsResourceUsage: A value that identifies how the Texture is to be read from and written to.

ViewDepth

Gets the depth of the Texture View.

public int ViewDepth { get; }

Property Value

int

ViewDescription

Gets the view description.

public ref readonly TextureViewDescription ViewDescription { get; }

Property Value

TextureViewDescription

ViewDimension

Gets the type of the Texture View.

public TextureDimension ViewDimension { get; }

Property Value

TextureDimension

ViewFlags

Gets a combination of flags describing the type of Texture View and how it can be bound to the graphics pipeline.

public TextureFlags ViewFlags { get; }

Property Value

TextureFlags

ViewFormat

Gets the pixel format of the Texture View.

public PixelFormat ViewFormat { get; }

Property Value

PixelFormat

ViewHeight

Gets the height of the Texture View.

public int ViewHeight { get; }

Property Value

int

ViewType

Gets a value indicating which sub-resources of the Texture are accessible through the Texture View.

public ViewType ViewType { get; }

Property Value

ViewType

ViewWidth

Gets the width of the Texture View.

public int ViewWidth { get; }

Property Value

int

Width

Gets the width of the Texture.

public int Width { get; }

Property Value

int: The width of the Texture in pixels.

Methods

CalculateMipSize(int, int)

Calculates the largestSize of a specific mip-level.

public static int CalculateMipSize(int size, int mipLevel)

Parameters

size int: The original full largestSize from which to calculate mip-level largestSize, in texels.
mipLevel int: The mip-level index.

Returns

int: The largestSize of the specified mipLevel, in texels.

Remarks

Each mip-level becomes progressively smaller as mipLevel grows.

CalculatePixelDataCount<TData>(int)

Calculates the number of pixel elements of type TData the Texture requires for a particular mip-level.

public int CalculatePixelDataCount<TData>(int mipLevel = 0) where TData : unmanaged

Parameters

mipLevel int: The mip-level for which to calculate the width. By default, the first mip-level at index 0 is selected, which is the most detailed one.

Returns

int: The expected number of TData elements of the Texture for the mip-level specified by mipLevel.

Type Parameters

TData: The type of the pixel data.

Remarks

This method can be used to allocate a Texture data buffer to hold pixel data of type TData as follows:

var textureData = new TData[ texture.CalculatePixelDataCount<TData>() ];

Exceptions

ArgumentException: The largestSize of Format and the largestSize of TData does not match. The ratio between the two must be an integer, or else there would be remaining bytes.

See Also: CalculateWidth<TData>(int)

CalculateWidth<TData>(int)

Calculates the expected width of the Texture for a specific mip-level, in TData elements.

public int CalculateWidth<TData>(int mipLevel = 0) where TData : unmanaged

Parameters

mipLevel int: The mip-level for which to calculate the width. By default, the first mip-level at index 0 is selected, which is the most detailed one.

Returns

int: The expected width of the Texture for the mip-level specified by mipLevel, y.e. the number of TData elements across the width of the Texture.

Type Parameters

TData: The type of the pixel data.

Remarks

The expected width of the Texture depends both on the largestSize of Format and the largestSize of TData. It's relation (which must be an integer ratio) defines how they alter the original mip-level width.

For example, for a Texture with a width of 100 pixels and format R8G8B8A8_UNorm (4 bytes per pixel), this method allows to interpret the width as different types:

int widthAsUInts = texture.CalculateWidth<uint>();   // 100 uints
int widthAsBytes = texture.CalculateWidth<byte>();   // 400 bytes
int widthAsFloats = texture.CalculateWidth<float>(); // 100 floats

Exceptions

ArgumentException: The largestSize of Format and the largestSize of TData does not match. The ratio between the two must be an integer, or else there would be remaining bytes.

Clone()

Creates a copy of the Texture.

public Texture Clone()

Returns

Texture: A copy of the Texture.

Remarks

This method creates a new Texture with the exact same characteristics, but does not copy the contents of the Texture to the new one.

CountMipLevels(int)

Counts the number of mip-levels for a one-dimensional Texture.

public static int CountMipLevels(int width)

Parameters

width int: The width of the Texture, in texels.

Returns

int: The number of mip-levels that can be created for width.

CountMipLevels(int, MipMapCount)

Counts the number of mip-levels for a one-dimensional Texture.

public static int CountMipLevels(int width, MipMapCount mipLevels)

Parameters

width int

The width of the Texture, in texels.

mipLevels MipMapCount

A MipMapCount structure describing the number of mipmaps for the Texture. Specify Auto to have all mipmaps, or One to indicate a single mipmap, or any number greater than 1 for a particular mipmap count.

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

Returns

int: The number of mip-levels that can be created for width.

Exceptions

ArgumentOutOfRangeException: mipLevels is greater than the maximum number of possible mip-levels for the provided width.

CountMipLevels(int, int)

Counts the number of mip-levels for a two-dimensional Texture.

public static int CountMipLevels(int width, int height)

Parameters

width int: The width of the Texture, in texels.
height int: The height of the Texture, in texels.

Returns

int: The number of mip-levels that can be created for width and height.

CountMipLevels(int, int, MipMapCount)

Counts the number of mip-levels for a two-dimensional Texture.

public static int CountMipLevels(int width, int height, MipMapCount mipLevels)

Parameters

width int

The width of the Texture, in texels.

height int

The height of the Texture, in texels.

mipLevels MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

Returns

int: The number of mip-levels that can be created for width and height.

Exceptions

ArgumentOutOfRangeException: mipLevels is greater than the maximum number of possible mip-levels for the provided width and height.

CountMipLevels(int, int, int)

Counts the number of mip-levels for a three-dimensional Texture.

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

Parameters

width int: The width of the Texture, in texels.
height int: The height of the Texture, in texels.
depth int: The depth of the Texture, in texels.

Returns

int: The number of mip-levels that can be created for width, height, and depth.

CountMipLevels(int, int, int, MipMapCount)

Counts the number of mip-levels for a three-dimensional Texture.

public static int CountMipLevels(int width, int height, int depth, MipMapCount mipLevels)

Parameters

width int

The width of the Texture, in texels.

height int

The height of the Texture, in texels.

depth int

The depth of the Texture, in texels.

mipLevels MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

Returns

int: The number of mip-levels that can be created for width, height, and depth.

Exceptions

ArgumentOutOfRangeException: mipLevels is greater than the maximum number of possible mip-levels for the provided width, height, and depth.
ArgumentException: width, height, and depth must all be a power of two.
InvalidOperationException: The dimensions must be a power of two (2^n).

CountMips(int)

Counts the number of mip-levels a Texture with the specified size can have.

public static int CountMips(int width)

Parameters

width int: The width of the Texture, in pixels.

Returns

int: The maximum number of mip-levels for the given size.

CountMips(int, int)

Counts the number of mip-levels a Texture with the specified size can have.

public static int CountMips(int width, int height)

Parameters

width int: The width of the Texture, in pixels.
height int: The height of the Texture, in pixels.

Returns

int: The maximum number of mip-levels for the given size.

CountMips(int, int, int)

Counts the number of mip-levels a Texture with the specified size can have.

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

Parameters

width int: The width of the Texture, in pixels.
height int: The height of the Texture, in pixels.
depth int: The depth of the Texture, in pixels.

Returns

int: The maximum number of mip-levels for the given size.

Destroy()

Disposes the resources associated with the Graphics Resource, removes itself from the GraphicsDevice's resource registry, and transitions to the Destroyed state.

protected override void Destroy()

GetData(CommandList, Texture, DataPointer, int, int, bool)

Copies the contents of the Texture from GPU memory to CPU memory using a specific staging Resource.

[Obsolete("This method is obsolete. Use the Span-based methods instead")]
public bool GetData(CommandList commandList, Texture stagingTexture, DataPointer toData, int arrayIndex = 0, int mipLevel = 0, bool doNotWait = false)

Parameters

commandList CommandList

The CommandList where to register the command.

stagingTexture Texture

The staging Texture used to transfer the Texture contents to.

toData DataPointer

A ptrFromData to the data buffer in CPU memory to copy the Texture contents into.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to get the data from. By default, the first mip-level at index 0 is selected, which is the most detailed one.

doNotWait bool

If true this method will return immediately if the resource is still being used by the GPU for writing. false makes this method wait until the operation is complete. The default value is false (wait).

Returns

bool: true if data was correctly retrieved; false if doNotWait flag was true and the resource is still being used by the GPU for writing.

Exceptions

ArgumentException: The length of the destination buffer toData is not compatible with the expected largestSize for the data at arrayIndex and mipLevel.

GetDataAsImage(CommandList)

Copies the contents of the Texture on GPU memory to an Image on the CPU.

public Image GetDataAsImage(CommandList commandList)

Parameters

commandList CommandList: The CommandList where to register the command.

Returns

Image: The Image on CPU memory.

GetDataAsImage(CommandList, Texture)

Gets the contents of the Texture on GPU memory to an Image on the CPU.

public Image GetDataAsImage(CommandList commandList, Texture stagingTexture)

Parameters

commandList CommandList: The CommandList where to register the command.
stagingTexture Texture: The staging Texture used to temporarily transfer the image from GPU memory to CPU memory.

Returns

Image: The Image on CPU memory.

Exceptions

ArgumentException: stagingTexture is not a staging Texture.
ArgumentNullException: stagingTexture is null.

GetData<T>(CommandList, Texture, Span<T>, int, int, bool)

Copies the contents of the Texture from GPU memory to CPU memory using a specific staging Resource.

public bool GetData<T>(CommandList commandList, Texture stagingTexture, Span<T> toData, int arrayIndex = 0, int mipLevel = 0, bool doNotWait = false) where T : unmanaged

Parameters

commandList CommandList

The CommandList where to register the command.

stagingTexture Texture

The staging Texture used to transfer the Texture contents to.

toData Span<T>

The data buffer in CPU memory to copy the Texture contents into.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to get the data from. By default, the first mip-level at index 0 is selected, which is the most detailed one.

doNotWait bool

Returns

bool: true if data was correctly retrieved; false if doNotWait flag was true and the resource is still being used by the GPU for writing.

Type Parameters

T

Exceptions

ArgumentException: The length of the destination buffer toData is not compatible with the expected largestSize for the data at arrayIndex and mipLevel.

GetData<TData>(CommandList, Texture, TData[], int, int, bool)

Copies the contents of the Texture from GPU memory to CPU memory using a specific staging Resource.

public bool GetData<TData>(CommandList commandList, Texture stagingTexture, TData[] toData, int arrayIndex = 0, int mipLevel = 0, bool doNotWait = false) where TData : unmanaged

Parameters

commandList CommandList

The CommandList where to register the command.

stagingTexture Texture

The staging Texture used to transfer the Texture contents to.

toData TData[]

The destination buffer to copy the Texture data into.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to get the data from. By default, the first mip-level at index 0 is selected, which is the most detailed one.

doNotWait bool

Returns

bool: true if data was correctly retrieved; false if doNotWait flag was true and the resource is still being used by the GPU for writing.

Type Parameters

TData: The type of the pixel data.

Exceptions

ArgumentException: The length of the destination buffer toData is not compatible with the expected largestSize for the data at arrayIndex and mipLevel.

GetData<TData>(CommandList, int, int)

Copies the contents of the Texture from GPU memory to CPU memory.

public TData[] GetData<TData>(CommandList commandList, int arrayIndex = 0, int mipLevel = 0) where TData : unmanaged

Parameters

commandList CommandList

The CommandList where to register the command.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to get the data from. By default, the first mip-level at index 0 is selected, which is the most detailed one.

Returns

TData[]: An array of TData with the Texture's data.

Type Parameters

TData: The type of the pixel data.

Remarks

This method is only working when called from the main thread that is accessing the main GraphicsDevice.

This method creates internally a staging Resource, copies the data into it, and maps it to CPU memory. You can use one of the methods that specify an explicit staging Resource for better performance.

GetData<TData>(CommandList, TData[], int, int, bool)

Copies the contents of the Texture from GPU memory to CPU memory.

public bool GetData<TData>(CommandList commandList, TData[] toData, int arrayIndex = 0, int mipLevel = 0, bool doNotWait = false) where TData : unmanaged

Parameters

commandList CommandList

The CommandList where to register the command.

toData TData[]

The destination buffer to copy the Texture data into.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to get the data from. By default, the first mip-level at index 0 is selected, which is the most detailed one.

doNotWait bool

Returns

bool: true if data was correctly retrieved; false if doNotWait flag was true and the resource is still being used by the GPU for writing.

Type Parameters

TData: The type of the pixel data.

Remarks

This method is only working when called from the main thread that is accessing the main GraphicsDevice.

GetMipMapDescription(int)

Gets the description a specific mipLevel of the Texture.

public ref readonly MipMapDescription GetMipMapDescription(int mipLevel)

Parameters

mipLevel int: The mipmap level to query.

Returns

MipMapDescription: A MipMapDescription describing the requested mipmap.

GetSubResourceIndex(int, int)

Returns the absolute sub-resource index from an array slice and mip-level.

public int GetSubResourceIndex(int arrayIndex, int mipLevel)

Parameters

arrayIndex int: The array index.
mipLevel int: The mip slice index.

Returns

int: The sub-resource absolute index, calculated as arrayIndex * Description.MipLevelCount + mipLevel.

IsDepthStencilReadOnlySupported(GraphicsDevice)

Checks if the specified GraphicsDevice supports binding a Depth-Stencil buffer as a read-only Render Target.

public static bool IsDepthStencilReadOnlySupported(GraphicsDevice device)

Parameters

device GraphicsDevice: The graphics device.

Returns

bool: true if the device supports binding a Depth-Stencil buffer as a read-only Render Target View; false otherwise.

See Also: HasDepthAsReadOnlyRT

Load(GraphicsDevice, Stream, TextureFlags, GraphicsResourceUsage, bool)

Loads a Texture from a stream.

public static Texture Load(GraphicsDevice device, Stream stream, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable, bool loadAsSrgb = false)

Parameters

device GraphicsDevice: The GraphicsDevice.
stream Stream: The stream to load the Texture from.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.
loadAsSrgb bool: true if the Texture should be loaded as an sRGB Texture; false to load it in its default format.

Returns

Texture: The loaded Texture.

New(GraphicsDevice, Image, TextureFlags, GraphicsResourceUsage)

Creates a new Texture from an Image.

public static Texture New(GraphicsDevice device, Image image, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable)

Parameters

device GraphicsDevice: The GraphicsDevice.
image Image: An Image to create the Texture from.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

Returns

Texture: The loaded Texture.

Exceptions

ArgumentNullException: device is null, or image is null.

New(GraphicsDevice, TextureDescription, params DataBox[])

Creates a new Texture with the specified description.

public static Texture New(GraphicsDevice graphicsDevice, TextureDescription description, params DataBox[] boxes)

Parameters

graphicsDevice GraphicsDevice
description TextureDescription: A TextureDescription for the new Texture.
boxes DataBox[]: An optional array of DataBox structures describing the initial data for all the sub-Resources of the new Texture.

Returns

Texture: The new Texture.

Exceptions

ArgumentNullException: graphicsDevice

New(GraphicsDevice, TextureDescription, TextureViewDescription, params DataBox[])

Creates a new Texture with the specified description.

public static Texture New(GraphicsDevice graphicsDevice, TextureDescription description, TextureViewDescription viewDescription, params DataBox[] boxes)

Parameters

graphicsDevice GraphicsDevice
description TextureDescription: A TextureDescription for the new Texture.
viewDescription TextureViewDescription: A TextureViewDescription describing a Texture View that will be created the same time.
boxes DataBox[]: An optional array of DataBox structures describing the initial data for all the sub-Resources of the new Texture.

Returns

Texture: The new Texture.

Exceptions

ArgumentNullException

graphicsDevice is null.

NotSupportedException

The Texture's Flags and the ViewFlags are not compatible. The parent Texture must include all the flags defined by the Texture View, or

The MultisampleCount is not supported for the specified Format. Check the Features for information about supported pixel formats and the compatible multi-sample counts.

New1D(GraphicsDevice, int, MipMapCount, PixelFormat, TextureFlags, int, GraphicsResourceUsage)

Creates a new one-dimensional (1D) Texture.

public static Texture New1D(GraphicsDevice device, int width, MipMapCount mipCount, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, int arraySize = 1, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

mipCount MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

format PixelFormat

The format to use.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

arraySize int

The number of array slices for the Texture. The default value is 1, indicating the Texture is not a Texture Array.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new one-dimensional Texture.

New1D(GraphicsDevice, int, PixelFormat, TextureFlags, int, GraphicsResourceUsage)

Creates a new one-dimensional (1D) Texture with a single mipmap.

public static Texture New1D(GraphicsDevice device, int width, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, int arraySize = 1, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice: The GraphicsDevice.
width int: The width of the Texture in texels.
format PixelFormat: The format to use.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
arraySize int: The number of array slices for the Texture. The default value is 1, indicating the Texture is not a Texture Array.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new one-dimensional Texture.

New1D(GraphicsDevice, int, PixelFormat, nint, TextureFlags, GraphicsResourceUsage)

Creates a new one-dimensional (1D) Texture with initial data and a single mipmap.

public static Texture New1D(GraphicsDevice device, int width, PixelFormat format, nint dataPtr, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable)

Parameters

device GraphicsDevice: The GraphicsDevice.
width int: The width of the Texture in texels.
format PixelFormat: The format to use.
dataPtr nint: A pointer to the data to upload to the Texture.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

Returns

Texture: A new one-dimensional Texture.

New1D<T>(GraphicsDevice, int, PixelFormat, T[], TextureFlags, GraphicsResourceUsage)

Creates a new one-dimensional (1D) Texture with initial data and a single mipmap.

public static Texture New1D<T>(GraphicsDevice device, int width, PixelFormat format, T[] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable) where T : unmanaged

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

format PixelFormat

The format to use.

textureData T[]

The initial data array to upload to the Texture. It must have a size (in bytes, not elements) equal to the size of the format times the width.

See PixelFormatExtensions.SizeInBytes(PixelFormat) for calculating the size of a pixel format.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

Returns

Texture: A new one-dimensional Texture.

Type Parameters

T: Type of the initial data to upload to the Texture.

New2D(GraphicsDevice, int, int, MipMapCount, PixelFormat, DataBox[], TextureFlags, int, GraphicsResourceUsage, MultisampleCount, TextureOptions)

Creates a new two-dimensional (2D) Texture with initial data.

public static Texture New2D(GraphicsDevice device, int width, int height, MipMapCount mipCount, PixelFormat format, DataBox[] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, int arraySize = 1, GraphicsResourceUsage usage = GraphicsResourceUsage.Default, MultisampleCount multisampleCount = MultisampleCount.None, TextureOptions options = TextureOptions.None)

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

height int

The height of the Texture in texels.

mipCount MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

format PixelFormat

The format to use.

textureData DataBox[]

An array of DataBox pointing to the initial Texture data for each of the mipmaps.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

arraySize int

The number of array slices for the Texture. The default value is 1, indicating the Texture is not a Texture Array.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

multisampleCount MultisampleCount

The number of samples per texel the Texture will have. The default value is None, indicating a non-multisampled Texture.

options TextureOptions

A combination of flags indicating options about the creation of the Texture, like creating it as a shared resource. The default value is None.

Returns

Texture: A new two-dimensional Texture.

New2D(GraphicsDevice, int, int, MipMapCount, PixelFormat, TextureFlags, int, GraphicsResourceUsage, TextureOptions)

Creates a new two-dimensional (2D) Texture.

public static Texture New2D(GraphicsDevice device, int width, int height, MipMapCount mipCount, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, int arraySize = 1, GraphicsResourceUsage usage = GraphicsResourceUsage.Default, TextureOptions options = TextureOptions.None)

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

height int

The height of the Texture in texels.

mipCount MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

format PixelFormat

The format to use.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

arraySize int

The number of array slices for the Texture. The default value is 1, indicating the Texture is not a Texture Array.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

options TextureOptions

A combination of flags indicating options about the creation of the Texture, like creating it as a shared resource. The default value is None.

Returns

Texture: A new two-dimensional Texture.

New2D(GraphicsDevice, int, int, PixelFormat, TextureFlags, int, GraphicsResourceUsage, TextureOptions)

Creates a new two-dimensional (2D) Texture with a single mipmap.

public static Texture New2D(GraphicsDevice device, int width, int height, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, int arraySize = 1, GraphicsResourceUsage usage = GraphicsResourceUsage.Default, TextureOptions options = TextureOptions.None)

Parameters

device GraphicsDevice: The GraphicsDevice.
width int: The width of the Texture in texels.
height int: The height of the Texture in texels.
format PixelFormat: The format to use.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
arraySize int: The number of array slices for the Texture. The default value is 1, indicating the Texture is not a Texture Array.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.
options TextureOptions: A combination of flags indicating options about the creation of the Texture, like creating it as a shared resource. The default value is None.

Returns

Texture: A new two-dimensional Texture.

New2D<T>(GraphicsDevice, int, int, PixelFormat, T[], TextureFlags, GraphicsResourceUsage, TextureOptions)

Creates a new two-dimensional (2D) Texture with initial data and a single mipmap.

public static Texture New2D<T>(GraphicsDevice device, int width, int height, PixelFormat format, T[] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable, TextureOptions options = TextureOptions.None) where T : unmanaged

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

height int

The height of the Texture in texels.

format PixelFormat

The format to use.

textureData T[]

The initial data array to upload to the Texture for a single mipmap and a single array slice. It must have a size (in bytes, not elements) equal to the size of the format times (width * height).

See PixelFormatExtensions.SizeInBytes(PixelFormat) for calculating the size of a pixel format.

Each value in the data array will be a texel in the destination Texture.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

options TextureOptions

A combination of flags indicating options about the creation of the Texture, like creating it as a shared resource. The default value is None.

Returns

Texture: A new two-dimensional Texture.

Type Parameters

T: Type of the initial data to upload to the Texture.

New3D(GraphicsDevice, int, int, int, MipMapCount, PixelFormat, DataBox[], TextureFlags, GraphicsResourceUsage)

Creates a new three-dimensional (3D) Texture (also known as a volume texture) with initial data.

public static Texture New3D(GraphicsDevice device, int width, int height, int depth, MipMapCount mipCount, PixelFormat format, DataBox[] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

height int

The height of the Texture in texels.

depth int

The depth of the Texture in texels.

mipCount MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

format PixelFormat

The format to use.

textureData DataBox[]

An array of DataBox pointing to the initial data to upload for each of the mipmaps. The first element will be the largest mipmap, and each successive element is for the smaller ones.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new three-dimensional Texture.

New3D(GraphicsDevice, int, int, int, MipMapCount, PixelFormat, TextureFlags, GraphicsResourceUsage)

Creates a new three-dimensional (3D) Texture (also known as a volume texture).

public static Texture New3D(GraphicsDevice device, int width, int height, int depth, MipMapCount mipCount, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

height int

The height of the Texture in texels.

depth int

The depth of the Texture in texels.

mipCount MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

format PixelFormat

The format to use.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new three-dimensional Texture.

New3D(GraphicsDevice, int, int, int, PixelFormat, TextureFlags, GraphicsResourceUsage)

Creates a new three-dimensional (3D) Texture (also known as a volume texture) with a single mipmap.

public static Texture New3D(GraphicsDevice device, int width, int height, int depth, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice: The GraphicsDevice.
width int: The width of the Texture in texels.
height int: The height of the Texture in texels.
depth int: The depth of the Texture in texels.
format PixelFormat: The format to use.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new three-dimensional Texture.

New3D<T>(GraphicsDevice, int, int, int, PixelFormat, T[], TextureFlags, GraphicsResourceUsage)

Creates a new three-dimensional (3D) Texture (also known as a volume texture) with initial data and a single mipmap.

public static Texture New3D<T>(GraphicsDevice device, int width, int height, int depth, PixelFormat format, T[] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable) where T : unmanaged

Parameters

device GraphicsDevice

The GraphicsDevice.

width int

The width of the Texture in texels.

height int

The height of the Texture in texels.

depth int

The depth of the Texture in texels.

format PixelFormat

The format to use.

textureData T[]

See PixelFormatExtensions.SizeInBytes(PixelFormat) for calculating the size of a pixel format.

Each value in the data array will be a texel in the destination Texture.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

Returns

Texture: A new three-dimensional Texture.

Type Parameters

T: Type of the initial data to upload to the Texture.

NewCube(GraphicsDevice, int, MipMapCount, PixelFormat, TextureFlags, GraphicsResourceUsage)

Creates a new cube-map composed of six two-dimensional (2D) Textures.

public static Texture NewCube(GraphicsDevice device, int size, MipMapCount mipCount, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice

The GraphicsDevice.

size int

The size in texels of the faces of the cube Texture. As the Texture is a cube, this single value specifies both the width and the height.

mipCount MipMapCount

You can also specify a number (which will be converted implicitly) or a bool. See MipMapCount for more information about accepted values.

format PixelFormat

The format to use.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new cube-map Texture.

NewCube(GraphicsDevice, int, PixelFormat, DataBox[], TextureFlags, GraphicsResourceUsage)

Creates a new cube-map composed of six two-dimensional (2D) Textures from a initial data.

public static Texture NewCube(GraphicsDevice device, int size, PixelFormat format, DataBox[] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable)

Parameters

device GraphicsDevice: The GraphicsDevice.
size int: The size in texels of the faces of the cube Texture. As the Texture is a cube, this single value specifies both the width and the height.
format PixelFormat: The format to use.
textureData DataBox[]: An array of DataBox pointing to the initial Texture data for each of cube faces. There must be exactly six.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

Returns

Texture: A new cube-map Texture.

Remarks

The first dimension of mipMapTextures describes the number of array (TextureCube Array), the second is the texture data for a particular cube face.

Exceptions

ArgumentException: The Texture data is invalid. There must be exactly six elements in the array.

NewCube(GraphicsDevice, int, PixelFormat, TextureFlags, GraphicsResourceUsage)

Creates a new cube-map composed of six two-dimensional (2D) Textures.

public static Texture NewCube(GraphicsDevice device, int size, PixelFormat format, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Default)

Parameters

device GraphicsDevice: The GraphicsDevice.
size int: The size in texels of the faces of the cube Texture. As the Texture is a cube, this single value specifies both the width and the height.
format PixelFormat: The format to use.
textureFlags TextureFlags: A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.
usage GraphicsResourceUsage: A combination of flags determining how the Texture will be used during rendering. The default is Default, meaning it will need read/write access by the GPU.

Returns

Texture: A new cube-map Texture.

NewCube<T>(GraphicsDevice, int, PixelFormat, T[][], TextureFlags, GraphicsResourceUsage)

Creates a new cube-map composed of six two-dimensional (2D) Textures from a initial data.

public static Texture NewCube<T>(GraphicsDevice device, int size, PixelFormat format, T[][] textureData, TextureFlags textureFlags = TextureFlags.ShaderResource, GraphicsResourceUsage usage = GraphicsResourceUsage.Immutable) where T : unmanaged

Parameters

device GraphicsDevice

The GraphicsDevice.

size int

The size in texels of the faces of the cube Texture. As the Texture is a cube, this single value specifies both the width and the height.

format PixelFormat

The format to use.

textureData T[][]

The initial data array to upload to the Texture for a single mipmap. It is an array of arrays (two dimensions):

The first dimension of the array is the index of the cube face. There must be exactly six.
The second dimension is the data for each of the cube faces. It must have a size (in bytes, not elements) equal to the size of the format times (size * size).

See PixelFormatExtensions.SizeInBytes(PixelFormat) for calculating the size of a pixel format.

Each value in the data array of each of the cube faces will be a texel in the destination Texture.

textureFlags TextureFlags

A combination of flags determining what kind of Texture and how the is should behave (i.e. how it is bound, how can it be read / written, etc.). By default, it is ShaderResource.

usage GraphicsResourceUsage

A combination of flags determining how the Texture will be used during rendering. The default is Immutable, meaning it will need read access by the GPU.

Returns

Texture: A new cube-map Texture.

Type Parameters

T: Type of the initial data to upload to the Texture.

Exceptions

ArgumentException: The Texture data is invalid. The first dimension of textureData array must be equal to 6.

OnDestroyed(bool)

Called when the GraphicsDevice has been detected to be internally destroyed, or when the Destroy() methad has been called. Raises the Destroyed event.

protected override void OnDestroyed(bool immediately = false)

Parameters

immediately bool: A value indicating whether the Texture should be destroyed immediately (true), or if it can be deferred until it's safe to do so (false).

Remarks

This method releases all the native resources associated with the Texture:

If it is a Texture, this releases the underlying native texture resource and also the associated Views.
If it is a Texture View, it releases only the resources related to the View, not the parent Texture's.

OnRecreate()

Called when the GraphicsDevice has been recreated.

protected override bool OnRecreate()

Returns

bool: true if resource has transitioned to the Active state.

Recreate(DataBox[])

Recreates the Texture from the specified data.

public void Recreate(DataBox[] dataBoxes = null)

Parameters

dataBoxes DataBox[]: An array of DataBox structures pointing to the data for all the subresources to initialize for the Texture.

ReleaseData()

Releases the Texture data.

public void ReleaseData()

Save(CommandList, Stream, ImageFileType)

Saves the Texture to a stream with the specified image format.

public void Save(CommandList commandList, Stream stream, ImageFileType fileType)

Parameters

commandList CommandList: The CommandList where to register the command.
stream Stream: The stream to write the Texture contents to.
fileType ImageFileType: The type of the image file to create.

Exceptions

ArgumentNullException: stream is null.

Save(CommandList, Stream, Texture, ImageFileType)

Saves the Texture to a stream with a specified format.

public void Save(CommandList commandList, Stream stream, Texture stagingTexture, ImageFileType fileType)

Parameters

commandList CommandList: The CommandList where to register the command.
stream Stream: The stream to write the Texture to.
stagingTexture Texture: The staging Texture used to temporarily transfer the image from GPU memory to CPU memory.
fileType ImageFileType: The type of the image file to create.

Exceptions

ArgumentException: stagingTexture is not a staging Texture.

SetData(CommandList, DataPointer, int, int, ResourceRegion?)

Copies the contents of a data buffer on CPU memory into the Texture in GPU memory.

[Obsolete("This method is obsolete. Use the Span-based methods instead")]
public void SetData(CommandList commandList, DataPointer fromData, int arrayIndex = 0, int mipLevel = 0, ResourceRegion? region = null)

Parameters

commandList CommandList

The CommandList where to register the command.

fromData DataPointer

A ptrFromData to the data buffer to copy from.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to copy the data to. By default, the first mip-level at index 0 is selected, which is the most detailed one.

region ResourceRegion?

An optional ResourceRegion describing the region of data of the Texture to copy into. Specify null to copy to the whole sub-Resource at arrayIndex/mipLevel.

Remarks

See MapSubResource(GraphicsResource, int, MapMode, bool, int, int) and UpdateSubResource(GraphicsResource, int, DataBox, ResourceRegion) for more information about usage and restrictions.

Exceptions

ArgumentException: The length of fromData is not compatible with the expected largestSize for the data at arrayIndex and mipLevel. This can also occur when the stride is different from the optimal stride, and TData is not the same largestSize as the largestSize of Format.
ArgumentException: region can only be specified (non-null) for Textures with Default.
ArgumentOutOfRangeException: The region largestSize (in any of its dimensions) cannot be greater than the mip-level largestSize.

SetData<TData>(CommandList, ReadOnlySpan<TData>, int, int, ResourceRegion?)

Copies the contents of a data buffer on CPU memory into the Texture in GPU memory.

public void SetData<TData>(CommandList commandList, ReadOnlySpan<TData> fromData, int arrayIndex = 0, int mipLevel = 0, ResourceRegion? region = null) where TData : unmanaged

Parameters

commandList CommandList

The CommandList where to register the command.

fromData ReadOnlySpan<TData>

The data buffer to copy from.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to copy the data to. By default, the first mip-level at index 0 is selected, which is the most detailed one.

region ResourceRegion?

An optional ResourceRegion describing the region of data of the Texture to copy into. Specify null to copy to the whole sub-Resource at arrayIndex/mipLevel.

Type Parameters

TData: The type of the pixel data.

Remarks

See MapSubResource(GraphicsResource, int, MapMode, bool, int, int) and UpdateSubResource(GraphicsResource, int, DataBox, ResourceRegion) for more information about usage and restrictions.

Exceptions

ArgumentException: The length of fromData is not compatible with the expected largestSize for the data at arrayIndex and mipLevel. This can also occur when the stride is different from the optimal stride, and TData is not the same largestSize as the largestSize of Format.
ArgumentException: region can only be specified (non-null) for Textures with Default.
ArgumentOutOfRangeException: The region largestSize (in any of its dimensions) cannot be greater than the mip-level largestSize.

SetData<TData>(CommandList, TData[], int, int, ResourceRegion?)

Copies the contents of an array of data on CPU memory into the Texture in GPU memory.

public void SetData<TData>(CommandList commandList, TData[] fromData, int arrayIndex = 0, int mipLevel = 0, ResourceRegion? region = null) where TData : unmanaged

Parameters

commandList CommandList

The CommandList where to register the command.

fromData TData[]

The data buffer to copy from.

arrayIndex int

The array index. If the Texture is not a Texture Array or a Cube-map, only a single array slice will exist with index 0, which is the default value.

This index must be 0 for a three-dimensional Texture.

mipLevel int

The mip-level to copy the data to. By default, the first mip-level at index 0 is selected, which is the most detailed one.

region ResourceRegion?

An optional ResourceRegion describing the region of data of the Texture to copy into. Specify null to copy to the whole sub-Resource at arrayIndex/mipLevel.

Type Parameters

TData: The type of the pixel data.

Remarks

See MapSubResource(GraphicsResource, int, MapMode, bool, int, int) and UpdateSubResource(GraphicsResource, int, DataBox, ResourceRegion) for more information about usage and restrictions.

Exceptions

ArgumentException: The length of fromData is not compatible with the expected largestSize for the data at arrayIndex and mipLevel. This can also occur when the stride is different from the optimal stride, and TData is not the same largestSize as the largestSize of Format.
ArgumentException: region can only be specified (non-null) for Textures with Default.
ArgumentOutOfRangeException: The region largestSize (in any of its dimensions) cannot be greater than the mip-level largestSize.

ToStaging()

Creates a new Texture with the needed changes to serve as a staging Texture that can be read / written by the CPU.

public Texture ToStaging()

Returns

Texture: The equivalent staging Texture.

ToTextureView(TextureViewDescription)

Gets a Texture View on this Texture.

public Texture ToTextureView(TextureViewDescription viewDescription)

Parameters

viewDescription TextureViewDescription: The description of the Texture View to create.

Returns

Texture: A new Texture that represents the requested Texture View.

Exceptions

NotSupportedException

The Texture's Flags and the ViewFlags are not compatible. The parent Texture must include all the flags defined by the Texture View, or

The MultisampleCount is not supported for the specified Format. Check the Features for information about supported pixel formats and the compatible multi-sample counts.

Table of Contents

Class Texture

Remarks

Constructors

Texture()

Properties

ArraySize

Property Value

Remarks

ArraySlice

Property Value

Remarks

Depth

Property Value

Description

Property Value

Dimension

Property Value

Flags

Property Value

Format

Property Value

FullQualitySize

Property Value

Height

Property Value

IsBlockCompressed

Property Value

IsDepthStencil

Property Value

IsDepthStencilReadOnly

Property Value

IsMultiSampled

Property Value

IsRenderTarget

Property Value

IsShaderResource

Property Value

IsUnorderedAccess

Property Value

MipLevel

Property Value

Remarks

MipLevelCount

Property Value

MultisampleCount

Property Value

Remarks

Options

Property Value

SharedHandle

Property Value

SharedNtHandleName

Property Value

Size

Property Value

Usage

Property Value

ViewDepth

Property Value

ViewDescription

Property Value

ViewDimension

Property Value

ViewFlags

Property Value

ViewFormat

Property Value

ViewHeight

Property Value

ViewType

Property Value

ViewWidth

Property Value

Width

Property Value

Methods

CalculateMipSize(int, int)

Parameters

Returns