mirror of
https://github.com/github/awesome-copilot.git
synced 2026-05-15 19:21:45 +00:00
Add complete skill for Slang shader language (#1677)
* Add complete skill for Slang shader language - Included the full Offical Slang LLM documentation. - Included sections on language features, interfaces, generics, automatic differentiation, modules, capabilities system, compiling code, reflection API, compilation targets, and FAQs. - Allows agents to write comprehensive slang code for graphics and compute shaders. * Fix for conflicting description matches established skill conventions Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Thomas Ray
GitHub
@@ -0,0 +1,449 @@
|
||||
# Slang Language Reference
|
||||
|
||||
**Source:** [Official Slang Shader Repository](https://github.com/shader-slang/slang "Slang Shader repository")
|
||||
**Official Docs:** [Official Slang Shader Online Documentation](https://shader-slang.com/slang/user-guide/ "Slang Shader Online documentation")
|
||||
**Playground:** [Official Slang Shader Sandbox](https://shader-slang.com/slang-playground)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Types](#types)
|
||||
2. [Interfaces and Generics](#interfaces-and-generics)
|
||||
3. [Automatic Differentiation](#automatic-differentiation)
|
||||
4. [Modules and Access Control](#modules-and-access-control)
|
||||
5. [Capabilities System](#capabilities-system)
|
||||
6. [Compilation API](#compilation-api-c)
|
||||
7. [Reflection API](#reflection-api)
|
||||
8. [Compilation Targets](#compilation-targets)
|
||||
9. [Target Compatibility Matrix](#target-compatibility-matrix)
|
||||
10. [slangc Command Line](#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
|
||||
```hlsl
|
||||
int a[3]; // fixed size
|
||||
int a[] = {1,2,3}; // inferred size
|
||||
void f(int b[]) {} // unsized parameter
|
||||
```
|
||||
Arrays have `.getCount()`.
|
||||
|
||||
### Structures
|
||||
```hlsl
|
||||
struct MyData { int a; float b; }
|
||||
// Custom constructor:
|
||||
__init(int a_, float b_) { a = a_; b = b_; }
|
||||
```
|
||||
|
||||
### Parameter Blocks
|
||||
```hlsl
|
||||
struct MaterialParams { float3 albedo; float metallic; float roughness; };
|
||||
ParameterBlock<MaterialParams> gMaterial;
|
||||
// Binds to a single descriptor table (D3D12) or descriptor set (Vulkan)
|
||||
```
|
||||
|
||||
### Import
|
||||
```hlsl
|
||||
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
|
||||
```hlsl
|
||||
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
|
||||
```hlsl
|
||||
struct MyType : IFoo, IBar { ... }
|
||||
```
|
||||
|
||||
### Default Implementations
|
||||
```hlsl
|
||||
interface IFoo
|
||||
{
|
||||
int getVal() { return 0; } // default
|
||||
}
|
||||
struct MyType2 : IFoo
|
||||
{
|
||||
override int getVal() { return 1; }
|
||||
}
|
||||
```
|
||||
|
||||
### Generic Methods and Constraints
|
||||
```hlsl
|
||||
// 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
|
||||
```hlsl
|
||||
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
|
||||
```hlsl
|
||||
type_param M : IMaterial;
|
||||
M gMaterial;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automatic Differentiation
|
||||
|
||||
### Marking Functions Differentiable
|
||||
```hlsl
|
||||
[Differentiable]
|
||||
float2 foo(float a, float b) { return float2(a * b * b, a * a); }
|
||||
```
|
||||
|
||||
### Forward Mode
|
||||
```hlsl
|
||||
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
|
||||
```hlsl
|
||||
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.
|
||||
```hlsl
|
||||
struct MyType : IDifferentiable { float x; float y; }
|
||||
```
|
||||
|
||||
### Custom Derivatives
|
||||
```hlsl
|
||||
[Differentiable]
|
||||
[ForwardDerivative(myForwardDeriv)]
|
||||
[BackwardDerivative(myBackwardDeriv)]
|
||||
float myFunc(float x) { ... }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Modules and Access Control
|
||||
|
||||
### Defining a Module
|
||||
```hlsl
|
||||
// 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
|
||||
```hlsl
|
||||
__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
|
||||
```hlsl
|
||||
[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
|
||||
```hlsl
|
||||
void myFunc()
|
||||
{
|
||||
__target_switch
|
||||
{
|
||||
case spirv: /* SPIR-V path */ break;
|
||||
case hlsl: /* HLSL path */ break;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Capability Aliases
|
||||
```hlsl
|
||||
// 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++)
|
||||
|
||||
```cpp
|
||||
// 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
|
||||
```cmake
|
||||
find_package(slang REQUIRED PATHS ${CMAKE_INSTALL_PREFIX} NO_DEFAULT_PATH)
|
||||
target_link_libraries(yourLib PUBLIC slang::slang)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reflection API
|
||||
|
||||
```cpp
|
||||
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.
|
||||
```hlsl
|
||||
[[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
|
||||
|
||||
```bash
|
||||
# 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`
|
||||
Reference in New Issue
Block a user