ID3D11DeviceContext::FinishCommandList Method

Create a command list and record graphics commands into it.

Syntax

public:
HRESULT FinishCommandList(
         BOOL RestoreDeferredContextState,
         ID3D11CommandList **ppCommandList
)

Parameters

RestoreDeferredContextState
Type: BOOL

A Boolean flag that determines whether the runtime saves deferred context state before it executes FinishCommandList and restores it afterwards. Use TRUE to indicate that the runtime needs to save and restore the state. Use FALSE to indicate that the runtime will not save or restore any state. In this case, the deferred context will return to its default state after the call to FinishCommandList completes. For information about default state, see ID3D11DeviceContext::ClearState. Typically, use FALSE unless you restore the state to be nearly equivalent to the state that the runtime would restore if you passed TRUE. When you use FALSE, you can avoid unnecessary and inefficient state transitions.

This parameter must be set to FALSE, if this method is being used with a Draw Bundle.

Note

This parameter does not affect the command list that the current call to FinishCommandList returns. However, this parameter affects the command list of the next call to FinishCommandList on the same deferred context.

ppCommandList
Type: ID3D11CommandList **

[out, optional] Upon completion of the method, the passed pointer to an ID3D11CommandList interface pointer is initialized with the recorded command list information.

Return value

Type: HRESULT

Returns S_OK if successful; otherwise, returns one of the following:

Returns DXGI_ERROR_DEVICE_REMOVED if the video card has been physically removed from the system, or a driver upgrade for the video card has occurred. If this error occurs, you should destroy and recreate the device.
Returns DXGI_ERROR_INVALID_CALL if FinishCommandList cannot be called from the current context. See remarks.
Returns E_OUTOFMEMORY if the application has exhausted available memory.

Remarks

Create a command list from a deferred context and record commands into it by calling FinishCommandList. Play back a command list with an immediate context by calling ID3D11DeviceContext::ExecuteCommandList.

Immediate context state is cleared before and after a command list is executed. A command list has no concept of inheritance. Each call to FinishCommandList will record only the state set since any previous call to FinishCommandList.

For example, the state of a device context is its render state or pipeline state. To retrieve device context state, an application can call ID3D11DeviceContext::GetData or ID3D11DeviceContext::GetPredication.

For more information about how to use FinishCommandList, see How to: Record a Command List.

Requirements

Header: Declared in d3d11_x.h (d3d11.h on other Windows platforms).