Merge remote-tracking branch 'origin/main' into cbieneman/terminology

.github/workflows/jekyll-gh-pages.yml

@@ -5,6 +5,10 @@ on:
   # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
+  pull_request:
+    types: [opened,synchronize]
+    paths:
+      - specs/language/**
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -31,6 +35,7 @@ jobs:
         uses: actions/configure-pages@v2
       - name: Install dependencies
         run: |
+          sudo apt-get update
           sudo apt -y install texlive
           sudo apt -y install texlive-latex-extra
           curl -fsSL https://github.com/jgm/pandoc/releases/download/3.1.9/pandoc-3.1.9-1-amd64.deb -o pandoc.deb
@@ -49,9 +54,15 @@ jobs:
           destination: ./_site
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
+      - if: ${{ github.event_name == 'pull_request'}}
+        uses: actions/upload-artifact@v4
+        with:
+          name: PDF
+          path: ${{github.workspace}}/specs/hlsl.pdf
 
   # Deployment job
   deploy:
+    if: ${{ github.event_name == 'push'}}
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

docs/Process.md

@@ -26,18 +26,13 @@ This process draws heavily from
 [Swift's Evolution process](https://github.com/apple/swift-evolution/), and is
 further tweaked to align with the HLSL team's goals and priorities.
 
-## Proposing a Feature
+Significant project infrastructure or implementation details will also use this
+process to refine and document the design process.
 
-By far the best way for an external contributor to propose a feature is through
-GitHub issues (See the section below on "Filing Issues"). Issues in this
-repository will be used to publicly track feature requests for the HLSL language
-and HLSL runtime interfaces. Direct tooling feature requests to the
-[DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new).
+## Making a Proposal
 
-> Note: a tooling feature would be a feature that does not impact HLSL source
-> representations in any way (no added syntax, APIs, or altered
-> interpretations), and instead exposes new ways to use the DXC compiler or
-> library.
+The best way for an external contributor to propose a feature is through GitHub
+issues (See the section below on "Filing Issues").
 
 If you write a proposal yourself you must find a member of the HLSL team to act
 as a _Sponsor_ for the change. The _Sponsor_ is responsible for tracking and
@@ -58,6 +53,10 @@ HLSL [Design Considerations](DesignConsiderations.md).
 Draft proposals are first provided as pull requests. They should be written
 following one of the templates in the `proposals/templates` directory.
 
+Add new proposals for language or runtime features directly in the `proposals`
+directory. Add new proposals for project infrastructure or implementation
+details of the compilers in the `proposals/infra` directory.
+
 Proposals that follow the most simplified path from idea to feature will move
 through the following states in order:
 
@@ -94,6 +93,19 @@ requirements for justification are not high and could be as simple as
 
 ## Filing Issues
 
+Issues in this repository publicly tracks feature requests for the HLSL language
+and HLSL runtime interfaces as well as issues with proposals and specifications
+contained within the repository.
+
+Please direct tooling feature requests to the
+[DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new),
+or [Clang](https://github.com/llvm/llvm-project/issues/new) as appropriate.
+
+> Note: a tooling feature would be a feature that does not impact HLSL source
+> representations in any way (no added syntax, APIs, or altered
+> interpretations), and instead exposes new ways to use the DXC compiler or
+> library.
+
 This repository provides three custom issue templates:
 
 1. Feature Request

proposals/0011-inline-spirv.md

@@ -102,8 +102,8 @@ extension in a header file. The header file could be something like
 // spv_khr_post_depth_coverage.h
 
 // It would be nice to have this live in a namespace spv::khr::, but not possible with attributes.
-const uint32_t SampleMaskPostDepthCoverageCapabilityId = 4447;
-const uint32_t PostDepthCoverageExecutionModeId = 4446;
+static const uint32_t SampleMaskPostDepthCoverageCapabilityId = 4447;
+static const uint32_t PostDepthCoverageExecutionModeId = 4446;
 #define SPV_KHR_PostDepthCoverageExecutionMode vk::ext_extension("SPV_KHR_post_depth_coverage"), vk::ext_capability(SampleMaskPostDepthCoverageCapabilityId), vk::spvexecutionmode(PostDepthCoverageExecutionModeId)
 ```
 
@@ -128,10 +128,10 @@ defined in the header file as a function, and then the function can be called by
 the users. For example,
 
 ```
+template<typename T>
 [[vk::ext_capability(5568)]]
 [[vk::ext_extension("SPV_INTEL_subgroups")]]
 [[vk::ext_instruction(/* OpSubgroupShuffleINTEL */ 5571)]]
-template<typename T>
 T SubgroupShuffleINTEL(T data, uint32 invocationId);
 ```
 
@@ -157,23 +157,49 @@ test. Some of the difficulties are:
     they cannot use the same id for two different types. This can become hard to
     manage.
 
-This proposal deprecates the old mechanism, and replaces it with a new type
-`vk::SpirvType<int OpCode, ...>`. The template on the type contains the opcode
-and all of the parameters necessary for that opcode. The difficulty with this is
-that the operands are not just literal integer values. Sometimes they are
-another type.
+This proposal deprecates the old mechanism, and replaces it with two new types
+`vk::SpirvOpaqueType<uint OpCode, ...>` and
+`vk::SpirvType<uint OpCode, uint size, uint alignment, ...>`. For
+`SpirvOpaqueType`, the template on the type contains the opcode and all of the
+parameters necessary for that opcode. Each parameter may be one of three kinds
+of values:
+
+1.  Any expression that can be evaluated to a constant scalar value at compile
+    time. This value will be passed in to the type-declaration instruction as
+    the id of an `OpConstant*` instruction.
+1.  An expression as described above, wrapped in a call to `vk::ext_literal`.
+    This value will be passed in to the type-declaration instruction as an
+    immediate literal value.
+1.  Any type. The id of the lowered type will be passed in to the
+    type-declaration instruction.
+
+For example, [`OpTypeArray`](https://registry.khronos.org/SPIR-V/specs/unified1/
+SPIRV.html#OpTypeArray) takes an id for the element type and an id for the
+element length, so an array of 16 integers could be declared as
+
+```
+vk::SpirvOpaqueType</* OpTypeArray */ 28, int, 16>
+```
+
+[`OpTypeVector`](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html#
+OpTypeVector) takes an id for the component type and a literal for the component
+count, so a 4-integer vector could be declared as
+
+```
+vk::SpirvOpaqueType</* OpTypeVector */ 23, int, vk::ext_literal(4)>
+```
 
 The header file could create a partial instantiation with a more meaningful
 name. For example, if you wanted to declare the types from the
 [SPV_INTEL_device_side_avc_motion_estimation](http://htmlpreview.github.io/?https://github.com/KhronosGroup/SPIRV-Registry/blob/main/extensions/INTEL/SPV_INTEL_device_side_avc_motion_estimation.html)
 you could have
 
 ```
-typedef vk::SprivType</* OpTypeAvcMcePayloadINTEL */ 5704> AvcMcePayloadINTEL;
+typedef vk::SpirvOpaqueType</* OpTypeAvcMcePayloadINTEL */ 5704> AvcMcePayloadINTEL;
 
 // Requires HLSL2021
 template<typename ImageType>
-using VmeImageINTEL = vk::SpirvType</* OpTypeVmeImageINTEL */ 5700, Imagetype>;
+using VmeImageINTEL = vk::SpirvOpaqueType</* OpTypeVmeImageINTEL */ 5700, Imagetype>;
 ```
 
 Then the user could simply use the types:
@@ -183,6 +209,22 @@ VmeImageINTEL<Texture2D> image;
 AvcMcePayloadINTEL payload;
 ```
 
+If you want to use an inline SPIR-V type in a context where the size and
+alignment matter, for example as an interface type or in a push constant, you
+should use `SpirvType` instead of `SpirvOpaqueType`.
+
+`SpirvType` additionally takes a `size` parameter, specifying the number of
+bytes a single value of the type occupies, and an `alignment` parameter,
+specifying a power of two that the value will be aligned to in memory. For
+example, an unsigned 8-bit integer type could be declared as
+
+```
+typedef vk::SpirvType</* OpTypeInt */ 21, /* size */ 1, /* alignment */ 1, vk::ext_literal(8), vk::ext_literal(false)> uint8_t;
+```
+
+Neither `SpirvType` nor `SpirvOpaqueType` may be used as the component type for
+an HLSL vector or matrix.
+
 ### Decorations
 
 The current inline SPIR-V includes the `vk::ext_decorate` attribute. This works