From 5f1ba7b614b64d24fb45a3815a9867c68dace466 Mon Sep 17 00:00:00 2001 From: Yong He Date: Thu, 5 Sep 2024 15:12:52 -0700 Subject: Various documentation improvements. (#5017) --- docs/user-guide/06-interfaces-generics.md | 71 ++++++++++++++++++++++++++ docs/user-guide/09-targets.md | 6 +-- docs/user-guide/a2-01-spirv-target-specific.md | 30 ++++++++++- docs/user-guide/toc.html | 4 ++ 4 files changed, 107 insertions(+), 4 deletions(-) (limited to 'docs/user-guide') diff --git a/docs/user-guide/06-interfaces-generics.md b/docs/user-guide/06-interfaces-generics.md index 61bc43f89..df51ac950 100644 --- a/docs/user-guide/06-interfaces-generics.md +++ b/docs/user-guide/06-interfaces-generics.md @@ -104,6 +104,22 @@ Generic value parameters can also be defined using the traditional C-style synta void g1() { ... } ``` +Slang allows multiple `where` clauses, and multiple interface types in a single `where` clause: +```csharp +struct MyType + where T: IFoo, IBar + where U : IBaz +{ +} +// equivalent to: +struct MyType + where T: IFoo + where T : IBar + where U : IBaz +{ +} +``` + Supported Constructs in Interface Definitions ----------------------------------------------------- @@ -793,6 +809,61 @@ void main() See [if-let syntax](convenience-features.html#if_let-syntax) for more details. +Generic Interfaces +------------------ + +Slang allows interfaces themselves to be generic. A common use of generic interfaces is to define the `IEnumerable` type: +```csharp +interface IEnumerator +{ + This moveNext(); + bool isEnd(); + T getValue(); +} + +interface IEnumerable +{ + assoicatedtype Enumerator : IEnumerator; + Enumerator getEnumerator(); +} +``` + +You can constrain a generic type parameter to conform to a generic interface: +```csharp +void traverse(TCollection c) + where TCollection : IEnumerable +{ + ... +} +``` + + +Generic Extensions +---------------------- +You can use generic extensions to extend a generic type. For example, +```csharp +interface IFoo { void foo(); } +interface IBar { void bar(); } + +struct MyType +{ + void foo() { ... } +} + +// Extend `MyType` so it conforms to `IBar`. +extension MyType : IBar +{ + void bar() { ... } +} +// Equivalent to: +__generic +extension MyType : IBar +{ + void bar() { ... } +} +``` + + Extensions to Interfaces ----------------------------- diff --git a/docs/user-guide/09-targets.md b/docs/user-guide/09-targets.md index e1219a39d..d6aebab0c 100644 --- a/docs/user-guide/09-targets.md +++ b/docs/user-guide/09-targets.md @@ -302,14 +302,14 @@ Metal > #### Note #### > Slang support for Metal is a work in progress. -Metal is a shading language exclusive on Apple slicons. The functionality from Metal is similar to DX12 or Vulkan with more or less features. +Metal is a shading language exclusive on Apple platforms. The functionality from Metal is similar to DX12 or Vulkan with more or less features. ### Pipelines -Metal includes rasterization, compute, and ray tracing pipelines with the same set of stages as described for D3D12 above. +Metal includes vertex, fragment, task, mesh and tessellation stages for rasterization, as well as compute, and ray tracing stages. > #### Note #### -> Ray-tracing and Mesh support for Metal is a work in progress. +> Ray-tracing support for Metal is a work in progress. ### Parameter Passing diff --git a/docs/user-guide/a2-01-spirv-target-specific.md b/docs/user-guide/a2-01-spirv-target-specific.md index a1ecbfefd..e0d6fd69b 100644 --- a/docs/user-guide/a2-01-spirv-target-specific.md +++ b/docs/user-guide/a2-01-spirv-target-specific.md @@ -134,7 +134,7 @@ SPIR-V 1.5 with [SPV_EXT_shader_atomic_float16_add](https://github.com/KhronosGr ConstantBuffer, (RW/RasterizerOrdered)StructuredBuffer, (RW/RasterizerOrdered)ByteAddressBuffer ----------------------------------------------------------------------------------------------- -Each member in a `ConstantBuffer` will be emitted as `uniform` parameter. +Each member in a `ConstantBuffer` will be emitted as `uniform` parameter in a uniform block. StructuredBuffer and ByteAddressBuffer are translated to a shader storage buffer with `readonly` layout. RWStructuredBuffer and RWByteAddressBuffer are translated to a shader storage buffer with `read-write` layout. RasterizerOrderedStructuredBuffer and RasterizerOrderedByteAddressBuffer will use an extension, `SPV_EXT_fragment_shader_interlock`. @@ -156,6 +156,34 @@ It is similar to `ConstantBuffer` in HLSL, and `ParameterBlock` can include not When both ordinary data fields and resource typed fields exist in a parameter block, all ordinary data fields will be grouped together into a uniform buffer and appear as a binding 0 of the resulting descriptor set. +Push Constants +--------------------- + +By default, a `uniform` parameter defined in the parameter list of an entrypoint function is translated to a push constant in SPIRV, if the type of the parameter is ordinary data type (no resources/textures). +All `uniform` parameter defined in global scope are grouped together and placed in a default constant bbuffer. You can make a global uniform parameter laid out as a push constant by using the `[vk::push_constant]` attribute +on the uniform parameter. + +Specialization Constants +------------------------ + +You can specify a global constant to translate into a SPIRV specialization constant with the `[SpecializationConstant]` attribute. +For example: +```csharp +[SpecializationConstant] +const int myConst = 1; // Maps to a SPIRV specialization constant +``` + +By default, Slang will automatically assign `constant_id` number for specialization constants. If you wish to explicitly specify them, use `[vk::constant_id]` attribute: +```csharp +[vk::constant_id(1)] +const int myConst = 1; +``` + +Alternatively, the GLSL `layout` syntax is also supported by Slang: +```glsl +layout(constant_id = 1) const int MyConst = 1; +``` + SPIR-V specific Compiler options -------------------------------- diff --git a/docs/user-guide/toc.html b/docs/user-guide/toc.html index df1b4ba9d..77c4f16d8 100644 --- a/docs/user-guide/toc.html +++ b/docs/user-guide/toc.html @@ -83,6 +83,8 @@
  • Interface-typed Values
  • Extending a Type with Additional Interface Conformances
  • `is` and `as` Operator
    • +
  • Generic Interfaces
    • +
  • Generic Extensions
  • Extensions to Interfaces
  • Variadic Generics
  • Builtin Interfaces
    • @@ -207,6 +209,8 @@
  • Supported atomic types for each target
  • ConstantBuffer, (RW/RasterizerOrdered)StructuredBuffer, (RW/RasterizerOrdered)ByteAddressBuffer
  • ParameterBlock for SPIR-V target
    • +
  • Push Constants
    • +
  • Specialization Constants
  • SPIR-V specific Compiler options
  • SPIR-V specific Attributes
  • Multiple entry points support
    • -- cgit v1.2.3