XCEngine/docs/api/rhi/d3d12/common/common.md

# D3D12Common

**命名空间**: `XCEngine::RHI`

**类型**: `inline 函数集合` (header-only)

**描述**: D3D12 通用辅助函数集合，提供描述符大小查询、资源屏障创建、格式支持检查、视图创建等功能。所有函数均为 `inline` 函数，封装自 DirectX 12 原生 API。

## 概述

D3D12Common 是 D3D12 后端的工具函数模块，封装了 DirectX 12 常用的辅助功能，包括：

- **描述符大小查询**: 封装 `ID3D12Device::GetDescriptorHandleIncrementSize`，提供各类描述符的增量大小
- **资源屏障创建**: 封装 `D3D12_RESOURCE_BARRIER` 的三种类型（Transition、UAV、Aliasing）
- **格式支持检查**: 封装 `ID3D12Device::CheckFeatureSupport`，检查格式是否支持特定用途
- **视图创建**: 封装 D3D12_VERTEX_BUFFER_VIEW、D3D12_INDEX_BUFFER_VIEW、D3D12_VIEWPORT 等创建
- **描述符句柄运算**: 提供描述符句柄的偏移计算

这些函数均为无状态的纯函数，设计用于简化 D3D12 常见操作的代码编写。

## 函数列表

### 描述符大小

| 函数 | 描述 |
|------|------|
| [`GetDescriptorHandleIncrementSize`](get-descriptor-handle-increment-size.md) | 获取指定描述符堆类型的增量大小 |
| [`GetRTVDescriptorSize`](get-rtv-descriptor-size.md) | 获取 RTV 描述符大小 |
| [`GetDSVDescriptorSize`](get-dsv-descriptor-size.md) | 获取 DSV 描述符大小 |
| [`GetCBV_SRV_UAVDescriptorSize`](get-cbv-srv-uav-descriptor-size.md) | 获取 CBV/SRV/UAV 描述符大小 |
| [`GetSamplerDescriptorSize`](get-sampler-descriptor-size.md) | 获取 Sampler 描述符大小 |

### 屏障创建

| 函数 | 描述 |
|------|------|
| [`CreateTransitionBarrier`](create-transition-barrier.md) | 创建资源状态转换屏障 |
| [`CreateUAVBarrier`](create-uav-barrier.md) | 创建 UAV 屏障 |
| [`CreateAliasingBarrier`](create-aliasing-barrier.md) | 创建别名化屏障 |

### 格式支持

| 函数 | 描述 |
|------|------|
| [`CheckFormatSupport`](check-format-support.md) | 检查格式是否支持指定功能 |
| [`IsRenderTargetFormatSupported`](is-render-target-format-supported.md) | 检查是否支持作为渲染目标 |
| [`IsDepthStencilFormatSupported`](is-depth-stencil-format-supported.md) | 检查是否支持作为深度模板 |
| [`IsShaderResourceFormatSupported`](is-shader-resource-format-supported.md) | 检查是否支持作为着色器资源 |
| [`IsTextureFormatSupported`](is-texture-format-supported.md) | 检查是否支持作为纹理 |

### 清除值创建

| 函数 | 描述 |
|------|------|
| [`CreateRenderTargetClearValue`](create-render-target-clear-value.md) | 创建渲染目标清除值 |
| [`CreateDepthStencilClearValue`](create-depth-stencil-clear-value.md) | 创建深度模板清除值 |

### 视口和裁剪矩形

| 函数 | 描述 |
|------|------|
| [`CreateViewport`](create-viewport.md) | 创建视口结构 |
| [`CreateScissorRect`](create-scissor-rect.md) | 创建裁剪矩形 |

### 缓冲区视图

| 函数 | 描述 |
|------|------|
| [`CreateVertexBufferView`](create-vertex-buffer-view.md) | 创建顶点缓冲区视图 |
| [`CreateIndexBufferView`](create-index-buffer-view.md) | 创建索引缓冲区视图 |

### 描述符句柄运算

| 函数 | 描述 |
|------|------|
| [`GetCPUDescriptorHandle`](get-cpu-descriptor-handle.md) | 计算偏移后的 CPU 描述符句柄 |
| [`GetGPUDescriptorHandle`](get-gpu-descriptor-handle.md) | 计算偏移后的 GPU 描述符句柄 |

## 使用示例

```cpp
#include <XCEngine/RHI/D3D12/D3D12Common.h>

using namespace XCEngine::RHI;

// 获取描述符大小
ID3D12Device* device = ...;
UINT rtvSize = GetRTVDescriptorSize(device);

// 创建资源屏障
D3D12_RESOURCE_BARRIER barrier = CreateTransitionBarrier(
    resource, 
    D3D12_RESOURCE_STATE_RENDER_TARGET, 
    D3D12_RESOURCE_STATE_COMMON
);

// 检查格式支持
if (IsTextureFormatSupported(device, DXGI_FORMAT_BC1_UNORM)) {
    // 使用压缩纹理
}

// 创建视口
D3D12_VIEWPORT viewport = CreateViewport(1280.0f, 720.0f);
```

## 相关文档

- [D3D12 后端概览](../d3d12.md) - D3D12 模块总览
- [RHI 模块总览](../../rhi.md) - RHI 抽象层
- [D3D12Device](../device/device.md) - D3D12 设备
- [D3D12DescriptorHeap](../descriptor-heap/descriptor-heap.md) - 描述符堆