summaryrefslogtreecommitdiff
path: root/docs/user-guide
AgeCommit message (Collapse)Author
2025-07-02add task shader alias (#7372)Sirox
* alias amplification shader as task shader and add mesh shader profile * add task shader stage alias to capabilities * regenerate command line reference --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-06-29Support the GLSL/SPIR-V Built-in variable `DeviceIndex` (#7552)ArielG-NV
* Support DeviceIndex * format code * regenerate command line reference --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-06-28Minimal optional constraints (#7422)Julius Ikkala
* Parse optional witness syntax * Allow failing optional constraint * Make `is` work with optional constraint * Allow using optional constraint in checked if statements * Fix tests * Make it work with structs * Fix MSVC build error * Disallow using `as` with optional constraints * Update test to match split is/as errors * Add tests * Fix uninitialized variables in tests * Add tests of incorrect uses & fix related bugs * Mention optional constraints in docs * format code * Fix type unification with NoneWitness * Fix formatting --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com> Co-authored-by: Nathan V. Morrical <natemorrical@gmail.com>
2025-06-16Require `override` keyword for overriding default interface methods. (#7458)Yong He
* Require `override` keyword for overriding default interface methods. * Update doc. * Fix test.
2025-06-13Allow interface methods to have default implementations. (#7439)Yong He
2025-06-13Add new capdef for lss intrinsics (#7427)Mukund Keshava
* Add new capdef for lss intrinsics Fixes #7426 Raygen shaders need to be supported for only hitobject APIs. So we need a special capability for that, instead of a common one. * regenerate command line reference --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-06-10Fix IR layout of 3-element vectors in cbuffers for -fvk-use-dx-layout (#7282)James Helferty (NVIDIA)
* Better handling for 16-byte boundary of d3d cbuffer Fixes #6921 D3D cbuffers have slightly different packing rules that allow packing vectors into a 16-byte slot at element alignments, except when a field would cross a 16-byte boundary. In that case, we need to realign the field to the next 16-byte boundary. In particular, this impacts vec3s, which are not a power of two in size and thus require slightly different alignment logic, compared to std430 and std140. (Example: a float and float3 should fit together in that order in a single slot.) Adds test cases. Adds documentation page for GLSL target
2025-06-10Add optix support for coopvec (#7286)Mukund Keshava
* WiP: Add coopvec support for Optix * format code * fix minor issues * Fix review comments --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-06-04Update user-guide toc. (#7349)Yong He
2025-06-04Add legalization for 0-sized arrays. (#7327)Yong He
* Add legalization for 0-sized arrays. * Allow 0-sized arrays in the front-end. * More tests. * Add `Conditional<T, hasValue>` type to core module. * Update toc. * Fix wording. * Update test.
2025-06-03Fix grammer for auto-diff doc (#7215)ArielG-NV
1. "here, $$f$$ here has" => "here, $$f$$ has" 2. $f$ ==> $$f$$ * $f$ does not render on website, works on vscode
2025-05-29Language version + tuple syntax. (#7230)Yong He
* Language version + tuple syntax. * Fix compile error. * regenerate documentation Table of Contents * Fix. * regenerate command line reference * Fix. * Fix. * Fix more test failures. * revert empty line change, * Retrigger CI * #version->#lang * Update source/core/slang-type-text-util.cpp Co-authored-by: ArielG-NV <159081215+ArielG-NV@users.noreply.github.com> * Remove comments. * Fix parsing logic. * Fix parser. * Fix parser. * update test comment * Update options. * regenerate documentation Table of Contents * regenerate command line reference --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com> Co-authored-by: ArielG-NV <159081215+ArielG-NV@users.noreply.github.com>
2025-05-28fix doc's website table & grammer (#7268)ArielG-NV
github pages reqire new-line to render table correctly. Grammer problem.
2025-05-28Change default descriptor binding to be VkMutable (#7224)ArielG-NV
* change default descriptor binding to be VkMutable
2025-05-27Add LSS intrinsics (#7200)Mukund Keshava
* WiP: LSS intrinsics: initial commit * format code * Fix CI failures * Address review comment --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-05-25Add full support for SPV_NV_shader_subgroup_partitioned (#7103)Darren Wihandi
* Properly implement WaveMask* variants of WaveMultiPrefix* intrinsics * More partitioned intrinsics * More partitioned intrinsics and cleaned up non-prefixed WaveMask* implementations * Refactor HLSL WaveMultiPrefix* implementations * fix cap atoms * Clean up implementation * Add GLSL intrinsics and cleanup * Add tests * Fix affected capability test * Update and fix tests * Move expected.txt file * Refactor WaveMask* to call WaveMulti* * Refactor SPIRV/GLSL preamble code * Enable emit-via-glsl tests * remove wave_multi_prefix capability in favor of subgroup_partitioned * Update docs * Update cap atoms doc
2025-05-23Implement throw & catch statements (#6916)Julius Ikkala
* Implement throw statement It already existed in the IR, so only parsing, checking and lowering was missing. * Initial catch implementation Likely very broken. * Error out when catch() isn't last in scope * Prevent accessing variables from scope preceding catch As those may actually not be available at that point. * Add IError and use it in Result type lowering * Add diagnostic tests * Allow caught throws in non-throw functions * Fix catch propagating between functions & SPIR-V merge issue * Add test for non-trivial error types * Fix MSVC build * Fix invalid value type from Result lowering * Also lower error handling in templates * Lower result types only after specialization * Attempt to disambiguate error enums by witness table * Revert matching by witness, types should be distinct too * Don't assert valueField when getting Result's error value It may not exist if the function returns void, but getting the error value is still legitimate. * Update tests for new error numbers & get rid of expected.txt * Change catch lowering to resemble breaking a loop ... To make SPIR-V happy. * Fix dead catch blocks and invalid cached dominator tree * More SPIR-V adjustment * Lower catch as two nested loops * Add defer interaction test and revert broken defer changes * Fix enum type when throwing literals * Cleanup and bikeshedding * Document error handling mechanism * Fix table of contents * Use boolean tag in Result<T, E> * Use anyValue storage for Result<T,E> * Remove IError * Fix formatting * Eradicate success values from docs and tests * Use parseModernParamDecl for catch parameter * Implement do-catch syntax * Implement catch-all * Fix formatting * Fix marshalling native calls that throw --------- Co-authored-by: Yong He <yonghe@outlook.com>
2025-05-22adjust docs as per review (#7168)ArielG-NV
2025-05-22Initial `dyn` keyword support & `-lang 2026` compiler option (#7172)ArielG-NV
fixes: [#7143](https://github.com/shader-slang/slang/issues/7143) fixes: [#7146](https://github.com/shader-slang/slang/issues/7146) Goal of PR: * This PR is part of the larger #7115 refactor to how dynamic dispatch works. * The first step is to add the `-std <std-revision>` flag. * The second step is to provide basic `dyn` keyword support in AST. This does not include `varDecl` support since most of these interactions require `some` keyword support. Future PR(s) goal: * Support `some` keyword in AST. With this we will also implement all varDecl interactions between `dyn` and `some`. * Add IR support for `some` and `dyn`. Breakdown of PR: * most of the logic is in `validateDyn.*`. This was done so that in the future when we implement more features we will have an easy time removing/adding restrictions to `dyn` interfaces. Breaking changes: * As per spec (https://github.com/shader-slang/spec/pull/14/files), any type conforming to a `dyn` interface errors if member list contains one of the following: opaque type, non copyable type, or unsized type. * Due to the breaking change, the test `tests\compute\dynamic-dispatch-bindless-texture.slang` is incorrect. This has been fixed.
2025-05-19Map `SV_VertexID` to `gl_VertexIndex-gl_BaseVertex`, add `SV_Vulkan*ID` ↵Darren Wihandi
semantics (#7150) * Map SV_VertexID to `gl_VertexIndex - gl_BaseVertex`, provide SV_Vulkan* SV semantics * Fix docs * Regenerate toc * Fix affected pointer-2 test * Add tests --------- Co-authored-by: Yong He <yonghe@outlook.com>
2025-05-16Support Vulkan memory model (#7057)Jay Kwak
The user can explicitly use Vulkan memory model, or it will be automatically used when cooperative-matrix is used. When vulkan memory model is used, two keywords, "Coherent" and "Volatile", are not allowed. There are many differences regarding atomic and texture but this PR has changes limited to support `globallycoherent` keyword. When variables with `globallycoherent` is used with `OpLoad`, it will use additional options, `MakePointerAvailable|NonPrivatePointer`, that will provide the same effect. For `OpStore`, it will use `MakePointerVisible|NonPrivatePointer`.
2025-05-16Fix correct bindings for bindless resource model [SPIRV and GLSL] (#7131)ArielG-NV
Fix correct bindings for bindless resource model [spirv and glsl] fixes: #6952 Problem: * Currently all bindless objects are placed in the same set (fine) and same binding (incorrect behavior for vulkan). This is incorrect since as per [spec](https://registry.khronos.org/vulkan/specs/latest/man/html/VkDescriptorType.html), only 1 resource type may be written to each index inside a set (these rules are loosened with VK_EXT_mutable_descriptor_type) * This means currently generated bindings do not work in practice if we (for example) use `Sampler2D.Handle` and `Texture1D.Handle` in a shader since we would place 2 incompatible objects in the same binding-index and set. Solution: * `__getDynamicResourceHeap` was modified to allow bindings to chosen dynamically for a descriptor * use `IOpaqueDescriptor` to check compile-time information of resource types so that we can identify different resources * Using this information of `IOpaqueDescriptor`, we modify `defaultGetDescriptorFromHandle` to provide a binding model (1 resource per binding-index) which produces legal spirv/glsl. * To support `VK_EXT_mutable_descriptor_type` the function `defaultGetDescriptorFromHandle` has a set of options (`BindlessDescriptorOptions`) for a user to pick-from to support their binding model. Capabilities are not used here for flexibility purposes (specifically old shaders mixed with modern vulkan extensions). Other changes: * Added `TexelBuffer` DescriptorKind to aid in generating correct bindings * format code * Add to docs bindless changes, make AccelerationStructure use its handle directly, adjust tests accordingly --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-05-15Support tensor addressing (#7060)Jay Kwak
This commit implements two new types and related Load/Store functions in CoopMat. tensor_addrressing.TensorLayout tensor_addressing.TensorView CoopMat.Load(..., TensorLayout) CoopMat.Load(..., TensorLayout, TensorView) CoopMat.Store(..., TensorLayout) CoopMat.Store(..., TensorLayout, TensorView) CoopMat.Load(..., TensorLayout, TensorView)
2025-05-14Add new coopmat2 functions: Reduce and Transpose (#7027)Jay Kwak
This commit adds three new functions for CoopMat as described in the proposal document, Cooperative matrix 2 proposal spec#12 The new functions are: CoopMat<T,S,M,N,R>::Transpose CoopMat<T,S,M,N,R>::ReduceRow CoopMat<T,S,M,N,R>::ReduceColumn CoopMat<T,S,M,N,R>::ReduceRowAndColumn CoopMat<T,S,M,N,R>::Reduce2x2
2025-05-14Support the new CoopVec builtins (#7108)Jay Kwak
**NOTE: This is a breaking change for users who were using POC variant of DXC. In order to keep the compatibility, the users will have to use -capability hlsl_coopvec_poc to their command line. This PR adds a new capability "hlsl_coopvec_poc". When it is used, the HLSL for CoopVec will be emitted for the POC variant of DXC. When it is not used, the HLSL for CoopVec will be emitted for the DXC that officially supports the cooperative vector.
2025-05-14Add explanation for SV_InstanceID usage difference from SPIR-V (#7072)aidanfnv
Closes https://github.com/shader-slang/slang/issues/6805 This change adds a note to the SPIR-V target specific doc that SV_InstanceID does not map directly to SPIR-V's BuiltIn InstanceIndex, and adds a more detailed explanation of the difference, its motivation, and how to derive the actual value equivalent to BuiltIn InstanceIndex with an example. --------- Co-authored-by: slangbot <ellieh+slangbot@nvidia.com> Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-05-12Make CUDA version capabilities reach NVRTC (#7074)Theresa Foley
Fixes #7049 The root cause of the problem in #7049 is simply that newer NVRTC versions produce a warning when asked to generate code for older CUDA SM versions, and the default that Slang was requesting compilation for was old enough to trigger that warning, and thus trip up the test case (which only looks at the first diagnostic produced by the downstream compiler). Superficially, the fix was easy: change the test case in question (`tests/diagnostics/local-line.slang`) to request `-capability cuda_sm_8_0`, the minimum version supported by current NVRTC. Unfortunately, the simple fix required some other fixes in order to actually work. The capability system includes capability names of the form `cuda_sm_*_*`, but specifying such a capability had *no* impact on the CUDA SM version passed in when invoking NVRTC. Instead, only the CUDA SM versions requested in the implementation of intrinsics in the core module were affecting the version number passed down. This change adds logic to `slang-compiler.cpp` to take explicitly requested capabilities into account when inferring the CUDA SM version to be passed downstream. A more complete fix would also add similar logic for all the other targets. Unfortunately... yet again... that fix wasn't enough to make things work as expect. Now I had the problem that requesting `-capability cuda_sm_8_0` was actually causing the NVRTC invocation to request CUDA SM version **9.0**! The underlying problem *there* was that the `slang-capabilities.capdef` file has defined certain capability names in a way that implies atomic capabilities much higher than one would expect. E.g., the `cuda_sm_8_0` alias was including HLSL `sm_5_0`, but then `sm_5_0` in turn included `_cuda_sm_9_0`. The fix, for now, is to change the definitions in `slang-capabilities.capdef` to not have the counter-intuitive definitions for `cuda_sm_*_*`. With this set of fixes, the test failure in the original bug report no longer occurs. The work that went into this change suggests several larger-scope fixes that would be good to pursue: * Ideally the capability definitions would have some sort of validation checking to make sure that counter-intuitive results like `cuda_sm_8_0` requesting CUDA SM 9.0 do not occur. * The translation of capabilities over to version numbers for a downstream compiler should be expanded to cover other targets, and not just CUDA. It might be better/simpler to just pass the capabilities themselves to the downstream compiler, since it is possible that a downstream compiler could have more fine-grained enable/disable options than a simple version number. * The entire approach to computing version numbers required for downstream compilation should be cleaned up so that we don't have this duplication between the capabilities that represent those versions and separate syntactic constructs that are used to "request" those versions as part of code generation. * We are very much at the point where we should consider dropping the current behavior where a profile name or capability like `sm_5_0`, that is specific to a single target or a subset of targets, also implies a set of comparable capabilities for other targets.
2025-05-12Cleanups related to RIFF support (#7041)Theresa Foley
2025-05-12cluster acceleration structure optix 6431 (#7028)Harsh Aggarwal (NVIDIA)
* Add cluster geometry intrinsics for ray tracing - Added GetClusterID() method to HitObject class - Added CandidateClusterID() and CommittedClusterID() methods to RayQuery class - Added SPV_NV_cluster_acceleration_structure extension support - Added GL_NV_cluster_acceleration_structure extension support - Added test files for RayQuery and HitObject cluster methods Fixes #6431 * OpRayQueryGetIntersectionClusterIdNV - unrecognized spirv Disabling spirv backend for SPV_NV_cluster_acceleration_structure hlsl.meta.slang(18674): error 29100: unrecognized spirv opcode: OpRayQueryGetIntersectionClusterIdNV result:$$int = OpRayQueryGetIntersectionClusterIdNV &this $iCandidateOrCommitted; ^~~~~~ hlsl.meta.slang(18670): error 30019: expected an expression of type 'int', got 'void' return spirv_asm ^~~~~~~~~ ninja: build stopped: subcommand failed. * 6431 - Fix spirv opcode * Remove tests * Add relevant tests * Review - Simplify tests
2025-05-08Fix broken links in Slang docs (#7039)aidanfnv
This change fixes some broken links/anchors in the Slang docs that I found after running a link checker tool on the readthedocs site. Some of these were broken on GitHub Pages as well, such as anchors with apostrophes or docs that were moved. The doc writer change adds an explicit .html extension to Parameter links, so that Sphinx/RTD does not treat it as an anchor.
2025-05-05Remove extra User Guide readthedocs TOC entries by turning extra H1 headings ↵aidanfnv
into H2 (#6986) readthedocs treats H1 headings as document titles in the sidebar table of contents. This change turns all extra H1 headings into H2 in the "Metal-Specific Functionalities" doc. These extra H1 headings seem to be errors, given that they are inconsistent, and the H2s after them do not belong. For examples, the heading "Resource Types" is H2, but "Array Types" is H1, and "Mesh Shader Support" is H1, but the following "Header Inclusions and Namespace" is not a subtopic of the Mesh Shader Support.
2025-05-02Add tables of contents to user guide for use on readthedocs (#6979)aidanfnv
This change adds hidden (commented out) tables of contents to the index of the User Guide, as well as each of the additional chapters, so that readthedocs will render the User Guide structure.
2025-04-30Add `IOpaqueDescriptor::descriptorAccess`. (#6967)Yong He
* Add `IOpaqueHandle::descriptorAccess`. * Update doc. * fix.
2025-04-28Add Slang Byte Code generation and interpreter. (#6896)Yong He
* Add Slang Byte Code generation and interpreter. * Fix compile issues. * format code * More compile fix. * Fix clang issue. * Fix more clang issues. * Another clang fix. * Fix clang issues. * Fix another clang issue. * Fix wasm build. * Update building.md * Fix test-server. * Fix compile error. * Fix bug. --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-04-22Implement shader subgroup rotate intrinsics (#6878)Darren Wihandi
* Initial implementation for SPIRV, GLSL and Metal * test add bool test * Fix and improve subgroup rotate tests * Add proper GLSL extensions and proper Metal type checking * Clean up tests and add diagnostics test for subgroup type for Metal * Update wave-intrinsics docs
2025-04-22Add a new SM profile 6.9 (#6879)Jay Kwak
2025-04-16Remove support for ad hoc Slang IR compression (#6834)Theresa Foley
* Remove support for ad hoc Slang IR compression This change is part of a larger effort to clean up the approach to serialization in the Slang compiler. The overall goal is to simplify and streamline all of the serialization-related logic, so that we are left with code that is less "clever," and easier to understand for contributors to the codebase. Removing support for compression of serialized Slang IR has benefits that include: * Reduction in code complexity: consider things like the subtle way that the `FOURCC`s for compressed chunks were being computed from the uncompressed versions, and the mental overhead that goes into understanding that, for anybody who would dare to touch this code. * Reduction in testing burden: there have been, de facto, two very different code paths for serialization of the Slang IR, and it is not clear that the existing test corpus for Slang has sufficient coverage for both options. By having only a single code path, every test that performs any amount of IR serialization helps with test coverage of that one path. * Opportunity to explore alternatives. This is perhaps a reiteration of the first point, but once the code is stripped down to the simplest thing that could possibly work (I am not claiming it has reached that point yet), it becomes easier for contributors to understand, and it becomes more tractable for somebody to come along with an improved approach that performs better (in either compression ratio or performance) while still being maintainable. In my own local setup, I found that removing support for Slang IR compression led to the `slang-core-module-generated.h` file increasing in size from 46.1MB to 47.4MB. This increase in the `.h` file size for the core library binary only resulted in a release build of `slang.dll` increasing from 20.0MB to 20.2MB. Removing the ad hoc compression support has almost no impact on the size of actual binary Slang modules *so long* as the additional LZ4 compression step is being applied to them. * format code --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com>
2025-04-15Add cooperative matrix 1 support (#6565)Darren Wihandi
* initial wip for spirv * working tiled example * clean up store and load * minor fixes * fix loadAny name * add initial tests, including broken/unimplemented intrinsics * fix subscript * run tests at 16x16, remove not supported arithmetic tests * minor fixups on implementation * rename CoopMatMatrixUse * Update tests to pass validation layers locally * Add mat-mul-add test and minor fixes * Add more tests * Remove dead code * Add coopMatLoad function and tests, enforce constexpr for matrix layout * Use getVectorOrCoopMatrixElementType in place of getVectorElementType
2025-04-14Add SV_PointCoord to match gl_PointCoord (#6795)Julius Ikkala
* Add gl_PointCoord support in GLSL compat mode * Add SV_PointCoord * Test on metal as well * Update SPIRV system value semantics table in docs * Update metal docs for SV_PointCoord
2025-04-11Fix user-guide typos (#6789)Gangzheng Tong
* Fix user-guide typos Use LLM to scan each of the markdown files to fix typos. Try not to change anything but the typos in this CL. * typo not caught by LLM * add output of ./build_toc.ps1
2025-04-06Add defer statement (#6619)Julius Ikkala
2025-04-01Update hyperlinks in User Guide's Reference section (#6715)Sruthik P
Fixes #6692 This change fixes the hyperlinks used in the User Guide's Reference section as the previously used paths were leading to a 404
2025-03-31[docs] Admonish slangc entry points / shader attributes (#6033)Ben-Fields
* [docs] Admonish slangc entry points / shader attributes Admonish the related non-functional compilation command in the reference manual until #5541 is addressed. * Refine shader attribute description. * Refine shader attribute description * Update with all supported targets Add all targets supporting shader attributes per provided verbiage. --------- Co-authored-by: Ellie Hermaszewska <ellieh@nvidia.com>
2025-03-19Output SPV_KHR_compute_shader_derivatives extension string instead of the NV ↵Darren Wihandi
extension (#6641) * Output SPV_KHR_compute_shader_derivatives instead of the NV extension * add alias for nv extension
2025-03-18Implement floating-point pack/unpack intrinsics for all targets (#6503)Darren Wihandi
* Implement floating-point pack/unpack intrinsics * remove unused functions and update caps in glsl meta file * rename pack capability
2025-03-05Add module organization suggestion doc (#6509)cheneym2
* Add module organization suggestion doc Suggest one method to keep slang modules organized in the file system. Closes #4841
2025-02-27Document bug with global session teardown in user guide (#6479)Anders Leino
This closes #6344. Co-authored-by: Yong He <yonghe@outlook.com>
2025-02-26Improve entry point lookup function documentation (#6451)Anders Leino
* Document that findEntryPointByName is not applicable if there is no [shader(...)] attribute * Update the user guide to mention findAndCheckEntryPoint for entry points without [shader(...)] attributes * format code --------- Co-authored-by: slangbot <186143334+slangbot@users.noreply.github.com> Co-authored-by: Yong He <yonghe@outlook.com>
2025-02-06Mark slangpy as deprecated and remove from user-guide. (#6300)Yong He
2025-02-06Update a3-reference.md (#6309)KoT
Co-authored-by: Yong He <yonghe@outlook.com>
generated by cgit v1.2.3 (git 2.39.1) at 2026-06-04 21:14:28 +0000