references/slang-documentation-full.md · 24000
Compilation Targets
Direct3D 11
D3D11 uses DirectX Bytecode (DXBC) format. Supports rasterization and compute pipelines.
Rasterization Pipeline Stages
vertex(VS) - requiredhull(HS) - optional tessellationdomain(DS) - optional tessellationgeometry(GS) - optionalfragment/pixel(PS) - optional
Parameter Passing
Each stage has dedicated slots:
- Constant buffers:
bregisters, ≤4KB uniform data - Shader resource views (SRVs):
tregisters, read-only resources - Unordered access views (UAVs):
uregisters, read-write resources - Samplers:
sregisters, texture sampling state
Direct3D 12
D3D12 uses DirectX Intermediate Language (DXIL) format. Adds ray tracing and mesh shader support.
Additional Pipeline Stages
Mesh Shaders (not yet supported in Slang):
amplification- determines mesh shader invocationsmesh- produces vertex and index data for meshlets
Ray Tracing Pipeline:
raygeneration- traces rays, similar to computeintersection- custom primitive intersectionanyhit- candidate hit acceptance/rejectionclosesthit- processes accepted hitsmiss- handles rays that miss geometrycallable- user-defined subroutines
Parameter Passing
Uses root signatures with:
- Root constants: Direct parameter passing for small data
- Descriptor tables: Groups of descriptors for resources
- Root descriptors: Direct descriptor binding
Vulkan
Uses SPIR-V intermediate representation. Similar capabilities to D3D12.
Key Features
- Descriptor sets instead of descriptor tables
- Push constants instead of root constants
- Extensive extension system
- Cross-vendor standardization
Vulkan-Specific Attributes
[[vk::binding(0, 1)]]
Texture2D myTexture;
[[vk::push_constant]]
cbuffer PushConstants
{
float4 color;
}
[[vk::shader_record]]
cbuffer ShaderRecord
{
uint shaderRecordID;
}
CUDA
Compiles to CUDA C++ or PTX. Supports compute workloads with GPU-specific optimizations.
Key Features
- Native pointer support
- Extensive math library
- Cooperative groups
- Tensor operations
Limitations
- No graphics pipeline stages
- Limited texture operations
- Different wave/warp model
Metal
Apple's graphics API and shading language.
Key Features
- Argument buffers for parameter passing
- Tile-based rendering optimizations
- Unified memory model
- iOS/macOS support
CPU/C++
Generates C++ code for CPU execution.
Key Features
- Host-side shader execution
- Debugging and testing
- Reference implementations
- Cross-platform deployment
Limitations
- No GPU-specific features
- Limited parallel execution
- Different memory model
Target Compatibility
Comprehensive compatibility matrix for Slang features across different targets:
Data Types
| Feature | D3D11 | D3D12 | Vulkan | CUDA | Metal | CPU | | ----------- | ----- | ----- | ------ | ---- | ----- | --- | | Half Type | No | Yes | Yes | Yes | Yes | No | | Double Type | Yes | Yes | Yes | Yes | No | Yes | | u/int8_t | No | No | Yes | Yes | Yes | Yes | | u/int16_t | No | Yes | Yes | Yes | Yes | Yes | | u/int64_t | No | Yes | Yes | Yes | Yes | Yes |
Shader Features
| Feature | D3D11 | D3D12 | Vulkan | CUDA | Metal | CPU | | --------------------- | ----- | ----- | ------- | ---- | ----- | --- | | SM6.0 Wave Intrinsics | No | Yes | Partial | Yes | No | No | | Ray Tracing DXR 1.0 | No | Yes | Yes | No | No | No | | Mesh Shaders | No | Yes | Yes | No | Yes | No | | Tessellation | Yes | Yes | No | No | No | No | | Graphics Pipeline | Yes | Yes | Yes | No | Yes | No |
Resource Features
| Feature | D3D11 | D3D12 | Vulkan | CUDA | Metal | CPU | | ---------------------- | ----- | ----- | ------ | ------- | ----- | ------- | | Native Bindless | No | No | No | Yes | No | Yes | | Buffer Bounds Checking | Yes | Yes | Yes | Limited | No | Limited | | Separate Samplers | Yes | Yes | Yes | No | Yes | Yes | | Atomics | Yes | Yes | Yes | Yes | Yes | Yes |
Platform-Specific Notes
Half Type
- D3D12: Problems with StructuredBuffer containing half
- CUDA: Requires cuda_fp16.h availability
Integer Types
- D3D11/D3D12: 8/16-bit types require specific shader models and DXIL
- Vulkan: Requires explicit arithmetic type extensions
Wave Intrinsics
- CUDA: Preliminary support with synthesized WaveMask
- Different hardware capabilities affect availability
Ray Tracing
- Vulkan: Uses shader records instead of local root signatures
- D3D12: Full DXR 1.0/1.1 support
Bindless Resources
- CUDA: Native support with texture objects
- Other targets: Require significant manual effort
Command Line Reference
General Options
-D<name>[=<value>]
Insert preprocessor macro. If no value specified, defines empty macro.
-entry <name>
Specify entry-point function name. Defaults to main if stage specified. Multiple entries allowed.
-o <file>
Specify output file path.
-target <format>
Specify compilation target format:
spirv- SPIR-V for Vulkandxil- DXIL for D3D12dxbc- DXBC for D3D11hlsl- HLSL source outputglsl- GLSL source outputcuda- CUDA C++ outputcpp- C++ outputmetal- Metal output
-profile <profile>
Specify target profile/version:
glsl_450,glsl_460- GLSL versionssm_5_0,sm_6_0,sm_6_7- Shader Model versions
-stage <stage>
Specify shader stage:
vertex,fragment,computehull,domain,geometryraygeneration,closesthit,miss,anyhit,intersection,callable
Include and Module Options
-I<path>
Add directory to include search path.
-r <module>
Reference precompiled module.
Optimization Options
-O<level>
Set optimization level:
-O0- No optimization-O1- Basic optimization-O2- Standard optimization-O3- Aggressive optimization
-g
Generate debug information.
-line-directive-mode <mode>
Control line directive generation:
none- No line directivesdefault- Standard line directivessource-map- Source map support
Target-Specific Options
Vulkan Options
-fvk-use-entrypoint-name
Use entry point name for SPIR-V OpEntryPoint.
-fvk-use-gl-layout
Use OpenGL-style memory layout rules.
CUDA Options
-cuda-sm <version>
Specify CUDA compute capability (e.g., 70 for 7.0).
CPU Options
-fpic
Generate position-independent code.
Advanced Options
-capability <cap>
Specify required capability for compilation.
-matrix-layout-column-major
Use column-major matrix layout.
-matrix-layout-row-major
Use row-major matrix layout.
-emit-ir
Output intermediate representation (.slang-module).
-load-stdlib-from <path>
Load standard library from specified path.
-no-stdlib
Don't automatically import standard library.
Building From Source
Prerequisites
Required:
- CMake (3.26 preferred, 3.22 minimum)
- C++ compiler with C++17 support (GCC, Clang, MSVC)
- CMake compatible backend (Visual Studio, Ninja)
- Python3 (for spirv-tools dependency)
Optional for tests:
- CUDA
- OptiX
- NVAPI
- Aftermath
- X11
Get Source Code
git clone https://github.com/shader-slang/slang --recursive
Configure and Build
Ninja Build (All Platforms)
cmake --preset default
cmake --build --preset releaseWithDebugInfo
Visual Studio
cmake --preset vs2022
cmake --build --preset releaseWithDebugInfo
Available presets:
debug- Debug buildrelease- Release buildreleaseWithDebugInfo- Release with debug info
Complete Workflow
cmake --workflow --preset release # Configure, build, and package
WebAssembly Build
Requires Emscripten SDK:
# Install and activate Emscripten
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
# Build generators for build platform
cmake --workflow --preset generators --fresh
mkdir generators
cmake --install build --prefix generators --component generators
# Configure and build for WebAssembly
source ../emsdk/emsdk_env
emcmake cmake -DSLANG_GENERATORS_PATH=generators/bin --preset emscripten -G "Ninja"
cmake --build --preset emscripten --target slang-wasm
Testing
build/Debug/bin/slang-test
See slang-test documentation for comprehensive testing information.
Installation
cmake --build . --target install
This installs SlangConfig.cmake for find_package support:
find_package(slang REQUIRED PATHS ${CMAKE_INSTALL_PREFIX} NO_DEFAULT_PATH)
target_link_libraries(yourLib PUBLIC slang::slang)
Cross-Compiling
For cross-compilation scenarios:
- Build generators for build platform
- Configure with target platform toolchain
- Build for target platform
CMake Options
Key configuration options:
| Option | Default | Description |
| ------------------------- | ------- | -------------------------------- |
| SLANG_ENABLE_TESTS | ON | Build test suite |
| SLANG_ENABLE_EXAMPLES | ON | Build example programs |
| SLANG_ENABLE_GFX | ON | Build graphics abstraction layer |
| SLANG_ENABLE_SLANGRT | ON | Build runtime library |
FAQ
How did this project start?
The Slang project forked from the "Spire" shading language research project. Slang takes lessons learned from research about productive shader compilation languages and applies them to a system that's easier to adopt and more suitable for production use.
Why use Slang instead of other HLSL-to-GLSL translators?
While tools like glslang and hlsl2glslfork are useful for basic HLSL-to-GLSL translation, Slang's goal is different. Rather than being "yet another HLSL-to-GLSL translator," Slang aims to create a shading language and toolchain that improves developer productivity over existing HLSL, while providing a reasonable adoption path for existing HLSL code.
If you're just looking for HLSL-to-GLSL translation, existing tools might meet your needs. If you're interested in a more productive shading language with better modularity, type safety, and modern language features, Slang may be worth investigating.
What makes a shading language more productive?
Key research informing Slang's design:
- Shader Components: Modular and High Performance Shader Development - Shows benefits of modular shader development
- A System for Rapid Exploration of Shader Optimization Choices - Demonstrates compiler techniques for shader optimization
- Spark: Modular, Composable Shaders for Graphics Hardware - Early work on composable shader systems
Core productivity improvements:
- Modularity: True separate compilation and module system
- Type Safety: Interfaces and generics replace error-prone preprocessor hacks
- Reflection: Consistent parameter binding information across targets
- Portability: Single source compiles to many targets
- Modern Features: Automatic differentiation, parameter blocks, etc.
Who is using Slang?
Current major users:
- NVIDIA Falcor - Real-time rendering framework developed by NVIDIA Research
- Various game studios - Adopting for next-generation renderers
- Research institutions - Graphics and ML research projects
- Independent developers - Hobby and commercial projects
The implementation has focused heavily on Falcor's needs but is designed to be broadly applicable.
Won't we all just use C/C++ for shaders soon?
The move to documented binary intermediate languages (SPIR-V, DXIL) creates opportunities for language innovation. While C++ shader support would be valuable, Slang addresses challenges unique to real-time graphics that won't automatically improve with C++:
- Parameter binding complexity across different APIs
- Shader stage semantics and validation
- Target-specific optimizations and capabilities
- Graphics-specific type systems (textures, samplers, etc.)
- Automatic differentiation for learning-based rendering
Slang is complementary to C++ shader efforts, focusing on domain-specific improvements for graphics programming.
What are the main limitations?
Current limitations include:
- Limited ecosystem compared to established tools
- Bleeding edge status - API and language changes still occurring
- Target coverage - Some advanced features not available on all targets
- Documentation - Still expanding coverage of advanced topics
- Tooling integration - IDE support improving but not universal
However, these limitations are actively being addressed as the project matures.
How stable is the language and API?
Slang is production-ready for many use cases but still evolving:
- Core language features are stable
- Compilation API has good stability with versioning
- Advanced features (autodiff, capabilities) may see refinements
- Backwards compatibility is prioritized for HLSL compatibility
- Incremental adoption is supported - can gradually introduce Slang features
The project follows semantic versioning and provides migration guidance for breaking changes.
Source: Slang Shader repository docs