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

# XBOX Texture Compressor (XBTC) 封存檔案規格

> XBOX Texture Compressor (XBTC) 封存檔案規格

封存檔案格式定義於 `XBTC.h` 中，本主題會詳細說明。

<Note>
  封存格式可能會變更，並包含遞增的版本號碼。在不含選項的情況下叫用時，[XBTC.exe](/zh-TW/build/core-features/graphics/newfeatures/xbtc/xbtc) 會顯示其目前的封存版本號碼。嘗試使用 `XBTC.lib` 載入不同版本的封存會失敗。
</Note>

每個封存都以標頭開頭，標頭以 FOURCC 代碼 "XBTC" 起始，後面接著 1 位元組的版本號碼。(此處記載的是版本 "2"。) 標頭如下所示。

```c++ theme={null}
    struct XBTC_ARCHIVE_HEADER
    {
        uint32_t    Identifier;             // File identifier; "XBTC" as char[].
        uint32_t    Version         : 8;    // Archive format version.
        uint32_t    TextureCount    : 24;   // Number of individual textures in archive.
        uint64_t    DataOffset      : 24;   // Header + Index size in bytes.
        uint64_t    DataSize        : 40;   // Size of all data streams in bytes.
    };
```

封存格式支援多個紋理，但 `XBTC.exe` 目前不提供合併封存或將紋理附加至封存的功能。資料位移欄位代表 TOC 的大小。它也代表從封存開頭到壓縮串流資料的搜尋距離。在 TOC 儲存於個別檔案的 (未來) 情況下，資料位移可以是 0，表示壓縮串流從其自身檔案的開頭開始。當包含在一個檔案中時，`DataOffset` + `DataSize` 應等於封存的位元組大小。

封存標頭之後會有若干個紋理描述。此數目等於 `TextureCount`。紋理描述之後會有相同數目的串流搜尋位移，代表每個紋理資料的起始位置。

```c++ theme={null}
    enum XBTC_TEX_DIMENSION
    {
        XBTC_TEX_DIMENSION_1D,              // 1D Texture or Buffer.
        XBTC_TEX_DIMENSION_2D,              // 2D Texture or Texture Array.
        XBTC_TEX_DIMENSION_3D,              // 3D (Volume) Texture.
        XBTC_TEX_DIMENSION_CUBE             // Cubemap or Cubemap Array.
    };

    enum XBTC_TILING_MODE
    {
        XBTC_TILING_SCARLETT_LINEAR,        // Texel elements are arranged in row major order, mips are 256-byte-aligned.
        XBTC_TILING_SCARLETT_256B,          // Tiles are 256 bytes (NO mip tail).
        XBTC_TILING_SCARLETT_4KB,           // Tiles are 4 KB (4 KB mip tail).
        XBTC_TILING_SCARLETT_64KB,          // Tiles are 64 KB (64 KB mip tail).
        XBTC_TILING_SCARLETT_64KB_PRT,      // Tiles are 64 KB, compressed individually for partial residency.
        XBTC_TILING_STANDARD_SWIZZLE        // D3D Standard Swizzle (64 KB tiles).
    };

    struct XBTC_TEXTURE_INFO
    {
        uint64_t    Format          : 8;    // DXGI_FORMAT
        uint64_t    Dimension       : 2;    // XBTC_TEX_DIMENSION
        uint64_t    Width           : 14;   // Width in pixels of mip 0 (minus 1).
        uint64_t    Height          : 14;   // Height in pixels of mip 0 (minus 1).
        uint64_t    Depth           : 11;   // Depth or array count (minus 1).
        uint64_t    TileMode        : 3;    // XBTC_TILING_MODE
        uint64_t    MipCount        : 4;    // Total number of LODs.
        uint64_t    MipStreams      : 4;    // Number of streamable LODs (excluding base).
        uint64_t    Reserved        : 4;
    };

    struct XBTC_OFFSET_AND_INDEX
    {
        uint64_t    BaseOffset      : 40;   // Base offset into data chunk.
        uint64_t    NextIndex       : 24;   // Base stream index of *next* resource.
    };
```

`XBTC_TEXTURE_INFO` 是 `D3D12_RESOURCE_DESC` 的精簡表示法，可在載入時描述紋理。這些詳細資料可用來計算記憶體大小、位移和對齊。位移和索引用於判斷哪些壓縮串流對應到某個紋理，以及到串流資料開頭的 40 位元搜尋位移。這可支援 1 TB 的封存，以及多達 16M 個個別串流。串流總數由最後一個紋理的 `NextIndex` 表示。每個紋理資訊之後是詳細的每個串流資訊。

```c++ theme={null}
    struct XBTC_STREAM_INFO
    {
        uint32_t RelativeOffset             // Stream start offset (relative to base).
        uint32_t CompressedSize;            // Length of compressed stream.
        uint32_t InflatedSize;              // Size of stream before Deflate.
        uint32_t UncompressedSize;          // Uncompressed stream size.
    };
```

串流所使用的壓縮轉碼器，可以從串流資訊中包含的各種大小推斷。如果 `CompressedSize` 小於 `InflatedSize`，表示使用了 `Deflate`。如果 `InflatedSize` 小於 `UncompressedSize`，表示使用了 `BCPack`。兩者可以同時使用，也可以都不使用。

在 `StreamInfo` 陣列之後，可以插入填補，將壓縮串流資料對齊到 16 位元組。檔案的其餘部分由壓縮串流資料組成。

## 另請參閱

[XBOX Texture Compressor 概觀](/zh-TW/build/core-features/graphics/newfeatures/xbtc/xbox-texture-compressor)

[XBTC.exe](/zh-TW/build/core-features/graphics/newfeatures/xbtc/xbtc)

[XBOX Series X|S 圖形功能概觀](/zh-TW/build/core-features/graphics/graphics-newfeatures-toc)


## Related topics

- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)
- [XBOX Texture Compressor (XBTC) tool reference](/build/core-features/graphics/newfeatures/xbtc/index.md)
- [XBOX Texture Compressor (XBTC) 도구 참고서](/ko/build/core-features/graphics/newfeatures/xbtc/index.md)
- [XBOX Texture Compressor (XBTC) 工具参考](/zh-CN/build/core-features/graphics/newfeatures/xbtc/index.md)
- [Referencia de la herramienta XBOX Texture Compressor (XBTC)](/es/build/core-features/graphics/newfeatures/xbtc/index.md)