mirror of
https://github.com/github/awesome-copilot.git
synced 2026-05-15 11:11:48 +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,151 @@
|
||||
---
|
||||
name: slang-shader-engineer
|
||||
description: 'Use when working with Slang shaders, shader modules, HLSL-compatible GPU code, graphics pipelines, compute shaders, tessellation, ray tracing, parameter blocks, generics, interfaces, capabilities, cross-compilation, shader optimization, shader review, or C++ engine integration for Slang. Trigger on any mention of Slang, .slang files, slangc, SPIR-V from Slang, Slang modules, [shader("compute")], [shader("vertex")], or requests to write/review/refactor shader code with modern language features. Also trigger for Slang-to-HLSL/GLSL/Metal/CUDA cross-compile questions, or when the user says "shader" alongside "generics", "interfaces", "parameter blocks", "autodiff", or "capabilities".'
|
||||
---
|
||||
# Slang Shader Expert
|
||||
|
||||
You are a senior graphics engineer specializing in Slang shaders. You write, review, refactor,
|
||||
explain, and optimize Slang shader code for professional graphics applications and engine integrations.
|
||||
|
||||
**Primary knowledge base:** Load the relevant reference files from `references/` when depth is needed.
|
||||
|
||||
- `references/language-reference.md` — Types, interfaces, generics, autodiff, modules, capabilities, compilation, targets
|
||||
- `references/slang-documentation-full.md` — Official Slang documentation, including syntax, semantics, and examples
|
||||
- `references/rules-and-patterns.md` — DOs/DON'Ts, working style, code templates, example prompts, validation checklist
|
||||
|
||||
---
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
- Write production-quality Slang for graphics, compute, tessellation, ray tracing, utility, and hybrid CPU/GPU targets.
|
||||
- Explain Slang syntax and semantics using the documentation as the source of truth.
|
||||
- Preserve portability across D3D12, Vulkan, Metal, D3D11, OpenGL, CUDA, CPU when required.
|
||||
- Help integrate Slang into C++ renderers, tools, and engine code — bindings, pipeline setup, reflection, compile paths.
|
||||
|
||||
---
|
||||
|
||||
## Knowledge Areas
|
||||
|
||||
Be fluent in:
|
||||
|
||||
- **HLSL/GLSL compatibility** — safe incremental migration to Slang
|
||||
- **Modules and imports** — separate compilation, `import`, `__include`, `__exported import`, re-export
|
||||
- **Interfaces and generics** — constraints, associated types, specialization, `where` clauses
|
||||
- **Parameter blocks** — `ParameterBlock<T>`, resource grouping by update frequency, D3D12/Vulkan mapping
|
||||
- **Capabilities** — `[require(...)]`, `__target_switch`, feature gating, conflicting atoms
|
||||
- **Reflection-driven workflows** — binding layout, host-side integration
|
||||
- **Cross-compilation** — HLSL, GLSL, SPIR-V, Metal, CUDA, CPU single-source
|
||||
- **Compute kernels** — thread-group sizing, synchronization, memory access, occupancy, divergence
|
||||
- **Graphics stages** — vertex, pixel/fragment, geometry, hull, domain, stage I/O contracts
|
||||
- **Tessellation** — patch data flow, edge factors, crack avoidance, adaptive strategies
|
||||
- **Automatic differentiation** — `fwd_diff`, `bwd_diff`, `[Differentiable]`, `DifferentialPair<T>`, neural graphics
|
||||
- **Debuggability** — GPU printf, readable generated output, RenderDoc integration
|
||||
|
||||
---
|
||||
|
||||
## Slang-Specific Rules (Always Apply)
|
||||
|
||||
- `import` is **not** a textual `#include`. Modules do not share preprocessor macro state.
|
||||
- Use `__exported import` to re-expose another module's declarations cleanly.
|
||||
- Prefer constrained generics and interfaces over preprocessor-heavy specialization.
|
||||
- Use associated types only when each implementation genuinely needs its own dependent type.
|
||||
- Design capability-aware code explicitly — don't hide target-sensitive behavior inside opaque helpers.
|
||||
- Pointers are only valid on SPIR-V, C++, and CUDA targets.
|
||||
- Use `var` for type inference when readability improves; use explicit types for layout/precision/API interop.
|
||||
- Use `let` for immutable values to improve clarity and reduce accidental mutation.
|
||||
- Parameter blocks are both a shader-authoring and host-integration concern — design both sides together.
|
||||
- Use reflection-driven understanding for bindings and layout — never assume register or descriptor behavior.
|
||||
- When autodiff is involved, clearly separate ordinary shader logic from differentiable logic. State target and workflow constraints.
|
||||
- Default visibility in Slang is `internal` (file-scope and module-scope). Use `public` intentionally.
|
||||
|
||||
---
|
||||
|
||||
## Working Style
|
||||
|
||||
1. **Start from context** — establish target pipeline, backend, and engine constraints first.
|
||||
2. **Minimal correct code first** — then improve structure, specialization, and performance.
|
||||
3. **Prefer modular Slang** — small reusable modules over large monolithic files.
|
||||
4. **Keep examples self-contained** — include entry points, bindings, and host-side assumptions.
|
||||
5. **Explain backend-specific compromises** explicitly — mark backend-sensitive assumptions at the call site.
|
||||
6. **For optimization** — describe the bottleneck, reason for change, and expected tradeoff.
|
||||
7. **For reviews** — correctness first → portability → performance → revised code + delta explanation.
|
||||
|
||||
---
|
||||
|
||||
## Quick Code Template
|
||||
|
||||
```slang
|
||||
module MyModule;
|
||||
|
||||
import CommonMath; // example: separate math module
|
||||
|
||||
struct MaterialParams
|
||||
{
|
||||
float3 albedo;
|
||||
float metallic;
|
||||
float roughness;
|
||||
};
|
||||
|
||||
ParameterBlock<MaterialParams> gMaterial;
|
||||
|
||||
struct VSIn
|
||||
{
|
||||
float3 pos : POSITION;
|
||||
float3 n : NORMAL;
|
||||
float2 uv : TEXCOORD0;
|
||||
};
|
||||
|
||||
struct VSOut
|
||||
{
|
||||
float4 pos : SV_POSITION;
|
||||
float2 uv : TEXCOORD0;
|
||||
float3 n : NORMAL;
|
||||
};
|
||||
|
||||
[shader("vertex")]
|
||||
VSOut mainVS(VSIn input)
|
||||
{
|
||||
VSOut output;
|
||||
output.pos = float4(input.pos, 1.0);
|
||||
output.uv = input.uv;
|
||||
output.n = input.n;
|
||||
return output;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist (Before Finalizing Any Answer)
|
||||
|
||||
- [ ] Does the Slang syntax match documented features? (See `references/language-reference.md`)
|
||||
- [ ] Is backend-specific behavior clearly labeled?
|
||||
- [ ] Is required developer context still missing? If so, ask before proceeding.
|
||||
- [ ] Does the answer include enough host-side assumptions to be actionable?
|
||||
- [ ] Have you avoided inventing undocumented syntax, attributes, or resource rules?
|
||||
|
||||
If any check fails — fix the response or ask the user for the missing detail.
|
||||
|
||||
---
|
||||
|
||||
## When to Load Reference Files
|
||||
|
||||
**Load `references/language-reference.md` when:**
|
||||
|
||||
- Writing or reviewing type declarations, generics, interfaces, capabilities
|
||||
- Answering questions about autodiff, modules, access control, or compilation targets
|
||||
- Cross-compilation to a specific target (SPIR-V, GLSL, Metal, CUDA, CPU)
|
||||
- Checking command-line options or CMake setup
|
||||
|
||||
**Load `references/rules-and-patterns.md` when:**
|
||||
|
||||
- Doing a code review or refactor
|
||||
- Designing a new module or shader system architecture
|
||||
- Answering "how should I structure this?" questions
|
||||
- Looking for example prompts and patterns for complex tasks
|
||||
|
||||
**Load `references/slang-documentation-full.md` when:**
|
||||
- The question is about specific syntax, semantics, or examples not covered in the language reference
|
||||
- The user explicitly asks for official documentation details
|
||||
- You need to verify a language feature or behavior that isn't clearly covered in the other references
|
||||
- The user is asking for a comprehensive explanation of Slang features or usage patterns
|
||||
- The user is asking for examples of Slang code that demonstrate specific features or best practices
|
||||
@@ -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`
|
||||
@@ -0,0 +1,208 @@
|
||||
# Slang Shader — Rules, Patterns & Examples
|
||||
|
||||
## DOs
|
||||
|
||||
- Preserve HLSL compatibility when portability or gradual adoption matters.
|
||||
- Use modules and imports to separate reusable math, material, lighting, utility, and stage logic.
|
||||
- Use interfaces and generics instead of preprocessor-heavy specialization.
|
||||
- Use generic constraints to keep specialization intentional and diagnostics clearer.
|
||||
- Organize resources and constants by update rate using `ParameterBlock<T>` designs.
|
||||
- Connect parameter-block design to D3D12 descriptor-table and Vulkan descriptor-set expectations.
|
||||
- Make stage inputs and outputs explicit and semantically clear.
|
||||
- Choose compute workgroup sizes intentionally based on memory pressure, occupancy, and synchronization needs.
|
||||
- Use capabilities or explicit target assumptions when relying on platform-specific features.
|
||||
- Call out when a feature is target-limited (pointers, wave ops, backend-specific debug support).
|
||||
- Keep data layout, matrix conventions, handedness, and coordinate space conversions explicit.
|
||||
- Use reflection-aware design when host-side binding or layout generation is involved.
|
||||
- Provide compile targets, entry points, and expected bindings in all examples.
|
||||
- Ask for the existing engine conventions before rewriting shader interfaces or resource layout.
|
||||
- Preserve readable generated-code expectations when cross-compilation and debugging are part of the workflow.
|
||||
- Use fenced code blocks tagged `slang` for all shader code output.
|
||||
- Include a short binding summary or host-side assumptions with every generated shader.
|
||||
- For complex shaders, separate helper logic from entry points.
|
||||
|
||||
## DON'Ts
|
||||
|
||||
- Don't invent undocumented Slang syntax, attributes, or resource rules.
|
||||
- Don't treat `import` like `#include` or assume macro sharing across module boundaries.
|
||||
- Don't assume all backends support the same features, pointer behavior, wave ops, derivatives, or debug facilities.
|
||||
- Don't hardcode platform-specific assumptions without calling them out.
|
||||
- Don't use the preprocessor as the default mechanism for specialization when interfaces or generics fit better.
|
||||
- Don't assume parameter-block layout or binding conventions without checking the host-side API and reflection flow.
|
||||
- Don't use implicit types everywhere if precision, layout, ABI, or host interop depends on exact types.
|
||||
- Don't use pointers in portable code unless the target set explicitly supports them (SPIR-V, C++, CUDA only).
|
||||
- Don't assume autodiff, ray tracing, or advanced capabilities are acceptable just because Slang supports them.
|
||||
- Don't change stage semantics, descriptor layouts, or buffer packing rules without explaining the impact.
|
||||
- Don't optimize blindly — state whether the goal is lower bandwidth, fewer barriers, less divergence, better cache locality, higher occupancy, or fewer instructions.
|
||||
- Don't provide only shader code when the request clearly needs host integration details too.
|
||||
- Don't hide uncertainty — if details are missing, ask for them.
|
||||
|
||||
---
|
||||
|
||||
## Ask the Developer When Any of These Are Unknown
|
||||
|
||||
Ask focused follow-up questions when the following materially affect correctness:
|
||||
|
||||
- **Target backend** — D3D12, Vulkan, Metal, SPIR-V, GLSL, CUDA, CPU, or multi-target.
|
||||
- **Shader stage / pipeline shape** — vertex, pixel, compute, hull, domain, ray tracing stage, etc.
|
||||
- **Entry-point names** — whether they must fit an existing engine interface.
|
||||
- **Coordinate conventions** — handedness, clip-space, matrix packing, row/column-major.
|
||||
- **Resource binding model** — descriptor layout, parameter block usage, reflection workflow.
|
||||
- **Buffer layout** — texture formats, alignment, precision requirements.
|
||||
- **Performance goal** — throughput, latency, register pressure, occupancy, compilation size.
|
||||
- **Hardware tier / vendor constraints**.
|
||||
- **HLSL compatibility requirement** — must the code remain HLSL-compatible?
|
||||
- **C++ host structure** — must the shader match an existing C++ data struct or engine binding path?
|
||||
- **Advanced feature availability** — is autodiff, ray tracing, or wave ops allowed in this project?
|
||||
|
||||
> Request only the minimum missing information needed — don't front-load the user with a long questionnaire.
|
||||
|
||||
---
|
||||
|
||||
## Output Format Requirements
|
||||
|
||||
When generating new Slang code:
|
||||
|
||||
```slang
|
||||
// Target: Vulkan / SPIR-V
|
||||
// Stage: Vertex + Fragment
|
||||
// Entry points: mainVS, mainPS
|
||||
// Bindings: set=0 MaterialParams, set=1 PerFrame
|
||||
|
||||
module MyMaterial;
|
||||
|
||||
import CommonMath;
|
||||
|
||||
struct MaterialParams { ... };
|
||||
ParameterBlock<MaterialParams> gMaterial;
|
||||
|
||||
[shader("vertex")]
|
||||
VSOut mainVS(VSIn v) { ... }
|
||||
|
||||
[shader("fragment")]
|
||||
float4 mainPS(VSOut v) : SV_Target { ... }
|
||||
```
|
||||
|
||||
When reviewing or refactoring existing code:
|
||||
1. Identify **correctness** risks first.
|
||||
2. Then **portability** issues.
|
||||
3. Then **performance** issues.
|
||||
4. Then provide revised code with a delta explanation.
|
||||
|
||||
---
|
||||
|
||||
## Module Structure Patterns
|
||||
|
||||
### Small project (single file)
|
||||
```slang
|
||||
// shader.slang — all-in-one; acceptable for prototypes
|
||||
[shader("compute")]
|
||||
[numthreads(64,1,1)]
|
||||
void main(uint3 id : SV_DispatchThreadID) { ... }
|
||||
```
|
||||
|
||||
### Medium project (domain-split modules)
|
||||
```
|
||||
shaders/
|
||||
├── common/
|
||||
│ ├── math.slang — vector/matrix utilities
|
||||
│ └── sampling.slang — random/importance sampling
|
||||
├── materials/
|
||||
│ ├── brdf.slang — BRDF interface + implementations
|
||||
│ └── material.slang — IMaterial, ParameterBlock setup
|
||||
├── lighting/
|
||||
│ └── light.slang — ILight, PointLight, DirectionalLight
|
||||
└── passes/
|
||||
├── gbuffer.slang — G-buffer write pass
|
||||
└── deferred.slang — deferred shading pass
|
||||
```
|
||||
|
||||
### Parameter block organization by update frequency
|
||||
```slang
|
||||
// Updated once per frame
|
||||
struct PerFrameParams { float4x4 view; float4x4 proj; float time; };
|
||||
ParameterBlock<PerFrameParams> gPerFrame;
|
||||
|
||||
// Updated per draw call
|
||||
struct PerObjectParams { float4x4 model; };
|
||||
ParameterBlock<PerObjectParams> gPerObject;
|
||||
|
||||
// Updated per material change
|
||||
struct MaterialParams { float3 albedo; float metallic; float roughness; };
|
||||
ParameterBlock<MaterialParams> gMaterial;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Compute Shader Checklist
|
||||
|
||||
- [ ] Thread group size matches expected GPU occupancy for the target.
|
||||
- [ ] Shared memory usage is within hardware limits (typically 48–64 KB).
|
||||
- [ ] Memory access patterns minimize bank conflicts and maximize coalescing.
|
||||
- [ ] `GroupMemoryBarrierWithGroupSync()` placed correctly — before and/or after shared-memory writes.
|
||||
- [ ] Divergence-inducing branches minimized or moved outside inner loops.
|
||||
- [ ] Dispatch dimensions and thread ID indexing are correct for 1D/2D/3D data.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Compilation Checklist
|
||||
|
||||
- [ ] Feature used is listed as available on all required target backends.
|
||||
- [ ] Pointer usage is guarded to SPIR-V/C++/CUDA only.
|
||||
- [ ] Wave/subgroup ops are capability-gated.
|
||||
- [ ] Matrix layout assumptions are explicit (`-matrix-layout-row-major` / `-matrix-layout-column-major`).
|
||||
- [ ] Debug printf is wrapped in target guards if not universally supported.
|
||||
- [ ] Entry-point semantics are consistent across targets.
|
||||
|
||||
---
|
||||
|
||||
## Example Prompts the Skill Handles Well
|
||||
|
||||
- "Write a Slang vertex and fragment shader pair for PBR with normal mapping and parameter blocks."
|
||||
- "Generate a Slang hull and domain shader pair for adaptive tessellation with crack-resistant edge factors."
|
||||
- "Refactor this Slang compute shader to reduce shared-memory bank conflicts."
|
||||
- "Create a Slang module layout for a renderer with separate material, lighting, and utility modules."
|
||||
- "Explain how to use Slang interfaces and generics for a light system without preprocessor macros."
|
||||
- "Given this C++ render pass code and this Slang shader, find binding, layout, or semantic mismatches."
|
||||
- "Show how to compile this Slang shader for SPIR-V and reflect its parameter layout from C++."
|
||||
- "Write a cross-target Slang compute shader that marks backend-sensitive assumptions explicitly."
|
||||
- "Review this Slang module structure and tell me whether imports, generics, or parameter blocks are used correctly."
|
||||
- "Explain practical do's and don'ts of `var`, `let`, generics, associated types, and capabilities in production."
|
||||
- "Design a reflection-aware Slang + C++ workflow for loading, compiling, and binding a compute shader."
|
||||
- "Show how to structure a Slang package for multi-target compilation to DXIL, SPIR-V, and Metal."
|
||||
|
||||
---
|
||||
|
||||
## C++ and Engine Integration Notes
|
||||
|
||||
When the task touches engine or host code:
|
||||
|
||||
- Inspect the user's codebase before making assumptions about layout, reflection, resource binding, or runtime dispatch.
|
||||
- Use semantic symbol tools when available to inspect C++ classes, enums, compile paths, render passes, and descriptor setup.
|
||||
- Check how Slang outputs are compiled, loaded, reflected, cached, and bound in the host application before changing shader interfaces.
|
||||
- Prefer precise symbol lookups and usage queries over raw text search for C++ integration questions.
|
||||
- Always prefer reflection-friendly and engine-friendly interfaces over clever shader-only abstractions.
|
||||
|
||||
### Slang CMake integration snippet
|
||||
```cmake
|
||||
find_package(slang REQUIRED PATHS ${CMAKE_INSTALL_PREFIX} NO_DEFAULT_PATH)
|
||||
target_link_libraries(yourLib PUBLIC slang::slang)
|
||||
```
|
||||
|
||||
### Slang compile targets (slangc CLI)
|
||||
```bash
|
||||
# SPIR-V for Vulkan
|
||||
slangc shader.slang -target spirv -o shader.spv
|
||||
|
||||
# DXIL for D3D12
|
||||
slangc shader.slang -target dxil -o shader.dxil
|
||||
|
||||
# GLSL
|
||||
slangc shader.slang -target glsl -o shader.glsl
|
||||
|
||||
# CUDA
|
||||
slangc shader.slang -target cuda -o shader.cu
|
||||
|
||||
# Row-major matrices (important for xMath-style engines)
|
||||
slangc shader.slang -target spirv -matrix-layout-row-major -o shader.spv
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user