Método ID3D12GraphicsCommandList::Reset (d3d12.h)

Artículo
02/26/2024

Restablece una lista de comandos a su estado inicial como si se acaba de crear una nueva lista de comandos.

Sintaxis

HRESULT Reset(
  [in]           ID3D12CommandAllocator *pAllocator,
  [in, optional] ID3D12PipelineState    *pInitialState
);

Parámetros

[in] pAllocator

Tipo: ID3D12CommandAllocator*

Puntero al objeto ID3D12CommandAllocator desde el que el dispositivo crea listas de comandos.

[in, optional] pInitialState

Tipo: ID3D12PipelineState*

Puntero al objeto ID3D12PipelineState que contiene el estado de canalización inicial de la lista de comandos. Esto es opcional y puede ser NULL. Si es NULL, el tiempo de ejecución establece un estado de canalización inicial ficticio para que los controladores no tengan que tratar con el estado indefinido. La sobrecarga para esto es baja, especialmente para una lista de comandos, para la que el costo total de grabación de la lista de comandos probablemente enano el costo de una configuración de estado inicial. Por lo tanto, hay poco costo al no establecer el parámetro de estado de canalización inicial si no es cómodo.

Por otro lado, en el caso de los conjuntos, es posible que tenga más sentido intentar establecer el parámetro de estado inicial, ya que es probable que los conjuntos sean más pequeños en general y se puedan reutilizar con frecuencia.

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se ejecuta correctamente; de lo contrario, devuelve uno de los valores siguientes:

E_FAIL si la lista de comandos no estaba en el estado "cerrado" cuando se realizó la llamada de restablecimiento o se habría superado el límite por dispositivo.
E_OUTOFMEMORY si el sistema operativo se quedó sin memoria.
E_INVALIDARG si el asignador se está usando actualmente con otra lista de comandos en el estado de "grabación" o si el asignador especificado se creó con el tipo incorrecto.

Consulte Códigos de retorno de Direct3D 12 para ver otros valores devueltos posibles.

Comentarios

Con Reset, puede volver a usar estructuras de seguimiento de listas de comandos sin asignaciones. A diferencia de ID3D12CommandAllocator::Reset, puede llamar a Reset mientras se sigue ejecutando la lista de comandos. Un patrón típico es enviar una lista de comandos y, a continuación, restablecerla inmediatamente para reutilizar la memoria asignada para otra lista de comandos.

Puede usar Reset para listas de comandos directos y agrupaciones.

El asignador de comandos que Reset toma como entrada se puede asociar a no más de una lista de comandos de grabación a la vez. El tipo de asignador, lista de comandos directos o agrupación, debe coincidir con el tipo de lista de comandos que se está creando.

Si un lote no especifica un montón de recursos, no puede realizar cambios en las tablas de descriptor que están enlazadas. En cualquier caso, las agrupaciones no pueden cambiar el montón de recursos dentro de la agrupación. Si se especifica un montón para una agrupación, el montón debe coincidir con el montón de comandos "primario" que llama.

Validación en tiempo de ejecución

Antes de que una aplicación llame a Reset, la lista de comandos debe estar en estado "cerrado". Se producirá un error en el restablecimiento si la lista de comandos no está en estado "cerrado".

Nota Si se produce un error en una llamada a ID3D12GraphicsCommandList::Close , la lista de comandos nunca se puede restablecer. Al llamar a Reset , se devolverá el mismo error que id3D12GraphicsCommandList::Close devuelto.

Una vez que el restablecimiento se realiza correctamente, la lista de comandos se deja en el estado de "grabación". Se producirá un error en el restablecimiento si provocaría que se superara el límite máximo de lista de comandos de grabación simultánea, que se especifica en la creación del dispositivo.

Las aplicaciones deben especificar un asignador de lista de comandos. El tiempo de ejecución garantizará que un asignador nunca esté asociado a más de una lista de comandos de grabación al mismo tiempo.

Se produce un error en el restablecimiento de los conjuntos a los que hace referencia una lista de comandos aún no enviada.

Capa de depuración

La capa de depuración también realizará un seguimiento del progreso de la unidad de procesamiento de gráficos (GPU) y emitirá un error si no puede demostrar que no hay ejecuciones pendientes de la lista de comandos.

Ejemplos

El ejemplo D3D12HelloTriangle usa ID3D12GraphicsCommandList::Reset de la siguiente manera:

D3D12_VIEWPORT m_viewport;
D3D12_RECT m_scissorRect;
ComPtr<IDXGISwapChain3> m_swapChain;
ComPtr<ID3D12Device> m_device;
ComPtr<ID3D12Resource> m_renderTargets[FrameCount];
ComPtr<ID3D12CommandAllocator> m_commandAllocator;
ComPtr<ID3D12CommandQueue> m_commandQueue;
ComPtr<ID3D12RootSignature> m_rootSignature;
ComPtr<ID3D12DescriptorHeap> m_rtvHeap;
ComPtr<ID3D12PipelineState> m_pipelineState;
ComPtr<ID3D12GraphicsCommandList> m_commandList;
UINT m_rtvDescriptorSize;

void D3D12HelloTriangle::PopulateCommandList()
{
    // Command list allocators can only be reset when the associated 
    // command lists have finished execution on the GPU; apps should use 
    // fences to determine GPU execution progress.
    ThrowIfFailed(m_commandAllocator->Reset());

    // However, when ExecuteCommandList() is called on a particular command 
    // list, that command list can then be reset at any time and must be before 
    // re-recording.
    ThrowIfFailed(m_commandList->Reset(m_commandAllocator.Get(), m_pipelineState.Get()));

    // Set necessary state.
    m_commandList->SetGraphicsRootSignature(m_rootSignature.Get());
    m_commandList->RSSetViewports(1, &m_viewport);
    m_commandList->RSSetScissorRects(1, &m_scissorRect);

    // Indicate that the back buffer will be used as a render target.
    m_commandList->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_PRESENT, D3D12_RESOURCE_STATE_RENDER_TARGET));

    CD3DX12_CPU_DESCRIPTOR_HANDLE rtvHandle(m_rtvHeap->GetCPUDescriptorHandleForHeapStart(), m_frameIndex, m_rtvDescriptorSize);
    m_commandList->OMSetRenderTargets(1, &rtvHandle, FALSE, nullptr);

    // Record commands.
    const float clearColor[] = { 0.0f, 0.2f, 0.4f, 1.0f };
    m_commandList->ClearRenderTargetView(rtvHandle, clearColor, 0, nullptr);
    m_commandList->IASetPrimitiveTopology(D3D_PRIMITIVE_TOPOLOGY_TRIANGLELIST);
    m_commandList->IASetVertexBuffers(0, 1, &m_vertexBufferView);
    m_commandList->DrawInstanced(3, 1, 0, 0);

    // Indicate that the back buffer will now be used to present.
    m_commandList->ResourceBarrier(1, &CD3DX12_RESOURCE_BARRIER::Transition(m_renderTargets[m_frameIndex].Get(), D3D12_RESOURCE_STATE_RENDER_TARGET, D3D12_RESOURCE_STATE_PRESENT));

    ThrowIfFailed(m_commandList->Close());
}

Vea Código de ejemplo en la referencia D3D12.