Home -> ITexelArray

Declaration

class ITexelArray;

Description

The ITexelArray interface defines an array of vector types containing up to four components. This maps to the concept of the Buffer/RWBuffer types in the HLSL shader language. This type is not limited to storing literal texel elements containing colour data, and can be used to encode any desired data that can be encoded into the supported data types. Additionally, an ITexelArray can be used to alias an IIndexBuffer or an IVertexBuffer, allowing these buffers to be written from a shader, such as a compute shader. It is also possible to schedule a transfer from one ITexelArray to another entirely on the GPU using the QueueDataTransfer method.

ImportantImportant

There are similarities between the IDataArray and the ITexelArray type. Both define potentially very large buffers of data, which can be read and written from both shaders and the CPU. There are distinct differences however. The ITexelArray type defines a regular array of vectors, with a specific list of supported types. Because the type is explicit and known by the hardware, automatic format conversion is supported for many data types when reading or writing from shaders. Additionally, an ITexelArray is able to alias an IIndexBuffer or an IVertexBuffer, allowing these buffers to be written from a shader, such as a compute shader. The IDataArray type on the other hand contains an array of structures, which are an arbitrary block of bytes. These data structures can be mapped to complex struct types within your shader, allowing a potentially large collection of differing types of values to be easily encoded in each entry of the array. The opaque nature of these structures to hardware however, means no automatic format conversion is possible, nor is it possible to alias an IIndexBuffer or IVertexBuffer. On the other hand, IDataArray can be used to perform indirect drawing, and atomic memory operations within shaders. You should consider the structure of your data and the features required, and select the array type which best fits your usage.

Enumerations

Name Description
Public Enum ImageFormat
The image format of the texel data on hardware, which represents the number of components and use of those components in the texel.
Public Enum DataFormat
The data format of the texel data on hardware, which represents the physical data encoding used for each component in the texel.
Public Enum SourceImageFormat
The image format of texel data in CPU memory, which represents the number of components and use of those components in the texel.
Public Enum SourceDataFormat
The data format of texel data in CPU memory, which represents the physical data encoding used for each component in the texel.
Public Enum UsageFlags
Flags to inform the renderer on how this data array will be used

Enumerations (Inherited from IResourceArray)

Name Description
Public Enum PerformanceHint
Flags to provide hints to the graphics system about how the application will use this buffer. Correct use of performance hints allows the renderer to optimize the way the data is stored and modified to give the best performance.
Public Enum DataPersistenceFlags
Flags to provide hints to the graphics system about the required lifetime of data stored in this buffer. These flags can be used to reduce memory requirements or increase performance in some circumstances.

Members

Initialization methods

Name Description
Public member Delete
Schedules the object for deletion. After calling this method, the object will be destroyed after the current frame completes drawing.
Public member AllocateMemory
Attempts to allocate memory for the buffer using the defined buffer layout
Public member SetBufferLayout
Defines the layout of the buffer. Must be set before calling AllocateMemory.

Usage methods

Name Description
Public member SetUsageFlags
Informs the renderer on how this buffer will be used. Certain operations are disallowed unless usage flags have been set to inform the renderer in advance that those operations may be requested.

Usage methods (Inherited from IResourceArray)

Name Description
Public member SetPerformanceHints
Provides hints to the renderer about how this object will be used. Correct use of hints is important to optimize performance.
Public member SetDataPersistenceFlags
Provides hints to the graphics system about the required lifetime of data stored in this buffer. This can be used to reduce memory requirements or increase performance in some circumstances.

Data methods

Name Description
Public member SetInitialData
Supplies initial data to use when allocating the buffer. Note that the supplied memory must remain valid and accessible until the AllocateMemory method is called.
Public member QueueDataUpdate
Updates data in the buffer. Unlike the SetInitialData method, the provided memory can be modified or deallocated immediately after this method returns.
Public member QueueDataTransfer
Schedules a transfer from one ITexelArray to another, within GPU memory.

Output capture methods

Name Description
Public member AddOutputCaptureTarget
Adds the specified output capture target to this texel array. This allows data written to the array from within shader programs to be retrieved by the application.
Public member RemoveOutputCaptureTarget
Removes the specified output capture target from this texel array.

Format helper methods

Name Description
Public member ElementCountPerPixelFromFormat
Returns the number of elements in each array entry for the specified image format.
Public member ByteSizePerElementFromFormat
Returns the byte size of each element for the specified data format.
Public member ImageFormatsAreBinaryEquivalent
Returns true if the supplied source and allocated image formats use binary compatible channel layouts.
Public member DataFormatsAreBinaryEquivalent
Returns true if the supplied source and allocated data formats use binary compatible data encodings.

See also