> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ResourceBarrier

> 드라이버에 리소스에 대한 여러 액세스를 동기화해야 함을 알립니다. (ID3D12GraphicsCommandList.ResourceBarrier)

드라이버에 리소스에 대한 여러 액세스를 동기화해야 함을 알립니다.

## 구문

```cpp theme={null}
void ResourceBarrier(
    UINT NumBarriers,
    const D3D12_RESOURCE_BARRIER  pBarriers
)
```

### 매개 변수

*NumBarriers \[in]*\
형식: UINT

제출된 배리어 설명의 수입니다.

*pBarriers \[in]*\
형식: const D3D12\_RESOURCE\_BARRIER \*

배리어 설명 배열에 대한 포인터입니다.

### 반환 값

형식: void

없음.

## 설명

> [!NOTE]
>
> [D3D12\_RESOURCE\_STATE\_RAYTRACING\_ACCELERATION\_STRUCTURE](/ko/reference/graphics/d3d12_x/enums/d3d12_resource_states.md) 상태에 사용될 리소스는 해당 상태로 생성되어야 하며, 그 상태를 벗어나서는 안 됩니다. 또한 해당 상태로 생성되지 않은 리소스는 해당 상태로 전환될 수 없습니다. 자세한 내용은 GitHub의 DirectX Raytracing(DXR) 기능 사양의 [가속 구조 메모리 제한](https://microsoft.github.io/DirectX-Specs/d3d/Raytracing.html#acceleration-structure-memory-restrictions)을 참조하세요.

세 가지 유형의 배리어 설명이 있습니다:

<ul>
  <li>
    [D3D12\_RESOURCE\_TRANSITION\_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_transition_barrier_public.md) - 전환 배리어는 하위 리소스 집합이 서로 다른 용도 사이에서 전환됨을 나타냅니다. 호출자는 하위 리소스의 *before* 및 *after* 용도를 지정해야 합니다. D3D12\_RESOURCE\_BARRIER\_ALL\_SUBRESOURCES 플래그는 리소스의 모든 하위 리소스를 동시에 전환하는 데 사용됩니다.
  </li>

  <li>
    [D3D12\_RESOURCE\_ALIASING\_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_aliasing_barrier_public.md) - 별칭 배리어는 동일한 힙에 매핑되는 두 개의 다른 리소스 사용 간의 전환을 나타냅니다. 애플리케이션은 이전 및 이후 리소스를 모두 지정할 수 있습니다. 하나 또는 두 리소스 모두 NULL일 수 있습니다(모든 타일 리소스가 별칭을 유발할 수 있음을 나타냄).
  </li>

  <li>
    [D3D12\_RESOURCE\_UAV\_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_uav_barrier_public.md) - 정렬되지 않은 액세스 뷰 배리어는 특정 리소스에 대한 모든 UAV 액세스(읽기 또는 쓰기)가 향후 UAV 액세스(읽기 또는 쓰기)가 시작되기 전에 완료되어야 함을 나타냅니다. 지정된 리소스는 NULL일 수 있습니다. UAV만 읽는 두 개의 draw 또는 dispatch 호출 사이에 UAV 배리어를 삽입할 필요는 없습니다. 또한 UAV 액세스를 임의의 순서로 실행하는 것이 안전하다는 것을 애플리케이션이 알고 있는 경우 동일한 UAV에 쓰는 두 draw 또는 dispatch 호출 사이에 UAV 배리어를 삽입할 필요는 없습니다. 리소스는 NULL일 수 있습니다(모든 UAV 액세스에 배리어가 필요할 수 있음을 나타냄).
  </li>
</ul>

**ID3D12GraphicsCommandList::ResourceBarrier**에 리소스 배리어 설명 배열이 전달되면 API는 지정된 순서로 N번(배열 요소당 하나씩) 호출된 것처럼 동작합니다.
성능 최적화를 위해 가능한 경우 전환을 단일 API 호출로 일괄 처리해야 합니다.

하위 리소스가 있을 수 있는 사용 상태에 대한 설명은 [D3D12\_RESOURCE\_STATES](/ko/reference/graphics/d3d12_x/enums/d3d12_resource_states.md) 열거형 및 [Direct3D 12에서 리소스 배리어를 사용하여 리소스 상태 동기화](https://learn.microsoft.com/en-us/windows/win32/direct3d12/using-resource-barriers-to-synchronize-resource-states-in-direct3d-12) 섹션을 참조하세요.

[ID3D12GraphicsCommandList::DiscardResource](/ko/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_discardresource_public.md)가 호출될 때 리소스의 모든 하위 리소스는 렌더 대상/깊이-스텐실 리소스에 대해 각각 RENDER\_TARGET 상태 또는 DEPTH\_WRITE 상태여야 합니다.

백 버퍼가 표시될 때는 D3D12\_RESOURCE\_STATE\_PRESENT 상태여야 합니다. PRESENT 상태가 아닌 리소스에서 [IDXGISwapChain1::Present1](https://learn.microsoft.com/en-us/windows/win32/api/dxgi1_2/nf-dxgi1_2-idxgiswapchain1-present1)이 호출되면 디버그 레이어 경고가 발생합니다.

리소스 사용 비트는 읽기 전용과 읽기/쓰기 두 범주로 그룹화됩니다.

다음 사용 비트는 읽기 전용입니다:

<ul>
  <li>D3D12\_RESOURCE\_STATE\_VERTEX\_AND\_CONSTANT\_BUFFER</li>
  <li>D3D12\_RESOURCE\_STATE\_INDEX\_BUFFER</li>
  <li>D3D12\_RESOURCE\_STATE\_NON\_PIXEL\_SHADER\_RESOURCE</li>
  <li>D3D12\_RESOURCE\_STATE\_PIXEL\_SHADER\_RESOURCE</li>
  <li>D3D12\_RESOURCE\_STATE\_INDIRECT\_ARGUMENT</li>
  <li>D3D12\_RESOURCE\_STATE\_COPY\_SOURCE</li>
  <li>D3D12\_RESOURCE\_STATE\_DEPTH\_READ</li>
</ul>

다음 사용 비트는 읽기/쓰기입니다:

<ul>
  <li>D3D12\_RESOURCE\_STATE\_UNORDERED\_ACCESS</li>
  <li>D3D12\_RESOURCE\_STATE\_DEPTH\_WRITE</li>
</ul>

다음 사용 비트는 쓰기 전용입니다:

<ul>
  <li>D3D12\_RESOURCE\_STATE\_COPY\_DEST</li>
  <li>D3D12\_RESOURCE\_STATE\_RENDER\_TARGET</li>
  <li>D3D12\_RESOURCE\_STATE\_STREAM\_OUT</li>
</ul>

최대 하나의 쓰기 비트만 설정할 수 있습니다.
쓰기 비트가 설정된 경우 읽기 비트를 설정할 수 없습니다.
쓰기 비트가 설정되지 않은 경우 여러 개의 읽기 비트를 설정할 수 있습니다.

주어진 시간에 하위 리소스는 (플래그 집합에 의해 결정되는) 정확히 하나의 상태에 있습니다. 애플리케이션은 일련의 **ResourceBarrier** 호출을 할 때 상태가 일치하도록 해야 합니다. 즉, 연속적인 **ResourceBarrier** 호출의 이전 및 이후 상태가 일치해야 합니다.

리소스 내의 모든 하위 리소스를 전환하려면 애플리케이션은 하위 리소스 인덱스를 D3D12\_RESOURCE\_BARRIER\_ALL\_SUBRESOURCES로 설정할 수 있으며, 이는 모든 하위 리소스가 변경됨을 의미합니다.

성능 향상을 위해 애플리케이션은 분할 배리어를 사용해야 합니다([다중 엔진 동기화](https://learn.microsoft.com/en-us/windows/win32/direct3d12/user-mode-heap-synchronization) 참조). 또한 가능한 경우 여러 전환을 단일 호출로 일괄 처리해야 합니다.

런타임 유효성 검사
런타임은 배리어 유형 값이 [D3D12\_RESOURCE\_BARRIER\_TYPE](/ko/reference/graphics/d3d12/enums/d3d12_resource_barrier_type_public.md) 열거형의 유효한 멤버인지 확인합니다.

또한 런타임은 다음을 확인합니다:

<ul>
  <li>리소스 포인터가 NULL이 아님.</li>
  <li>하위 리소스 인덱스가 유효함</li>
  <li>이전 및 이후 상태가 리소스의 [D3D12\_RESOURCE\_BINDING\_TIER](/ko/reference/graphics/d3d12/enums/d3d12_resource_binding_tier_public.md) 및 [D3D12\_RESOURCE\_FLAGS](/ko/reference/graphics/d3d12_x/enums/d3d12_resource_flags.md) 플래그에서 지원됨.</li>
  <li>상태 마스크의 예약 비트가 설정되지 않음.</li>
  <li>이전 및 이후 상태가 다름.</li>
  <li>이전 및 이후 상태의 비트 집합이 유효함.</li>
  <li>D3D12\_RESOURCE\_STATE\_RESOLVE\_SOURCE 비트가 설정된 경우 리소스 샘플 카운트는 1보다 커야 함.</li>
  <li>D3D12\_RESOURCE\_STATE\_RESOLVE\_DEST 비트가 설정된 경우 리소스 샘플 카운트는 1과 같아야 함.</li>
</ul>

별칭 배리어의 경우 런타임은 리소스 포인터가 NULL이 아닌 경우 타일 리소스를 참조하는지 확인합니다.

UAV 배리어의 경우 런타임은 리소스가 NULL이 아닌 경우 리소스에 D3D12\_RESOURCE\_STATE\_UNORDERED\_ACCESS 바인딩 플래그가 설정되어 있는지 확인합니다.

유효성 검사에 실패하면 [ID3D12GraphicsCommandList::Close](/ko/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_close_public.md)가 E\_INVALIDARG를 반환합니다.

디버그 레이어
디버그 레이어는 일반적으로 런타임 유효성 검사가 실패하는 곳에서 오류를 발생시킵니다:

<ul>
  <li>명령 목록의 하위 리소스 전환이 동일한 명령 목록의 이전 전환과 일치하지 않는 경우. </li>
  <li>리소스를 올바른 상태로 만들기 위해 **ResourceBarrier**를 먼저 호출하지 않고 리소스를 사용하는 경우.  </li>
  <li>리소스가 동시에 읽기 및 쓰기용으로 잘못 바인딩된 경우.</li>
  <li>**ResourceBarrier**에 전달된 *before* 상태가 별칭 사례를 포함하여 이전 **ResourceBarrier** 호출의 *after* 상태와 일치하지 않는 경우.</li>
</ul>

디버그 레이어는 런타임 규칙을 검증하려고 시도하지만 보수적으로 작동하므로 디버그 레이어 오류는 실제 오류이며, 경우에 따라 실제 오류가 디버그 레이어 오류를 발생시키지 않을 수 있습니다.

디버그 레이어는 다음 경우에 경고를 발생시킵니다:

<ul>
  <li>D3D12 디버그 레이어가 [ID3D12GraphicsCommandList::ResourceBarrier](/ko/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_resourcebarrier_public.md)에 대해 경고를 발생시키는 모든 경우.</li>
  <li>리소스에 D3D12\_RESOURCE\_STATE\_PIXEL\_SHADER\_RESOURCE 사용 비트가 설정된 동안 깊이 버퍼가 읽기 전용이 아닌 모드에서 사용되는 경우.</li>
</ul>

## 예제

[D3D12HelloTriangle](https://learn.microsoft.com/en-us/windows/win32/direct3d12/working-samples) 샘플은 다음과 같이 **ID3D12GraphicsCommandList::ResourceBarrier**를 사용합니다:

```cpp theme={null}
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;

```

```cpp theme={null}
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 참조의 예제 코드](https://learn.microsoft.com/en-us/windows/win32/direct3d12/notes-on-example-code)를 참조하세요.

## 요구 사항

**헤더:** d3d12\_xs.h 또는 d3d12\_x.h\
**라이브러리:** d3d12\_xs.lib 또는 d3d12\_x.lib\
**지원 플랫폼**: XBOX Series 콘솔 및 XBOX One 제품군

## 함께 보기

[ID3D12GraphicsCommandList](/ko/reference/graphics/d3d12_xs/interfaces/ID3D12GraphicsCommandList/id3d12graphicscommandlist_xs.md)

[Direct3D 12에서 리소스 배리어를 사용하여 리소스 상태 동기화](https://learn.microsoft.com/en-us/windows/win32/direct3d12/using-resource-barriers-to-synchronize-resource-states-in-direct3d-12)


## Related topics

- [D3D12_RESOURCE_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_barrier_public.md)
- [D3D12_RESOURCE_BARRIER_TYPE](/ko/reference/graphics/d3d12/enums/d3d12_resource_barrier_type_public.md)
- [D3D12_RESOURCE_TRANSITION_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_transition_barrier_public.md)
- [D3D12_RESOURCE_ALIASING_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_aliasing_barrier_public.md)
- [D3D12_RESOURCE_UAV_BARRIER](/ko/reference/graphics/d3d12/structs/d3d12_resource_uav_barrier_public.md)