XG_USAGE Enumeration

Identifies expected resource use during rendering. The usage directly reflects whether a resource is accessible by the CPU and/or the graphics processing unit (GPU).

Syntax

enum XG_USAGE
{
    XG_USAGE_DEFAULT = 0,
    XG_USAGE_IMMUTABLE = 1,
    XG_USAGE_DYNAMIC = 2,
    XG_USAGE_STAGING = 3
};

Constants

Constant	Description
XG_USAGE_DEFAULT	A resource that requires read and write access by the GPU. This is likely to be the most common usage choice.
XG_USAGE_IMMUTABLE	A resource that can only be read by the GPU. It cannot be written by the GPU, and cannot be accessed at all by the CPU. This type of resource must be initialized when it is created, since it cannot be changed after creation.
XG_USAGE_DYNAMIC	A resource that is accessible by both the GPU (read only) and the CPU (write only). A dynamic resource is a good choice for a resource that will be updated by the CPU at least once per frame. To update a dynamic resource, use a Map method. XG_USAGE_DYNAMIC (or D3D11_USAGE_DYNAMIC) is not supported for offline/placement resources. If you try to use this enumeration constant for offline/placement resources, the create texture computer functions (such as XGCreateTexture1DComputer) or the compute texture layout functions (such as XGComputeTexture1DLayout) will return E_INVALIDARGS.
XG_USAGE_STAGING	A resource that supports data transfer (copy) from the GPU to the CPU.

Remarks

XG_USAGE is the same as D3D11_USAGE.

An application identifies the way a resource is intended to be used (its usage) in a resource description. There are several structures for creating resources including: XG_TEXTURE1D_DESC, XG_TEXTURE2D_DESC, XG_TEXTURE3D_DESC, XG_BUFFER_DESC.

An app does not specify what type of memory (the pool) to create a resource in. Instead, you specify the intended usage of the resource, and let the runtime (in concert with the driver and a memory manager) choose the type of memory that will achieve the best performance.

Resource Usage Restrictions

Each usage dictates a tradeoff between accessibility for the CPU and accessibility for the graphics processing unit (GPU). In general, higher-performance access for one of these two processors means lower-performance access for the other. At either extreme are the XG_USAGE_DEFAULT and XG_USAGE_STAGING usages. XG_USAGE_DEFAULT restricts access almost entirely to the graphics processing unit (GPU). XG_USAGE_STAGING restricts access almost entirely to the CPU and allows only a data transfer (copy) of a resource between the graphics processing unit (GPU) and the CPU. You can perform these copy operations via the ID3D11DeviceContext::CopySubresourceRegion and ID3D11DeviceContext::CopyResource methods. You can also use these copy methods to copy data between two resources of the same usage. You can also use the ID3D11DeviceContext::UpdateSubresource method to copy memory directly from a CPU-supplied pointer to any resource, most usefully a resource with XG_USAGE_DEFAULT.

XG_USAGE_DYNAMIC usage is a special case that optimizes the flow of data from CPU to graphics processing unit (GPU) when the CPU generates that data on-the-fly and sends that data with high frequency. XG_USAGE_DYNAMIC is typically used on resources with vertex data and on constant buffers. Use the ID3D11DeviceContext::Map and ID3D11DeviceContext::Unmap methods to write data to these resources. To achieve the highest performance for data consumed serially, like vertex data, use the D3D11_MAP_WRITE_NO_OVERWRITE and D3D11_MAP_WRITE_DISCARD sequence. For more info about this sequence, see Common Usage of D3D11_MAP_WRITE_DISCARD with D3D11_MAP_WRITE_NO_OVERWRITE.

XG_USAGE_IMMUTABLE usage is another special case that causes the graphics processing unit (GPU) to generate data just once when you create a resource. XG_USAGE_IMMUTABLE is well-suited to data such as textures because such data is typically read into memory from some file format. Therefore, when you create a texture with XG_USAGE_IMMUTABLE, the graphics processing unit (GPU) directly reads that texture into memory.

Use the following table to choose the usage that best describes how the resource will need to be accessed by the CPU and/or the GPU. There are performance tradeoffs.

Resource Usage	Default	Dynamic	Immutable	Staging
GPU-Read	yes	yes	yes	yes¹
GPU-Write	yes			yes¹

CPU-Read				yes¹
CPU-Write		yes		yes¹

1 - graphics processing unit (GPU) read or write of a resource with the XG_USAGE_STAGING usage is restricted to copy operations. You use ID3D11DeviceContext::CopySubresourceRegion and ID3D11DeviceContext::CopyResource for these copy operations. Also, because depth-stencil formats and multisample layouts are implementation details of a particular graphics processing unit (GPU) design, the operating system can’t expose these formats and layouts to the CPU in general. Therefore, staging resources can’t be a depth-stencil buffer or a multisampled render target.

Note

You can technically use ID3D11DeviceContext::UpdateSubresource to copy to a resource with any usage except XG_USAGE_IMMUTABLE. However, we recommend to use ID3D11DeviceContext::UpdateSubresource to update only a resource with XG_USAGE_DEFAULT. We recommend to use ID3D11DeviceContext::Map and ID3D11DeviceContext::Unmap to update resources with XG_USAGE_DYNAMIC because that is the specific purpose of XG_USAGE_DYNAMIC resources, and is therefore the most optimized path.

Note

XG_USAGE_DYNAMIC resources consume specific hardware capabilities. Therefore, use them sparingly. The display driver typically allocates memory for XG_USAGE_DYNAMIC resources with a caching algorithm that favors CPU writes and hinders CPU reads. Furthermore, the memory behind XG_USAGE_DYNAMIC resources might not even be the same for successive calls to ID3D11DeviceContext::Map. Therefore, do not expect high performance or even consistent CPU reads from XG_USAGE_DYNAMIC resources.

Note

ID3D11DeviceContext::CopyStructureCount is a special case of GPU-to-CPU copy. Use ID3D11DeviceContext::CopyStructureCount only with unordered access views (UAVs) of buffers.

Resource Bind Options

To maximize performance, not all resource usage options can be used as input or output resources to the pipeline. This table identifies these limitations.

Resource Can Be Bound As	Default	Dynamic	Immutable	Staging
Input to a Stage	yes²	yes³	yes
Output from a Stage	yes²

2 - If bound as an input and an output using different views, each view must use different subresources.
3 - The resource can only be created with a single subresource. The resource cannot be a texture array. The resource cannot be a mipmap chain.

Requirements

Header: Declared in xg.h.

Library: Use xg_x.lib.