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

# SetShaderScratchSpaceX (XBOX Series 主機)

> 允許直接控制 SPI_TMPRING_SIZE 與 COMPUTE_TMPRING_SIZE 暫存器，以及對應的圖形與計算環形緩衝區。

允許直接控制 SPI\_TMPRING\_SIZE 與 COMPUTE\_TMPRING\_SIZE 暫存器，以及對應的圖形與計算環形緩衝區。

## 語法

```cpp theme={null}
void SetShaderScratchSpaceX(  
         D3D12XBOX_SET_SHADER_SCRATCH_SPACE_FLAGS Flags,  
         D3D12_GPU_VIRTUAL_ADDRESS Destination,  
         UINT64 SizeBytes,  
         UINT SizePerWaveInBytes  
)  
```

### 參數

*Flags*   \_In\_\
類型：[D3D12XBOX\_SET\_SHADER\_SCRATCH\_SPACE\_FLAGS](/zh-TW/reference/graphics/d3d12_xs/enums/d3d12xbox_set_shader_scratch_space_flags_xs)

選擇計算、圖形或兩者。

*Destination*   \_In\_\
類型：D3D12\_GPU\_VIRTUAL\_ADDRESS

暫存空間的基底位址，必須以 1KB 對齊或為 null。將此值設為 null 會重新設定為目前驅動程式的預設值。

*SizeBytes*   \_In\_\
類型：UINT64

暫存空間的大小，以 1KB 對齊；如果位址為 null，則必須為 0。

*SizePerWaveInBytes*   \_In\_\
類型：UINT

每個波的暫存空間大小，必須以 1KB 對齊，必須小於或等於暫存空間的總大小；如果位址為 null，則必須為 0。

### 傳回值

類型：void

## 備註

我們的硬體支援以管線方式變更 tmpring\_size 暫存器，但在重複使用暫存空間的基礎記憶體位址時，需要完整清除管線。這會導致以下情況：根據預設，圖形驅動程式會為圖形與計算配置單一暫存空間，並將 tmpring\_size 暫存器設定為每個 SIMD 只能容納少數幾個波。這表示當著色器中啟用暫存空間時，佔用率會很低。根據預設，由於只有單一計算配置，非同步計算無法與圖形計算同時使用，這表示具有暫存空間的著色器完全無法在非同步計算上使用。開發人員可以透過專用的 XBOX 建立裝置 API 覆寫暫存空間大小，但無法覆寫該行為。

此 API 允許重新設定該預設行為，以便在圖形與非同步計算上達到更高的佔用率與工作重疊。內部不會執行任何同步處理，也不會檢查記憶體指標以避免重複使用，因此使用者務必實作自己的同步處理，以確保在重新設定 tmpring\_size 暫存器時不會發生記憶體重複使用。

您可以使用下列 API 查詢每個波所需的暫存空間大小

```cpp theme={null}
UINT GetScratchSize(
    ID3D12PipelineState* pPso)
{
    ComPtr<ID3DBlob> blob;

    // Retrieve scratch size, if present
    HRESULT hr = pPso->GetInformationX(D3D12XBOX_PIPELINE_STATE_INFORMATION_TYPE_SCRATCH_SIZE_PER_WAVE_IN_UNITS_OF_256DW, 0, &blob);
    if (FAILED(hr))
        return 0;

    const UINT* pValue = (UINT*)blob->GetBufferPointer();

    return *pValue * 1024;
}
```

以下是設定方式的範例，例如允許 8 個波共用暫存空間 (請注意，實際上這樣的波數太少)

```cpp theme={null}
    const UINT scratchSizePerWaveBytes = GetScratchSize(pso.Get());
    const UINT scratchSize = scratchSizePerWaveBytes * 8;

    pCmdList->SetShaderScratchSpaceX(D3D12XBOX_SET_SHADER_SCRATCH_SPACE_FLAGS_GRAPHICS,
        pScratch0->GetGPUVirtualAddress(),
        scratchSize,
        scratchSizePerWaveBytes);
    pCmdList->SetPipelineState(pso.Get());
    pCmdList->DrawInstanced(128, 1, 0, 0);
```

最後，啟用 SCRATCH\_EN 時，硬體不支援高於 16 的佔用率，因為 tmpring\_size 設定不允許為每個計算單元指定超過 32 個波。

## 需求

**標頭：** d3d12\_xs.h

**程式庫：** d3d12\_xs.lib

**支援的平台：** XBOX Series X|S

## 另請參閱

[ID3D12GraphicsCommandList6](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12GraphicsCommandList6/id3d12graphicscommandlist6)


## Related topics

- [Scratch page](/tools/tools-console/wdp/windows-device-portal-on-xbox-scratch.md)
- [Répertoire des rubriques NDA : liens actifs vers Microsoft Learn](/fr/nda/nda-topic-directory.md)
- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)
- [XBOX Series X|S 總覽](/zh-TW/paths/series-xs/overview.md)
- [RSSetShadingRateImage (XBOX Series consoles)](/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrateimage_public.md)