Метод ID3D12GraphicsCommandList::Reset (d3d12.h)

Статья
06/27/2024

Сбрасывает список команд обратно в исходное состояние, как если бы новый список команд был только что создан.

Синтаксис

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

Параметры

[in] pAllocator

Тип: ID3D12CommandAllocator*

Указатель на объект ID3D12CommandAllocator, из которой устройство создает списки команд.

[in, optional] pInitialState

Тип: ID3D12PipelineState*

Указатель на объект ID3D12PipelineState, содержащий начальное состояние конвейера для списка команд. Это необязательно и может иметь значение NULL. Если значение NULL, среда выполнения задает фиктивное начальное состояние конвейера, чтобы драйверы не должны иметь дело с неопределенным состоянием. Затраты на это низкие, особенно для списка команд, для которых общая стоимость записи списка команд, скорее всего, затмевает стоимость одного начального параметра состояния. Поэтому мало затрат при настройке начального параметра состояния конвейера, если это не удобно.

С другой стороны, для пакетов может быть больше смысла пытаться задать начальный параметр состояния, так как пакеты, скорее всего, меньше и часто используются повторно.

Возвращаемое значение

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения; в противном случае возвращает одно из следующих значений:

E_FAIL, если список команд не был в состоянии "закрытый" при вызове сброса или превышен предел на устройство.
E_OUTOFMEMORY, если операционная система не хватает памяти.
E_INVALIDARG, если в настоящее время распределитель используется с другим списком команд в состоянии записи или если указанный распределитель был создан с неправильным типом.

Дополнительные возможные значения возвращаемых значений см. в Direct3D 12 Return Code.

Замечания

С помощью сбросаможно повторно использовать структуры отслеживания списков команд без выделения. В отличие от ID3D12CommandAllocator::Reset, можно вызывать сброс во время выполнения списка команд.

Для прямых списков команд и пакетов можно использовать сброса.

Распределитель команд, переданный сброс не может быть связан с любым другим списком команд записи в настоящее время. Тип распределителя, прямой список команд или пакет, должен соответствовать типу создаваемого списка команд.

Если пакет не указывает кучу ресурсов, он не может вносить изменения, к которым привязаны таблицы дескриптора. В любом случае пакеты не могут изменить кучу ресурсов в пакете. Если куча указана для пакета, куча должна соответствовать кучи вызывающего "родительского" списка команд.

проверка среды выполнения

Прежде чем приложение вызывает Сброс, список команд должен находиться в состоянии "закрытый". сброс завершится ошибкой, если список команд не указан в состоянии "закрытый".

Примечание Если вызов ID3D12GraphicsCommandList::Close завершается ошибкой, список команд никогда не может быть сброшен. Вызов Сброс приведет к тому же ошибке, что возвращается ID3D12GraphicsCommandList::Close возвращено.

После успешного сброса список команд остается в состоянии записи. сброс завершится ошибкой, если это приведет к превышению максимального ограничения списка команд параллельной записи, указанного при создании устройства.

Приложения должны указать список команд. Среда выполнения гарантирует, что распределитель никогда не связан с несколькими списками команд записи одновременно.

сброс завершается ошибкой для пакетов, на которые ссылается список команд, на которые еще не отправлен список команд.

уровень отладки

Уровень отладки также отслеживает ход выполнения графической обработки (GPU) и выдает ошибку, если она не может доказать, что невыполненные выполнения списка команд отсутствуют.

Примеры

В примере D3D12HelloTriangle используется ID3D12GraphicsCommandList::Reset следующим образом:

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());
}

См. пример кода в справочнике по D3D12.