.CSO File Format – Container

Compiled Direct3D shader object

A .cso file is one DirectX shader container, the binary form both of Microsoft’s HLSL compilers produce: fxc for DXBC bytecode (shader model 5.1 and earlier) and dxc for DXIL (shader model 6 and later). The container is also called the DXBC format or DXIL container.

What is documented

  • Microsoft publishes the container header, the part header, the part FourCCs and the structures of most DXC parts as C++ headers in its open-source DirectXShaderCompiler repository (DxilContainer.h, DxilConstants.h).
  • The LLVM project’s DirectX Container document describes the same format, part by part, for LLVM’s own DirectX back end.
  • The 16-byte digest in the header is “computed with a proprietary algorithm” (LLVM’s words) and is not documented. Implementations outside Microsoft compute it by reverse engineering; this page does not describe it.
  • The FXC-only parts (RDEF, ISGN, OSGN, OSG5, PCSG, SHDR, SHEX) are named in LLVM’s list, but their inner layouts are not described in the sources read for this page.

Part header

OffsetSizeFieldMeaning
04PartFourCCFour-character code naming the part.
44PartSizeNumber of bytes of part data that follow.
8PartSizedataThe part’s contents; see parts.

The format does not require parts to be 32-bit aligned; LLVM’s writer aligns them and its reader does not rely on it. PRIV is the one part whose size need not be a multiple of four; it must be the last part, and there may be only one.

Part FourCCs

FourCCDXC nameContentsWritten by
DXILDFCC_DXILDXIL program: program header and LLVM bitcode.DXC
ILDBDFCC_ShaderDebugInfoDXILDXIL with debug information, not stripped.DXC
ILDNDFCC_ShaderDebugNameName of the debug file.DXC
HASHDFCC_ShaderHashShader MD5 hash and flags.DXC
ISG1DFCC_InputSignatureInput signature.shader model 5.1 and later
OSG1DFCC_OutputSignatureOutput signature.shader model 5.1 and later
PSG1DFCC_PatchConstantSignaturePatch-constant signature.shader model 6 and later
PSV0DFCC_PipelineStateValidationPipeline state validation data.—
RDATDFCC_RuntimeDataRuntime data.DXC
RTS0DFCC_RootSignatureRoot signature.—
SFI0DFCC_FeatureInfo64-bit mask of optional features the shader needs.—
STATDFCC_ShaderStatisticsShader statistics.DXC
PRIVDFCC_PrivateDataOpaque private data, such as an embedded PDB.DXC
SRCIDFCC_ShaderSourceInfoShader source information.DXC
PDBIDFCC_ShaderPDBInfoPDB information.DXC
VERSDFCC_CompilerVersionCompiler version.DXC
RDEFDFCC_ResourceDefResource definitions.FXC
ISGN—Input signature.FXC, shader model 4 and earlier
OSGN—Output signature.FXC, shader model 4 and earlier
OSG5—Output signature.FXC, shader model 5
PCSG—Patch-constant signature.FXC, shader model 5.1 and earlier
SHDR—DXBC bytecode.FXC
SHEX—DXBC bytecode.FXC

DXBC itself is also the FourCC of the container (DFCC_Container); LLVM’s list also names a DXBC part holding DXBC bytecode. “—” in the last column means the sources do not tie the part to one compiler.

Worked example

Offset  Bytes                     Field
0       44 58 42 43               "DXBC"
4       xx × 16                   digest
20      01 00 00 00               version 1.0
24      (4 bytes)                 total size
28      03 00 00 00               3 parts
32      2C 00 00 00               part 0 at 0x2C
36      (4 bytes)                 part 1 offset
40      (4 bytes)                 part 2 offset
44      53 46 49 30  08 00 00 00  part 0: "SFI0", 8 bytes of data
52      (8 bytes)                 the 64-bit feature mask
…
The start of a container with three parts. The first part follows the 32-byte header and three 4-byte offsets.

Sources

  • DxilContainer.h – Microsoft’s DirectXShaderCompiler: DxilContainerHeader, DxilPartHeader, the version and size constants and the FourCC list
  • DirectX Container – LLVM documentation: the header, part alignment, the full part list with FXC/DXC markings, and the statement that the digest is proprietary