> ## 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.

# Mesh Shader 管線 API 概觀

> Mesh Shader 管線 API 概觀

## 管線狀態建立

如需這些 API 的使用範例，請參閱 [Mesh Shader 管線使用方式](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-usage)。

下列程式碼範例顯示 Mesh Shader 功能支援 API。

```c theme={null}
typedef  enum D3D12_FEATURE {
    ...
    D3D12_FEATURE_D3D12_OPTIONS7,
} D3D12_FEATURE;

typedef enum D3D12_MESH_SHADER_TIER
{
    D3D12_MESH_SHADER_TIER_NOT_SUPPORTED,
    D3D12_MESH_SHADER_TIER_1
} D3D12_MESH_SHADER_TIER;

typedef struct D3D12_FEATURE_DATA_D3D12_OPTIONS7 
{
    _Out_  D3D12_MESH_SHADER_TIER       MeshShaderTier;
    _Out_  D3D12_SAMPLER_FEEDBACK_TIER  SamplerFeedbackTier;
} D3D12_FEATURE_DATA_D3D12_OPTIONS7;

HRESULT ID3D12Device::CheckFeatureSupport(
  D3D12_FEATURE Feature,
  void*         pFeatureSupportData,
  UINT          FeatureSupportDataSize
);
```

下列程式碼範例顯示 Mesh Shader 管線狀態規格，這些規格使用管線串流建立 API。

```
typedef struct D3D12_PIPELINE_STATE_STREAM_DESC {
    _In_  SIZE_T SizeInBytes;
    _In_  void*  pPipelineStateSubobjectStream;
} D3D12_PIPELINE_STATE_STREAM_DESC;

HRESULT ID3D12Device2::CreatePipelineState(
    const D3D12_PIPELINE_STATE_STREAM_DESC* pDesc,
    REFIID                                  riid,
    void**                                  ppPipelineState
);
```

下列程式碼範例顯示將 Mesh Shader 管線執行緒群組分派至 GPU 的 Direct3D 12 API。

```c theme={null}
void ID3D12GraphicsCommandList::DispatchMesh(uint groupCountX, uint groupCountY, uint groupCountZ);

typedef enum D3D12_INDIRECT_ARGUMENT_TYPE {
    ...
    D3D12_INDIRECT_ARGUMENT_TYPE_DISPATCH_MESH
} D3D12_INDIRECT_ARGUMENT_TYPE;

typedef struct D3D12_INDIRECT_ARGUMENT_DESC
{
    D3D12_INDIRECT_ARGUMENT_TYPE Type; // = D3D12_INDIRECT_ARGUMENT_TYPE_DISPATCH_MESH
    union 
    {
        ...
        struct 
        {
            UINT ThreadGroupCountX;
            UINT ThreadGroupCountY;
            UINT ThreadGroupCountZ;
        } D3D12_DISPATCH_MESH_ARGUMENTS;
    }
} D3D12_INDIRECT_ARGUMENT_DESC;

void ID3D12GraphicsCommandList::ExecuteIndirect(
    ID3D12CommandSignature* pCommandSignature,
    UINT                    MaxCommandCount,
    ID3D12Resource*         pArgumentBuffer,
    UINT64                  ArgumentBufferOffset,
    ID3D12Resource*         pCountBuffer,
    UINT64                  CountBufferOffset
);
```

下列程式碼範例顯示如何建立和分派 Mesh Shader 管線。

```
struct MyPsoStreamDesc
{
    CD3DX12_PIPELINE_STATE_STREAM_ROOT_SIGNATURE        pRootSignature;
    CD3DX12_PIPELINE_STATE_STREAM_AS                    AS;
    CD3DX12_PIPELINE_STATE_STREAM_MS                    MS;
    CD3DX12_PIPELINE_STATE_STREAM_PS                    PS;
    CD3DX12_PIPELINE_STATE_STREAM_BLEND_DESC            BlendState;
    CD3DX12_PIPELINE_STATE_STREAM_DEPTH_STENCIL1        DepthStencilState;
    CD3DX12_PIPELINE_STATE_STREAM_RASTERIZER            RasterizerState;
    CD3DX12_PIPELINE_STATE_STREAM_RENDER_TARGET_FORMATS RTFormats;
    CD3DX12_PIPELINE_STATE_STREAM_DEPTH_STENCIL_FORMAT  DepthFormat;
    CD3DX12_PIPELINE_STATE_STREAM_SAMPLE_DESC           SampleDesc;
    CD3DX12_PIPELINE_STATE_STREAM_SAMPLE_MASK           SampleMask;
}

void CreatePipelineState(ID3D12Device* d3dDevice)
{
    // Check Mesh Shader pipeline feature support.
    D3D12_FEATURE_DATA_D3D12_OPTIONS7 options;
    device->CheckFeatureSupport(D3D12_FEATURE_D3D12_OPTIONS7, &options, sizeof(options));

    if (options.MeshShaderTier == D3D12_MESH_SHADER_TIER_NOT_SUPPORTED)
        throw std::exception("Mesh Shaders not supported!"); 

    // Set up PSO Stream Desc.
    MyPsoStreamDesc psoDesc;
    psoDesc.AS = D3D12_SHADER_BYTECODE{ ... };
    psoDesc.MS = D3D12_SHADER_BYTECODE{ ... };
    ...

    // Create Pipeline State Object with stream desc.
    D3D12_PIPELINE_STATE_STREAM_DESC desc = { sizeof(psoDesc), &psoDesc };
    device->CreatePipelineState(&desc, IID_PPV_ARGS(&msPso));
}

void Draw(ID3D12GraphicsCommandList* commandList)
{
    // Set up pipeline and root signature parameters.
    commandList->SetPipelineState(&msPso);
    commandList->SetGraphicsRootSignature(&msRootSig);
    ...

    // Dispatch threadgroups.
    commandList->DispatchMesh(someGroupCount, 1, 1);
}
```

## Mesh Shader 內建函式

### 屬性

| 名稱 | 描述 |
| - | - |
| **OutputTopology** | 指定著色器匯出的基本型別類型，可以是 "line" 或 "triangle"。必須與 *indices* 共用輸出陣列類型相符 (線條為 *uint2*，三角形為 *uint3*)。 |

### 函式

| | |
| - | - |
| 名稱 | **SetMeshOutputCounts** |
| 參數 | *uint numVerts* *uint numPrims* |
| 描述 | 宣告執行緒群組要匯出的頂點和基本型別數量；若未呼叫，計數預設為零。必須小於或等於共用輸出陣列長度，且必須從非分歧的執行內容呼叫，並假設參數值在執行緒群組內為常數。必須在所有寫入輸出陣列的作業之前呼叫。 |

### 參數

| 名稱 | 修飾詞 | 描述 |
| - | - | - |
| *payload* | in | 從 Amplification Shader 傳遞至其 Mesh Shader 執行個體叢集的自訂類型承載資料，最多 16 KB。此資料由叢集中的所有執行個體共用。如果管線中 Mesh Shader 之前沒有 Amplification Shader 階段，則不適用。 |
| *vertices* 陣列 | out | 用來匯出頂點屬性的共用輸出陣列。定義自訂頂點屬性類型，並以陣列長度定義最大頂點匯出數量。 |
| *indices* 陣列 | out | 用來匯出基本型別索引的共用輸出陣列。定義要匯出的基本型別類型，並以陣列長度定義最大基本型別匯出數量。這些基本型別索引會直接索引至 *vertices* 陣列。線條的類型應為 uint2，三角形則為 uint3。 |
| *primitives* 陣列 | out | 用來匯出基本型別屬性的共用輸出陣列。定義使用者定義的基本型別屬性類型。其長度必須等於 *indices* 陣列的長度。 |

## Amplification Shader 內建函式

### 函式

| | |
| - | - |
| 名稱 | **DispatchMesh** |
| 參數 | *uint groupsX* *uint groupsY* *uint groupsZ* *groupshared payload\_t payload* |
| 描述 | 分派 Mesh Shader 執行緒群組叢集，並可選擇附帶承載資料。最多只能從非分歧的程式碼路徑呼叫一次。若未呼叫，則不會分派任何執行緒群組。後續 Mesh Shader 執行緒群組的 GroupID 和 DispatchThreadID 會在其所屬叢集內進行在地化。 |

## 另請參閱

[Mesh Shader 管線概觀](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-overview)

[為什麼要使用 Mesh Shader？](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-why)

[Mesh Shader 管線使用方式](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-usage)


## Related topics

- [Mesh Shader 管線概觀](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-overview.md)
- [為什麼要使用 Mesh Shader？](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-why.md)
- [Meshlet](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-meshlet-render.md)
- [Meshlet 剔除範例](/zh-TW/build/core-features/graphics/newfeatures/ms/ms-meshlet-culling.md)
- [XBOX Series X|S 上的 Mesh Shader 與 Meshlet](/zh-TW/build/core-features/graphics/newfeatures/ms/index.md)