references/slang-documentation-full.md
Slang Language Documentation - Complete Reference
Source: Official Slang Shader Repository
Table of Contents
- Project Overview
- Introduction and Why Use Slang
- Getting Started
- Language Features
- Conventional Features
- Interfaces and Generics
- Automatic Differentiation
- Modules and Access Control
- Capabilities System
- Compiling Code with Slang
- Reflection API
- Compilation Targets
- Target Compatibility
- Command Line Reference
- Building From Source
- FAQ
Project Overview
Slang is a real-time shading language designed to improve developer productivity for GPU programming while maintaining high performance. It extends HLSL with modern programming language features and supports compilation to multiple target platforms including Direct3D, Vulkan, CUDA, Metal, and CPU.
Key benefits:
- Backwards compatible with most existing HLSL code
- Parameter blocks for efficient descriptor table usage
- Interfaces and generics for type-safe shader specialization
- Automatic differentiation for machine learning applications
- Module system for better code organization
- Comprehensive reflection API
- Cross-platform compilation to multiple targets
Introduction and Why Use Slang
Why use Slang?
The Slang system helps real-time graphics developers write cleaner and more maintainable GPU code, without sacrificing run-time performance. Slang extends the HLSL language with thoughtfully selected features from modern general-purpose languages that support improved developer productivity and code quality.
Some of the benefits of Slang include:
- Backwards compatibility: Slang is backwards compatible with most existing HLSL code
- Parameter blocks: Allow shader parameters to be grouped by update rate to take advantage of Direct3D 12 descriptor tables and Vulkan descriptor sets
- Interfaces and generics: Provide first-class alternatives to preprocessor-based shader specialization
- Automatic differentiation: Greatly simplifies implementation of learning-based techniques in shaders
- Module system: Enables true separate compilation and semantic checking of shader code
- Multi-platform support: Same compiler generates code for DX bytecode, DXIL, SPIR-V, HLSL, GLSL, CUDA, and more
- Robust reflection API: Provides binding/offset/layout information about shader parameters in consistent format
Who is Slang for?
Slang aims to be the best language possible for real-time graphics developers who care about code quality, portability and performance.
Real-Time Graphics Developers
Slang is primarily intended for developers creating real-time graphics applications that run on end-user/client machines, such as 3D games and digital content creation (DCC) tools.
From Hobbyists to Professionals
The Slang language is simple and familiar enough for hobbyist developers to use, but scales up to the demands of professional development teams creating next-generation game renderers.
Developers of Multi-Platform Applications
The Slang system builds for multiple OSes, supports many graphics APIs, and works with GPUs from multiple hardware vendors. The project is completely open-source.
Developers with existing HLSL investment
One of Slang's key features is its high degree of compatibility with existing HLSL code. Developers can incrementally adopt Slang features to improve codebase quality over time.
Goals and Non-Goals
Key design goals:
- Performance: Benefits of using Slang must not come at the cost of performance
- Productivity: Language concepts foster greater developer productivity in large codebases
- Portability: Support wide variety of hardware, graphics APIs, and operating systems
- Ease of Adoption: Compatible with existing code, familiar syntax from other languages
- Predictability: Code should do what it appears to, consistently across platforms
- Limited Scope: Slang is a language, compiler, and module - not an engine or framework
Getting Started
Installation
The easiest way to start using Slang is to download a binary release from the GitHub repository. Extract the files and find slangc.exe under /bin/windows-x64/release/. Note that slang.dll and slang-glslang.dll must be in the same directory.
For building from source, see the Building From Source section.
Your First Slang Shader
Create a file named hello-world.slang:
// hello-world.slang
StructuredBuffer<float> buffer0;
StructuredBuffer<float> buffer1;
RWStructuredBuffer<float> result;
[shader("compute")]
[numthreads(1,1,1)]
void computeMain(uint3 threadId : SV_DispatchThreadID)
{
uint index = threadId.x;
result[index] = buffer0[index] + buffer1[index];
}
Compile to SPIR-V:
slangc hello-world.slang -target spirv -o hello-world.spv
Compile to GLSL:
slangc hello-world.slang -target glsl -o hello-world.glsl
Language Features
Import Declarations
Slang introduces import declarations for better software modularity:
// foo.slang
float4 someFunc(float4 x) { return x; }
// bar.slang
import foo;
float4 someOtherFunc(float4 y) { return someFunc(y); }
Key details:
- Import searches for
.slangfiles using same search paths as#include - Multiple imports of same file only processed once
- No automatic namespacing (potential for name collisions)
- Use
__exported importto re-export declarations - Import is not like
#include- no preprocessor macro sharing
Explicit Parameter Blocks
Slang supports explicit syntax for parameter blocks using descriptor tables/sets:
struct ViewParams
{
float3 cameraPos;
float4x4 viewProj;
TextureCube envMap;
}
ParameterBlock<ViewParams> gViewParams;
Fields are assigned to registers/bindings to support allocation into a single parameter block.
Interfaces
Slang supports declaring interfaces that user-defined struct types can implement:
// Interface definition
struct LightSample { float3 intensity; float3 direction; };
interface ILight
{
LightSample sample(float3 position);
}
// Implementation
struct PointLight : ILight
{
float3 position;
float3 intensity;
LightSample sample(float3 hitPos)
{
float3 delta = hitPos - position;
float distance = length(delta);
LightSample sample;
sample.direction = delta / distance;
sample.intensity = intensity * falloff(distance);
return sample;
}
}
Generics
Slang supports generic declarations using angle-bracket syntax:
float4 computeDiffuse<L : ILight>(float4 albedo, float3 P, float3 N, L light)
{
LightSample sample = light.sample(P);
float nDotL = max(0, dot(N, sample.direction));
return albedo * nDotL;
}
Global-Scope Generic Parameters
For compatibility with existing HLSL global declarations:
type_param M : IMaterial;
M gMaterial;
Associated Types
For cases where each implementing type needs its own choice of intermediate type:
interface IMaterial
{
associatedtype B : IBRDF;
B evalPattern(float3 position, float2 uv);
}
struct MyCoolMaterial : IMaterial
{
typedef DisneyBRDF B;
B evalPattern(float3 position, float2 uv) { ... }
}
Conventional Features
Types
Slang supports conventional shading language types including scalars, vectors, matrices, arrays, structures, enumerations, and resources.
Scalar Types
Integer types:
int8_t,int16_t,int,int64_tuint8_t,uint16_t,uint,uint64_t
Floating-point types:
half(16-bit)float(32-bit)double(64-bit)
Boolean type: bool
Void type: void
Vector Types
Vector types: vector<T,N> where T is scalar type and N is 2-4
Convenience names: float3 = vector<float,3>
Matrix Types
Matrix types: matrix<T,R,C> where T is scalar, R and C are 2-4
Convenience names: float3x4 = matrix<float,3,4>
Array Types
Array type T[N] represents array of N elements of type T:
int a[3]; // sized array
int a[] = {1,2,3}; // inferred size
void f(int b[]) {} // unsized array parameter
Arrays have getCount() method that returns length.
Structure Types
Structure types with struct keyword:
struct MyData
{
int a;
float b;
}
Structures can have constructors defined with __init keyword.
Interfaces and Generics
Interfaces
Interfaces define methods and services a type should provide:
interface IFoo
{
int myMethod(float arg);
}
struct MyType : IFoo
{
int myMethod(float arg)
{
return (int)arg + 1;
}
}
Multiple Interface Conformance
interface IBar { uint myMethod2(uint2 x); }
struct MyType : IFoo, IBar
{
int myMethod(float arg) {...}
uint myMethod2(uint2 x) {...}
}
Default Implementations
interface IFoo
{
int getVal() { return 0; } // default implementation
}
struct MyType : IFoo {} // uses default
struct MyType2 : IFoo
{
override int getVal() { return 1; } // explicit override
}
Generics
Generic methods eliminate duplicate code for shared logic:
int myGenericMethod<T>(T arg) where T : IFoo
{
return arg.myMethod(1.0);
}
// Usage
MyType obj;
int a = myGenericMethod<MyType>(obj); // explicit type
int b = myGenericMethod(obj); // type deduction
Generic Value Parameters
void g1<let n : int>() { ... }
enum MyEnum { A, B, C }
void g2<let e : MyEnum>() { ... }
void g3<let b : bool>() { ... }
Alternative Syntax
__generic<typename T>
int myGenericMethod(T arg) where T : IFoo { ... }
// Simplified syntax
int myGenericMethod<T:IFoo>(T arg) { ... }
Multiple Constraints
struct MyType<T, U>
where T: IFoo, IBar
where U : IBaz<T>
{
}
Optional Conformances
int myGenericMethod<T>(T arg) where optional T: IFoo
{
if (T is IFoo)
{
arg.myMethod(1.0); // OK in conformance check block
}
}
Supported Interface Constructs
Properties
interface IFoo
{
property int count {get; set;}
}
Generic Methods
interface IFoo
{
int compute<T>(T val) where T : IBar;
}
Static Methods
interface IFoo
{
static int compute(int val);
}
Automatic Differentiation
Slang provides first-class support for differentiable programming through automatic differentiation.
Key Features
fwd_diffandbwd_diffoperators for forward and backward-mode derivative propagationDifferentialPair<T>type for passing derivatives with inputsIDifferentiableandIDifferentiablePtrTypeinterfaces for differentiable types- User-defined derivative functions via
[ForwardDerivative]and[BackwardDerivative] - Compatible with all Slang features: control-flow, generics, interfaces, etc.
Mathematical Background
Forward-mode computes Jacobian-vector products: <Df(x), v>
Backward-mode computes vector-Jacobian products: <v^T, Df(x)>
Forward-Mode Example
[Differentiable]
float2 foo(float a, float b)
{
return float2(a * b * b, a * a);
}
void main()
{
DifferentialPair<float> dp_a = diffPair(1.0, 1.0); // value and derivative
DifferentialPair<float> dp_b = diffPair(2.4, 0.0);
DifferentialPair<float2> dp_output = fwd_diff(foo)(dp_a, dp_b);
float2 output_p = dp_output.p; // primal output
float2 output_d = dp_output.d; // derivative output
}
Backward-Mode Example
[Differentiable]
float2 foo(float a, float b)
{
return float2(a * b * b, a * a);
}
void main()
{
DifferentialPair<float> dp_a = diffPair(1.0);
DifferentialPair<float> dp_b = diffPair(2.4);
float2 dL_doutput = float2(1.0, 0.0); // output derivatives
bwd_diff(foo)(dp_a, dp_b, dL_doutput);
float dL_da = dp_a.d; // computed input derivatives
float dL_db = dp_b.d;
}
Differentiable Type System
Built-in Differentiable Types
- Scalars:
float,double,half - Vectors/matrices of differentiable scalars
- Arrays:
T[n]ifTis differentiable - Tuples:
Tuple<each T>ifTis differentiable
User-Defined Differentiable Types
struct MyType : IDifferentiable
{
float x;
float y;
}
The Differential associated type carries corresponding derivative (usually same as primal type).
Custom Derivatives
[Differentiable]
[ForwardDerivative(myForwardDerivative)]
[BackwardDerivative(myBackwardDerivative)]
float myFunction(float x) { ... }
Modules and Access Control
Defining a Module
A module comprises one or more files with a primary file containing a module declaration:
// scene.slang
module scene;
__include "scene-helpers";
// scene-helpers.slang
implementing scene;
// ...
Module Include Semantics
__include differs from #include:
- No preprocessor state sharing between files
- Each file included exactly once
- Circular includes allowed
- All module files can access all other entities regardless of include order
Module Reference Syntax
Both identifier and string literal syntax supported:
__include dir.file_name; // translated to "dir/file-name.slang"
__include "dir/file-name.slang";
__include "dir/file-name";
Importing a Module
// MyShader.slang
import YourLibrary;
Import rules:
- Can only import primary module files
- Multiple imports of same module loaded once
- No preprocessor sharing between files
Access Control
Three visibility levels:
public
Accessible everywhere - different types, files, modules
private
Only visible within same type:
struct MyType
{
private int member;
int f() { member = 5; } // OK
struct ChildType
{
int g(MyType t) { return t.member; } // OK
}
}
void outerFunc(MyType t)
{
t.member = 2; // Error - not visible
}
internal
Visible throughout same module:
// a.slang
module a;
public struct PS
{
internal int internalMember;
public int publicMember;
}
internal void f() { ... }
// m.slang
module m;
import a;
void main()
{
f(); // Error - f is internal to module a
PS p;
p.internalMember = 1; // Error - not visible outside module a
p.publicMember = 1; // OK
}
Default visibility is internal (except interface members inherit interface visibility).
Validation Rules
- More visible entities cannot expose less visible entities in signature
- Members cannot have higher visibility than parent
- Type definitions cannot be
private - Interface requirements cannot be
private
Legacy Module Compatibility
Modules without module declaration, __include, or visibility modifiers are treated as legacy with all symbols public.
Capabilities System
The capabilities system helps manage differences in hardware capabilities across different GPUs, graphics APIs, and shader stages.
Capability Atoms and Requirements
Capability atoms represent targets, stages, extensions, and features:
GLSL_460- GLSL 460 targetcompute- compute shader stage_sm_6_7- shader model 6.7 featuresSPV_KHR_ray_tracing- SPIR-V extensionspvShaderClockKHR- SPIR-V capability
Declaring Requirements
[require(spvShaderClockKHR)]
[require(glsl, GL_EXT_shader_realtime_clock)]
[require(hlsl_nvapi)]
uint2 getClock() {...}
This creates requirement:
(spvShaderClockKHR | glsl + GL_EXT_shader_realtime_clock | hlsl_nvapi)
Conflicting Capabilities
Some capabilities are mutually exclusive:
- Different code generation targets (
hlsl,glsl) - Different shader stages (
vertex,fragment)
Requirements with conflicting atoms are incompatible.
Parent Scope Requirements
Requirements merge with parent scope:
[require(glsl)]
[require(hlsl)]
struct MyType
{
[require(hlsl, hlsl_nvapi)]
[require(spirv)]
static void method() { ... } // requirement: glsl | hlsl + hlsl_nvapi | spirv
}
Automatic Inference
Slang infers requirements for internal/private functions:
void myFunc()
{
if (getClock().x % 1000 == 0)
discard; // requires fragment stage
}
// Inferred: (spirv + SPV_KHR_shader_clock + spvShaderClockKHR + fragment | ...)
Target Switch
__target_switch introduces disjunctions:
void myFunc()
{
__target_switch
{
case spirv: ...;
case hlsl: ...;
}
}
// Requirement: (spirv | hlsl)
Capability Aliases
Aliases simplify cross-platform requirements:
alias sm_6_6 = _sm_6_6
| glsl_spirv_1_5 + sm_6_5 + GL_EXT_shader_atomic_int64 + atomicfloat2
| spirv_1_5 + sm_6_5 + GL_EXT_shader_atomic_int64 + atomicfloat2 + SPV_EXT_descriptor_indexing
| cuda
| cpp;
Usage: [require(sm_6_6)]
Validation
- Public methods and interface methods require explicit capability declarations
- Functions verified to not use capabilities beyond declared requirements
- Entrypoint capabilities recommended but not required
Compiling Code with Slang
Concepts
Source Units and Translation Units
Source units (files/strings) are grouped into translation units. Each translation unit produces a single module when compiled.
Entry Points
Entry points can be identified via:
[shader(...)]attributes (recommended)- Explicit entry point options for compatibility
Targets
A target represents platform and capabilities:
- Format: SPIR-V, DXIL, etc.
- Profile: D3D Shader Model 5.1, GLSL 4.60, etc.
- Optional capabilities: Vulkan extensions
- Code generation options
Layout
Parameter layout depends on:
- Modules and entry points used together
- Ordering of parameters
- Target-specific rules and constraints
Composition
Component types (modules, entry points) can be composed into composites defining units of shader code meant to be used together.
Linking
Resolves cross-module references and produces self-contained IR module for target code generation.
Kernels
Entry points generate kernel code. Same entry point can generate different kernels for different targets and compositions.
Command-Line Compilation with slangc
Simple Example
slangc hello-world.slang -target spirv -o hello-world.spv
Source Files and Translation Units
- Each input file is a distinct source unit
.slangfiles grouped into single translation unit- Each
.hlslfile gets its own translation unit
Common Options
-target <format>: Specify output format (spirv, dxil, hlsl, glsl, cuda, cpp)-entry <name>: Specify entry point function name-profile <profile>: Specify target profile-o <file>: Specify output file-D<name>[=<value>]: Define preprocessor macro-I<path>: Add include search path
Multiple Targets
Compile for multiple targets in single invocation:
slangc shader.slang -target spirv -o shader.spv -target dxil -o shader.dxil
Parameter Binding
Slang provides deterministic parameter binding across targets. Generated code includes explicit binding layouts to ensure consistent parameter locations.
Using the Compilation API
For applications requiring runtime compilation:
// Create session
Slang::ComPtr<slang::IGlobalSession> globalSession;
slang::createGlobalSession(globalSession.writeRef());
slang::ComPtr<slang::ISession> session;
slang::SessionDesc sessionDesc;
sessionDesc.targetCount = 1;
slang::TargetDesc targetDesc;
targetDesc.format = SLANG_SPIRV;
targetDesc.profile = SLANG_PROFILE_GLSL_450;
sessionDesc.targets = &targetDesc;
globalSession->createSession(sessionDesc, session.writeRef());
// Load module
slang::ComPtr<slang::IModule> module;
session->loadModule("myModule", module.writeRef());
// Create entry point
slang::ComPtr<slang::IEntryPoint> entryPoint;
module->findEntryPointByName("main", entryPoint.writeRef());
// Compose program
slang::ComPtr<slang::IComponentType> program;
slang::IComponentType* components[] = { module, entryPoint };
session->createCompositeComponentType(components, 2, program.writeRef());
// Compile
slang::ComPtr<slang::IComponentType> linkedProgram;
program->link(linkedProgram.writeRef());
// Get kernel code
slang::ComPtr<slang::IBlob> kernelCode;
linkedProgram->getEntryPointCode(0, 0, kernelCode.writeRef());
Reflection API
Compiling for Reflection
slang::IComponentType* program = ...;
slang::ProgramLayout* programLayout = program->getLayout(targetIndex);
Types and Variables
Variables
VariableReflection represents variable declarations:
void printVariable(slang::VariableReflection* variable)
{
const char* name = variable->getName();
slang::TypeReflection* type = variable->getType();
print("name: "); printQuotedString(name);
print("type: "); printType(type);
}
Types
TypeReflection represents types in the program:
void printType(slang::TypeReflection* type)
{
const char* name = type->getName();
slang::TypeReflection::Kind kind = type->getKind();
print("name: "); printQuotedString(name);
print("kind: "); printTypeKind(kind);
switch(type->getKind())
{
case slang::TypeReflection::Kind::Scalar:
print("scalar type: ");
printScalarType(type->getScalarType());
break;
case slang::TypeReflection::Kind::Struct:
print("fields:");
int fieldCount = type->getFieldCount();
for (int f = 0; f < fieldCount; f++)
{
slang::VariableReflection* field = type->getFieldByIndex(f);
printVariable(field);
}
break;
case slang::TypeReflection::Kind::Array:
print("element count: ");
printPossiblyUnbounded(type->getElementCount());
print("element type: ");
printType(type->getElementType());
break;
}
}
Parameter Layouts
Parameter layouts describe how parameters are mapped to target-specific resources:
void printParameterLayout(slang::ParameterLayout* parameterLayout)
{
slang::VariableReflection* variable = parameterLayout->getVariable();
printVariable(variable);
// Print binding information
int bindingRangeCount = parameterLayout->getBindingRangeCount();
for (int r = 0; r < bindingRangeCount; r++)
{
slang::BindingRangeType rangeType = parameterLayout->getBindingRangeType(r);
int rangeIndex = parameterLayout->getBindingRangeIndex(r);
int rangeSpace = parameterLayout->getBindingRangeSpace(r);
print("binding: ");
printBindingRangeType(rangeType);
printf(" index=%d space=%d", rangeIndex, rangeSpace);
}
}
Entry Point Layouts
Entry point layouts provide information about varying inputs/outputs and their stage-specific semantics:
void printEntryPointLayout(slang::EntryPointLayout* entryPointLayout)
{
slang::Stage stage = entryPointLayout->getStage();
print("stage: "); printStage(stage);
// Print varying parameters
int varyingCount = entryPointLayout->getVaryingParamCount();
for (int v = 0; v < varyingCount; v++)
{
slang::VaryingParameterReflection* varying =
entryPointLayout->getVaryingParamByIndex(v);
printVaryingParameter(varying);
}
}