ID3D12Device::CreateCommittedResource-Methode (d3d12.h)

Artikel
08/23/2023

Erstellt sowohl eine Ressource als auch einen impliziten Heap, sodass der Heap groß genug ist, um die gesamte Ressource zu enthalten, und die Ressource dem Heap zugeordnet wird.

Syntax

HRESULT CreateCommittedResource(
  [in]            const D3D12_HEAP_PROPERTIES *pHeapProperties,
  [in]            D3D12_HEAP_FLAGS            HeapFlags,
  [in]            const D3D12_RESOURCE_DESC   *pDesc,
  [in]            D3D12_RESOURCE_STATES       InitialResourceState,
  [in, optional]  const D3D12_CLEAR_VALUE     *pOptimizedClearValue,
  [in]            REFIID                      riidResource,
  [out, optional] void                        **ppvResource
);

Parameter

[in] pHeapProperties

Typ: const D3D12_HEAP_PROPERTIES*

Ein Zeiger auf eine D3D12_HEAP_PROPERTIES-Struktur , die Eigenschaften für den Heap der Ressource bereitstellt.

[in] HeapFlags

Typ: D3D12_HEAP_FLAGS

Heapoptionen als bitweise OR'd Kombination aus D3D12_HEAP_FLAGS Enumerationskonstanten.

[in] pDesc

Typ: const D3D12_RESOURCE_DESC*

Ein Zeiger auf eine D3D12_RESOURCE_DESC Struktur, die die Ressource beschreibt.

[in] InitialResourceState

Typ: D3D12_RESOURCE_STATES

Der Anfangszustand der Ressource als bitweise OR'd-Kombination aus D3D12_RESOURCE_STATES Enumerationskonstanten.

Wenn Sie eine Ressource zusammen mit einem D3D12_HEAP_TYPE_UPLOAD Heap erstellen, müssen Sie InitialResourceState auf D3D12_RESOURCE_STATE_GENERIC_READ festlegen.

Wenn Sie eine Ressource zusammen mit einem D3D12_HEAP_TYPE_READBACK Heap erstellen, müssen Sie InitialResourceState auf D3D12_RESOURCE_STATE_COPY_DEST festlegen.

[in, optional] pOptimizedClearValue

Typ: const D3D12_CLEAR_VALUE*

Gibt eine D3D12_CLEAR_VALUE-Struktur an, die den Standardwert für eine klare Farbe beschreibt.

pOptimizedClearValue gibt einen Wert an, für den klare Vorgänge optimal sind. Wenn es sich bei der erstellten Ressource um eine Textur mit dem D3D12_RESOURCE_FLAG_ALLOW_RENDER_TARGET - oder D3D12_RESOURCE_FLAG_ALLOW_DEPTH_STENCIL-Flags handelt, sollten Sie den Wert auswählen, mit dem der Clear-Vorgang am häufigsten aufgerufen wird. Sie können den Clear-Vorgang mit anderen Werten aufrufen, aber diese Vorgänge sind nicht so effizient, wie wenn der Wert mit dem an die Ressourcenerstellung übergebenen Wert übereinstimmt.

Wenn Sie D3D12_RESOURCE_DIMENSION_BUFFER verwenden, müssen Sie pOptimizedClearValue auf nullptrfestlegen.

[in] riidResource

Typ: REFIID

Ein Verweis auf den Globally Unique Identifier (GUID) der Ressourcenschnittstelle, die in ppvResource zurückgegeben werden soll.

RiidResource ist zwar am häufigsten die GUID von ID3D12Resource, kann jedoch die GUID einer beliebigen Schnittstelle sein. Wenn das Ressourcenobjekt die Schnittstelle für diese GUID nicht unterstützt, schlägt die Erstellung mit E_NOINTERFACE fehl.

[out, optional] ppvResource

Typ: void**

Ein optionaler Zeiger auf einen Speicherblock, der den angeforderten Schnittstellenzeiger auf das erstellte Ressourcenobjekt empfängt.

ppvResource kann sein nullptr, um Funktionstests zu aktivieren. Wenn ppvResource ist nullptr, wird kein Objekt erstellt, und S_FALSE wird zurückgegeben, wenn pDesc gültig ist.

Rückgabewert

Typ: HRESULT

Wenn die Funktion erfolgreich ist, gibt sie S_OK zurück. Andernfalls wird ein HRESULT-Fehlercode zurückgegeben.

Rückgabewert	BESCHREIBUNG
E_OUTOFMEMORY	Es ist nicht genügend Arbeitsspeicher vorhanden, um die Ressource zu erstellen.

Weitere mögliche Rückgabewerte finden Sie unter Direct3D 12-Rückgabecodes .

Hinweise

Diese Methode erstellt sowohl eine Ressource als auch einen Heap, sodass der Heap groß genug ist, um die gesamte Ressource zu enthalten, und die Ressource dem Heap zugeordnet wird. Der erstellte Heap wird als impliziter Heap bezeichnet, da das Heapobjekt von der Anwendung nicht abgerufen werden kann. Bevor Sie den endgültigen Verweis auf die Ressource freigeben, muss Ihre Anwendung sicherstellen, dass die GPU diese Ressource nicht mehr liest oder schreibt.

Der implizite Heap wird für den GPU-Zugriff resident gemacht, bevor die Methode die Steuerung an Ihre Anwendung zurückgibt. Siehe auch Residency.

Die GPU-VA-Zuordnung der Ressource kann nicht geändert werden. Siehe ID3D12CommandQueue::UpdateTileMappings und volume tiled resources.

Diese Methode kann von mehreren Threads gleichzeitig aufgerufen werden.

Beispiele

Im D3D12Bundles-Beispiel wird ID3D12Device::CreateCommittedResource wie folgt verwendet:

Erstellen Sie einen Vertexpuffer.

auto heapProperties = CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_DEFAULT);
auto resourceDesc = CD3DX12_RESOURCE_DESC::Buffer(SampleAssets::VertexDataSize);
ThrowIfFailed(m_device->CreateCommittedResource(
    &heapProperties,
    D3D12_HEAP_FLAG_NONE,
    &resourceDesc,
    D3D12_RESOURCE_STATE_COPY_DEST,
    nullptr,
    IID_PPV_ARGS(&m_vertexBuffer)));

Siehe Beispielcode in der Direct3D 12-Referenz.