From a508b264eda4bc3c99ba1f44eab1dec6e5ce06c0 Mon Sep 17 00:00:00 2001 From: Jay Kwak <82421531+jkwak-work@users.noreply.github.com> Date: Fri, 25 Oct 2024 21:12:37 -0700 Subject: Swap the term StdLib with Core-Module or Standard-Module in documents (#5414) This PR is limited to documents. All use of "Standard library" or "StdLib" are replaced with either "core module" or "standard modules", depending on the context. --- README.md | 2 +- docs/build_reference.ps1 | 4 ++-- docs/cpu-target.md | 2 +- docs/cuda-target.md | 2 +- docs/design/autodiff/decorators.md | 6 +++--- docs/design/autodiff/types.md | 4 ++-- docs/design/capabilities.md | 6 +++--- docs/design/coding-conventions.md | 4 ++-- docs/design/interfaces.md | 2 +- docs/design/overview.md | 4 ++-- docs/design/serialization.md | 4 ++-- docs/design/stdlib-intrinsics.md | 14 +++++++------- docs/doc-system.md | 2 +- docs/gpu-feature/texture/footprint-queries.md | 4 ++-- docs/language-reference/04-types.md | 6 +++--- docs/language-reference/07-declarations.md | 2 +- docs/proposals/007-variadic-generics.md | 4 ++-- docs/proposals/008-tuples.md | 10 +++++----- docs/proposals/010-new-diff-type-system.md | 4 ++-- docs/proposals/implementation/ast-ir-serialization.md | 6 +++--- docs/proposals/legacy/001-basic-interfaces.md | 6 +++--- docs/proposals/legacy/003-error-handling.md | 2 +- docs/stdlib-docgen.md | 8 ++++---- docs/user-guide/00-introduction.md | 2 +- docs/user-guide/02-conventional-features.md | 4 ++-- docs/user-guide/07-autodiff.md | 4 ++-- docs/user-guide/08-compiling.md | 18 +++++++++--------- docs/user-guide/a1-03-obfuscation.md | 6 +++--- docs/user-guide/a1-04-interop.md | 2 +- 29 files changed, 72 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index ad7a56329..dc9878db0 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Documentation The Slang project provides a variety of different [documentation](docs/), but most users would be well served starting with the [User's Guide](https://shader-slang.github.io/slang/user-guide/). -For developers writing Slang code, the [Slang Standard Library Reference](https://shader-slang.com/stdlib-reference/) provides detailed documentation on Slang's built-in types and functions. +For developers writing Slang code, the [Slang Core Module Reference](https://shader-slang.com/stdlib-reference/) provides detailed documentation on Slang's built-in types and functions. We also provide a few [examples](examples/) of how to integrate Slang into a rendering application. diff --git a/docs/build_reference.ps1 b/docs/build_reference.ps1 index 0aa424771..726fa804c 100644 --- a/docs/build_reference.ps1 +++ b/docs/build_reference.ps1 @@ -1,4 +1,4 @@ -# This script uses `slangc` to generate stdlib reference documentation and push the updated +# This script uses `slangc` to generate the core module reference documentation and push the updated # documents to shader-slang/stdlib-reference repository. # The stdlib-reference repository has github-pages setup so that the markdown files we generate # in this step will be rendered as html pages by Jekyll upon a commit to the repository. @@ -38,7 +38,7 @@ Move-Item -Path ".\toc.html" -Destination ".\_includes\stdlib-reference-toc.html git config user.email "bot@shader-slang.com" git config user.name "Stdlib Reference Bot" git add . -git commit -m "Update stdlib reference" +git commit -m "Update the core module reference" git push cd ../ diff --git a/docs/cpu-target.md b/docs/cpu-target.md index 46e33c0c2..8b9afabdd 100644 --- a/docs/cpu-target.md +++ b/docs/cpu-target.md @@ -90,7 +90,7 @@ The `shader` style implies * The code *can* be executed in a GPU-kernel like execution model, launched across multiple threads (as described in the [ABI](#abi)) * Currently no reference counting -* Only functionality from the Slang stdlib, built in HLSL or anything supplied by a [COM interfaces](#com-interface) is available +* Only functionality from the Slang core module, built in HLSL or anything supplied by a [COM interfaces](#com-interface) is available * Currently [slang-llvm](#slang-llvm) only supports the `shader` style The `host` style implies diff --git a/docs/cuda-target.md b/docs/cuda-target.md index adb56d922..c59703259 100644 --- a/docs/cuda-target.md +++ b/docs/cuda-target.md @@ -267,7 +267,7 @@ There is broad support for [HLSL Wave intrinsics](https://docs.microsoft.com/en- Most Wave intrinsics will work with vector, matrix or scalar types of typical built in types - uint, int, float, double, uint64_t, int64_t. -The support is provided via both the Slang stdlib as well as the Slang CUDA prelude found in 'prelude/slang-cuda-prelude.h'. Many Wave intrinsics are not directly applicable within CUDA which supplies a more low level mechanisms. The implementation of most Wave functions work most optimally if a 'Wave' where all lanes are used. If all lanes from index 0 to pow2(n) -1 are used (which is also true if all lanes are used) a binary reduction is typically applied. If this is not the case the implementation fallsback on a slow path which is linear in the number of active lanes, and so is typically significantly less performant. +The support is provided via both the Slang core module as well as the Slang CUDA prelude found in 'prelude/slang-cuda-prelude.h'. Many Wave intrinsics are not directly applicable within CUDA which supplies a more low level mechanisms. The implementation of most Wave functions work most optimally if a 'Wave' where all lanes are used. If all lanes from index 0 to pow2(n) -1 are used (which is also true if all lanes are used) a binary reduction is typically applied. If this is not the case the implementation fallsback on a slow path which is linear in the number of active lanes, and so is typically significantly less performant. For more a more concrete example take diff --git a/docs/design/autodiff/decorators.md b/docs/design/autodiff/decorators.md index b08da2912..626f8bc4c 100644 --- a/docs/design/autodiff/decorators.md +++ b/docs/design/autodiff/decorators.md @@ -50,11 +50,11 @@ In such cases, we provide the `[TreatAsDifferentiable]` decoration (AST node: `T ## Custom derivative decorators In many cases, it is desirable to manually specify the derivative code for a method rather than let the auto-diff pass synthesize it from the method body. This is usually desirable if: 1. The body of the method is too complex, and there is a simpler, mathematically equivalent way to compute the same value (often the case for intrinsics like `sin(x)`, `arccos(x)`, etc..) -2. The method involves global/shared memory accesses, and synthesized derivative code may cause race conditions or be very slow due to overuse of synchronization. For this reason Slang assumes global memory accesses are non-differentiable by default, and requires that the user (or stdlib) define separate accessors with different derivative semantics. +2. The method involves global/shared memory accesses, and synthesized derivative code may cause race conditions or be very slow due to overuse of synchronization. For this reason Slang assumes global memory accesses are non-differentiable by default, and requires that the user (or the core module) define separate accessors with different derivative semantics. The Slang front-end provides two sets of decorators to facilitate this: 1. To reference a custom derivative function from a primal function: `[ForwardDerivative(fn)]` and `[BackwardDerivative(fn)]` (AST Nodes: `ForwardDerivativeAttribute`/`BackwardDerivativeAttribute`, IR: `OpForwardDervativeDecoration`/`OpBackwardDerivativeDecoration`), and -2. To reference a primal function from its custom derivative function: `[ForwardDerivativeOf(fn)]` and `[BackwardDerivativeOf(fn)]` (AST Nodes: `ForwardDerivativeAttributeOf`/`BackwardDerivativeAttributeOf`). These attributes are useful to provide custom derivatives for existing methods in a different file without having to edit/change that module. For instance, we use `diff.meta.slang` to provide derivatives for stdlib functions in `hlsl.meta.slang`. When lowering to IR, these references are placed on the target (primal function). That way both sets of decorations are lowered on the primal function. +2. To reference a primal function from its custom derivative function: `[ForwardDerivativeOf(fn)]` and `[BackwardDerivativeOf(fn)]` (AST Nodes: `ForwardDerivativeAttributeOf`/`BackwardDerivativeAttributeOf`). These attributes are useful to provide custom derivatives for existing methods in a different file without having to edit/change that module. For instance, we use `diff.meta.slang` to provide derivatives for the core module functions in `hlsl.meta.slang`. When lowering to IR, these references are placed on the target (primal function). That way both sets of decorations are lowered on the primal function. These decorators also work on generically defined methods, as well as struct methods. Similar to how function calls work, these decorators also work on overloaded methods (and reuse the `ResolveInoke` infrastructure to perform resolution) @@ -89,4 +89,4 @@ void sampleTexture_bwd(TexHandle2D tex, inout DifferentialPair dp_uv, fl } ``` -The implementation of `[PrimalSubstitute(fn)]` is relatively straightforward. When the transcribers are asked to synthesize a derivative of a function, they check for a `OpPrimalSubstituteDecoration`, and swap the current function out for the substitute function before proceeding with derivative synthesis. \ No newline at end of file +The implementation of `[PrimalSubstitute(fn)]` is relatively straightforward. When the transcribers are asked to synthesize a derivative of a function, they check for a `OpPrimalSubstituteDecoration`, and swap the current function out for the substitute function before proceeding with derivative synthesis. diff --git a/docs/design/autodiff/types.md b/docs/design/autodiff/types.md index 12b468a6e..2655b5c25 100644 --- a/docs/design/autodiff/types.md +++ b/docs/design/autodiff/types.md @@ -8,7 +8,7 @@ Here we detail the main components of the type system: the `IDifferentiable` int We also detail how auto-diff operators are type-checked (the higher-order function checking system), how the `no_diff` decoration can be used to avoid differentiation through attributed types, and the derivative data flow analysis that warns the the user of unintentionally stopping derivatives. ## `interface IDifferentiable` -Defined in core.meta.slang, `IDifferentiable` forms the basis for denoting differentiable types, both within the stdlib, and otherwise. +Defined in core.meta.slang, `IDifferentiable` forms the basis for denoting differentiable types, both within the core module, and otherwise. The definition of `IDifferentiable` is designed to encapsulate the following 4 items: 1. `Differential`: The type of the differential value of the conforming type. This allows custom data-structures to be defined to carry the differential values, which may be optimized for space instead of relying solely on compiler synthesis/ @@ -110,7 +110,7 @@ void bwd_myFunc( Existential types are interface-typed values, where there are multiple possible implementations at run-time. The existential type carries information about the concrete type at run-time and is effectively a 'tagged union' of all possible types. #### Differential type of an Existential -The differential type of an existential type is tricky to define since our type system's only restriction on the `.Differential` type is that it also conforms to `IDifferentiable`. The differential type of any interface `IInterface : IDifferentiable` is therefore the interface type `IDifferentiable`. This is problematic since Slang generally requires a static `anyValueSize` that must be a strict upper bound on the sizes of all conforming types (since this size is used to allocate space for the union). Since `IDifferentiable` is defined in the stdlib `core.meta.slang` and can be used by the user, it is impossible to define a reliable bound. +The differential type of an existential type is tricky to define since our type system's only restriction on the `.Differential` type is that it also conforms to `IDifferentiable`. The differential type of any interface `IInterface : IDifferentiable` is therefore the interface type `IDifferentiable`. This is problematic since Slang generally requires a static `anyValueSize` that must be a strict upper bound on the sizes of all conforming types (since this size is used to allocate space for the union). Since `IDifferentiable` is defined in the core module `core.meta.slang` and can be used by the user, it is impossible to define a reliable bound. We instead provide a new **any-value-size inference** pass (`slang-ir-any-value-inference.h`/`slang-ir-any-value-inference.cpp`) that assembles a list of types that conform to each interface in the final linked IR and determines a relevant upper bound. This allows us to ignore types that conform to `IDifferentiable` but aren't used in the final IR, and generate a tighter upper bound. **Future work:** diff --git a/docs/design/capabilities.md b/docs/design/capabilities.md index 74c08fca9..a4f4fa396 100644 --- a/docs/design/capabilities.md +++ b/docs/design/capabilities.md @@ -9,7 +9,7 @@ Slang aims to be a portable language for shader programming, which introduces tw Item (2) is traditionally handled with preprocessor techniques (e.g., `#ifdef`ing the body of a function based on target platform), but that of course requires that the user invoke the Slang front end once for each target platform, and target-specific coding in a library will then "infect" code that uses that library, forcing them to invoke the front-end once per target as well. -We are especially sensitive to this problem in the compiler itself, because we have to author and maintain the Slang standard library, which needs to (1) expose the capabilities of many platforms and (2) work across all those platforms. It would be very unfortunate if we had to build different copies of our standard library per-target. +We are especially sensitive to this problem in the compiler itself, because we have to author and maintain the Slang standard modules, which needs to (1) expose the capabilities of many platforms and (2) work across all those platforms. It would be very unfortunate if we had to build different copies of our standard modules per-target. The intention in Slang is to solve both of these problems with a system of *capabilities*. @@ -19,7 +19,7 @@ What is a capability? For our purposes a capability is a discrete feature that a compilation target either does or does not support. We could imagine defining a capability for the presence of texture sampling operations with implicit gradients; this capability would be supported when generating fragment shader kernel code, but not when generating code for other stages. -Let's imagine a language syntax that the standard library could use to define some *atomic* capabilities: +Let's imagine a language syntax that the standard modules could use to define some *atomic* capabilities: ``` capability implicit_gradient_texture_fetches; @@ -268,4 +268,4 @@ Conclusion ---------- Overall, the hope is that in many cases developers will be able to use capability-based partitioning and overloading of APIs to build code that only has to pass through the Slang front-end once, but that can then go through back-end code generation for each target. -In cases where this can't be achieved, the way that capability-based overloading is built into the Slang IR design means that we should be able to merge multiple target-specific definitions into one IR module, so that a library can employ target-specific specializations while still presenting a single API to consumers. +In cases where this can't be achieved, the way that capability-based overloading is built into the Slang IR design means that we should be able to merge multiple target-specific definitions into one IR module, so that a module can employ target-specific specializations while still presenting a single API to consumers. diff --git a/docs/design/coding-conventions.md b/docs/design/coding-conventions.md index b2492685f..228b26de7 100644 --- a/docs/design/coding-conventions.md +++ b/docs/design/coding-conventions.md @@ -72,7 +72,7 @@ As a general rule, default to making the implementation of a type `public`, and ### Slang -The Slang project codebase also includes `.slang` files implementing the Slang standard library, as well as various test cases and examples. +The Slang project codebase also includes `.slang` files implementing the Slang core module, as well as various test cases and examples. The conventions described here are thus the "official" recommendations for how users should format Slang code. To the extent possible, we will try to apply the same basic conventions to both C++ and Slang. @@ -132,7 +132,7 @@ Namespaces Favor fewer namespaces when possible. Small programs may not need any. -All library code that a Slang user might link against should go in the `Slang` namespace for now, to avoid any possibility of clashes in a static linking scenario. +All standard module code that a Slang user might link against should go in the `Slang` namespace for now, to avoid any possibility of clashes in a static linking scenario. The public C API is obviously an exception to this. diff --git a/docs/design/interfaces.md b/docs/design/interfaces.md index 29740694e..c0e284f59 100644 --- a/docs/design/interfaces.md +++ b/docs/design/interfaces.md @@ -163,7 +163,7 @@ That is intentional, because at the most basic level, interfaces are designed to ### Generic Declarations -The Slang compiler currently has some ad hoc support for generic declarations that it uses to implement the HLSL standard library (which has a few generic types). +The Slang compiler currently has some ad hoc support for generic declarations that it uses to implement the HLSL standard module (which has a few generic types). The syntax for those is currently very bad, and it makes sense to converge on the style for generic declarations used by C# and Swift: float myGenericFunc(T someValue); diff --git a/docs/design/overview.md b/docs/design/overview.md index 7c2b16cf3..c81853f1a 100644 --- a/docs/design/overview.md +++ b/docs/design/overview.md @@ -71,7 +71,7 @@ This means that most of the language "keywords" in Slang aren't keywords at all, Syntax declarations are associated with a callback that is invoked to parse the construct they name. The design of treating syntax as ordinary declarations has a long-term motivation (we'd like to support a flexible macro system) but it also has short-term practical benefits. -It is easy for us to add new modifier keywords to the language without touching the lexer or parser (just adding them to the standard library), and we also don't have to worry about any of Slang's extended construct (e.g., `import`) breaking existing HLSL code that just happens to use one of those new keywords as a local variable name. +It is easy for us to add new modifier keywords to the language without touching the lexer or parser (just adding them to the core module), and we also don't have to worry about any of Slang's extended construct (e.g., `import`) breaking existing HLSL code that just happens to use one of those new keywords as a local variable name. What the parser produces is an abstract syntax tree (AST). The AST currently uses a strongly-typed C++ class hierarchy with a "visitor" API generated via some ugly macro magic. @@ -186,7 +186,7 @@ We make a copy of things so that any optimization/transformation passes we do fo While copying IR code into the fresh module, we have cases where there might be multiple definitions of the same function or other entity. In those cases, we apply "target specialization" to pick the definition that is the best for the chosen target. -This step is where we can select between, say, a built-in definition of the `saturate` function for D3D targets, vs. a hand-written one in the Slang standard library to use for GLSL-based targets. +This step is where we can select between, say, a built-in definition of the `saturate` function for D3D targets, vs. a hand-written one in a Slang standard module to use for GLSL-based targets. ### API Legalization diff --git a/docs/design/serialization.md b/docs/design/serialization.md index 1f69eb61d..c05c60ad8 100644 --- a/docs/design/serialization.md +++ b/docs/design/serialization.md @@ -268,7 +268,7 @@ AST Serialization AST serialization uses the generalized serialization mechanism. -When serializing out an AST module it is typical to want to just serialize out the definitions within that module. Without this, the generalized serializer will crawl over the whole of the AST structure serializing every thing that can be reached - including the whole of the standard library. +When serializing out an AST module it is typical to want to just serialize out the definitions within that module. Without this, the generalized serializer will crawl over the whole of the AST structure serializing every thing that can be reached - including the whole of the core module. The filter `ModuleSerialFilter` can be used when writing the AST module, it will replace any references to elements outside of the current module with a `ImportExternalDecl`. This contains a mangled name to the item being referenced in another module. @@ -328,4 +328,4 @@ Issues * All types (and typedefs) that are serialized must be defined in the same scope - child types don't work correctly * When using value serialization serialization all the members that are serializable must be public -* The types output in slang fields do not correctly take into account scope (this is a similar issue to the issue above) \ No newline at end of file +* The types output in slang fields do not correctly take into account scope (this is a similar issue to the issue above) diff --git a/docs/design/stdlib-intrinsics.md b/docs/design/stdlib-intrinsics.md index 8d78de504..6e86f4c3f 100644 --- a/docs/design/stdlib-intrinsics.md +++ b/docs/design/stdlib-intrinsics.md @@ -1,17 +1,17 @@ -Stdlib Intrinsics -================= +Core Module Intrinsics +====================== -The following document aims to cover a variety of systems used to add target specific features. They are most extensively used in the slang standard library (stdlib). +The following document aims to cover a variety of systems used to add target specific features. They are most extensively used in the slang core module. **NOTE!** These features should *not* be considered stable! They can be used in regular slang code to add features, but they risk breaking with any Slang version change. Additionally the features implementation can be very particular to what is required for a specific feature set, so might not work as expected in all scenarios. As these features are in flux, it is quite possible this document is behind the current features available within the Slang code base. -If you want to add support for a feature for a target to Slang, implementing it as part of the Slang standard library is typically a good way to progress. Depending on the extension/feature it may not be possible to add support exclusively via changes to the standard library alone. That said most support for target specific extensions and features involve at least some changes to the slang standard library, and typically using the mechanisms described here. +If you want to add support for a feature for a target to Slang, implementing it as a part of the Slang standard modules is typically a good way to progress. Depending on the extension/feature it may not be possible to add support exclusively via changes to the standard module alone. That said most support for target specific extensions and features involve at least some changes to the slang standard modules including the core module, and typically using the mechanisms described here. -## Standard Library +## Core Module -The main place these features are used are within the slang standard library (aka stdlib). This is implemented with a set of slang files within the slang project +The main place these features are used are within the slang core module. This is implemented with a set of slang files within the slang project * core.meta.slang * hlsl.meta.slang @@ -146,7 +146,7 @@ Used before a type declaration. The clsName is the name of the class that is use Used to specify the IR opcode associated with a type. The IR opcode is listed as something like `$(kIROp_HLSLByteAddressBufferType)`, which will expand to the integer value of the opcode (because the opcode value is an enum value that is visible from C++). It is possible to just write the opcode number, but that is generally inadvisable as the ids for ops are not stable. If a code change in Slang C++ adds or removes an opcode the number is likely to be incorrect. -As an example from stdlib +As an example from the core module ```slang __magic_type(HLSLByteAddressBufferType) diff --git a/docs/doc-system.md b/docs/doc-system.md index 1eb55f817..d552bf1e4 100644 --- a/docs/doc-system.md +++ b/docs/doc-system.md @@ -85,7 +85,7 @@ Currently the Slang doc system does not support any of the 'advanced' doxygen do Currently the only documentation style supported is a single file 'markdown' output. Future versions will support splitting into multiple files and linking between them. Also future versions may also support other documentation formats/standards. -It is possible to generate documentation for Slangs internal `stdlib`. This can be achieved with `slangc` via +It is possible to generate documentation for the slang core module. This can be achieved with `slangc` via ``` slangc -doc -compile-core-module diff --git a/docs/gpu-feature/texture/footprint-queries.md b/docs/gpu-feature/texture/footprint-queries.md index b47a95262..6e76414c8 100644 --- a/docs/gpu-feature/texture/footprint-queries.md +++ b/docs/gpu-feature/texture/footprint-queries.md @@ -28,7 +28,7 @@ Texture footprint queries are intended to solve this problem by providing applic # Slang Shader API -Rather than exactly mirror the Vulkan GLSL extension or the NVAPI functions, Slang's standard library provides a single common interface that can map to either of those implementations. +Rather than exactly mirror the Vulkan GLSL extension or the NVAPI functions, the Slang core module provides a single common interface that can map to either of those implementations. ## Basics @@ -154,7 +154,7 @@ TextureFootprint3D Texture3D.queryFootprintFineBiasClamp( ## Footprint Types -Footprint queries on 2D and 3D textures return values of type `TextureFootprint2D` and `TextureFootprint3D`, respectively, which are built-in `struct`s defined in the Slang standard library: +Footprint queries on 2D and 3D textures return values of type `TextureFootprint2D` and `TextureFootprint3D`, respectively, which are built-in `struct`s defined in the Slang core module: ``` struct TextureFootprint2D diff --git a/docs/language-reference/04-types.md b/docs/language-reference/04-types.md index bef9f2d31..3ccc7bdcb 100644 --- a/docs/language-reference/04-types.md +++ b/docs/language-reference/04-types.md @@ -92,7 +92,7 @@ The alignment of a vector type may vary by target platforms. The alignment of `vector` will be at least the alignment of `T` and may be at most `N` times the alignment of `T`. As a convenience, Slang defines built-in type aliases for vectors of the built-in scalar types. -E.g., declarations equivalent to the following are provided by the Slang standard library: +E.g., declarations equivalent to the following are provided by the Slang core module: ```hlsl typealias float4 = vector; @@ -139,7 +139,7 @@ Under column-major layout, a matrix is laid out in memory equivalent to the row- This means it will be laid out equivalently to a `C`-element array of `vector` elements. As a convenience, Slang defines built-in type aliases for matrices of the built-in scalar types. -E.g., declarations equivalent to the following are provided by the Slang standard library: +E.g., declarations equivalent to the following are provided by the Slang core module: ```hlsl typealias float3x4 = matrix; @@ -311,7 +311,7 @@ Opaque Types _Opaque_ types are built-in types that (depending on the target platform) may not have a well-defined size or representation in memory. Similar languages may refer to these as "resource types" or "object types." -The full list of opaque types supported by Slang can be found in the standard library reference, but important examples are: +The full list of opaque types supported by Slang can be found in the core module reference, but important examples are: * Texture types such as `Texture2D`, `TextureCubeArray`, and `RWTexture2DMS` * Sampler state types: `SamplerState` and `SamplerComparisonState` diff --git a/docs/language-reference/07-declarations.md b/docs/language-reference/07-declarations.md index 2df87b8a6..e3b7aa60d 100644 --- a/docs/language-reference/07-declarations.md +++ b/docs/language-reference/07-declarations.md @@ -642,7 +642,7 @@ float f = v.getLength(); int n = MyVector.getDimensionality(); ``` -An extension declaration need not be placed in the same module as the type being extended; it is possible to extend a type from third-party or standard-library code. +An extension declaration need not be placed in the same module as the type being extended; it is possible to extend a type from third-party or standard module code. The members of an extension are only visible inside of modules that `import` the module declaring the extension; extension members are *not* automatically visible wherever the type being extended is visible. diff --git a/docs/proposals/007-variadic-generics.md b/docs/proposals/007-variadic-generics.md index 9249119f7..8e5de1f04 100644 --- a/docs/proposals/007-variadic-generics.md +++ b/docs/proposals/007-variadic-generics.md @@ -29,8 +29,8 @@ Background ---------- We have several cases that will benefit from variadic generics. One simplest example is the `printf` function is currently -defined to have different overloads for each number of arguments. The downside of duplicating overloads is the bloating standard -library size and a predefined upper limit of argument count. If users are to build their own functions that wraps the `printf` +defined to have different overloads for each number of arguments. The downside of duplicating overloads is the bloating the core +module size and a predefined upper limit of argument count. If users are to build their own functions that wraps the `printf` function, they will have to define a set of overloads for each number of arguments too, further bloating code size. Some of our users would like to implement the functor idiom in their shader code with interfaces. This is almost possible diff --git a/docs/proposals/008-tuples.md b/docs/proposals/008-tuples.md index efbcb7d28..a052585d6 100644 --- a/docs/proposals/008-tuples.md +++ b/docs/proposals/008-tuples.md @@ -28,7 +28,7 @@ to interop more directly with other parts of the user application written in oth Proposed Approach ----------------- -With variadic generics support, we can now easily define a Tuple type in stdlib as: +With variadic generics support, we can now easily define a Tuple type in the core module as: ``` __generic __magic_type(TupleType) @@ -43,7 +43,7 @@ This will allow users to instantiate tuple types from their code with `Tuple makeTuple(expand each T values); @@ -73,7 +73,7 @@ let v = t._1_0; ### Concatenation -We can define tuple concatenation operation in stdlib as: +We can define tuple concatenation operation in the core module as: ``` Tuple concat(Tuple first, Tuple second) { @@ -103,7 +103,7 @@ int foo() ### Operator Overloads We should have builtin operator overloads for all comparison operators if every element type of a tuple conforms to `IComparable`. -This can be supported by defining an overload for these operators in stdlib in the form of: +This can be supported by defining an overload for these operators in the core module in the form of: ``` bool assign(inout bool r, bool v) { r = v; return v; } @@ -137,4 +137,4 @@ Tuple concat(Tuple t, each U values); ``` However, this could lead to surprising behavior when the user writes `concat(t0, t1, t2)` where t1 and t2 are also tuples. Having this overload means the result would be `(t0_0, t0_1, ... t0_n, t1, t2)` where the user could be expecting `t1` and `t2` -to be flattened into the resulting tuple. To avoid this surprising behavior, we decide to not include this overload in stdlib. \ No newline at end of file +to be flattened into the resulting tuple. To avoid this surprising behavior, we decide to not include this overload in the core module. diff --git a/docs/proposals/010-new-diff-type-system.md b/docs/proposals/010-new-diff-type-system.md index dd5623a1d..61157819e 100644 --- a/docs/proposals/010-new-diff-type-system.md +++ b/docs/proposals/010-new-diff-type-system.md @@ -111,9 +111,9 @@ interface IDifferentiablePtrType : __IDifferentiableBase ``` -Some extras in stdlib allow us to constrain the diffpair type for things like `IArithmetic` +Some extras in the core module allow us to constrain the diffpair type for things like `IArithmetic` ```csharp -// --- STDLIB EXTRAS --- +// --- CORE MODULE EXTRAS --- interface ISelfDifferentiableValueType : IDifferentiableValueType { diff --git a/docs/proposals/implementation/ast-ir-serialization.md b/docs/proposals/implementation/ast-ir-serialization.md index 62f18dca9..248b752a1 100644 --- a/docs/proposals/implementation/ast-ir-serialization.md +++ b/docs/proposals/implementation/ast-ir-serialization.md @@ -18,8 +18,8 @@ Currently, deserialization of the AST or IR for a module is an all-or-nothing op Either the entire `Decl` hierarchy of the AST is deserialized and turned into in-memory C++ objects, or none of it is. Similarly, we can either construct the `IRInst` hierarchy for an entire module, or none of it. -Releases of the Slang compiler typically included a serialized form of the standard library ("stdlib") module, and the runtime cost of deserializing this module has proven to be a problem for users of the compiler. -Becuse parts of the Slang compiler are not fully thread-safe/reentrant, the stdlib must be deserialized for each "global session," so that deserialization cost is incurred per-thread in scenarios with thread pools. +Releases of the Slang compiler typically included a serialized form of the core module, and the runtime cost of deserializing this module has proven to be a problem for users of the compiler. +Becuse parts of the Slang compiler are not fully thread-safe/reentrant, the core module must be deserialized for each "global session," so that deserialization cost is incurred per-thread in scenarios with thread pools. Even in single-threaded scenarios, the deserialization step adds significantly to the startup time for the compiler, making single-file compiles less efficient than compiling large batches of files in a single process. Overview of Proposed Solution @@ -283,4 +283,4 @@ Each entry in the abbreviation table would store: When deserializing a node, code would read its abbreviation index first, and then look up the corresponding abbreviation to both find important information about the node, and also to drive deserialization of the rest of its data (e.g., by determining how many operands to read before reading in children). -In cases where the low-level serialization uses things like variable-length encodings for integers, the abbreviations can be sorted so that the most-frequently used abbreviations have the lowest indices, and thus take the fewest bits/bytes to encode. \ No newline at end of file +In cases where the low-level serialization uses things like variable-length encodings for integers, the abbreviations can be sorted so that the most-frequently used abbreviations have the lowest indices, and thus take the fewest bits/bytes to encode. diff --git a/docs/proposals/legacy/001-basic-interfaces.md b/docs/proposals/legacy/001-basic-interfaces.md index 4d04cbe04..6083c8ae9 100644 --- a/docs/proposals/legacy/001-basic-interfaces.md +++ b/docs/proposals/legacy/001-basic-interfaces.md @@ -1,7 +1,7 @@ Basic Interfaces ================ -The Slang standard library is in need of basic interfaces that allow generic code to be written that abstracts over built-in types. +The Slang core module is in need of basic interfaces that allow generic code to be written that abstracts over built-in types. This document sketches what the relevant interfaces and their operations might be. Status @@ -49,7 +49,7 @@ T horizontalSum( vector v ) } ``` -This alternative is much more palatable to users, but it results in them using a double-underscored interface (which we consider to mean "implementation details that are subject to change"). Users often get tripped up when they find out that certain operations that make sense to be available through `__BuiltinFloatingPointType` are not available (because those operations were not needed in the definition of the stdlib, which is what the `__` interfaces were created to support). +This alternative is much more palatable to users, but it results in them using a double-underscored interface (which we consider to mean "implementation details that are subject to change"). Users often get tripped up when they find out that certain operations that make sense to be available through `__BuiltinFloatingPointType` are not available (because those operations were not needed in the definition of the core module, which is what the `__` interfaces were created to support). Related Work ------------ @@ -228,7 +228,7 @@ The main reason for the current `__Builtin` interfaces is that it allows us to d ### What should the naming convention be for `interface`s in Slang? -These would be the first `interface`s officially exposed by the standard library. +These would be the first `interface`s officially exposed by the core module. While most of our existing code written in Slang uses an `I` prefix as the naming convention for `interface`s (e.g., `IThing`), we have never really discussed that choice in detail. Whatever we decide to expose for this stuff is likely to become the de facto convention for Slang code. diff --git a/docs/proposals/legacy/003-error-handling.md b/docs/proposals/legacy/003-error-handling.md index 28652824f..23c7bdc40 100644 --- a/docs/proposals/legacy/003-error-handling.md +++ b/docs/proposals/legacy/003-error-handling.md @@ -84,7 +84,7 @@ Proposed Approach We propose a modest starting point for error handling in Slang that can be extended over time. The model borrows heavily from Swift, but also focuses on strongly-typed errors. -The standard library will provide a built-in interface for errors, initially empty: +The core module will provide a built-in interface for errors, initially empty: ``` interface IError {} diff --git a/docs/stdlib-docgen.md b/docs/stdlib-docgen.md index 0be3af548..1ccd43052 100644 --- a/docs/stdlib-docgen.md +++ b/docs/stdlib-docgen.md @@ -1,11 +1,11 @@ -# Slang Standard Library Documentation Generation Tool +# Slang Core Module Documentation Generation Tool -Slang's standard library reference (https://shader-slang.com/stdlib-reference) is generated by `slangc` from the source of the standard library. +Slang's core module reference (https://shader-slang.com/stdlib-reference) is generated by `slangc` from the source of the core module. This page covers how `slangc` can be used to generate this documentation. ## Generating Documentation -Follow these steps to generate stdlib reference documentation and view the generated markdown files locally: +Follow these steps to generate the core module reference documentation and view the generated markdown files locally: ``` # clone stdlib-reference repo @@ -36,7 +36,7 @@ You should review the generated markdown file to make sure it is formated correc ## Writing and Updating Documentation -Stdlib documentation is done directly in comments inside `source/slang/*.meta.slang` files. +The core module documentation is done directly in comments inside `source/slang/*.meta.slang` files. A documentation comment should be placed directly above the declaration, either insde a `/** */` comment block, or after `///`. The following directives are allowed in comments: diff --git a/docs/user-guide/00-introduction.md b/docs/user-guide/00-introduction.md index 07b860d9c..6bc64dd36 100644 --- a/docs/user-guide/00-introduction.md +++ b/docs/user-guide/00-introduction.md @@ -98,6 +98,6 @@ Before we dive into actually _using_ Slang, let us step back and highlight some * **Predictability**: Code should do what it appears to, consistently, across as many platforms as possible. Whenever possible the compiler should conform to programmer expectation, even in the presence of "undefined behavior." Tools and optimization passes should keep their behavior as predictable as possible; simple tools empower the user to do smart things. -* **Limited Scope**: The Slang system is a language, compiler, and library. It is not an engine, not a renderer, and not a "framework." The Slang system explicitly does *not* assume responsibility for interacting with GPU APIs to load code, allocate resources, bind parameters, or kick off work. While a user *may* use the Slang runtime library in their application, they are not *required* to do so. +* **Limited Scope**: The Slang system is a language, compiler, and module. It is not an engine, not a renderer, and not a "framework." The Slang system explicitly does *not* assume responsibility for interacting with GPU APIs to load code, allocate resources, bind parameters, or kick off work. While a user *may* use the Slang runtime library in their application, they are not *required* to do so. The ordering here is significant, with earlier goals generally being more important than later ones. diff --git a/docs/user-guide/02-conventional-features.md b/docs/user-guide/02-conventional-features.md index 0e0f18096..e3f6336e7 100644 --- a/docs/user-guide/02-conventional-features.md +++ b/docs/user-guide/02-conventional-features.md @@ -275,7 +275,7 @@ enum Channel ### Opaque Types -The Slang standard library defines a large number of _opaque_ types which provide access to objects that are allocated via GPU APIs. +The Slang core module defines a large number of _opaque_ types which provide access to objects that are allocated via GPU APIs. What all opaque types have in common is that they are not "first-class" types on most platforms. Opaque types (and structure or array types that contain them) may be limited in the following ways (depending on the platform): @@ -1150,4 +1150,4 @@ __init() { this = {}; //zero-initialize `this` } -``` \ No newline at end of file +``` diff --git a/docs/user-guide/07-autodiff.md b/docs/user-guide/07-autodiff.md index 9209a903c..9fc5205e7 100644 --- a/docs/user-guide/07-autodiff.md +++ b/docs/user-guide/07-autodiff.md @@ -268,7 +268,7 @@ struct MyRayDifferential : IDifferentiable float3 d_dir; } ``` -In this case, since all fields in `MyRayDifferential` are differentiable, and the `Differential` of each field is the same as the original type of each field (i.e. `float3.Differential == float3` as defined in built-in library), the compiler will automatically use the type itself as its own `Differential`, making `MyRayDifferential` suitable for use as `Differential` of `MyRay`. +In this case, since all fields in `MyRayDifferential` are differentiable, and the `Differential` of each field is the same as the original type of each field (i.e. `float3.Differential == float3` as defined in the core module), the compiler will automatically use the type itself as its own `Differential`, making `MyRayDifferential` suitable for use as `Differential` of `MyRay`. We can also choose to manually implement `IDifferentiable` interface for `MyRayDifferential` as in the following code: @@ -487,7 +487,7 @@ void back_prop( ## Builtin Differentiable Functions -The following built-in functions are backward differentiable and both their forward-derivative and backward-propagation functions are already defined in the built-in library: +The following built-in functions are backward differentiable and both their forward-derivative and backward-propagation functions are already defined in the core module: - Arithmetic functions: `abs`, `max`, `min`, `sqrt`, `rcp`, `rsqrt`, `fma`, `mad`, `fmod`, `frac`, `radians`, `degrees` - Interpolation and clamping functions: `lerp`, `smoothstep`, `clamp`, `saturate` diff --git a/docs/user-guide/08-compiling.md b/docs/user-guide/08-compiling.md index 623a3111f..8fd94ff3c 100644 --- a/docs/user-guide/08-compiling.md +++ b/docs/user-guide/08-compiling.md @@ -266,19 +266,19 @@ The `slangc` compiler provides a few conveniences for command-line compilation: You can compile a `.slang` file into a binary IR module. For example, given the following source: ```hlsl -// library.slang +// my_library.slang float myLibFunc() { return 5.0; } ``` -You can compile it into `library.slang-module` with the following slangc command line: +You can compile it into `my_library.slang-module` with the following slangc command line: ```bat -slangc library.slang -o library.slang-module +slangc my_library.slang -o my_library.slang-module ``` -This allows you to deploy just the `library.slang-module` file to users of the library, and it can be consumed in the user code with the same `import` syntax: +This allows you to deploy just the `my_library.slang-module` file to users of the module, and it can be consumed in the user code with the same `import` syntax: ```hlsl -import library; +import my_library; ``` ### More Options @@ -329,8 +329,8 @@ Slang::ComPtr globalSession; createGlobalSession(globalSession.writeRef()); ``` -When a global session is created, the Slang system will load its internal representation of the _standard library_ that the compiler provides to user code. -The standard library can take a significant amount of time to load, so applications are advised to use a single global session if possible, rather than creating and then disposing of one for each compile. +When a global session is created, the Slang system will load its internal representation of the _core module_ that the compiler provides to user code. +The core module can take a significant amount of time to load, so applications are advised to use a single global session if possible, rather than creating and then disposing of one for each compile. > #### Note #### > Currently, the global session type is *not* thread-safe. @@ -611,8 +611,8 @@ The only functions which are currently thread safe are ```C++ SlangSession* spCreateSession(const char* deprecated); SlangResult slang_createGlobalSession(SlangInt apiVersion, slang::IGlobalSession** outGlobalSession); -SlangResult slang_createGlobalSessionWithoutStdLib(SlangInt apiVersion, slang::IGlobalSession** outGlobalSession); -ISlangBlob* slang_getEmbeddedStdLib(); +SlangResult slang_createGlobalSessionWithoutCoreModule(SlangInt apiVersion, slang::IGlobalSession** outGlobalSession); +ISlangBlob* slang_getEmbeddedCoreModule(); SlangResult slang::createGlobalSession(slang::IGlobalSession** outGlobalSession); const char* spGetBuildTagString(); ``` diff --git a/docs/user-guide/a1-03-obfuscation.md b/docs/user-guide/a1-03-obfuscation.md index abce92e12..dab216940 100644 --- a/docs/user-guide/a1-03-obfuscation.md +++ b/docs/user-guide/a1-03-obfuscation.md @@ -169,13 +169,13 @@ slangc module-source.slang -o module.zip -g -obfuscate This will compile "module-source.slang" into SlangIR module (aka `slang-module`) and places the `.slang-module` inside of the zip. As obfuscation is enabled the .zip will also contain the obfuscated source map for the module. -The `.zip` file can now be used and referenced as a library +The `.zip` file can now be used and referenced as a module ``` slangc source.slang -target dxil -stage compute -entry computeMain -obfuscate -r module.zip ``` -Notice here that the `-r` library reference is to the `.zip` file rather than the more usual `.slang-module` that is contained in the zip file. By referencing the library in this way Slang will automatically associate the contained obfuscated source map with the module. It will use that mapping for outputting diagnostics. +Notice here that the `-r` module reference is to the `.zip` file rather than the more usual `.slang-module` that is contained in the zip file. By referencing the module in this way Slang will automatically associate the contained obfuscated source map with the module. It will use that mapping for outputting diagnostics. It is also worth noticing that in this second compilation, using `module.zip`, we need the `-obfuscate` flag set. If this isn't set linking will not work correctly. @@ -256,7 +256,7 @@ Why you might not want to use an emit source map * The `#line` mechanism doesn't require any special handling, and the mapping back is embedded directly into the emitted source/output binary * There is more housekeeping in getting keeping and using source maps * Currently Slang doesn't directly expose a source map processing API directly - * We do support source maps in library files, or produced as part of a compilation + * We do support source maps in module files, or produced as part of a compilation * A developer could use the slang `compiler-core` implementation * In the future the project could provide some API support diff --git a/docs/user-guide/a1-04-interop.md b/docs/user-guide/a1-04-interop.md index a13f75c48..a13bb5ca2 100644 --- a/docs/user-guide/a1-04-interop.md +++ b/docs/user-guide/a1-04-interop.md @@ -110,7 +110,7 @@ void test_0() The strings in `__requirePrelude` are deduplicated: the same prelude string will only be emitted once no matter how many times an intrinsic function is invoked. Therefore, it is good practice to put `#include` lines as separate `__requirePrelude` statements to prevent duplicate `#include`s being generated in the output code. ## Managing Cross-Platform Code -If you are defining an intrinsic function that maps to multiple targets in different ways, you can use `__target_switch` construct to manage the target-specific definitions. For example, here is a snippet from Slang's builtin standard library that defines `getRealtimeClock`: +If you are defining an intrinsic function that maps to multiple targets in different ways, you can use `__target_switch` construct to manage the target-specific definitions. For example, here is a snippet from the Slang core module that defines `getRealtimeClock`: ```hlsl [__requiresNVAPI] __glsl_extension(GL_EXT_shader_realtime_clock) -- cgit v1.2.3