DOCSEARCHbyAlgolia
Submit Docs

SDL_shadercross Documentation

repository·main·Indexed 18 days ago

https://github.com/libsdl-org/sdl_shadercross

A shader translation library for SDL's GPU API that converts shaders from SPIRV or HLSL into DXBC, DXIL, SPIRV, MSL, or HLSL. It supports runtime translation and offline translation via a command-line interface, including the ability to reflect shader metadata to JSON.

Tokens
970
Snippets
2
Records
6
Agent score
16%

What's inside SDL_shadercross

  1. Overview of SDL_shadercross

    main

    SDL_shadercross is a shader translation library designed for use with SDL's GPU API. It allows you to convert shaders between multiple formats, supporting both runtime translation (returning compiled SDL GPU shader objects) and offline translation via a command-line interface.

    Supported Formats:

    • Source: SPIRV, HLSL
    • Output: DXBC, DXIL, SPIRV, MSL, HLSL

  2. Configure dependencies for SPIRV and DXIL translation

    main

    Depending on your target output format, you must provide specific external dependencies. It is strongly recommended to ship these dependencies alongside your application.

    SPIRV Translation

    Requires SPIRV-Cross. You can obtain spirv-cross-c-shared.dll (or the equivalent for your platform) from the Vulkan SDK.

    DXIL Translation

    Requires dxcompiler.dll and dxil.dll (or the equivalent for your platform). These can be obtained from the DirectXShaderCompiler releases.

    DXBC Translation

    • Windows: d3dcompiler_47 is shipped with the OS.
    • Other platforms: Requires vkd3d-utils.

  3. Reflect shader metadata to JSON using shadercross

    main

    You can use the shadercross CLI to extract shader reflection data into a JSON format. This is useful for understanding resource bindings (samplers, buffers, textures) and input/output variable locations.

    To do this, set the destination format to JSON using -d JSON or by using a .json extension for the output file.

    Output Formats:

    • Graphics Shaders: Includes samplers, storage_textures, storage_buffers, uniform_buffers, and arrays for inputs and outputs (containing name, type, and location).
    • Compute Shaders: Includes samplers, readonly_storage_textures, readonly_storage_buffers, readwrite_storage_textures, readwrite_storage_buffers, uniform_buffers, and thread counts (threadcount_x, threadcount_y, threadcount_z).
    shadercross my_shader.hlsl -s HLSL -d JSON -t compute -o my_shader.json

  4. Reference the shadercross CLI required options

    main

    The following options must be provided if they cannot be inferred from the filenames:

    FlagLong FlagDescription
    -s--source <value>Source language format. Values: [SPIRV, HLSL]
    -d--dest <value>Destination format. Values: [DXBC, DXIL, MSL, SPIRV, HLSL, JSON]
    -t--stage <value>Shader stage. Values: [vertex, fragment, compute]
    -e--entrypoint <value>Entrypoint function name. Default: "main"
    -o--output <value>Output file path.

  5. Reference the shadercross CLI optional options

    main

    The following options are optional and used for advanced configuration:

    FlagLong FlagDescription
    -I--include <value>HLSL include directory. Only used with HLSL source.
    -D<name>[=<value>]N/AHLSL define. Can be repeated. If =<value> is omitted, the define is treated as 1.
    N/A--msl-version <value>Target MSL version. Only used when transpiling to MSL. Default: 1.2.0
    -c--cullAllow the compiler to cull unused resource bindings. Use with caution.
    -g--debugGenerate debug information. Shaders are valid only when graphics debuggers are attached.
    -p--psslGenerate PSSL-compatible shader. Destination format must be HLSL.

  6. Use the shadercross CLI for offline shader translation

    main

    The shadercross command-line tool allows you to translate shaders between different formats (e.g., HLSL to SPIR-V, SPIR-V to MSL, etc.) and reflect shader metadata to JSON.

    Basic Usage: shadercross <input_file> [options]

    Format Inference: If not explicitly provided, the tool attempts to infer the source format from the input filename (e.g., .spv for SPIR-V, .hlsl for HLSL) and the destination format from the output filename (e.g., .msl, .dxil, .json).

    shadercross my_shader.hlsl -s HLSL -d SPIRV -t vertex -o my_shader.spv