awesome-copilot/skills/slang-shader-engineer/references/language-reference.md

Slang Language Reference

Source: Official Slang Shader Repository Official Docs: Official Slang Shader Online Documentation Playground: Official Slang Shader Sandbox

---

Table of Contents

1. Types
2. Interfaces and Generics
3. Automatic Differentiation
4. Modules and Access Control
5. Capabilities System
6. Compilation API
7. Reflection API
8. Compilation Targets
9. Target Compatibility Matrix
10. slangc Command Line

---

Types

Scalars

• Integer: int8_t, int16_t, int, int64_t, uint8_t, uint16_t, uint, uint64_t
• Float: half (16-bit), float (32-bit), double (64-bit)
• Other: bool, void

Vectors and Matrices

• vector<T,N> (N = 2–4), convenience: float3, uint2, etc.
• matrix<T,R,C> (R,C = 2–4), convenience: float3x4, etc.

Arrays

int a[3];            // fixed size
int a[] = {1,2,3};  // inferred size
void f(int b[]) {}  // unsized parameter

Arrays have .getCount().

Structures

struct MyData { int a; float b; }
// Custom constructor:
__init(int a_, float b_) { a = a_; b = b_; }

Parameter Blocks

struct MaterialParams { float3 albedo; float metallic; float roughness; };
ParameterBlock<MaterialParams> gMaterial;
// Binds to a single descriptor table (D3D12) or descriptor set (Vulkan)

Import

import foo;                  // imports foo.slang
__exported import foo;       // re-exports foo's declarations

import ≠ #include — no preprocessor sharing, each module loaded once.

---

Interfaces and Generics

Interface Definition and Implementation

interface ILight
{
    LightSample sample(float3 position);
    static int  getCount();               // static method in interface
    property int id { get; set; }        // property in interface
    int compute<T>(T val) where T : IBar; // generic method in interface
}

struct PointLight : ILight
{
    float3 position;
    LightSample sample(float3 hitPos) { ... }
    static int getCount() { return 1; }
    property int id { get { return _id; } set { _id = value; } }
    int _id;
    int compute<T>(T val) where T : IBar { ... }
}

Multiple Conformance

struct MyType : IFoo, IBar { ... }

Default Implementations

interface IFoo
{
    int getVal() { return 0; }  // default
}
struct MyType2 : IFoo
{
    override int getVal() { return 1; }
}

Generic Methods and Constraints

// Basic
float4 computeDiffuse<L : ILight>(float4 albedo, float3 P, float3 N, L light) { ... }

// where clause (multiple constraints)
struct MyType<T, U>
    where T: IFoo, IBar
    where U : IBaz<T>
{ ... }

// Simplified constraint syntax
int myMethod<T:IFoo>(T arg) { ... }

// Generic value parameters
void g<let n : int>() { ... }

// Optional conformance
int myMethod<T>(T arg) where optional T: IFoo
{
    if (T is IFoo) { arg.myMethod(1.0); }
}

Associated Types

interface IMaterial
{
    associatedtype B : IBRDF;
    B evalPattern(float3 pos, float2 uv);
}

struct MyCoolMaterial : IMaterial
{
    typedef DisneyBRDF B;
    B evalPattern(float3 pos, float2 uv) { ... }
}

Global-Scope Generic Parameters

type_param M : IMaterial;
M gMaterial;

---

Automatic Differentiation

Marking Functions Differentiable

[Differentiable]
float2 foo(float a, float b) { return float2(a * b * b, a * a); }

Forward Mode

DifferentialPair<float> dp_a = diffPair(1.0, 1.0); // (value, derivative)
DifferentialPair<float> dp_b = diffPair(2.4, 0.0);
DifferentialPair<float2> out = fwd_diff(foo)(dp_a, dp_b);
float2 primal     = out.p;
float2 derivative = out.d;

Backward Mode

DifferentialPair<float> dp_a = diffPair(1.0);
DifferentialPair<float> dp_b = diffPair(2.4);
float2 dL_doutput = float2(1.0, 0.0);
bwd_diff(foo)(dp_a, dp_b, dL_doutput);
float dL_da = dp_a.d;
float dL_db = dp_b.d;

Differentiable Types

Built-in: float, double, half, vectors/matrices thereof, arrays of differentiable types.

struct MyType : IDifferentiable { float x; float y; }

Custom Derivatives

[Differentiable]
[ForwardDerivative(myForwardDeriv)]
[BackwardDerivative(myBackwardDeriv)]
float myFunc(float x) { ... }

---

Modules and Access Control

Defining a Module

// scene.slang
module scene;
__include "scene-helpers";   // NOT preprocessor — no macro sharing

// scene-helpers.slang
implementing scene;
// all entities in module are mutually visible regardless of include order

Module Include Syntax

__include dir.sub_file;           // → "dir/sub-file.slang"
__include "dir/sub-file.slang";

Access Modifiers

Modifier	Visibility
public	Everywhere (other files, modules)
internal	Same module only (default for most)
private	Same type and nested types only

Rules:

• Interface members inherit the interface's visibility.
• Legacy modules (no module declaration) treat all symbols as public.
• More-visible entities cannot expose less-visible entities in their signatures.

---

Capabilities System

Declaring Requirements

[require(spvShaderClockKHR)]
[require(glsl, GL_EXT_shader_realtime_clock)]
[require(hlsl_nvapi)]
uint2 getClock() { ... }
// Combined: (spvShaderClockKHR | glsl + GL_EXT_shader_realtime_clock | hlsl_nvapi)

Target Switch

void myFunc()
{
    __target_switch
    {
    case spirv: /* SPIR-V path */ break;
    case hlsl:  /* HLSL path  */ break;
    }
}

Capability Aliases

// Use a named alias instead of spelling out the full disjunction:
[require(sm_6_6)]
void myFunc() { ... }

Common Capability Atoms

• Stages: vertex, fragment, compute, hull, domain, geometry
• APIs: hlsl, glsl, spirv, cuda, cpp
• Features: _sm_6_7, SPV_KHR_ray_tracing, spvShaderClockKHR, hlsl_nvapi

---

Compilation API (C++)

// 1. Create global session
Slang::ComPtr<slang::IGlobalSession> globalSession;
slang::createGlobalSession(globalSession.writeRef());

// 2. Create session with target
slang::SessionDesc sessionDesc = {};
slang::TargetDesc targetDesc   = {};
targetDesc.format   = SLANG_SPIRV;
targetDesc.profile  = SLANG_PROFILE_GLSL_450;
sessionDesc.targets      = &targetDesc;
sessionDesc.targetCount  = 1;
Slang::ComPtr<slang::ISession> session;
globalSession->createSession(sessionDesc, session.writeRef());

// 3. Load module and entry point
Slang::ComPtr<slang::IModule>     module;
Slang::ComPtr<slang::IEntryPoint> entryPoint;
session->loadModule("myModule", module.writeRef());
module->findEntryPointByName("main", entryPoint.writeRef());

// 4. Compose and link
slang::IComponentType* components[] = { module, entryPoint };
Slang::ComPtr<slang::IComponentType> program, linkedProgram;
session->createCompositeComponentType(components, 2, program.writeRef());
program->link(linkedProgram.writeRef());

// 5. Get kernel code
Slang::ComPtr<slang::IBlob> kernelCode;
linkedProgram->getEntryPointCode(0, 0, kernelCode.writeRef());

CMake integration

find_package(slang REQUIRED PATHS ${CMAKE_INSTALL_PREFIX} NO_DEFAULT_PATH)
target_link_libraries(yourLib PUBLIC slang::slang)

---

Reflection API

slang::ProgramLayout* layout = program->getLayout(targetIndex);

// Enumerate global parameters
int paramCount = layout->getParameterCount();
for (int i = 0; i < paramCount; i++)
{
    slang::VariableLayoutReflection* param = layout->getParameterByIndex(i);
    const char* name = param->getName();
    int binding      = param->getBindingIndex();
    int space        = param->getBindingSpace();
}

// Entry point layouts (stage, varying params)
slang::EntryPointLayout* ep = layout->getEntryPointByIndex(0);
slang::Stage stage = ep->getStage();

Type reflection kind values: Scalar, Vector, Matrix, Array, Struct, Resource, SamplerState, etc.

---

Compilation Targets

D3D11 (DXBC)

Stages: vertex, hull, domain, geometry, fragment
Registers: b (cbuffers), t (SRVs), u (UAVs), s (samplers)

D3D12 (DXIL)

Adds: ray tracing (raygeneration, closesthit, miss, anyhit, intersection, callable)
Root signatures: root constants, descriptor tables, root descriptors.

Vulkan (SPIR-V)

Descriptor sets instead of tables. Push constants instead of root constants.

[[vk::binding(0, 1)]] Texture2D myTexture;
[[vk::push_constant]]  cbuffer PC { float4 color; };
[[vk::shader_record]]  cbuffer SR { uint id; };

CUDA

• Native pointer support, cooperative groups, tensor ops.
• No graphics pipeline stages, limited texture ops.

Metal

• Argument buffers, tile-based optimizations, unified memory.
• No double type.

CPU/C++

• Host-side execution for debugging and reference implementations.
• No GPU-specific features.

---

Target Compatibility Matrix

Feature	D3D11	D3D12	Vulkan	CUDA	Metal	CPU
half type	✗	✓	✓	✓	✓	✗
double type	✓	✓	✓	✓	✗	✓
u/int8_t	✗	✗	✓	✓	✓	✓
u/int16_t	✗	✓	✓	✓	✓	✓
u/int64_t	✗	✓	✓	✓	✓	✓
Wave intrinsics (SM6)	✗	✓	Partial	✓	✗	✗
Ray tracing	✗	✓	✓	✗	✗	✗
Mesh shaders	✗	✓	✓	✗	✓	✗
Tessellation	✓	✓	✗	✗	✗	✗
Graphics pipeline	✓	✓	✓	✗	✓	✗
Native bindless	✗	✗	✗	✓	✗	✓
Atomics	✓	✓	✓	✓	✓	✓
Pointers	✗	✗	✓	✓	✗	✓

Platform notes:

• Tessellation: Not available on Vulkan (use tessellation via mesh shaders instead).
• Half in D3D12: Problems with StructuredBuffer<half> — avoid.
• Wave intrinsics on CUDA: Preliminary, uses synthesized WaveMask.
• 8/16-bit integers on D3D: Require specific shader models and DXIL flags.

---

slangc Command Line

# Basic
slangc shader.slang -target spirv -o shader.spv
slangc shader.slang -target dxil  -o shader.dxil
slangc shader.slang -target glsl  -o shader.glsl
slangc shader.slang -target cuda  -o shader.cu
slangc shader.slang -target metal -o shader.metal
slangc shader.slang -target cpp   -o shader.cpp

# Multi-target
slangc shader.slang -target spirv -o shader.spv -target dxil -o shader.dxil

# Entry point and stage
slangc shader.slang -target spirv -entry mainCS -stage compute -o out.spv

# Profile
slangc shader.slang -target glsl  -profile glsl_460 -o out.glsl
slangc shader.slang -target dxil  -profile sm_6_7   -o out.dxil

# Matrix layout (important for row-major engines like xMath)
slangc shader.slang -target spirv -matrix-layout-row-major -o out.spv

# Optimization
slangc shader.slang -O0   # no optimization
slangc shader.slang -O2   # standard
slangc shader.slang -O3   # aggressive

# Debug info
slangc shader.slang -g -o out.spv

# Include paths and macros
slangc shader.slang -I./include -DENABLE_SHADOWS=1 -o out.spv

# Capabilities
slangc shader.slang -capability spvShaderClockKHR -target spirv -o out.spv

# Vulkan-specific
slangc shader.slang -target spirv -fvk-use-entrypoint-name -o out.spv
slangc shader.slang -target spirv -fvk-use-gl-layout       -o out.spv

# Precompiled modules
slangc shader.slang -r prebuilt.slang-module -target spirv -o out.spv

# Emit IR
slangc shader.slang -emit-ir -o shader.slang-module

Optimization Levels

Flag	Effect
-O0	No optimization (debugging)
-O1	Basic optimization
-O2	Standard optimization (default)
-O3	Aggressive (may increase compile time)

Stage Names for -stage

vertex · fragment · compute · hull · domain · geometry raygeneration · closesthit · miss · anyhit · intersection · callable