ID3D12GraphicsCommandList::ExecuteIndirectBundleX Method

Indirectly executes a bundle from a buffer, where a bundle is a GPU command buffer representation of GPU draws and state setting. This API allows for more efficient creation and management of bundles than can be achieved with the standard ExecuteBundle API.

Syntax

public:
void ExecuteIndirectBundleX(
         ID3D12Resource *pBundleBuffer,
         UINT BundleBufferOffset,
         UINT MaxSize,
         ID3D12Resource *pSizeBuffer,
         UINT SizeBufferOffset,
         UINT PredicationBufferOffset
)

Parameters

pBundleBuffer
Type: ID3D12Resource *

[in] Specifies a pointer to a buffer resource that contains bundle data. The buffer must have been created with the D3D12XBOX_RESOURCE_FLAG_ALLOW_INDIRECT_BUFFER attribute set or otherwise be located in PAGE_GPU_EXECUTE memory.

BundleBufferOffset
Type: UINT

[in] Offset (in bytes) from the start of the bundle buffer to the beginning of the bundle data. Must be a multiple of 4.

MaxSize
Type: UINT

[in] There are two ways that the bundle size can be specified:

If pSizeBuffer is NULL, then MaxSize specifies the exact number of bytes of the bundle to be executed.
If pSizeBuffer is not NULL, then MaxSize specifies the maximum number of bytes which will be executed. If at GPU execution time the size specified by pSizeBuffer exceeds MaxSize, then the GPU will completely discard the execution of the bundle. This is useful to avoid a GPU hang when the GPU is used to create the bundle and the data overflows its allotted budget.

Bundles cannot exceed 4 MB in size.

pSizeBuffer
Type: ID3D12Resource *

[in, optional] Specifies a buffer resource (ID3D12Resource) that contains a 32-bit size in bytes. This is used for GPU-generated sizes.

SizeBufferOffset
Type: UINT

[in] Offset (in bytes) from the start of the size buffer to the 32-bit size in bytes.

PredicationBufferOffset
Type: UINT

[in] Reserved for future use and must be zero.

Return value

Type: void

Returns nothing.

Remarks

This API enables “Build-Your-Own-Bundles” functionality whereby a caller can create GPU command buffers using their own CPU or GPU code, at run-time or offline. The bundle memory can additionally be explicitly managed. Both of these attributes contrast with the standard ExecuteBundle API where creation of the bundles can be done only at run-time on the CPU using D3D APIs, and with significant object memory overhead.

“Build-Your-Own-Bundles” can contain all of the same sort of Draws and state changes that can be recorded into regular bundles. This set includes all high frequency D3D APIs, but no low frequency D3D APIs such as those for setting render targets or clears. The Xbox One’s GPU Command Processor natively implements these APIs with very straightforward packet encodings. Use the D3D12XBOX_PACKET_* defines in the d3d12_x.h header in conjunction with Pipeline State object and Root Signature object introspection to create the command buffer data. Use the inlined functions in d3d12_x.h as a reference for how to do this; no additional documentation is provided beyond what is in the header.

Note that the packet data for Pipeline State objects is good only during the lifetime of that Pipeline State object. This means that if a bundle is created offline, then all SetPipelineState invocations within that bundle must be fixed up to reflect the run-time created versions of those Pipeline State objects before the bundle can be executed by the GPU. Similarly, any pointer data recorded offline into a bundle (such as for descriptor tables) must be fixed up at run-time before execution.

ExecuteIndirectBundleX cannot itself be invoked from a bundle.

Note the use of NopX to add no-operation padding to a Command List.

To execute a command list before it is closed, refer to CreateCommandListX and CloseBundleX.

Requirements

Header: Declared in d3d12_x.h.

Library: Use d3d12_x.lib.