├── .gitattributes ├── .github ├── ISSUE_TEMPLATE │ ├── agenda_item.md │ ├── feature_request.md │ ├── proposal.md │ └── spec.md ├── pr-labels.yml └── workflows │ ├── jekyll-gh-pages.yml │ ├── pr-description-checker.yml │ └── pr-labeler.yml ├── .gitignore ├── CODE_OF_CONDUCT.md ├── LICENSE ├── README.md ├── SECURITY.md ├── SUPPORT.md ├── docs ├── Contact.md ├── DesignConsiderations.md ├── DesignMeeting.md ├── DesignMeetingMinutes │ ├── 2025-01-21.md │ ├── 2025-02-04.md │ ├── 2025-02-18.md │ ├── 2025-03-18.md │ ├── 2025-04-01.md │ ├── 2025-04-15.md │ ├── 2025-04-29.md │ ├── Template.md │ └── index.md ├── DesignMeetingTerms.txt ├── HLSL202x.md └── Process.md ├── proposals ├── 0001-hlsl-namespace.md ├── 0002-assets │ ├── AttributeGrammarRender.png │ ├── ClassGrammarRender.png │ └── StatementGrammarRender.png ├── 0002-cxx-attributes.md ├── 0003-numeric-constants.md ├── 0004-unions.md ├── 0005-strict-initializer-lists.md ├── 0006-reference-types.md ├── 0007-const-member-functions.md ├── 0008-non-member-operator-overloading.md ├── 0009-math-modes.md ├── 0010-vk-buffer-ref.md ├── 0011-inline-spirv.md ├── 0012-psv0-entry-name.md ├── 0013-wave-size-range.md ├── 0014-expanded-comparison-sampling.md ├── 0015-extended-command-info.md ├── 0017-assets │ ├── DiffExample1.png │ └── DiffExample2.png ├── 0017-conforming-literals.md ├── 0018-work-graphs.md ├── 0019-mesh-nodes.md ├── 0020-hlsl-202x-202y.md ├── 0021-vk-coop-matrix.md ├── 0022-hlsl-loop-unroll-factor.md ├── 0023-cxx11-base.md ├── 0024-opacity-micromaps.md ├── 0025-max-records-per-node.md ├── 0026-hlsl-long-vector-type.md ├── 0027-shader-execution-reordering.md ├── 0028-dxil18.md ├── 0029-cooperative-vector.md ├── 0030-dxil-vectors.md ├── 0031-hlsl-vector-matrix-operations.md ├── 0032-constructors.md ├── 0033-dxil19.md ├── 0034-vk-sampled-texture.md ├── index.md ├── infra │ ├── INF-0004-validator-hashing.md │ ├── INF-0005-validator-backcompat-testing.md │ └── index.md └── templates │ ├── basic-template.md │ ├── extension-template.md │ ├── infrastructure-template.md │ └── shader-model-feature-template.md ├── resources └── HLSL.png └── specs └── language ├── CMakeLists.txt ├── basic.tex ├── conversions.tex ├── declarations.tex ├── expressions.tex ├── glossary.tex ├── hlsl.tex ├── introduction.tex ├── lex.tex ├── macros.tex ├── overloading.tex ├── placeholders.tex ├── resources.tex └── statements.tex /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto 2 | *.png binary 3 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/agenda_item.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Design Meeting Agenda Item 3 | about: Add an item to the next Design Meeting agenda 4 | title: '' 5 | labels: ['Design Meeting'] 6 | assignees: ['llvm-beanz', 'farzonl'] 7 | 8 | --- 9 | 10 | **Does the agenda item relate to an existing proposal or specification language?** 11 | Please link the file in the repo where the problem is documented. 12 | 13 | **Describe the issue or outstanding question.** 14 | This can be as short as a question that needs answering or as complex as needed 15 | to convey the problem that needs solving. 16 | 17 | **Additional context** 18 | Add any other context or screenshots about the feature request here. 19 | 20 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: ['enhancement', 'needs-triage'] 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Is your feature request related to a problem? Please describe.** 11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 12 | 13 | **Describe the solution you'd like** 14 | A clear and concise description of what you want to happen. 15 | 16 | **Describe alternatives you've considered** 17 | A clear and concise description of any alternative solutions or features you've considered. 18 | 19 | **Additional context** 20 | Add any other context or screenshots about the feature request here. 21 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/proposal.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Proposal Follow-up 3 | about: Follow-up issue for a proposal 4 | title: '' 5 | labels: ['active proposal', 'needs-triage'] 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Which proposal does this relate to?** 11 | Please link the file in the repo where the problem is documented. 12 | 13 | **Describe the issue or outstanding question.** 14 | This can be as short as a question that needs answering or as complex as needed 15 | to convey the problem that needs solving. 16 | 17 | **Additional context** 18 | Add any other context or screenshots about the feature request here. 19 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/spec.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Spec 3 | about: Highlight a problem with a published spec or accepted proposal 4 | title: '' 5 | labels: ['spec', 'needs-triage'] 6 | assignees: '' 7 | 8 | --- 9 | 10 | **Which document does this relate to?** 11 | Please link the file in the repo where the problem is documented. 12 | 13 | **Describe the issue you see with the spec** 14 | A clear and concise description of the problem. 15 | 16 | **Additional context** 17 | Add any other context or screenshots about the feature request here. 18 | -------------------------------------------------------------------------------- /.github/pr-labels.yml: -------------------------------------------------------------------------------- 1 | needs-triage: 2 | - changed-files: 3 | - any-glob-to-any-file: 'proposals/**/*' 4 | 5 | language-spec: 6 | - changed-files: 7 | - any-glob-to-any-file: 'specs/**/*' 8 | -------------------------------------------------------------------------------- /.github/workflows/jekyll-gh-pages.yml: -------------------------------------------------------------------------------- 1 | # Sample workflow for building and deploying a Jekyll site to GitHub Pages 2 | name: Deploy Jekyll with GitHub Pages dependencies preinstalled 3 | 4 | on: 5 | # Runs on pushes targeting the default branch 6 | push: 7 | branches: ["main"] 8 | pull_request: 9 | types: [opened,synchronize] 10 | paths: 11 | - specs/language/** 12 | 13 | # Allows you to run this workflow manually from the Actions tab 14 | workflow_dispatch: 15 | 16 | # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages 17 | permissions: 18 | contents: read 19 | pages: write 20 | id-token: write 21 | 22 | # Allow one concurrent deployment 23 | concurrency: 24 | group: "pages" 25 | cancel-in-progress: true 26 | 27 | jobs: 28 | # Build job 29 | build: 30 | runs-on: ubuntu-latest 31 | steps: 32 | - name: Checkout 33 | uses: actions/checkout@v3 34 | with: 35 | ref: ${{ github.event.pull_request.head.sha }} 36 | - name: Setup Pages 37 | uses: actions/configure-pages@v2 38 | - name: Install dependencies 39 | run: | 40 | sudo apt-get update 41 | sudo apt -y install texlive 42 | sudo apt -y install texlive-latex-extra 43 | curl -fsSL https://github.com/jgm/pandoc/releases/download/3.1.9/pandoc-3.1.9-1-amd64.deb -o pandoc.deb 44 | sudo dpkg -i pandoc.deb 45 | - name: Build LaTeX 46 | run: | 47 | cmake -B build ${{github.workspace}}/specs/language 48 | cmake --build build --target html 49 | cmake --build build --target pdf 50 | cp build/hlsl.pdf ${{github.workspace}}/specs/ 51 | cp build/html/* ${{github.workspace}}/specs/ 52 | - name: Build with Jekyll 53 | uses: actions/jekyll-build-pages@v1 54 | with: 55 | source: ./ 56 | destination: ./_site 57 | - name: Upload artifact 58 | uses: actions/upload-pages-artifact@v3 59 | - if: ${{ github.event_name == 'pull_request'}} 60 | uses: actions/upload-artifact@v4 61 | with: 62 | name: PDF 63 | path: ${{github.workspace}}/specs/hlsl.pdf 64 | 65 | # Deployment job 66 | deploy: 67 | if: ${{ github.event_name == 'push'}} 68 | environment: 69 | name: github-pages 70 | url: ${{ steps.deployment.outputs.page_url }} 71 | runs-on: ubuntu-latest 72 | needs: build 73 | steps: 74 | - name: Deploy to GitHub Pages 75 | id: deployment 76 | uses: actions/deploy-pages@v4 77 | -------------------------------------------------------------------------------- /.github/workflows/pr-description-checker.yml: -------------------------------------------------------------------------------- 1 | name: 'PR description checker' 2 | on: 3 | pull_request_target: 4 | types: 5 | - opened 6 | - edited 7 | - reopened 8 | - labeled 9 | - unlabeled 10 | jobs: 11 | check-pr-description: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v4 15 | - uses: jadrol/pr-description-checker-action@c659fed338a52d657d34462c8bc7fc1f65d25758 16 | id: description-checker 17 | with: 18 | repo-token: ${{ secrets.GITHUB_TOKEN }} 19 | -------------------------------------------------------------------------------- /.github/workflows/pr-labeler.yml: -------------------------------------------------------------------------------- 1 | name: "Pull Request Labeler" 2 | on: 3 | - pull_request_target 4 | 5 | jobs: 6 | labeler: 7 | permissions: 8 | contents: read 9 | pull-requests: write 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Checkout Automation Script 13 | uses: actions/checkout@v4 14 | with: 15 | sparse-checkout: .github 16 | ref: main 17 | - uses: actions/labeler@v5 18 | with: 19 | configuration-path: .github/pr-labels.yml 20 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | ## Ignore Visual Studio temporary files, build results, and 2 | ## files generated by popular Visual Studio add-ons. 3 | ## 4 | ## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore 5 | 6 | # User-specific files 7 | *.rsuser 8 | *.suo 9 | *.user 10 | *.userosscache 11 | *.sln.docstates 12 | 13 | # User-specific files (MonoDevelop/Xamarin Studio) 14 | *.userprefs 15 | 16 | # Mono auto generated files 17 | mono_crash.* 18 | 19 | # Build results 20 | [Dd]ebug/ 21 | [Dd]ebugPublic/ 22 | [Rr]elease/ 23 | [Rr]eleases/ 24 | x64/ 25 | x86/ 26 | [Aa][Rr][Mm]/ 27 | [Aa][Rr][Mm]64/ 28 | bld/ 29 | [Bb]in/ 30 | [Oo]bj/ 31 | [Ll]og/ 32 | [Ll]ogs/ 33 | 34 | # Visual Studio 2015/2017 cache/options directory 35 | .vs/ 36 | # Uncomment if you have tasks that create the project's static files in wwwroot 37 | #wwwroot/ 38 | 39 | # Visual Studio 2017 auto generated files 40 | Generated\ Files/ 41 | 42 | # MSTest test Results 43 | [Tt]est[Rr]esult*/ 44 | [Bb]uild[Ll]og.* 45 | 46 | # NUnit 47 | *.VisualState.xml 48 | TestResult.xml 49 | nunit-*.xml 50 | 51 | # Build Results of an ATL Project 52 | [Dd]ebugPS/ 53 | [Rr]eleasePS/ 54 | dlldata.c 55 | 56 | # Benchmark Results 57 | BenchmarkDotNet.Artifacts/ 58 | 59 | # .NET Core 60 | project.lock.json 61 | project.fragment.lock.json 62 | artifacts/ 63 | 64 | # StyleCop 65 | StyleCopReport.xml 66 | 67 | # Files built by Visual Studio 68 | *_i.c 69 | *_p.c 70 | *_h.h 71 | *.ilk 72 | *.meta 73 | *.obj 74 | *.iobj 75 | *.pch 76 | *.pdb 77 | *.ipdb 78 | *.pgc 79 | *.pgd 80 | *.rsp 81 | *.sbr 82 | *.tlb 83 | *.tli 84 | *.tlh 85 | *.tmp 86 | *.tmp_proj 87 | *_wpftmp.csproj 88 | *.log 89 | *.vspscc 90 | *.vssscc 91 | .builds 92 | *.pidb 93 | *.svclog 94 | *.scc 95 | 96 | # Chutzpah Test files 97 | _Chutzpah* 98 | 99 | # Visual C++ cache files 100 | ipch/ 101 | *.aps 102 | *.ncb 103 | *.opendb 104 | *.opensdf 105 | *.sdf 106 | *.cachefile 107 | *.VC.db 108 | *.VC.VC.opendb 109 | 110 | # Visual Studio profiler 111 | *.psess 112 | *.vsp 113 | *.vspx 114 | *.sap 115 | 116 | # Visual Studio Trace Files 117 | *.e2e 118 | 119 | # TFS 2012 Local Workspace 120 | $tf/ 121 | 122 | # Guidance Automation Toolkit 123 | *.gpState 124 | 125 | # ReSharper is a .NET coding add-in 126 | _ReSharper*/ 127 | *.[Rr]e[Ss]harper 128 | *.DotSettings.user 129 | 130 | # TeamCity is a build add-in 131 | _TeamCity* 132 | 133 | # DotCover is a Code Coverage Tool 134 | *.dotCover 135 | 136 | # AxoCover is a Code Coverage Tool 137 | .axoCover/* 138 | !.axoCover/settings.json 139 | 140 | # Visual Studio code coverage results 141 | *.coverage 142 | *.coveragexml 143 | 144 | # NCrunch 145 | _NCrunch_* 146 | .*crunch*.local.xml 147 | nCrunchTemp_* 148 | 149 | # MightyMoose 150 | *.mm.* 151 | AutoTest.Net/ 152 | 153 | # Web workbench (sass) 154 | .sass-cache/ 155 | 156 | # Installshield output folder 157 | [Ee]xpress/ 158 | 159 | # DocProject is a documentation generator add-in 160 | DocProject/buildhelp/ 161 | DocProject/Help/*.HxT 162 | DocProject/Help/*.HxC 163 | DocProject/Help/*.hhc 164 | DocProject/Help/*.hhk 165 | DocProject/Help/*.hhp 166 | DocProject/Help/Html2 167 | DocProject/Help/html 168 | 169 | # Click-Once directory 170 | publish/ 171 | 172 | # Publish Web Output 173 | *.[Pp]ublish.xml 174 | *.azurePubxml 175 | # Note: Comment the next line if you want to checkin your web deploy settings, 176 | # but database connection strings (with potential passwords) will be unencrypted 177 | *.pubxml 178 | *.publishproj 179 | 180 | # Microsoft Azure Web App publish settings. Comment the next line if you want to 181 | # checkin your Azure Web App publish settings, but sensitive information contained 182 | # in these scripts will be unencrypted 183 | PublishScripts/ 184 | 185 | # NuGet Packages 186 | *.nupkg 187 | # NuGet Symbol Packages 188 | *.snupkg 189 | # The packages folder can be ignored because of Package Restore 190 | **/[Pp]ackages/* 191 | # except build/, which is used as an MSBuild target. 192 | !**/[Pp]ackages/build/ 193 | # Uncomment if necessary however generally it will be regenerated when needed 194 | #!**/[Pp]ackages/repositories.config 195 | # NuGet v3's project.json files produces more ignorable files 196 | *.nuget.props 197 | *.nuget.targets 198 | 199 | # Microsoft Azure Build Output 200 | csx/ 201 | *.build.csdef 202 | 203 | # Microsoft Azure Emulator 204 | ecf/ 205 | rcf/ 206 | 207 | # Windows Store app package directories and files 208 | AppPackages/ 209 | BundleArtifacts/ 210 | Package.StoreAssociation.xml 211 | _pkginfo.txt 212 | *.appx 213 | *.appxbundle 214 | *.appxupload 215 | 216 | # Visual Studio cache files 217 | # files ending in .cache can be ignored 218 | *.[Cc]ache 219 | # but keep track of directories ending in .cache 220 | !?*.[Cc]ache/ 221 | 222 | # Others 223 | ClientBin/ 224 | ~$* 225 | *~ 226 | *.dbmdl 227 | *.dbproj.schemaview 228 | *.jfm 229 | *.pfx 230 | *.publishsettings 231 | orleans.codegen.cs 232 | 233 | # Including strong name files can present a security risk 234 | # (https://github.com/github/gitignore/pull/2483#issue-259490424) 235 | #*.snk 236 | 237 | # Since there are multiple workflows, uncomment next line to ignore bower_components 238 | # (https://github.com/github/gitignore/pull/1529#issuecomment-104372622) 239 | #bower_components/ 240 | 241 | # RIA/Silverlight projects 242 | Generated_Code/ 243 | 244 | # Backup & report files from converting an old project file 245 | # to a newer Visual Studio version. Backup files are not needed, 246 | # because we have git ;-) 247 | _UpgradeReport_Files/ 248 | Backup*/ 249 | UpgradeLog*.XML 250 | UpgradeLog*.htm 251 | ServiceFabricBackup/ 252 | *.rptproj.bak 253 | 254 | # SQL Server files 255 | *.mdf 256 | *.ldf 257 | *.ndf 258 | 259 | # Business Intelligence projects 260 | *.rdl.data 261 | *.bim.layout 262 | *.bim_*.settings 263 | *.rptproj.rsuser 264 | *- [Bb]ackup.rdl 265 | *- [Bb]ackup ([0-9]).rdl 266 | *- [Bb]ackup ([0-9][0-9]).rdl 267 | 268 | # Microsoft Fakes 269 | FakesAssemblies/ 270 | 271 | # GhostDoc plugin setting file 272 | *.GhostDoc.xml 273 | 274 | # Node.js Tools for Visual Studio 275 | .ntvs_analysis.dat 276 | node_modules/ 277 | 278 | # Visual Studio 6 build log 279 | *.plg 280 | 281 | # Visual Studio 6 workspace options file 282 | *.opt 283 | 284 | # Visual Studio 6 auto-generated workspace file (contains which files were open etc.) 285 | *.vbw 286 | 287 | # Visual Studio LightSwitch build output 288 | **/*.HTMLClient/GeneratedArtifacts 289 | **/*.DesktopClient/GeneratedArtifacts 290 | **/*.DesktopClient/ModelManifest.xml 291 | **/*.Server/GeneratedArtifacts 292 | **/*.Server/ModelManifest.xml 293 | _Pvt_Extensions 294 | 295 | # Paket dependency manager 296 | .paket/paket.exe 297 | paket-files/ 298 | 299 | # FAKE - F# Make 300 | .fake/ 301 | 302 | # CodeRush personal settings 303 | .cr/personal 304 | 305 | # Python Tools for Visual Studio (PTVS) 306 | __pycache__/ 307 | *.pyc 308 | 309 | # Cake - Uncomment if you are using it 310 | # tools/** 311 | # !tools/packages.config 312 | 313 | # Tabs Studio 314 | *.tss 315 | 316 | # Telerik's JustMock configuration file 317 | *.jmconfig 318 | 319 | # BizTalk build output 320 | *.btp.cs 321 | *.btm.cs 322 | *.odx.cs 323 | *.xsd.cs 324 | 325 | # OpenCover UI analysis results 326 | OpenCover/ 327 | 328 | # Azure Stream Analytics local run output 329 | ASALocalRun/ 330 | 331 | # MSBuild Binary and Structured Log 332 | *.binlog 333 | 334 | # NVidia Nsight GPU debugger configuration file 335 | *.nvuser 336 | 337 | # MFractors (Xamarin productivity tool) working folder 338 | .mfractor/ 339 | 340 | # Local History for Visual Studio 341 | .localhistory/ 342 | 343 | # BeatPulse healthcheck temp database 344 | healthchecksdb 345 | 346 | # Backup folder for Package Reference Convert tool in Visual Studio 2017 347 | MigrationBackup/ 348 | 349 | # Ionide (cross platform F# VS Code tools) working folder 350 | .ionide/ 351 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Microsoft Open Source Code of Conduct 2 | 3 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 4 | 5 | Resources: 6 | 7 | - [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) 8 | - [Microsoft Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) 9 | - Contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions or concerns 10 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) Microsoft Corporation. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # HLSL Specifications 4 | 5 | This repository contains documentation for HLSL feature proposals and specifications. Please see the documentation for 6 | the HLSL Feature [Proposal Process](docs/Process.md) for more information on proposals. 7 | 8 | A listing of the active proposals is available [here](proposals/). 9 | 10 | This repository also contains specifications for the HLSL language. The draft 11 | HLSL specification is available in 12 | [HTML](https://microsoft.github.io/hlsl-specs/specs/hlsl.html) and 13 | [PDF](https://microsoft.github.io/hlsl-specs/specs/hlsl.pdf). 14 | 15 | ## Contributing 16 | 17 | This project welcomes contributions and suggestions. Most contributions require you to agree to a 18 | Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us 19 | the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. 20 | 21 | When you submit a pull request, a CLA bot will automatically determine whether you need to provide 22 | a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions 23 | provided by the bot. You will only need to do this once across all repos using our CLA. 24 | 25 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 26 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or 27 | contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 28 | 29 | ## Public Design Meeting 30 | 31 | The HLSL team organizes a meeting every two weeks which is open to the public to discuss work in progress in this repository. 32 | That includes proposals for new HLSL features as well as the ongoing work to write a language specification. 33 | 34 | For more information on this meeting and the terms and conditions for 35 | participation, see the [Design Meeting](docs/DesignMeeting.md) documentation. 36 | 37 | ## Trademarks 38 | 39 | This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 40 | trademarks or logos is subject to and must follow 41 | [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general). 42 | Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. 43 | Any use of third-party trademarks or logos are subject to those third-party's policies. 44 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /SUPPORT.md: -------------------------------------------------------------------------------- 1 | # Support 2 | 3 | ## How to file issues and get help 4 | 5 | This project uses GitHub Issues to track bugs and feature requests. Please search the existing 6 | issues before filing new issues to avoid duplicates. For new issues, file your bug or 7 | feature request as a new Issue. 8 | 9 | For help and questions about using this project, please reach out to 10 | [HLSL Support](mailto:AskHLSL@microsoft.com). 11 | 12 | ## Microsoft Support Policy 13 | 14 | Support for this HLSL Specifications is limited to the resources listed above. 15 | -------------------------------------------------------------------------------- /docs/Contact.md: -------------------------------------------------------------------------------- 1 | # Contacting the HLSL Team 2 | 3 | This page lists some of the public spaces where you can find members of the HLSL. 4 | 5 | ## Discord Channels 6 | 7 | * [DirectX](https://discord.com/invite/directx) - For D3D related 8 | HLSL topics. 9 | * [LLVM](https://discord.gg/xS7Z362) - For HLSL Compiler Modernization and other 10 | compiler topics. 11 | 12 | ## GitHub Issues 13 | 14 | * [DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new) 15 | - For bugs and feature requests specific to the DXC compiler. 16 | * [hlsl-specs](https://github.com/microsoft/hlsl-specs/issues/new) - For feature 17 | requests for the HLSL language or runtimes (Shader Models, Vulkan, etc). 18 | * [LLVM](https://github.com/llvm/llvm-project/issues/new) - For bugs and feature 19 | requests specific to the Clang HLSL implementation. 20 | 21 | ## Email 22 | 23 | * [Ask HLSL](mailto:askhlsl@microsoft.com) - For issues where privacy is 24 | essential. 25 | -------------------------------------------------------------------------------- /docs/DesignConsiderations.md: -------------------------------------------------------------------------------- 1 | # HLSL Design Considerations 2 | 3 | When designing and proposing a feature for HLSL there are some design 4 | considerations that should be taken into account. 5 | 6 | ## Style Conventions 7 | 8 | HLSL's built-in types and methods should conform to a consistent coding style. 9 | 10 | * Data types, methods and built-in functions should all be `CamelCase`. 11 | * Namespaces and keywords are lowercase, `_` separated. 12 | * Vulkan-specific functionality should be added to the `vk` namespace. 13 | * Microsoft-style attributes interchangably use `CamelCase` and `_` separation, 14 | but should prefer `CamelCase` 15 | * System Value semantics are case insensitive, should be specified `CamelCase` 16 | and prefixed `SV_`. 17 | 18 | ## Versioning 19 | 20 | All features should consider how users can adapt to the presence or absence of 21 | support. HLSL has two primary revisioning axis: language version and runtime 22 | version. How the two versions interact is not always a clean and easy line to 23 | see. 24 | 25 | ### Language Changes 26 | 27 | > Language versioning changes the core language of HLSL: syntax, grammar, 28 | > semantics, etc. 29 | 30 | HLSL identifies language versions by the year of release (2015, 2016, 2017, 31 | 2018, 2021, ...), and future language versions have placeholder years (202x, 32 | 202y, ...). 33 | 34 | Most language features do not require underlying runtime features so they can be 35 | exposed in HLSL regardless of runtime targeting. 36 | 37 | Some HLSL language features are _strictly additive_, and may be retroactively 38 | enabled in older language modes. See the section below on "Exposing versioning" 39 | for more information about retroactively exposing features. 40 | 41 | ### Runtime Changes 42 | 43 | > Runtime versioning changes the library functionality of the language: data 44 | > types, methods, etc. 45 | 46 | HLSL's supported runtimes are DirectX and Vulkan. For DirectX versioning of HLSL 47 | is broken down by Shader Model and DXIL version, and for Vulkan versioning is 48 | broken down by Vulkan and SPIR-V version. 49 | 50 | When a new runtime version is released and no previous HLSL compilers have 51 | supported it, the feature can be added dependent only on targeting the new 52 | runtime version. When a feature is added to a runtime version that has 53 | previously been supported by a compiler release, the feature should be treated 54 | as a retroactive addition. See the section below on "Exposing versioning" for 55 | more information about retroactively exposing features. 56 | 57 | ### Exposing versioning 58 | 59 | HLSL language and target runtime versions are exposed in the HLSL preprocessor 60 | via the built-in preprocessor macros described below: 61 | 62 | * **`__HLSL_VERSION`** - Integer value for the HLSL language version. Unreleased 63 | or experimental language versions are defined as a number larger than the 64 | highest released version. 65 | * **`__SHADER_TARGET_STAGE`** - Integer value corresponding to the shader stage. 66 | Shader stage. The shader stage values are exposed as 67 | `__SHADER_STAGE_**STAGE**` (i.e. `__SHADER_STAGE_VERTEX`, 68 | `__SHADER_STAGE_PIXEL`, ...) 69 | * **`__SHADER_TARGET_MAJOR`** - Major version for Shader Model target. 70 | * **`__SHADER_TARGET_MINOR`** - Minor version for Shader Model target. 71 | 72 | If these macros are not sufficient for a given feature new macros or other 73 | mechanisms should be added as appropriate for the feature to enable developers 74 | to know if a given compiler release supports the required feature(s). 75 | 76 | For features that are added retroactively to an already final runtime or 77 | language version, a `__has_feature` check should be added to allow the user to 78 | query for feature support in the preprocessor instead of forcing the user to 79 | check compiler versions explicitly. The Clang feature checking macros are 80 | documented 81 | [here](https://clang.llvm.org/docs/LanguageExtensions.html#feature-checking-macros). 82 | The `__has_feature` macro is known to work in DXC, and should be used. 83 | -------------------------------------------------------------------------------- /docs/DesignMeeting.md: -------------------------------------------------------------------------------- 1 | # Design Meeting 2 | 3 | > NOTE: Please read the [terms of participation](#design-meeting-terms) 4 | > ("Terms") below prior to joining the Teams meeting. You joining the Teams 5 | > meeting with Microsoft indicates your acknowledgement, agreement, and consent 6 | > to these Terms. If you do not agree to these Terms, please do not join the 7 | > meeting. 8 | > 9 | > If you intend to contribute code or other copyrightable materials (e.g. 10 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 11 | > you are required to sign a Contributor License Agreement (CLA). For details, 12 | > visit https://cla.microsoft.com. 13 | 14 | Public design meetings are held every other week (cancelling for holidays). 15 | During these meetings the facilitator will iterate through PRs, issues and other 16 | agenda topics to ensure forward progress and facilitate discussion. 17 | 18 | The meetings are facilitated by [Chris Bieneman](https://github.com/llvm-beanz) 19 | and [Farzon Lotfi](https://github.com/farzonl). 20 | 21 | Meeting minutes will be posted into the [Meeting Minutes](docs/DesignMeetingMinutes) 22 | folder of this repository following the [template](docs/DesignMeetingMinutes/Template.md). 23 | 24 | ## Adding Agenda Items 25 | 26 | If there is an existing Issue or Pull Request you would like to discuss at the 27 | next design meeting please add the 28 | [Design Meeting](https://github.com/microsoft/hlsl-specs/labels/Design%20Meeting) 29 | label. Issues and Pull Requests with the Design Meeting label will be given priority 30 | during the meeting. 31 | 32 | If there is not an existing Issue or Pull request. File an issue with the 33 | [Design Meeting Agenda Item](https://github.com/microsoft/hlsl-specs/issues/new?template=agenda_item.md) 34 | template. 35 | 36 | ## Attending the Meeting 37 | 38 | The design meeting is held using Microsoft Teams. 39 | 40 | If you wish to attend the meeting for an individual occurrence or on a recurring 41 | basis, email [Ask HLSL @ Microsoft](mailto:AskHLSL@microsoft.com). Please 42 | specify whether you want the recurring invite or a specific occurrence. 43 | 44 | ## Design Meeting Terms 45 | 46 | NOTE: Please read the following terms of participation ("Terms") prior to 47 | joining the Teams meeting. You joining the Teams meeting with Microsoft 48 | indicates your acknowledgement, agreement, and consent to these Terms. If you 49 | do not agree to these Terms, please do not join the meeting. 50 | 51 | 1. **Your Consent.** You, as the participant in the Teams meeting hosted by 52 | Microsoft ("You") that provides these Terms as part of the meeting invitation, 53 | must read and agree to these Terms prior to joining and/or participating in the 54 | Teams meeting hosted by Microsoft ("Meeting"). By joining the Meeting, You 55 | consent to these Terms. 56 | 57 | 58 | 2. **Definitions.** 59 | 60 | * "Code" means any computer software code, whether in human-readable or 61 | machine-executable form, that is delivered by You to Microsoft. 62 | 63 | * "Input" means all written or verbal suggestions, comments, feedback, ideas, or 64 | know-how, that You provide to Microsoft during or relating to a Meeting. 65 | 66 | * "Materials" means any documentation, reports, tools, or other copyrighted 67 | materials that have relevance to a Meeting. 68 | 69 | 70 | 3. **Scope.** These Terms cover any and all Input that You provide, now or in 71 | the future, at any time, related to the Meeting subject matter. Any Code or 72 | Materials that you want to submit to Microsoft must be submitted via the 73 | Microsoft Contribution License Agreement. For details, visit 74 | https://cla.microsoft.com. 75 | 76 | 77 | 4. **Your Employer.** References to "employer" in these Terms include Your 78 | employer or anyone else for whom You are acting in providing your Input, e.g. as 79 | a contractor, vendor, or agent. If Your Input is provided in the course of Your 80 | work for an employer You must be authorized by the scope of your work, or secure 81 | permission from Your employer, to provide Input before consenting to these Terms 82 | by joining a Meeting. In that case, the term "You" or "Your" in these Terms will 83 | refer to You and the employer collectively. 84 | 85 | 86 | 5. **License grants.** You grant to Microsoft under all of Your applicable 87 | intellectual property rights, a nonexclusive, perpetual, irrevocable, 88 | royalty-free, worldwide right and license in the Input to modify, reproduce, 89 | create derivative works, test, display, perform, distribute, support, copy, 90 | make, have made, use, offer to sell, sell and import, and otherwise dispose of 91 | the Input, and to sublicense any or all of the foregoing rights to 92 | third-parties. 93 | 94 | 95 | 6. **Representations and Warranties.** You represent that You are legally 96 | entitled to provide Input according to these Terms and grant the licenses in 97 | Section 5. If You are joining this meeting on behalf of Your employer, You 98 | represent and warrant that You have the necessary authority to bind Your 99 | employer to the obligations contained in these Terms. UNLESS REQUIRED BY 100 | APPLICABLE LAW OR AGREED TO IN WRITING, AND EXCEPT FOR THE WARRANTIES EXPRESSLY 101 | STATED IN THESE TERMS, THE INPUT PROVIDED UNDER THESE TERMS IS PROVIDED WITHOUT 102 | WARRANTY OF ANY KIND, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY OF 103 | NONINFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. 104 | 105 | 106 | 7. **Notice to Microsoft.** You agree to notify Microsoft in writing of any 107 | facts or circumstances of which You later become aware that would make Your 108 | representations in these Terms inaccurate in any respect. 109 | 110 | 111 | 8. **Maintenance and Disclosure.** You agree that Input provided may be 112 | maintained indefinitely and disclosed publicly. 113 | 114 | 115 | 9. **Governing Law/Jurisdiction.** These Terms are governed by the laws of the 116 | State of Washington, and the parties consent to exclusive jurisdiction and venue 117 | in the federal courts sitting in King County, Washington, unless no federal 118 | subject matter jurisdiction exists, in which case the parties consent to 119 | exclusive jurisdiction and venue in the Superior Court of King County, 120 | Washington. The parties waive all defenses of lack of personal jurisdiction and 121 | forum non-conveniens. 122 | 123 | 124 | 10. **Entire Agreement/Assignment.** These Terms are the entire agreement 125 | between the parties, and supersedes any and all prior agreements, understandings 126 | or communications, written or oral, between the parties relating to the subject 127 | matter hereof. 128 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-01-21.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/01/21 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * Meeting timing & cadence 15 | * Current meeting is scheduled every other week on Tuesday at 5pm GMT, 12pm ET, 9am PT 16 | * Once attendence stabilizes in a month or so we'll revisit the meeting cadence and timing 17 | * Release Overview 18 | * Upcoming HLSL language versions are 202x (DXC & Clang) and 202y (Clang-only) 19 | * Upcoming Shader Model versions are 6.9 (DXIL - DXC & Clang) and 7.0 (SPIR-V - Clang-only) 20 | ## Issues 21 | 22 | * https://github.com/microsoft/hlsl-specs/issues/360 23 | * Action Item: @tex3d and @llvm-beanz to coordinate with @bob80905 to ensure the spec gets updated. 24 | 25 | ## PRs 26 | 27 | * https://github.com/microsoft/hlsl-specs/pull/13 28 | * Closed due to no driving engineer. This was not a user-requested feature and we believe it may encourage users to use ByteAddressBuffer in ways that are not performant. We should revisit how resource types work with references as part of the references proposal. 29 | * https://github.com/microsoft/hlsl-specs/pull/34 30 | * Action Item: @llvm-beanz will review to ensure it is reflective of changes since the PR was first posted. 31 | * Action Item: @tex3d and @pow2clk to review the PR and comment 32 | * https://github.com/microsoft/hlsl-specs/pull/61 33 | * We are committed to bringing a wave matrix feature to HLSL with the target being SM 6.9. It will substantially deviate from the proposal in this PR, so it probably isn't useful to use this PR as a base. 34 | * Action Item: @llvm-beanz to close. 35 | * https://github.com/microsoft/hlsl-specs/pull/65 36 | * Action Item: @pow2clk to review. 37 | * https://github.com/microsoft/hlsl-specs/pull/77 38 | * This isn't really in a great shape, but it is useful documentation to not lose. 39 | * Action Item: @llvm-beanz to merge 40 | * https://github.com/microsoft/hlsl-specs/pull/154 41 | * The general consensus is that this may be part of a larger set of features we need in HLSL for managing alignment of data more explicitly. 42 | * Filed issue to track: https://github.com/microsoft/hlsl-specs/issues/369 43 | * https://github.com/microsoft/hlsl-specs/pull/200 44 | * Action Item: @damyanp to close since this should be tracked in https://github.com/llvm/wg-hlsl 45 | * https://github.com/microsoft/hlsl-specs/pull/277 46 | * This is a major feature for SM 6.9. 47 | * Assigned to @derlemsft who is helping usher the feature. 48 | * Next steps: (1) File issues to track outstanding problems, (2) merge proposal, (3) rinse and repeat 49 | * https://github.com/microsoft/hlsl-specs/pull/317 50 | * AMD will have updates in a week or two on this 51 | * Action Item: Will re-review at the next meeting. 52 | * https://github.com/microsoft/hlsl-specs/pull/324 53 | * @damyanp and @llvm-beanz are uncertain that the appraoch of adding a "non-semantic" instruction for printf in DXIL is the right design appraoch. 54 | * This feature will also require design coordination with the Direct3D and PIX teams. 55 | * @pow2clk and @tex3d will review this in more detail. 56 | * Action Item: Schedule a deep-dive on this feature in a future design meeting. 57 | * https://github.com/microsoft/hlsl-specs/pull/361 58 | * @pow2clk is aiming to merge this later this week. Seems to be on track. 59 | * Action Item: @llvm-beanz to review. -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-02-04.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/02/04 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * No topics 15 | 16 | ## Issues 17 | * No marked issues 18 | * Action Item: @llvm-beanz to review issues for HLSL 202x 19 | 20 | ## PRs 21 | 22 | ### Carried Forward 23 | * [[0007] Big update to flesh out const instance methods](https://github.com/microsoft/hlsl-specs/pull/34) 24 | * Action Item: @llvm-beanz update based on @tex3d's feedback 25 | * Action Item: @pow2clk to review the PR and comment 26 | * [[0002] Specify the grammar formulations for attributes](https://github.com/microsoft/hlsl-specs/pull/65) 27 | * Action Item: @pow2clk to review. 28 | * [[SM6.8] Add proposal for DXIL 1.8](https://github.com/microsoft/hlsl-specs/pull/77) 29 | * This isn't really in a great shape, but it is useful documentation to not lose. 30 | * Action Item: @llvm-beanz to merge 31 | * [[dxil] Proposal to add new debug printf dxil op](https://github.com/microsoft/hlsl-specs/pull/324) 32 | * @pow2clk and @tex3d will review this in more detail. 33 | * [Rework hlsl-vector-type into two specs](https://github.com/microsoft/hlsl-specs/pull/361) 34 | * Action Item: @llvm-beanz to review. 35 | 36 | ### Current Business 37 | 38 | * [Add proposal for scalar layout for constant buffers](https://github.com/microsoft/hlsl-specs/pull/317) 39 | * Action Item: @llvm-beanz to review updates from AMD 40 | * [[202y] Propose adding C++11-style constructors](https://github.com/microsoft/hlsl-specs/pull/325) 41 | * Action Item: @farzonl & @V-FEXrt to review. 42 | * [[202x] Propose adding vk::SampledTexture* types](https://github.com/microsoft/hlsl-specs/pull/343) 43 | * Action Item: @llvm-beanz to review. 44 | * [Add resource chapter documenting buffers and bindings](https://github.com/microsoft/hlsl-specs/pull/344) 45 | * Action Item: @llvm-beanz to review. 46 | * [Specification language to describe flat conversions and aggregate splats](https://github.com/microsoft/hlsl-specs/pull/358) 47 | * The PR needs revision based on feedback, but one outstanding question is 48 | what do we name the cast? 49 | * @llvm-beanz: Flat doesn't describe what the conversion does 50 | * We had a lengthy discussion about @llvm-beanz's dislike of the "flat" term. 51 | * Alternatives suggested: elementwise conversion, reshape conversion 52 | * Action Item: @spall to update 53 | 54 | ## Other Discussion 55 | 56 | * Effects Syntax support in HLSL 202x 57 | * We have an issue to turn effects syntax usage into errors in HLSL 202x - [[202x] Remove HLSL Effects Syntax Support](https://github.com/microsoft/hlsl-specs/issues/380) 58 | * This will potentially cause some source breakage for codebases that are shared between DX 10/11 and DX 12. 59 | * There is at least one known case where DXC assumes valid C++11 syntax is an effects annotation 60 | ([C++-style initialization of vectors (int2 x{0,1}) does not work, but compiles](https://github.com/microsoft/DirectXShaderCompiler/issues/7111)). 61 | * Today, DXC ignores the effects annotation, which seems to users to be ignoring a valid intializer. 62 | * This syntax is C++11 initialization syntax that is not intended to be supported in DXC (which is C++98-based), but will be supported in Clang. 63 | * Proposed Solution: 64 | * In DXC: Make all effects syntax parsing errors in HLSL 202x mode. 65 | * In Clang: Make any effects-like syntax that is valid in modern C++ warn that it is a 202y extension. 66 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-02-18.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/02/18 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * No topics 15 | 16 | ## Issues 17 | * No marked issues 18 | * Action Item: @llvm-beanz to review issues for HLSL 202x 19 | 20 | ## PRs 21 | 22 | ### Carried Forward 23 | * [[0007] Big update to flesh out const instance methods](https://github.com/microsoft/hlsl-specs/pull/34) 24 | * Action Item: @pow2clk to review the PR and comment 25 | * [[0002] Specify the grammar formulations for attributes](https://github.com/microsoft/hlsl-specs/pull/65) 26 | * Action Item: @llvm-beanz to revise. 27 | * [[dxil] Proposal to add new debug printf dxil op](https://github.com/microsoft/hlsl-specs/pull/324) 28 | * @pow2clk and @tex3d will review this in more detail. 29 | * [[202x] Propose adding vk::SampledTexture* types](https://github.com/microsoft/hlsl-specs/pull/343) 30 | * Ready to merge. 31 | * [Specification language to describe flat conversions and aggregate splats](https://github.com/microsoft/hlsl-specs/pull/358) 32 | * Action Item: @spall to update 33 | 34 | ### Current Business 35 | 36 | * [Add proposal for scalar layout for constant buffers](https://github.com/microsoft/hlsl-specs/pull/317) 37 | * Call for consensus on consideration. 38 | * No objections, will be merged under-consideration once ready. 39 | * @llvm-beanz: There are details in the proposal that still need to be worked 40 | out, but I'm comfortable calling for acceptance and we can merge and iterate. 41 | * [Adding proposal for C++ constructors](https://github.com/microsoft/hlsl-specs/pull/325) 42 | * Call for consensus on consideration. 43 | * No objections, will be merged under-consideration once ready. 44 | * Carried forward - Action Item: @V-FEXrt to review. 45 | * @llvm-beanz: There are more details here that we should fully spec out like 46 | the required wider changes to object initialization. 47 | * [Update on 202x & 202y](https://github.com/microsoft/hlsl-specs/pull/391) 48 | 49 | ## Other Discussion 50 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-03-18.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/03/18 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * FYI: Updates coming to design meeting terms 15 | 16 | ## Issues 17 | * No marked issues 18 | 19 | ## PRs 20 | 21 | ### Carried Forward 22 | 23 | * [[0007] Big update to flesh out const instance methods](https://github.com/microsoft/hlsl-specs/pull/34) 24 | * Action Item: @pow2clk to review the PR and comment 25 | * Action Item: @V-FEXrt & @spall to review 26 | * [[0002] Specify the grammar formulations for attributes](https://github.com/microsoft/hlsl-specs/pull/65) 27 | * @llvm-beanz provided update, needs review. 28 | * Action Item: @V-FEXrt to review. 29 | * [[dxil] Proposal to add new debug printf dxil op](https://github.com/microsoft/hlsl-specs/pull/324) 30 | * @pow2clk and @tex3d will review this in more detail. 31 | * [[202x] Propose adding vk::SampledTexture* types](https://github.com/microsoft/hlsl-specs/pull/343) 32 | * Ready to merge. 33 | * [Specification language to describe flat conversions and aggregate splats](https://github.com/microsoft/hlsl-specs/pull/358) 34 | * @llvm-beanz provided feedback, need second review. 35 | * Action Item: @spall to update 36 | * Action Item: @V-FEXrt to review. 37 | * [Add proposal for scalar layout for constant buffers](https://github.com/microsoft/hlsl-specs/pull/317) 38 | * Action Item @llvm-beanz - Move to merge. 39 | * [Adding proposal for C++ constructors](https://github.com/microsoft/hlsl-specs/pull/325) 40 | * Carried forward - Action Item: @V-FEXrt to review. 41 | * Action Item @llvm-beanz - Move to merge. 42 | 43 | ### Current Business 44 | 45 | * [Update on 202x & 202y](https://github.com/microsoft/hlsl-specs/pull/391) 46 | * Request for reviews 47 | * [Introduce really rough linalg matrix proposal](https://github.com/microsoft/hlsl-specs/pull/404) 48 | * Request for reviews 49 | * [Rough proposal collecting thoughts on uniformity](https://github.com/microsoft/hlsl-specs/pull/405) 50 | * Request for reviews 51 | * [Constant buffers language spec - initial draft](https://github.com/microsoft/hlsl-specs/pull/419) 52 | * Action Item: @llvm-beanz to review 53 | * Action Item: @V-FEXrt to review. 54 | 55 | ### SM 6.9 56 | 57 | * [Long vector test plan](https://github.com/microsoft/hlsl-specs/pull/421) 58 | * [Cooperative Vectors Test Plan](https://github.com/microsoft/hlsl-specs/pull/428) 59 | * [[0029] Use consistent n-byte aligned notation](https://github.com/microsoft/hlsl-specs/pull/429) 60 | * Action Item: @damyanp to merge 61 | * [[0029] Clarify 16-byte underling allocation requirement](https://github.com/microsoft/hlsl-specs/pull/430) 62 | * Neds second review 63 | * [[0031] Preliminary draft of the HLSL changes for CoopVec](https://github.com/microsoft/hlsl-specs/pull/432) 64 | * Action Item: @llvm-beanz to review 65 | * [[0029] Fix some stale type names / typos in Coop Vec D3D API example](https://github.com/microsoft/hlsl-specs/pull/434) 66 | * Action Item: @damyanp to review 67 | 68 | 69 | ## Other Discussion 70 | 71 | * [Report on impact of overload resolution behavior](https://github.com/microsoft/hlsl-specs/pull/408) 72 | * [202x](https://github.com/microsoft/hlsl-specs/milestone/2) 73 | * [Deprecate and remove `interface` keyword](https://github.com/microsoft/hlsl-specs/issues/291) 74 | * [Deprecate existing `uniform` keyword usage ](https://github.com/microsoft/hlsl-specs/issues/135) 75 | * [Remove unsized arrays](https://github.com/microsoft/hlsl-specs/issues/141) 76 | * [Error on cbuffer variable initializer](https://github.com/microsoft/hlsl-specs/issues/259) 77 | * [static variable inside cbuffer are not marked const](https://github.com/microsoft/hlsl-specs/issues/351) 78 | * Action Item: @V-FEXrt to review. 79 | * [Remove HLSL Effects Syntax 80 | Support](https://github.com/microsoft/hlsl-specs/issues/380) 81 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-04-01.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/04/01 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * No updates 15 | 16 | ## Issues 17 | * No marked issues 18 | 19 | ## PRs 20 | 21 | ### Carried Forward 22 | 23 | * [[dxil] Proposal to add new debug printf dxil op](https://github.com/microsoft/hlsl-specs/pull/324) 24 | * @pow2clk and @tex3d will review this in more detail. 25 | * [[202x] Propose adding vk::SampledTexture* types](https://github.com/microsoft/hlsl-specs/pull/343) 26 | * Ready to merge. 27 | * [Specification language to describe flat conversions and aggregate splats](https://github.com/microsoft/hlsl-specs/pull/358) 28 | * Ready to merge. 29 | * [Add proposal for scalar layout for constant buffers](https://github.com/microsoft/hlsl-specs/pull/317) 30 | * Action Item @llvm-beanz - Move to merge. 31 | * [Introduce really rough linalg matrix proposal](https://github.com/microsoft/hlsl-specs/pull/404) 32 | * Request for extra eyes 33 | * Action Item: @llvm-beanz to update 34 | * [Rough proposal collecting thoughts on uniformity](https://github.com/microsoft/hlsl-specs/pull/405) 35 | * Request for reviews 36 | * Request for extra eyes 37 | * Action Item: @llvm-beanz to update 38 | * [Constant buffers language spec - initial draft](https://github.com/microsoft/hlsl-specs/pull/419) 39 | * Action Item: @llvm-beanz to review. 40 | * Action Item: @V-FEXrt to review. 41 | 42 | ### Current Business 43 | * [New Proposal: Draft proposal to modify resource typing in HLSL](https://github.com/microsoft/hlsl-specs/pull/461) 44 | * [[Decl.Init.Agg] Arrays of unknown size](https://github.com/microsoft/hlsl-specs/pull/469) 45 | 46 | ### SM 6.9 47 | 48 | * [Long vector test plan](https://github.com/microsoft/hlsl-specs/pull/421) 49 | * Action Item: @llvm-beanz to review. 50 | * [Cooperative Vectors Test Plan](https://github.com/microsoft/hlsl-specs/pull/428) 51 | * Action Item: @llvm-beanz to review. 52 | * [[0029] Clarify 16-byte underling allocation requirement](https://github.com/microsoft/hlsl-specs/pull/430) 53 | * Needs second review 54 | * **NEW** [[0031] Add MatrixRef, VectorRef, Vector, Mul, MulAdd, OuterProductAccumulate, VectorAccumulate](https://github.com/microsoft/hlsl-specs/pull/451) 55 | * **NEW** [[0029] Make outerproductaccumulate params consistent with other ops](https://github.com/microsoft/hlsl-specs/pull/465) 56 | * **NEW** [[0029] Rename optimal matrix layouts to match operations](https://github.com/microsoft/hlsl-specs/pull/468) 57 | * **NEW** [Add a DXIL 1.9 summary proposal](https://github.com/microsoft/hlsl-specs/pull/470) 58 | 59 | ## Other Discussion 60 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-04-15.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/04/15 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * No updates 15 | 16 | ## Issues 17 | * No marked issues 18 | 19 | ## PRs 20 | 21 | ### Carried Forward 22 | 23 | * [[dxil] Proposal to add new debug printf dxil op](https://github.com/microsoft/hlsl-specs/pull/324) 24 | * @pow2clk and @tex3d will review this in more detail. 25 | * [[202x] Propose adding vk::SampledTexture* types](https://github.com/microsoft/hlsl-specs/pull/343) 26 | * Ready to merge. 27 | * [Add proposal for scalar layout for constant buffers](https://github.com/microsoft/hlsl-specs/pull/317) 28 | * Action Item @llvm-beanz - Move to merge. 29 | * [Introduce really rough linalg matrix proposal](https://github.com/microsoft/hlsl-specs/pull/404) 30 | * Request for extra eyes 31 | * Action Item: @llvm-beanz to merge 32 | * [Rough proposal collecting thoughts on uniformity](https://github.com/microsoft/hlsl-specs/pull/405) 33 | * Request for reviews 34 | * Request for extra eyes 35 | * Action Item: @llvm-beanz to update 36 | * [Constant buffers language spec - initial draft](https://github.com/microsoft/hlsl-specs/pull/419) 37 | * What is the correct relationship between `cbuffer` and `namespace`? 38 | * [Some fun cbuffer examples](https://godbolt.org/z/GcKes6Eeh) 39 | 40 | ### Current Business 41 | * [New Proposal: Draft proposal to modify resource typing in HLSL](https://github.com/microsoft/hlsl-specs/pull/461) 42 | * [[Decl.Init.Agg] Arrays of unknown size](https://github.com/microsoft/hlsl-specs/pull/469) 43 | * [Add an initial proposal for HLSL 202x deprecations](https://github.com/microsoft/hlsl-specs/pull/488) 44 | 45 | ### SM 6.9 46 | 47 | * [Long vector test plan](https://github.com/microsoft/hlsl-specs/pull/421) 48 | * [Cooperative Vectors Test Plan](https://github.com/microsoft/hlsl-specs/pull/428) 49 | * [[0029] Update example code to use real API](https://github.com/microsoft/hlsl-specs/pull/472) 50 | * [[0030][SM6.9] Add list of ops with vector overload](https://github.com/microsoft/hlsl-specs/pull/481) 51 | * [[0029] Make "input signed op kind"s be "is input unsigned" and booleans](https://github.com/microsoft/hlsl-specs/pull/483) 52 | * [[0027] Avoid using undef for dx.op.MaybeReorderThread](https://github.com/microsoft/hlsl-specs/pull/487) 53 | * [Cooperative vectors API proposal](https://github.com/microsoft/hlsl-specs/blob/main/proposals/0031-hlsl-vector-matrix-operations.md) 54 | * Please review and provide feedback! 55 | 56 | ## Other Discussion 57 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/2025-04-29.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: 2025/04/29 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | 13 | ## Administrivia 14 | * No updates 15 | 16 | ## Issues 17 | * No marked issues 18 | 19 | ## PRs 20 | 21 | ### Carried Forward 22 | 23 | * [[dxil] Proposal to add new debug printf dxil op](https://github.com/microsoft/hlsl-specs/pull/324) 24 | * @pow2clk and @tex3d will review this in more detail. 25 | * [[202x] Propose adding vk::SampledTexture* types](https://github.com/microsoft/hlsl-specs/pull/343) 26 | * Ready to merge. 27 | * [Add proposal for scalar layout for constant buffers](https://github.com/microsoft/hlsl-specs/pull/317) 28 | * Action Item @llvm-beanz - Move to merge. 29 | * [Introduce really rough linalg matrix proposal](https://github.com/microsoft/hlsl-specs/pull/404) 30 | * Action Item: @llvm-beanz to merge 31 | * [Rough proposal collecting thoughts on uniformity](https://github.com/microsoft/hlsl-specs/pull/405) 32 | * Action Item: @llvm-beanz to update 33 | * [New Proposal: Draft proposal to modify resource typing in HLSL](https://github.com/microsoft/hlsl-specs/pull/461) 34 | * Action item: @llvm-beanz to work with author 35 | 36 | ### Current Business 37 | * [[Decl.Init.Agg] Arrays of unknown size](https://github.com/microsoft/hlsl-specs/pull/469) 38 | * Ready for review 39 | * [Add an initial proposal for HLSL 202x deprecations](https://github.com/microsoft/hlsl-specs/pull/488) 40 | * Why isn't `uniform` propagated to DXIL? 41 | * @llvm-beanz: I don't actually know the history. DXC has never done anything with the keyword and we don't have a representation in DXIL. 42 | * We do have a larger proposal to address [uniformity](https://github.com/microsoft/hlsl-specs/pull/405) 43 | * We should also consider if that proposal needs DXIL and SPIRV changes to preserve information for the backends. 44 | * ISVs represented in the room did not express any immediate concerns about these deprecations. 45 | * Constant Buffers! 46 | * [Constant buffers language spec - initial draft](https://github.com/microsoft/hlsl-specs/pull/419) 47 | * [Constant Buffer Contexts](https://github.com/microsoft/hlsl-specs/pull/497) 48 | * What is the correct relationship between `cbuffer` and `namespace`? 49 | * [Some fun cbuffer examples](https://godbolt.org/z/GcKes6Eeh) 50 | * We would like to undesrstand the impact of this change on existing shader codebases. 51 | * ISVs represented in the room did not express any immediate concerns. 52 | 53 | ### SM 6.9 54 | 55 | * [Long vector test plan](https://github.com/microsoft/hlsl-specs/pull/421) 56 | * [Cooperative Vectors Test Plan](https://github.com/microsoft/hlsl-specs/pull/428) 57 | * [[0029] Update example code to use real API](https://github.com/microsoft/hlsl-specs/pull/472) 58 | * [[0030][SM6.9] Add list of ops with vector overload](https://github.com/microsoft/hlsl-specs/pull/481) 59 | * [[0029] Make "input signed op kind"s be "is input unsigned" and booleans](https://github.com/microsoft/hlsl-specs/pull/483) 60 | * [[0027] Avoid using undef for dx.op.MaybeReorderThread](https://github.com/microsoft/hlsl-specs/pull/487) 61 | 62 | ## Other Discussion 63 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/Template.md: -------------------------------------------------------------------------------- 1 | # Design Meeting Minutes: YYYY/MM/DD 2 | 3 | > NOTE: Please read the [terms of participation](DesignMeetingTerms.txt) 4 | > ("Terms") prior to joining the Teams meeting. You joining the Teams meeting 5 | > with Microsoft indicates your acknowledgement, agreement, and consent to these 6 | > Terms. If you do not agree to these Terms, please do not join the meeting. 7 | > 8 | > If you intend to contribute code or other copyrightable materials (e.g. 9 | > written comments, tools, documentation, etc.) to the hlsl specs repository, 10 | > you are required to sign a Contributor License Agreement (CLA). For details, 11 | > visit https://cla.microsoft.com. 12 | -------------------------------------------------------------------------------- /docs/DesignMeetingMinutes/index.md: -------------------------------------------------------------------------------- 1 | # Meeting Minute Index 2 | 3 | {% assign doclist = site.pages | sort: 'url' %} 4 | {% for doc in doclist %} 5 | {% if doc.name contains '.md' and doc.dir == '/docs/DesignMeetingMinutes/' and doc.name != 'index.md' %} 6 | * [{{ doc.name }}]({{ doc.url | relative_url }}) 7 | {% endif %} 8 | {% endfor %} 9 | -------------------------------------------------------------------------------- /docs/DesignMeetingTerms.txt: -------------------------------------------------------------------------------- 1 | NOTE: Please read the following terms of participation ("Terms") prior to 2 | joining the Teams meeting. You joining the Teams meeting with Microsoft 3 | indicates your acknowledgement, agreement, and consent to these Terms. If you 4 | do not agree to these Terms, please do not join the meeting. 5 | 6 | 1. **Your Consent.** You, as the participant in the Teams meeting hosted by 7 | Microsoft ("You") that provides these Terms as part of the meeting invitation, 8 | must read and agree to these Terms prior to joining and/or participating in the 9 | Teams meeting hosted by Microsoft ("Meeting"). By joining the Meeting, You 10 | consent to these Terms. 11 | 12 | 13 | 2. **Definitions.** 14 | 15 | * "Code" means any computer software code, whether in human-readable or 16 | machine-executable form, that is delivered by You to Microsoft. 17 | 18 | * "Input" means all written or verbal suggestions, comments, feedback, ideas, or 19 | know-how, that You provide to Microsoft during or relating to a Meeting. 20 | 21 | * "Materials" means any documentation, reports, tools, or other copyrighted 22 | materials that have relevance to a Meeting. 23 | 24 | 25 | 3. **Scope.** These Terms cover any and all Input that You provide, now or in 26 | the future, at any time, related to the Meeting subject matter. Any Code or 27 | Materials that you want to submit to Microsoft must be submitted via the 28 | Microsoft Contribution License Agreement. For details, visit 29 | https://cla.microsoft.com. 30 | 31 | 32 | 4. **Your Employer.** References to "employer" in these Terms include Your 33 | employer or anyone else for whom You are acting in providing your Input, e.g. as 34 | a contractor, vendor, or agent. If Your Input is provided in the course of Your 35 | work for an employer You must be authorized by the scope of your work, or secure 36 | permission from Your employer, to provide Input before consenting to these Terms 37 | by joining a Meeting. In that case, the term "You" or "Your" in these Terms will 38 | refer to You and the employer collectively. 39 | 40 | 41 | 5. **License grants.** You grant to Microsoft under all of Your applicable 42 | intellectual property rights, a nonexclusive, perpetual, irrevocable, 43 | royalty-free, worldwide right and license in the Input to modify, reproduce, 44 | create derivative works, test, display, perform, distribute, support, copy, 45 | make, have made, use, offer to sell, sell and import, and otherwise dispose of 46 | the Input, and to sublicense any or all of the foregoing rights to 47 | third-parties. 48 | 49 | 50 | 6. **Representations and Warranties.** You represent that You are legally 51 | entitled to provide Input according to these Terms and grant the licenses in 52 | Section 5. If You are joining this meeting on behalf of Your employer, You 53 | represent and warrant that You have the necessary authority to bind Your 54 | employer to the obligations contained in these Terms. UNLESS REQUIRED BY 55 | APPLICABLE LAW OR AGREED TO IN WRITING, AND EXCEPT FOR THE WARRANTIES EXPRESSLY 56 | STATED IN THESE TERMS, THE INPUT PROVIDED UNDER THESE TERMS IS PROVIDED WITHOUT 57 | WARRANTY OF ANY KIND, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY OF 58 | NONINFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. 59 | 60 | 61 | 7. **Notice to Microsoft.** You agree to notify Microsoft in writing of any 62 | facts or circumstances of which You later become aware that would make Your 63 | representations in these Terms inaccurate in any respect. 64 | 65 | 66 | 8. **Maintenance and Disclosure.** You agree that Input provided may be 67 | maintained indefinitely and disclosed publicly. 68 | 69 | 70 | 9. **Governing Law/Jurisdiction.** These Terms are governed by the laws of the 71 | State of Washington, and the parties consent to exclusive jurisdiction and venue 72 | in the federal courts sitting in King County, Washington, unless no federal 73 | subject matter jurisdiction exists, in which case the parties consent to 74 | exclusive jurisdiction and venue in the Superior Court of King County, 75 | Washington. The parties waive all defenses of lack of personal jurisdiction and 76 | forum non-conveniens. 77 | 78 | 79 | 10. **Entire Agreement/Assignment.** These Terms are the entire agreement 80 | between the parties, and supersedes any and all prior agreements, understandings 81 | or communications, written or oral, between the parties relating to the subject 82 | matter hereof. 83 | -------------------------------------------------------------------------------- /docs/HLSL202x.md: -------------------------------------------------------------------------------- 1 | # HLSL 202x 2 | 3 | HLSL 202x is the working name for the language version that will succeed HLSL 4 | 2021. 5 | 6 | The primary goal of HLSL 202x is to make the language more regular, more 7 | consistent with C++, and to codify language behaviors in a describable and 8 | understandable way for users. 9 | 10 | The proposed features for HLSL 202x are a combination of new features for the 11 | language to improve compatibility with C++, and the removal of old features 12 | which caused inconsistency. 13 | 14 | As a secondary goal, HLSL 202x strives to make language behaviors more regular 15 | to aid in a long term goal of producing a formal language specification. 16 | -------------------------------------------------------------------------------- /docs/Process.md: -------------------------------------------------------------------------------- 1 | # Proposal Process 2 | 3 | The primary purpose of this repository is to provide visibility into the feature 4 | development process for HLSL and solicit feedback from the wider community. 5 | Despite the openness of this process there are two significant caveats that 6 | should be noted: 7 | 8 | 1. Final decisions about what features are included or excluded from HLSL are 9 | made by the MSFT HLSL Team. Our goals are to make HLSL the best programming 10 | language across all supported runtime targets, not just DirectX or Vulkan. 11 | 2. Some HLSL features may instead go through a 12 | 13 | [Fast-track](#fast-track-for-extensions) process. This process is reserved 14 | for platform and vendor extensions and is not suitable to all features. 15 | 16 | Feature proposals from outside the HLSL team will be interpreted as requests, 17 | and may be considered or rejected based on team and release priorities. You 18 | should not create a pull request against this repository if you're not committed 19 | to at least making a best effort to navigate the process as described below. 20 | 21 | If you want to request a feature but not get involved in the process, the best 22 | way to request features for HLSL is to file GitHub issues rather than creating 23 | pull requests against this repository. 24 | 25 | This process draws heavily from 26 | [Rust's RFC process](https://github.com/rust-lang/rfcs), and from 27 | [Swift's Evolution process](https://github.com/apple/swift-evolution/), and is 28 | further tweaked to align with the HLSL team's goals and priorities. 29 | 30 | Significant project infrastructure or implementation details will also use this 31 | process to refine and document the design process. 32 | 33 | ## Making a Proposal 34 | 35 | The best way for an external contributor to propose a feature is through GitHub 36 | issues (See the section below on "Filing Issues"). 37 | 38 | If you write a proposal yourself you must find a member of the HLSL team to act 39 | as a _Sponsor_ for the change. The _Sponsor_ is responsible for tracking and 40 | helping change proposals through the proposal life cycle. For Vulkan-specific 41 | features we require at least one _Sponsor_ from the HLSL team and one _Sponsor_ 42 | from the Khronos Vulkan Working Group. If you need assistance finding a 43 | _Sponsor_ for a proposal reach out to the [HLSL Team](Contact.md). 44 | 45 | All feature proposals are evaluated against the goals for the next HLSL language 46 | revision. The goals for the upcoming HLSL language version can be found 47 | [here](HLSL202x.md). 48 | 49 | When writing a feature proposal you should also familiarize yourself with the 50 | HLSL [Design Considerations](DesignConsiderations.md). 51 | 52 | ## Proposal Lifecycle 53 | 54 | Draft proposals are first provided as pull requests. They should be written 55 | following one of the templates in the `proposals/templates` directory. 56 | 57 | Add new proposals for language or runtime features directly in the `proposals` 58 | directory. Add new proposals for project infrastructure or implementation 59 | details of the compilers in the `proposals/infra` directory. 60 | 61 | Proposals that follow the most simplified path from idea to feature will move 62 | through the following states in order: 63 | 64 | * **Under Consideration** - All proposed features start in this state. While 65 | under consideration features are reviewed by members of the HLSL team and 66 | feedback is solicited from users and hardware vendors. 67 | 68 | * **Under Review** - If a feature is deemed to be in alignment with the release 69 | goals, and of value to the community a feature may be promoted to being under 70 | review. During this time, a feature specification must be drafted, revised, 71 | and accepted. 72 | 73 | * **Accepted** - Once a feature is accepted it becomes a planned feature for the 74 | release. At this time changes to enable the feature under the new language 75 | mode can begin landing in the HLSL compiler. The Accepted state does not mean 76 | the feature will ship in the planned release. There are a variety of reasons 77 | why features may not make the final release, but it does signify an intent to 78 | bring the feature into the release. 79 | 80 | * **Completed** - Once a feature is fully implemented in the main compiler 81 | branch under the appropriate language version, the proposal completed. 82 | 83 | Additionally feature proposals may end up in the **Rejected** or **Deferred** 84 | states. 85 | 86 | **Rejected** features are features that will not be included in HLSL. All 87 | rejected features will be appended with a detailed reasoning explaining the 88 | rationale behind why the feature was rejected. 89 | 90 | **Deferred** features can occur for a variety of reasons. Features that are 91 | deferred may be provided with some justification for the deferral although the 92 | requirements for justification are not high and could be as simple as 93 | "insufficient resources". 94 | 95 | ### Differences for Infrastructure Proposals 96 | 97 | Infrastructure proposals may skip the **Under Review** phase and go straight 98 | from **Under Consideration** to **Accepted**. This flow is expected in cases 99 | where the proposal does not impact end users, and may garner little to no 100 | feedback from outside the core developers. 101 | 102 | In cases where contributions are being made to the LLVM-Project, the **Under 103 | Review** phase may be useful for communicating when a proposal has been posted 104 | as an RFC to [LLVM's Discourse](https://discourse.llvm.org/). In this case the 105 | proposal header should be updated to include a link to the Discord post. 106 | 107 | ### Moving Through States 108 | 109 | #### Merging a New Proposal 110 | 111 | The bar for a proposal to be merged should be kept low. Ideally a PR introducing 112 | a new proposal should be reviewed for obvious mistakes (typos, grammar, etc), 113 | and general alignment with project goals and direction. If the proposal aligns 114 | with the goals and direction, it should be merged as **Under Consideration**, 115 | and the authors should file issues tracking the work to flesh out and complete 116 | the detailed design. 117 | 118 | #### Completing the Detailed Design 119 | 120 | As the proposal authors and sponsors work through issues with the proposal and 121 | flesh out a complete design each change to the proposal will be reviewed. 122 | 123 | #### Final Review 124 | 125 | Once the authors and sponsors feel that all outstanding issues are resolved a 126 | sponsor will file an issue to propose a review period, and create a PR to mark 127 | the proposal as **Under Review**. 128 | 129 | During the review period the sponsor will reach out to stakeholders (users, 130 | partners, etc) to collect feedback about the proposal. Any issues that need to 131 | be addressed will be filed and tracked. 132 | 133 | If there are outstanding issues at the end of the scheduled review period, the 134 | review period will be extended by one week. The extensions will continue 135 | week-by-week until all outstanding issues are addressed. 136 | 137 | #### Accepting a Proposal 138 | 139 | After the review period concludes and all outstanding issues are addressed, a 140 | sponsor will create a PR to mark the proposal as **Accepted**, at which time we 141 | will accept PRs to begin implementation. 142 | 143 | #### Implementation 144 | 145 | During implementation a proposal may need to further evolve as the implementors 146 | discover issues. Those issues will be addressed with PRs to the proposal and 147 | reviewed. 148 | 149 | Once the implementation is complete and all associated issues are resolved, a 150 | sponsor will create a PR to mark the proposal as **Completed**. 151 | 152 | ## Filing Issues 153 | 154 | Issues in this repository publicly tracks feature requests for the HLSL language 155 | and HLSL runtime interfaces as well as issues with proposals and specifications 156 | contained within the repository. 157 | 158 | Please direct tooling feature requests to the 159 | [DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/issues/new), 160 | or [Clang](https://github.com/llvm/llvm-project/issues/new) as appropriate. 161 | 162 | > Note: a tooling feature would be a feature that does not impact HLSL source 163 | > representations in any way (no added syntax, APIs, or altered 164 | > interpretations), and instead exposes new ways to use the DXC compiler or 165 | > library. 166 | 167 | This repository provides three custom issue templates: 168 | 169 | 1. Feature Request 170 | 2. Proposal 171 | 3. Spec 172 | 173 | When filing feature requests please use the _Feature Request_ template. The more 174 | detailed information you can provide in a feature request the easier it is for 175 | our team to scope, prioritize, design and implement the requested feature. 176 | 177 | When filing issues relating to a currently in-progress proposal (i.e. any proposal not 178 | **Completed** or **Rejected**), use the _Proposal Follow-up_ template. 179 | 180 | When filing issues relating to a completed feature or specification document 181 | please use the _Spec_ template. 182 | 183 | ## Fast-Track for Extensions 184 | 185 | Some features for HLSL expose new hardware capabilities and require years of 186 | development before they can be made public. For these features we have a 187 | fast-track process to incorporate platform-specific and vendor-specific 188 | extensions to HLSL as long as they are _conforming extensions_. Extension 189 | proposals should use the [Extension 190 | Template](/proposals/templates/extension-template.md). 191 | 192 | ### Conforming Extensions 193 | 194 | Conforming extensions are language features which do not add new language 195 | behavior or syntax. They cannot remove or deprecate functionality, and they 196 | cannot be breaking changes. They can add new builtin function declarations, 197 | builtin data types, and attributes as long as the added features do not change 198 | the rules of the language. All added declarations must be under a namespace, and 199 | cannot be under the `hlsl`, `std` or global namespaces which are reserved for 200 | core language features. 201 | 202 | #### Extension Attribute Restrictions 203 | 204 | Additionally there are limitations specifically for attributes. Added attributes 205 | may not modify canonical types, or otherwise change how HLSL code is 206 | interpreted. They can compile down to metadata that produces annotations, and 207 | they can be used for analysis and verification. Adding attributes that change 208 | language behavior must be done through the full review process. As some concrete 209 | examples: 210 | 211 | * Type attributes like `precise` and `groupshared` _can not_ be added as 212 | extension attributes, because they (1) modify underlying canonical types, and 213 | (2) are not namespaced. 214 | * Type attributes like `[vk::ext_reference]` _can not_ be added as extension 215 | attributes, because it modifies the underlying canonical type. 216 | * Parameter attributes like `[vk::ext_literal]` _can_ be added as an extension 217 | attribute, because it does not modify the type or behavior of the language it 218 | just annotates a declaration for additional verification. 219 | * Entry attributes like `[NodeIsProgramEntry]` _can not_ be added as an extension 220 | attribute, because it is not namespaced. If instead it were spelled 221 | `[dx::NodeIsProgramEntry]` it would comply since it does not modify the code 222 | generation of the function it only changes generated metadata. 223 | 224 | ### Fast-Track Process 225 | 226 | Features that meet the definition of a conforming extension can be merged 227 | directly as **Accepted** features with only a PR review. During that review a 228 | feature will only be rejected if it does not meet the restrictions of a 229 | conforming extension, in which case it will need to either be revised to meet 230 | that definition or go through the full review process. 231 | 232 | ### Extension Deprecation Process 233 | 234 | If a significant number of user bugs arise with an extension and the platform or 235 | vendor who contributed the feature abandons maintenance and no other party takes 236 | up the maintenance an extension may be deprecated and removed following a 237 | deprecation period of no less than 6 months. 238 | 239 | Decisions to deprecate an extension will not be taken lightly, however carrying 240 | broken features in the compiler will cause more harm to users than good. 241 | -------------------------------------------------------------------------------- /proposals/0001-hlsl-namespace.md: -------------------------------------------------------------------------------- 1 | # HLSL Namespace 2 | 3 | * Proposal: [0001](0001-hlsl-namespace.md) 4 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 5 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Status: **Under Consideration** 7 | * Planned Version: 202y 8 | 9 | ## Introduction 10 | 11 | Following conventions of other languages HLSL data types should be moved into a 12 | namespace so that they can be disambiguated. 13 | 14 | ## Motivation 15 | 16 | As HLSL is evolving to be more source compatible with C++, some HLSL names will 17 | begin to conflict with C++ names which mean very different things (i.e. 18 | `vector`) and other names which have subtly different usage (i.e. `sin` vs 19 | `sinf`). Moving HLSL library functionality into a namespace removes the 20 | ambiguity and will prevent common errors in the future as HLSL becomes more 21 | C++-like. 22 | 23 | We have also received requests in the past to allow developers to 24 | define their own versions of built-in functions. Moving the built-in versions 25 | into a namespace will enable this use case as well. 26 | 27 | ## Proposed solution 28 | 29 | Each HLSL data type and builtin function will be moved from global scope to the 30 | `hlsl` namespace. This can be implemented in the AST construction, HLSL headers, 31 | and other lookup hooks. This would apply to all built in types (`vector`, 32 | `matrix`, `Texture`, `Buffer`, etc), as well as to their typedefs (`float3`, 33 | `float3x3`, etc), and to all builtin functions (`DeviceMemoryBarrier`, 34 | `WaveIsFirstLane`, etc) including math operations (`abs`, `sin`, etc). 35 | -------------------------------------------------------------------------------- /proposals/0002-assets/AttributeGrammarRender.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/hlsl-specs/36ac9489c3d95e7a7cd5c4a732ef689c09e589a9/proposals/0002-assets/AttributeGrammarRender.png -------------------------------------------------------------------------------- /proposals/0002-assets/ClassGrammarRender.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/hlsl-specs/36ac9489c3d95e7a7cd5c4a732ef689c09e589a9/proposals/0002-assets/ClassGrammarRender.png -------------------------------------------------------------------------------- /proposals/0002-assets/StatementGrammarRender.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/hlsl-specs/36ac9489c3d95e7a7cd5c4a732ef689c09e589a9/proposals/0002-assets/StatementGrammarRender.png -------------------------------------------------------------------------------- /proposals/0002-cxx-attributes.md: -------------------------------------------------------------------------------- 1 | 2 | # C++ Attributes 3 | 4 | * Proposal: [0002](0002-cxx-attributes.md) 5 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 7 | * Status: **Under Consideration** 8 | * Planned Version: 202y 9 | 10 | ## Introduction 11 | 12 | The C++ 11 ISO standard introduced a standard syntax for attribute annotations 13 | which is grammatically unambiguous when annotating a wide variety of language 14 | elements. This syntax has become common, recognized and well known, and is an 15 | ideal addition to HLSL. 16 | 17 | ## Motivation 18 | 19 | HLSL has two syntaxes for specifying source annotations. One, the 20 | Microsoft-style C Attribute syntax, which uses single brackets `[]` to enclose 21 | an attribute and it's arguments: 22 | 23 | ```c++ 24 | [WaveOpsIncludeHelperLanes] 25 | [shader("compute")] 26 | [numthreads(1,1,1)] 27 | ``` 28 | 29 | The second, the HLSL annotation syntax, which annotates variable, field and 30 | parameter declarations using a `:` to separate the name from the specifier: 31 | 32 | ```c++ 33 | SamplerState samp1 : register(s5); 34 | Texture2D text1 : register(t3); 35 | 36 | float4 main(float2 a : A) : SV_Target { 37 | ... 38 | } 39 | ``` 40 | 41 | The existing syntaxes in HLSL have limitations. With the introduction of 42 | bitfields in HLSL 2021, HLSL semantic syntax on members of a struct or class is 43 | syntactically ambiguous with bitfields. Take the following code example: 44 | 45 | ```c++ 46 | struct { 47 | uint i : SV_RenderTargetArrayIndex; 48 | } 49 | ``` 50 | 51 | In this case the syntax is ambiguous with a bitfield declaration, on 52 | encountering the `:` token the parser must look ahead to see if the next 53 | token is a semantic identifier or an integer constant. 54 | 55 | This case is further ambiguous with user-specified semantics where the following 56 | code is ambiguous and currently _not_ interpreted as a bitfield declaration: 57 | 58 | ```c++ 59 | static int Foo = 1; 60 | struct { 61 | uint i : Foo; 62 | } 63 | ``` 64 | 65 | If we wish to add source annotations to more grammatical elements in the future 66 | we will encounter more ambiguities because the `:` character has other meanings 67 | in C and modern C++ as well. to name a few examples: the ternary operator 68 | (`condition ? a : b`), range-based for syntax (`for (variable : collection)`), 69 | and switch label marking (`case 1:`). 70 | 71 | We will also encounter ambiguities with the `[]` syntax. We may encounter issues 72 | with array indexing which valid in contexts where we may wish to annotate 73 | sources in the future. In the future this ambiguity could grow if we incorporate 74 | more C++ features, like lambdas. 75 | 76 | ## Proposed solution 77 | 78 | Adopting C++ attributes enables an unambiguous annotation syntax for all the 79 | cases where HLSL annotations are supported. Using C++11 attributes the example 80 | above can be written as: 81 | 82 | ```c++ 83 | struct { 84 | uint i [[hlsl::SV_RenderTargetArrayIndex]]; 85 | } 86 | ``` 87 | 88 | Which has no syntactic ambiguity. As in the example above, C++ attributes can 89 | also be namespaced, which allows for a clearer delineation of the attribute's 90 | applicability. C++ defines that namespaced attributes not supported by the 91 | compiler can be ignored. This enables more robust code sharing in codebases that 92 | contain both C++ and HLSL. 93 | 94 | Additionally, introducing C++ 11 attributes enables placing attributes on more 95 | grammatical constructs in the language. C++ 11 attributes can be applied to 96 | statements, declarations and expressions. 97 | 98 | Below are a few more examples of C++ attributes that we could support: 99 | 100 | ```c++ 101 | struct [[hlsl::layout_attribute]] { // applies to the struct type 102 | int x; 103 | int y; 104 | }; 105 | 106 | Texture2D Tex [[hlsl::register(1, 0)]]; // applies to `Tex`; 107 | 108 | uint i [[hlsl::SV_RenderTargetArrayIndex]]; // applies to `i`. 109 | [[hlsl::SV_RenderTargetArrayIndex]] uint j; // applies to `j`. 110 | uint &[[hlsl::AddressSpace(1)]] Ref = ...; // applies to the type `uint &`. 111 | 112 | [[hlsl::SV_Target]] // applies to the function `fn`. 113 | float3 fn( ) { 114 | [[hlsl::fast]] // applies to the compound expression `{...}`. 115 | { 116 | ... 117 | } 118 | float f = [[hlsl::strict]](1.0 * 2.0); // applies to the parenthesis expression `(...)`. 119 | 120 | [[hlsl::unroll]] // applies to the for-loop expression. 121 | for (int x = 0; x < 10; ++x) { 122 | ... 123 | } 124 | } 125 | ``` 126 | 127 | ## Detailed design 128 | 129 | The simplest explanation of this feature is supporting C++11 attribute syntax on 130 | all shared grammar elements between HLSL and C++. This spec attempts to detail 131 | some of the grammar and parsing implications and will specify the process by 132 | which existing attributes will convert to C++ attributes. 133 | 134 | ### Attribute Parsing 135 | 136 | This proposal introduces grammar formulations for parsing attributes matching 137 | some formulations from C++ `dcl.attr.grammar`. Specifically: 138 | 139 | ```latex 140 | \begin{grammar} 141 | \define{attribute-specifier-seq}\br 142 | \opt{attribute-specifier-seq} \textit{attribute-specifier}\br 143 | 144 | \define{attribute-specifier}\br 145 | \terminal{[ [} \textit{attribute-list} \terminal{] ]}\br 146 | 147 | \define{attribute-list}\br 148 | \opt{attribute}\br 149 | \textit{attribute-list} \terminal{,} \opt{attribute}\br 150 | 151 | \define{attribute}\br 152 | \textit{attribute-token} \opt{attribute-argument-clause}\br 153 | 154 | \define{attribute-token}\br 155 | \textit{identifier}\br 156 | \textit{attribute-scoped-token}\br 157 | 158 | \define{attribute-scoped-token}\br 159 | \textit{attribute-namespace} \terminal{::} \textit{identifier}\br 160 | 161 | \define{attribute-namespace}\br 162 | \textit{identifier}\br 163 | 164 | \define{attribute-argument-clause}\br 165 | \terminal{(} \textit{balanced-token-seq} \terminal{)}\br 166 | 167 | \define{balanced-token-seq}\br 168 | \opt{balanced-token}\br 169 | \textit{balanced-token-seq} \textit{balanced-token}\br 170 | 171 | \define{balanced-token}\br 172 | \terminal{(} \textit{balanced-token-seq} \terminal{)}\br 173 | \terminal{[} \textit{balanced-token-seq} \terminal{]}\br 174 | \terminal{\{} \textit{balanced-token-seq} \terminal{\}}\br 175 | any token other than a parenthesis, bracket or brace\br 176 | \end{grammar} 177 | ``` 178 | ![Latex Rendering](0002-assets/AttributeGrammarRender.png) 179 | 180 | In contrast to existing HLSL annotations and Microsoft-style attributes, these 181 | formulations use case-sensitive identifier tokens 182 | 183 | 184 | #### Statements 185 | 186 | > Note: This is already reflected in the language specification. 187 | 188 | ```latex 189 | \begin{grammar} 190 | \define{statement}\br 191 | labeled-statement\br 192 | \opt{attribute-specifier-sequence} expression-statement\br 193 | \opt{attribute-specifier-sequence} compound-statement\br 194 | \opt{attribute-specifier-sequence} iteration-statement\br 195 | \opt{attribute-specifier-sequence} selection-statement\br 196 | declaration-statement 197 | \end{grammar} 198 | ``` 199 | ![Latex Rendering](0002-assets/StatementGrammarRender.png) 200 | 201 | #### Declarations 202 | 203 | The `attribute-specifier-seq` element supports annotating type declarations. The 204 | following grammar formulations are valid: 205 | 206 | ```latex 207 | \begin{grammar} 208 | \define{class-name}\br 209 | \textit{identifier}\br 210 | \textit{simple-template-id}\br 211 | 212 | \define{class-specifier}\br 213 | \textit{class-head} \terminal{\{} \opt{member-specification} \terminal{\}}\br 214 | 215 | 216 | \define{class-head}\br 217 | \textit{class-key} \opt{attribute-specifier-seq} \textit{class-head-name} \opt{base-clause}\br 218 | \textit{class-key} \opt{attribute-specifier-seq} \opt{base-clause}\br 219 | 220 | \define{class-head-name}\br 221 | \opt{nested-name-specifier} \textit{class-name}\br 222 | 223 | \define{class-key}\br 224 | \terminal{class}\br 225 | \terminal{struct}\br 226 | 227 | \define{alias-declaration}\br 228 | \terminal{using} \textit{identifier} \opt{attribute-specifier-seq} \terminal{=} \textit{type-id} \terminal{;}\br 229 | \end{grammar} 230 | ``` 231 | 232 | ![Latex Rendering](0002-assets/ClassGrammarRender.png) 233 | 234 | 235 | -------------------------------------------------------------------------------- /proposals/0003-numeric-constants.md: -------------------------------------------------------------------------------- 1 | # Numeric Constants 2 | 3 | * Proposal: [0003](0003-numeric-constants.md) 4 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 5 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Status: **Under Consideration** 7 | * Planned Version: 202x 8 | 9 | ## Introduction 10 | 11 | A new C++ STL-styled numeric constants interface will enable migrating off older 12 | inconsistent language features and make cleaner more concise code. 13 | 14 | ## Motivation 15 | 16 | The HLSL Infinity constant syntax violates C token rules by using the `#` 17 | character, and is not consistent with C or C++ language styling. This causes 18 | technical challenges by using reserved preprocessor tokens, but also makes the 19 | feature foreign and less approachable in a C-like language. 20 | 21 | ## Proposed solution 22 | 23 | Starting with adoption the `#INF` token becomes unsupported preferring instead a 24 | new library class modeled after the C++ `std::numeric_limits` classes. Below is 25 | the proposed interface for the `hlsl::numeric_limits` class: 26 | 27 | ```c++ 28 | template 29 | class numeric_limits { 30 | public: 31 | static Ty min(); 32 | static Ty max(); 33 | static Ty lowest(); 34 | static Ty denorm_min(); 35 | 36 | // Implement infinity in terms of __builtin_huge_val 37 | static Ty infinity(); 38 | static Ty negative_infinity(); 39 | 40 | static Ty quiet_NaN(); 41 | static Ty signaling_NaN(); 42 | } 43 | ``` 44 | 45 | This enables a straightforward code transformation from `1.#INF` to 46 | `hlsl::numeric_limits::infinity()`. While the later is more verbose, it 47 | is more clear and provides a more consistent C++ style. 48 | -------------------------------------------------------------------------------- /proposals/0004-unions.md: -------------------------------------------------------------------------------- 1 | # Unions 2 | 3 | * Proposal: [0004](0004-unions.md) 4 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 5 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Status: **Under Consideration** 7 | * Planned Version: 202y 8 | 9 | ## Introduction 10 | 11 | Introduce C++ Union data types into HLSL. 12 | 13 | ## Motivation 14 | 15 | Unions in C++ are used in a wide array of cases. 16 | 17 | One common case is when the layout of data matches between two data types and 18 | the user wants to be able to access the data interchangeably as the two types. 19 | This is frequently used in C++ SIMD code in conjunction with anonymous data 20 | structures to implement vector objects. For example: 21 | 22 | ``` 23 | struct vector { 24 | union { 25 | struct { 26 | float x; 27 | float y; 28 | float z; 29 | float w; 30 | }; 31 | struct { 32 | float r; 33 | float g; 34 | float b; 35 | float a; 36 | }; 37 | float f[4]; 38 | }; 39 | }; 40 | ``` 41 | 42 | Additionally, unions are often used to reduce the storage requirements when a 43 | data structure may contain one of a exclusive set of objects. The example below 44 | is a common tagged union: 45 | 46 | ``` 47 | struct FloatOrBool { 48 | enum Format { 49 | Invalid, 50 | Float, 51 | Bool 52 | } F; 53 | union { 54 | float f; 55 | bool b; 56 | }; 57 | }; 58 | ``` 59 | 60 | ## Proposed solution 61 | 62 | Union data types are defined in *\[class.union\]*of the ISO C++ language 63 | specification. HLSL 202x introduces a compliant implementation with some HLSL 64 | specific clarifications. 65 | 66 | * Following C++ Unions are always sized large enough to contain their largest 67 | member type. 68 | * Union members cannot have HLSL semantics applied to them. 69 | * Union objects in buffer layouts are aligned as elements of their 70 | most-restrictive member type. 71 | * Union objects in struct layouts behave as defined in C++. 72 | * Union objects cannot have semantics applied to them. 73 | * Union's cannot have user-defined constructors or destructors until the 74 | language supports them for other user defined data types (See: 75 | [0007](0007-constructors.md)). 76 | 77 | ## Acknowledgments 78 | 79 | Special thanks to [Dan Brown](https://github.com/danbrown-amd), and Meghana 80 | Thatishetti (Unknown GitHub ID), for their contributions to this implementation. 81 | -------------------------------------------------------------------------------- /proposals/0005-strict-initializer-lists.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Strict Initializer Lists 4 | 5 | * Proposal: [0005](0005-strict-initializer-lists.md) 6 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 7 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 8 | * Status: **Under Consideration** 9 | * Planned Version: 202y 10 | 11 | ## Introduction 12 | 13 | HLSL should adopt C and C++ initializer list formatting rules, rather than 14 | custom rules that are unintuitive and error prone. 15 | 16 | ## Motivation 17 | 18 | HLSL supports flattened brace initialization such that the structure of the 19 | bracket initializer on the right hand side of an initialization is ignored, and 20 | only the number of initialization arguments matters. Further, vector and matrix 21 | arguments are implicitly expanded. 22 | 23 | This feature likely results in a variety of common errors as HLSL will attempt 24 | to fit an initializer list to a structure regardless of the underlying structure 25 | of the members. 26 | 27 | In HLSL the following code is valid: 28 | 29 | ```c++ 30 | struct A { 31 | int a; 32 | double b; 33 | }; 34 | struct B { 35 | A a[2]; 36 | int c; 37 | }; 38 | B b = {{1, 1.2}, {2, 2.2}, 3}; // Array elements specified as members 39 | B b2 = {1, 2, 3, 4, 5}; // each field initialized separately 40 | B b3 = {{1, {2, 3}}, {4, 5}}; // Completely random grouping of arguments 41 | int4 i4 = {1,2,3,4}; // valid int4 in C-syntax 42 | B b4 = {i4, 5}; // int4 implicitly expanded to 4 arguments 43 | ``` 44 | 45 | Formalizing this code to comply with C/C++ initializer list rules will likely 46 | break existing code, however following C/C++ rules will allow error checking and 47 | validation of initializer lists which is likely to catch bugs which may be 48 | difficult to identify otherwise. Additionally in order to ease developer 49 | adoption we can implement a clang fix-it to transform flattened initializers 50 | into conformant initializer lists. 51 | 52 | ## Proposed solution 53 | 54 | Adopt C & C++ initializer list rules, and remove HLSL-specific initialization 55 | list behaviors. Specifically, this will remove implicit vector and structure 56 | element extraction, and enforce type system rules for data types passed into 57 | initializer lists. 58 | 59 | This will also introduce C rules for zero-initialization including zero 60 | initialization for structure members omitted from the initialization list. 61 | 62 | This change will be forward source breaking, and backwards compatible with some 63 | caveats. Current code that takes advantage of HLSL initialization semantics will 64 | produce an error that the compiler can generate a Fix-It for. Code with applied 65 | Fix-It will be backwards compatible to prior HLSL versions. 66 | 67 | New code that takes advantage of C & C++'s zero-initialization behavior, will 68 | not be backwards compatible to older HLSL versions. 69 | 70 | ## Unanswered Questions 71 | 72 | ### Should we support initialization constructors (i.e. `uint4 i4{}`)? 73 | 74 | This syntax conflicts with the effects annotation syntax which DXC supports 75 | parsing but is unsupported in code generation. Should we just stop parsing it? 76 | 77 | 78 | -------------------------------------------------------------------------------- /proposals/0006-reference-types.md: -------------------------------------------------------------------------------- 1 | # Reference Data Types 2 | 3 | * Proposal: [0006](0006-reference-types.md) 4 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 5 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Status: **Under Consideration** 7 | * Planned Version: 202y 8 | 9 | ## Introduction 10 | 11 | The addition of reference types in HLSL will improve the expressivity of the 12 | language, enable more code sharing between CPU and GPU code and enable future 13 | language enhancements. 14 | 15 | ## Motivation 16 | 17 | The continued absence of references in HLSL makes some C++ features and patterns 18 | impossible to replicate. As specific examples, assignment operators, container 19 | data types, and read-write parameters are all impossible without references. 20 | 21 | ## Proposed solution 22 | 23 | Add support for references as local variables, function parameters and return 24 | types. This enables common code patterns like returning references and 25 | implementing assignment or subscript operators. 26 | 27 | All addresses must be assumed to be in the GPUs addressing and cannot be assumed 28 | to be valid from the CPU, nor can CPU addresses be assumed to be valid in HLSL. 29 | For this reason HLSL references cannot be present in any input or output data 30 | structure. 31 | 32 | References may be annotated with an address space attribute. References cannot 33 | be casted between address spaces, however data from a reference in one address 34 | space can be loaded and stored to an object through a reference in another 35 | address space. 36 | 37 | References declared without an address space annotation will be references to 38 | the default address space (0), which corresponds to thread-local addresses. 39 | References to any other address space will need explicit annotation. 40 | 41 | ### Expanded Operator Overloading 42 | 43 | Along with the introduction of references we can expand operator overloading to 44 | remove the restrictions introduced in HLSL 2021. 45 | 46 | Support for overloading operators that idiomatically returned references are 47 | prohibited in HLSL 2021. With the addition of limited reference support those 48 | prohibitions can be lifted, enabling full compatibility with C++ operator 49 | overloading. 50 | 51 | Additionally, HLSL 2021 only allowed overloading member operators. With this 52 | proposal, operator overloading is supported for global and namespace-level 53 | operators following C++ syntax and semantics. 54 | 55 | ## Unanswered Questions From Review 56 | 57 | * Elaborate on address spaces, their use and annotations 58 | * Should `in`, `inout` and `out` be deprecated? 59 | * What is the extent of updates required to the HLSL built-in types 60 | -------------------------------------------------------------------------------- /proposals/0007-const-member-functions.md: -------------------------------------------------------------------------------- 1 | 2 | # `const`-qualified Non-`static` Member Functions 3 | 4 | * Proposal: [0007](0007-const-member-functions.md) 5 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Sponsor: TBD 7 | * Status: **Under Consideration** 8 | * Planned Version: 202y 9 | 10 | ## Introduction 11 | 12 | HLSL does not currently support `const` non-`static` member functions for user-defined data 13 | types. This proposal seeks to add support for `const` non-`static` member functions, and to 14 | adopt const-correct behaviors across the HLSL library objects. 15 | 16 | ## Motivation 17 | 18 | The absence of `const` non-`static` member functions causes some challenges since HLSL 19 | injected ASTs do have `const` and non-`const` non-`static` member functions. Further, since 20 | variables can be `const`-qualified, without the ability to specify `const` there 21 | are some cases that cannot be worked around without breaking 22 | `const`-correctness. 23 | 24 | DXC has received a number of issues relating to this. Two recent issues are 25 | listed below: 26 | 27 | * https://github.com/microsoft/DirectXShaderCompiler/issues/4340 28 | * https://github.com/microsoft/DirectXShaderCompiler/issues/4706 29 | 30 | In the first issue, a user defined data type's functions are basically unusable if 31 | the data type is placed in a `ConstantBuffer`. This results from the 32 | `ConstantBuffer` access returning `const &` objects. 33 | 34 | The second issue describes a similar problem, where overloaded operators on 35 | instances of `const`-qualified user-defined types are unusable. 36 | 37 | ## Proposed solution 38 | 39 | Following C++, HLSL will enable support for `const` non-`static` member functions and 40 | instance operator overloads (henceforth collectively referred to as constant 41 | member functions) to allow execution of member functions on `const` objects and 42 | preserve `const` qualifiers. 43 | 44 | Updates to HLSL's built-in data types to observe best practices in 45 | const-correctness will follow the introduction of language support. Functions 46 | which return mutable lvalue references will become non-constant member 47 | functions, and functions which return constant lvalue references or object values 48 | will become constant member functions. 49 | 50 | ## Detailed design 51 | ### Syntactic Changes 52 | 53 | C++'s existing syntax for declaring constant instance functions is compatible 54 | with HLSL. Adoption of this syntax does not introduce any syntactic ambiguities 55 | with existing HLSL constructs. Adding the `const` keyword to the end of the 56 | function declarator before the optional function body will denote a const 57 | member function function. The `const` keyword applies to the implicit object 58 | argument so it can only be applied to non-`static` member functions. See the 59 | examples below defining both a constant function and a constant overload of the 60 | call `()` operator: 61 | 62 | ```c++ 63 | struct Pupper { 64 | void Wag() const { /* body omitted */ } 65 | void operator() const { /* body omitted */ } 66 | }; 67 | ``` 68 | 69 | ### Semantic Changes 70 | 71 | In a const member function, the implicit object parameter (`this`) becomes a 72 | constant lvalue reference (`const &`). Code modifying any field of the `this` 73 | object is ill-formed and will produce a diagnostic. Calls to non-constant member 74 | functions are also ill-formed and will produce a diagnostic. 75 | 76 | This change requires modifications to HLSL's overload resolution rules to 77 | account for the const-ness of object parameters. When performing lookup of 78 | possible overload candidates, overloaded functions with non-constant implicit 79 | object parameters are invalid candidates when the implicit object is constant. 80 | 81 | Standard HLSL argument promotion rules will apply for the object parameter, but 82 | they cannot remove the `const` qualifier and shall not convert from a constant 83 | lvalue to a non-constant rvalue by copying the implicit argument as is valid for 84 | other arguments. 85 | 86 | ### HLSL Data Type Changes 87 | 88 | Introducing constant member functions provides an opportunity to revisit the 89 | const-correctness patterns of existing HLSL data types. With this change we will 90 | perform an audit of existing data types to provide constant and non-constant 91 | member functions as appropriate for the data type. 92 | 93 | When applied to HLSL intangible types, the `const` qualifier will apply as if to 94 | the handle, not the data the handle grants access to. For example, a `const 95 | RWBuffer` will still allow writes to the underlying resource, however the 96 | resource variable itself cannot be re-assigned. 97 | 98 | ### Impact on Existing Code 99 | 100 | Supporting constant member function overload resolution will break existing code 101 | that calls member functions on `cbuffer`, `tbuffer` or global constant variables. 102 | Consider the following valid HLSL: 103 | 104 | ```c++ 105 | struct Hat { 106 | int getFeathers() { 107 | return Feathers; 108 | } 109 | int Feathers; 110 | }; 111 | 112 | cbuffer CB { 113 | Hat H; 114 | }; 115 | 116 | export int GetFeatherCount() { 117 | return H.getFeathers(); 118 | } 119 | ``` 120 | 121 | This code is valid under HLSL 2021 because HLSL ignores the const-ness of the 122 | implicit object parameter. On introducing constant member functions, this code 123 | is ill-formed and will produce a diagnostic. 124 | 125 | The code is ill-formed because these declarations inside a `cbuffer` are 126 | implicitly constant. Today we ignore the `const`-ness of the object parameter 127 | and resolve the function. 128 | 129 | ### Const-correct Resources 130 | 131 | Implementing const-correct member functions on built-in HLSL data types should 132 | have no disruption to users. 133 | 134 | Consider the following code: 135 | 136 | ```c++ 137 | void setValue(RWBuffer R, int Val, int Index) { 138 | R[Index] = Val; 139 | } 140 | void setValueConst(const RWBuffer R, int Val, int Index) { 141 | setValue(R, Val, Index); 142 | } 143 | ``` 144 | 145 | In `setValueConst`, the `const` qualifier applies to the _instance_ of the 146 | `RWBuffer` parameter. A new `RWBuffer` variable can be created from a `const 147 | RWBuffer` via copy-initialization (standard copy construction), allowing 148 | `setValueConst` to call `setValue`. This does not violate const-correctness 149 | since the handle is treated as const while the data it references is not. 150 | 151 | ### Detailed Description of Overload Resolution Rules 152 | 153 | TBD: HLSL's current overload resolution rules are not fully codified anywhere 154 | I'm aware of. For this design to be complete we need to fully specify the 155 | overload resolution and standard argument conversions. 156 | 157 | ### Other Considerations 158 | 159 | This change should have no impact on code generation through SPIR-V or DXIL 160 | assuming that the existing parameter mangling for constant implicit object 161 | parameters works as expected. 162 | 163 | 164 | -------------------------------------------------------------------------------- /proposals/0008-non-member-operator-overloading.md: -------------------------------------------------------------------------------- 1 | # Non-member Operator Overloading 2 | 3 | ## Instructions 4 | 5 | * Proposal: [0008](0008-non-member-operator-overloading.md) 6 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 7 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 8 | * Status: **Under Consideration** 9 | * Planned Version: 202y 10 | * Related Proposal(s): [0006 Reference Types](0006-reference types.md) 11 | 12 | ## Introduction 13 | 14 | HLSL 2021 introduced operator overloading for member operators of user defined 15 | data types. Only supporting member operators has some drawbacks, specifically 16 | defining binary operators where the LHS is a built-in type is impossible, 17 | additionally scoping operators to namespaces is also impossible. 18 | 19 | ## Motivation 20 | 21 | Beyond common use cases where global operators are nice to have, users adopting 22 | HLSL 2021 have provided feedback that global operator overloading would be a 23 | significant benefit. 24 | 25 | HLSL 2021's introduction of short circuiting boolean operators users have been 26 | forced to translate their code that operates on HLSL vector types to use the 27 | new `select`, `and` and `or` intrinsics. We believe the new intrinsics are the 28 | right step for the language in removing ambiguity and clearly expressing code 29 | meaning. Global operator overloading provides an opportunity for the language to 30 | remain clear and unambiguous, while allowing users to define custom operators 31 | that allow them to not migrate legacy code. 32 | 33 | ## Proposed solution 34 | 35 | This change requires fully adopting C++ rules for operator overload resolution 36 | and supporting defining global and namespace scoped operator overloads. The 37 | limitations currently in place on operator overloading (disallowing overloading 38 | operators that idiomatically return references) will remain in effect on 39 | non-member operators as well unless the restrictions are lifted as proposed in 40 | [0006 Reference Types](0006-reference types.md). 41 | 42 | Because this solution should not break existing code, it could also be enabled 43 | under HLSL 2021 as an extension. Using the feature in HLSL 2021 mode as an 44 | extension will produce warnings so that users can be aware of portability issues 45 | that may arise between compiler versions. 46 | 47 | ## Alternatives considered 48 | 49 | Non-member operator overloading is a feature that is generally useful, an no 50 | alternatives have been considered to the feature itself. Reflecting on the 51 | problems caused by HLSL 2021 removing boolean operators from vector types other 52 | options were considered. 53 | 54 | One considered option was to roll back the HLSL 2021 removal of vector 55 | operators. Operator short circuiting was introduced in HLSL 2021 to reduce 56 | behavioral differences between HLSL and C/C++. With operator short circuiting 57 | vector operator aren't intuitive because they can't short circuit. 58 | 59 | Having scalar operators short circuit and vector operators not was also 60 | considered. The argument against that approach is that having two code 61 | representations that look the same but behave differently is unintuitive. This 62 | gets more unintuitive when you consider that with the introduction of templates 63 | the same literal line of code could be used for both vector and scalar 64 | conditionals with different behavior. 65 | 66 | For these reasons, this proposal posits that HLSL 2021's decision is the correct 67 | approach for the language. This proposal gives users the ability to introduce 68 | source compatibility if they choose, but at their own maintenance expense. It 69 | also adopts behavior that is consistent with C++ for evaluation of logical 70 | operators. 71 | 72 | ## Acknowledgments 73 | 74 | This proposal is the result of conversations with users and teammates. Thank you 75 | everyone who contributed feedback on HLSL 2021. 76 | -------------------------------------------------------------------------------- /proposals/0009-math-modes.md: -------------------------------------------------------------------------------- 1 | # Math Modes 2 | 3 | * Proposal: [0009](0009-math-modes.md) 4 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 5 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Status: **Under Consideration** 7 | * Planned Version: 202y 8 | * Dependencies: [0002 C++ Attributes](0002-cxx-attributes.md) 9 | 10 | ## Introduction 11 | 12 | Shaders frequently need fine-grained control over the way the compiler optimizes 13 | (or doesn't) math optimizations. To enhance developer control in a more robust 14 | way than the existing `precise` qualifier, HLSL should gain a higher level 15 | concept of math modes. 16 | 17 | ## Motivation 18 | 19 | The `precise` qualifier is particularly gnarly to implement and is wrought with 20 | bugs that are inscrutable to developers. The source of the implementation 21 | challenges come from the fact that the precise attribute is applied to a 22 | declaration, but does not impact the uses of the declaration. Instead it impacts 23 | reverse-propagates and applies to all of the math expressions that are used to 24 | compute the declared variable. 25 | 26 | The goal of this proposal is to create a new language feature which allows 27 | shader authors the control they need to replace precise, without the tooling 28 | complexity. 29 | 30 | ## Proposed solution 31 | 32 | First and foremost, since the goal is to _replace_ the `precise` qualifier, this 33 | proposal should deprecate `precise` in the language. Allowing the new feature 34 | and `precise` to exist together for a single language version will ease 35 | adoption, however `precise` will be removed in the future. 36 | 37 | ### Math Modes 38 | 39 | The core of this proposal is to introduce new math modes `strict` and `fast`. 40 | The `strict` math mode prohibits optimizations which may impact the precision of 41 | results. This prevents optimizations like fusing multiply and add instructions. 42 | The `fast` math mode prioritizes speed over precision guarantees. This does not 43 | mean that `fast` math is less precise. In some cases optimal fused operations 44 | are faster, but the results are less consistent across hardware architectures. 45 | 46 | As a simplified view, `strict` can be viewed as "execute the math as written in 47 | source", while `fast` is "let the optimizer do its thing". 48 | 49 | The new math modes are exposed through a variety of mechanisms described below. 50 | 51 | ### Attributes 52 | 53 | The new `hlsl::math_mode()` attribute can be set to either `strict`, `fast`, or 54 | `default`. The default math mode is `fast`, however this can be changed with the 55 | compiler flag:`math-mode=precise|fast`. 56 | 57 | The math attribute can be applied to functions or expressions, but it does not 58 | propagate in the way that the `precise` keyword did. 59 | 60 | For example: 61 | 62 | ```c++ 63 | [hlsl::math_mode(strict)] 64 | float fma(float x, float y, float z) { 65 | return x * y + z; 66 | } 67 | 68 | float fma2(float x, float y, float z) { 69 | return [hlsl::math_mode(strict)] x * y + z; 70 | } 71 | ``` 72 | 73 | In both of the above functions optimization to an FMA instruction is prevented. 74 | 75 | ### Namespaces 76 | 77 | New math namespaces are also added which provide simplified access to math 78 | operations with the expected performance characteristics. 79 | 80 | For example: 81 | 82 | ```c++ 83 | float f = hlsl::strict::fma(1.0, 2.0, 3.0); // strict mode math 84 | float f = hlsl::fast::fma(1.0, 2.0, 3.0); // fast mode math 85 | float f = hlsl::fma(1.0, 2.0, 3.0); // default mode math 86 | ``` 87 | -------------------------------------------------------------------------------- /proposals/0015-extended-command-info.md: -------------------------------------------------------------------------------- 1 | # Extended Command Information 2 | 3 | * Proposal: [0015](0015-extended-command-info.md) 4 | * Author(s): [Greg Roth](https://github.com/pow2clk) 5 | * Sponsor: [Greg Roth](https://github.com/pow2clk) 6 | * Status: Complete 7 | * Version: Shader Model 6.8 8 | 9 | ## Introduction 10 | 11 | Two new system-value semantics are to be supported in HLSL shader 12 | model 6.8: 13 | 14 | * `SV_StartVertexLocation` - 15 | Reports `StartVertexLocation` from `DrawInstanced()` 16 | or `BaseVertexLocation` from `DrawIndexedInstanced()` to a vertex shader. 17 | * SV_StartInstanceLocation - 18 | Reports `StartInstanceLocation` from `DrawInstanced()` or 19 | `DrawIndexedInstanced()` to a vertex shader. 20 | 21 | ## Motivation 22 | 23 | Since SV_VertexID doesn't include the StartVertexLocation 24 | and SV_InstanceID doesn't include the StartInstanceLocation values provided to 25 | the API through the corresponding draw or execute calls, 26 | this information has been unavailable to HLSL unless independently passed in. 27 | Availability of these values allows reconstruction of the vertex and instance 28 | representation used within the API. 29 | In particular, if the vertex or instance information is offset by a certain 30 | amount in the API, the shader can access that information and potentially 31 | make use of data before that offset for special usage. 32 | It also provides compatibility support for APIs that include these values 33 | in their VertexID and InstanceID equivalents. 34 | 35 | ## Proposed solution 36 | 37 | The values provided to `DrawInstanced()` or `DrawIndexInstanced()` that 38 | represent the start or base vertex and instance location should be made 39 | available through semantic values applied to parameters to the entry function 40 | of a vertex shader. 41 | These values will be lowered to DXIL intrinsics that represent a 42 | platform-specific mechanism to retrieve the corresponding values provided by 43 | the API draw call that invoked the vertex shader. 44 | 45 | ## Detailed Design 46 | 47 | ### HLSL additions 48 | 49 | New semantic inputs are added to HLSL vertex shaders. 50 | 51 | | Semantic Input | Type | Stages | 52 | |---------------------------|------|--------| 53 | | SV_StartInstanceLocation | uint | Vert | 54 | | SV_StartVertexLocation | int | Vert | 55 | 56 | `SV_StartInstanceLocation` represents the value added to each index before 57 | reading instance data from instance buffer(s) if present. 58 | Regardless of presence or use of instance buffers, 59 | the value will behave the same and the shader can use this 60 | or any other system value for any purpose. 61 | It corresponds to `StartInstanceLocation` from the underlying `DrawInstanced()` 62 | or `DrawIndexedInstanced()` call 63 | or equivalent indirect call from `ExecuteIndirect()` on the command list. 64 | 65 | `SV_StartVertexLocation` represents the value added to each index before reading 66 | a vertex from vertex buffer(s) if present. 67 | Regardless of presence or use of vertex buffers, 68 | the value will behave the same and the shader can use this 69 | or any other system value for any purpose. 70 | It corresponds to `StartVertexLocation` from the underlying `DrawInstanced()` call, 71 | to `BaseVertexLocation` from the underlying `DrawIndexedInstanced()` call, 72 | or to equivalent parameters to the the equivalent indirect calls from ExecuteIndirect() 73 | on the command list. 74 | `SV_StartVertexLocation` is signed to allow for negative values 75 | just like the `BaseVertexLocation` parameter is. 76 | A negative value allows the first vertex to be referenced 77 | by a positive vertex index value that is shifted to a lower value, 78 | but should not index below zero. 79 | The `StartVertexLocation` parameter to `DrawInstanced()` is unsigned and 80 | it will continue to be used as unsigned when reading vertex data 81 | but will be reinterpret-casted to a signed int for HLSL. 82 | 83 | The system only populates these values as inputs to the vertex shader. 84 | For any subsequent stage that cares about them, the shader must pass them manually 85 | using a user semantic. 86 | These semantics are invalid for any shader outputs. 87 | 88 | ### DXIL Additions 89 | 90 | Two new DXIL operations that return the two semantic values are introduced in 91 | DXIL 1.8. 92 | As they return values that are determined by the draw calls, 93 | they require no input from the shader and have only the associated opcodes as 94 | parameters. 95 | 96 | ```C++ 97 | // SV_StartVertexLocation 98 | $result1 = call i32 @dx.op.StartVertexLocation(i32 256) 99 | 100 | // SV_StartInstanceLocation 101 | $result2 = call i32 @dx.op.StartInstanceLocation(i32 257) 102 | ``` 103 | 104 | ### SPIR-V Additions 105 | 106 | Use of HLSL entry parameters with the new semantic annotations 107 | `SV_StartInstanceLocation` or `SV_StartVertexLocation` can be supported in 108 | SPIR-V using OpVariables with the result id of the OpVariable set to 109 | `BaseInstance`(4425) or `BaseVertex`(4424) respectively. 110 | 111 | ### Diagnostic Changes 112 | 113 | #### New Errors 114 | 115 | These are where new errors are produced: 116 | 117 | * A parameter with `SV_StartInstanceLocation` is not `uint` type. 118 | (currently blocked by bug [#5768](https://github.com/microsoft/DirectXShaderCompiler/issues/5768)) 119 | * A parameter with `SV_StartVertexLocation` is not `int` type. 120 | (currently blocked by bug [#5768](https://github.com/microsoft/DirectXShaderCompiler/issues/5768)) 121 | * `SV_StartVertexLocation` or `SV_StartInstanceLocation` are used 122 | in any non-vertex shader stages 123 | * `SV_StartVertexLocation` or `SV_StartInstanceLocation` are used on any vertex 124 | shader outputs. 125 | * `SV_StartVertexLocation` or `SV_StartInstanceLocation` are used 126 | in a vertex shader targeting a shader model earlier than 6.8. 127 | 128 | #### Validation Changes 129 | 130 | Validation should confirm: 131 | 132 | * That neither `dx.op.StartVertexLocation` nor `dx.op.StartInstanceLocation` 133 | are used in any DXIL compiled for any non-vertex shader stage. 134 | 135 | ### Runtime Additions 136 | 137 | #### Runtime information 138 | 139 | A new feature info flag is added to SFI0: 140 | 141 | | Tag | Bit | Value | Description | 142 | |-------------------------|-----|------------|-----------------------------------------| 143 | |ExtendedCommandInfo | 32 | 0x100000000ull | `SV_StartInstanceLocation` or `SV_StartVertexLocation` are used | 144 | 145 | It indicates to the runtime that the shader makes use of any of the above system values. 146 | 147 | This indicates to the runtime that that the shader requires the presence of 148 | the corresponding capability bit (described below) indicating support. 149 | 150 | #### Device Capability 151 | 152 | Applications can query the availability 153 | of these features by 154 | passing `D3D12_FEATURE_D3D12_OPTIONS21` 155 | as the `Feature` parameter 156 | and retrieving the `pFeatureSupportData` parameter 157 | as a struct of type `D3D12_FEATURE_DATA_D3D12_OPTIONS21`. 158 | The relevant parts of these structs are defined below. 159 | 160 | ```C++ 161 | typedef enum D3D12_FEATURE { 162 | ... 163 | D3D12_FEATURE_D3D12_OPTIONS21 164 | } D3D12_FEATURE; 165 | 166 | typedef struct D3D12_FEATURE_DATA_D3D12_OPTIONS21 { 167 | ... 168 | BOOL ExtendedCommandInfo; 169 | } D3D12_FEATURE_DATA_D3D12_OPTIONS21; 170 | ``` 171 | 172 | `ExtendedCommandInfo` is a boolean that specifies 173 | whether the system values definded here are supported 174 | by the given hardware and runtime. For devices that support `D3D_FEATURE_LEVEL_12_2`, `ExtendedCommandInfo` will 175 | always be `TRUE`. The capability check is useful in case running on a device on a lower feature level. 176 | 177 | ## Testing 178 | 179 | ### Correct Behavior Testing 180 | 181 | Verify the following compiler output: 182 | 183 | * A vertex shader with an int entry point parameter annotated with 184 | `SV_StartInstanceLocation` that is passed directly into the output produces 185 | DXIL IR with a call op to `dx.op.StartInstanceLocation` that returns that 186 | result to the output. 187 | * A vertex shader with an input struct with an element annotated with 188 | `SV_StartInstanceLocation` that is passed directly into the output produces 189 | DXIL IR with a call op to `dx.op.StartInstanceLocation` that returns that 190 | result to the output. 191 | * A vertex shader with an int entry point parameter annotated with 192 | `SV_StartVertexLocation` that is passed directly into the output produces 193 | DXIL IR with a call op to `dx.op.StartVertexLocation` that returns that 194 | result to the output. 195 | * A vertex shader with an input struct with an element annotated with 196 | `SV_StartVertexLocation` that is passed directly into the output produces 197 | DXIL IR with a call op to `dx.op.StartVertexLocation` that returns that 198 | result to the output. 199 | * Each of the above tests produces the expected output within a library shader 200 | with a "vertex" shader attribute. 201 | 202 | ### Diagnostics Testing 203 | 204 | Ensure that each of the following scenarios produces appropriate errors: 205 | 206 | * Use invalid types for entry parameters with the new semantics 207 | (currently blocked by bug [#5768](https://github.com/microsoft/DirectXShaderCompiler/issues/5768)) 208 | * A `float` parameter with `SV_StartInstanceLocation` 209 | * An `int` parameter with `SV_StartInstanceLocation` 210 | * A `float` parameter with `SV_StartVertexLocation` 211 | * A `uint` parameter with `SV_StartInstanceLocation` 212 | * Use new semantics in invalid shader targets 213 | * `SV_StartVertexLocation` is used in each 6.8 non-vertex shader stage target 214 | * `SV_StartInstanceLocation` is used in each 6.8 non-vertex shader stage target 215 | * `SV_StartVertexLocation` is used in a 6.7 vertex shader stage target 216 | * `SV_StartInstanceLocation` is used in a 6.7 vertex shader stage target 217 | 218 | ### Validation Testing 219 | 220 | Assemble shaders targeting each non-vertex shader stage with calls to 221 | `dx.op.StartInstanceLocation` and `dx.op.StartVertexLocation` and ensure that 222 | the validator produces an appropriate error. 223 | 224 | ### Execution Testing 225 | 226 | Create a vertex shader with a uint entry point parameter annotated with 227 | `SV_StartInstanceLocation` and an int entry point parameter annotated with 228 | `SV_StartVertexLocation` that stores those values into a raw buffer. 229 | Invoke this shader using `DrawInstanced()`, `DrawIndexedInstanced()`, and 230 | equivalent indirect call from `ExecuteIndirect()` with positive integer values 231 | for the parameters that correspond to start vertex and start instance values. 232 | Read back the content of the raw buffer to ensure that the values match the 233 | parameters used in the API calls. 234 | Perform an additional test where the start vertex parameters are negative values 235 | and ensure that the read back values match the parameters. 236 | 237 | ## Alternatives considered 238 | 239 | There may have been utility to making StartVertexLocation and StartInstanceLocation 240 | available in entry shader stages beyond just the vertex shader. 241 | That would have exceeded the requirement that motivated this feature without 242 | certainty that it would be useful for anyone, 243 | so availability was limited to the vertex stage. 244 | 245 | The StartVertexLocation and StartInstanceLocation information might have been 246 | accessible to the HLSL author by built-in functions rather than semantics. 247 | It was a technical possibility that would have made them more readily available 248 | without having to pipe entry parameters to subfunctions, 249 | however semantic values are consistent with how the corresponding information 250 | is accessed such as VertexID. 251 | For the sake of consistency and the principal of least surprise, 252 | they are represented as semantic values as well. 253 | 254 | ## Acknowledgements 255 | 256 | * Jesse Natalie 257 | * Amar Patel 258 | * Tex Riddell 259 | -------------------------------------------------------------------------------- /proposals/0017-assets/DiffExample1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/hlsl-specs/36ac9489c3d95e7a7cd5c4a732ef689c09e589a9/proposals/0017-assets/DiffExample1.png -------------------------------------------------------------------------------- /proposals/0017-assets/DiffExample2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/hlsl-specs/36ac9489c3d95e7a7cd5c4a732ef689c09e589a9/proposals/0017-assets/DiffExample2.png -------------------------------------------------------------------------------- /proposals/0020-hlsl-202x-202y.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # HLSL 202x and 202y 4 | 5 | * Proposal: [0020](0020-hlsl-202x-202y.md) 6 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 7 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 8 | * Status: **Under Consideration** 9 | * Impacted Projects: DXC & Clang 10 | 11 | ## Introduction 12 | 13 | This proposal seeks to provide a framework for defining the next two versions of 14 | the HLSL programming language. It seeks to define HLSL 202x as a bridge between 15 | DXC's implementation and Clang's implementation, and HLSL 202y as the next major 16 | feature release. 17 | 18 | ## Motivation 19 | 20 | The HLSL compiler is undergoing a massive transition moving to Clang. Since 21 | the HLSL language is not formally specified and existing implementations 22 | disagree about fundamental behaviors, the new compiler will not be fully 23 | compatible with the previous compilers. This will create three conflicting 24 | implementations. 25 | 26 | This poses a challenge for users as they seek to migrate to Clang. Sources used 27 | with DXC may not be compatible with Clang by preventing the ability to switch to 28 | Clang piecemeal or being able to A/B test shaders. 29 | 30 | ## Version Naming and Management 31 | 32 | HLSL versions names match the intended year of completion. Historically we 33 | missed with HLSL 2021 not completing the implementation and deployment in 2023. 34 | Due to schedule uncertainty and a desire to not repeat _that mistake_, future 35 | versions have placeholder names. 36 | 37 | The next language version is HLSL 202x. HLSL 202y will release after 202x. As we 38 | near the final release of 202x the release name will change to the target year. 39 | The same will follow for 202y. 40 | 41 | The expectation is that HLSL `x` is a placeholder integer value less than `y`. 42 | All features added to HLSL 202x will be implicitly inherited by HLSL 202y. 43 | 44 | ## Proposed Solution 45 | 46 | This proposal adopts the development of two new language versions for HLSL in 47 | parallel. The proposal adopts a narrowly focused HLSL 202x which will be 48 | supported by both DXC and Clang, and a wider focused HLSL 202y feature release 49 | which will only be supported by Clang. 50 | 51 | ### HLSL 202x 52 | 53 | HLSL 202x shall contain features that bridge compatibility between DXC and 54 | Clang. This shall be limited to cases where Clang's implementations do not match 55 | DXC and it is expected to cause potential disruption. 56 | 57 | Existing proposals that fall into this category are: 58 | * [Numeric Constants](/proposals/0003-numeric-constants.md) 59 | * DXC Issue - [[202x] [0003] Numeric Constants](https://github.com/microsoft/DirectXShaderCompiler/issues/7218) 60 | * Clang Issue - [[202x] [0003] Numeric Constants](https://github.com/llvm/llvm-project/issues/131808) 61 | * [Conforming Literals](/proposals/0017-conforming-literals.md) 62 | * Completed in DXC - [[202x] Implementaiton of conforming literals](https://github.com/microsoft/DirectXShaderCompiler/pull/6572) 63 | * Completed in Clang - [[HLSL] Implement 202x conforming literals](https://github.com/llvm/llvm-project/pull/91015) 64 | * [Loop Unroll Factor](/proposals/0022-hlsl-loop-unroll-factor.md) 65 | * DXC Issue - [[202x][0022] Loop Unroll Factor](https://github.com/microsoft/DirectXShaderCompiler/issues/7219) 66 | * Completed in Clang - [[HLSL] add loop unroll](https://github.com/llvm/llvm-project/pull/93879) 67 | 68 | In addition to the new features, HLSL 202x will remove features that were not 69 | fully supported by DXC. Issues tracking 202x feature deprecations: 70 | * [Effects Syntax](https://github.com/microsoft/hlsl-specs/issues/380) 71 | * [HLSL Interfaces](https://github.com/microsoft/hlsl-specs/issues/291) 72 | * [cbuffer variable initializers](https://github.com/microsoft/hlsl-specs/issues/259) 73 | * [`uniform` keyword](https://github.com/microsoft/hlsl-specs/issues/135) 74 | 75 | HLSL 202x will not include features for all differences between DXC and Clang. 76 | Some of the 77 | [differences](https://clang.llvm.org/docs/HLSL/ExpectedDifferences.html), are 78 | not expected to have meaningful difference to users, or have reasonable source 79 | compatible workarounds. HLSL 202x is specifically for differences that do not 80 | have workarounds and may pose a barrier to adoption. 81 | 82 | ### HLSL 202y 83 | 84 | HLSL 202y is an opportunity to address some frequently requested features that 85 | we can deliver more quickly in Clang than in DXC. Some of the features in HLSL 86 | 202y require significant changes to core language behaviors and will likely 87 | cause source compatibility issues. 88 | 89 | Two big areas of investment in HLSL 202y are overload resolution and object 90 | initialization. While the two areas are intertwined, we will discuss them mostly 91 | separately. 92 | 93 | #### Overload Resolution 94 | 95 | In Clang we've adopted overload resolution behavior more similar to C++. This 96 | causes some source incompatibilities as cited in the [clang 97 | docs](https://clang.llvm.org/docs/HLSL/ExpectedDifferences.html). Taking these 98 | behavior changes into HLSL makes HLSL's overload best-match algorithm more 99 | familiar and will produce ambiguous resolution errors instead of potentially 100 | choosing an unexpected overload when ambiguity exists in the source. 101 | 102 | Adopting C++ overload best match and set selection rules implements proposal 103 | [0007 `const` non-static member 104 | functions](https://github.com/microsoft/hlsl-specs/blob/main/proposals/0007-const-instance-methods.md). 105 | 106 | Adopting C++ language rules for the contexts in which overload resolution occurs 107 | implements proposal [0008 non-member operator 108 | overloading](https://github.com/microsoft/hlsl-specs/blob/main/proposals/0008-non-member-operator-overloading.md). 109 | 110 | #### Object Initialization 111 | 112 | Supporting [C++ 113 | constructors](https://github.com/microsoft/hlsl-specs/issues/303) requires 114 | revisiting HLSL's approach where all objects support aggregate initialization 115 | (braced initializer lists), which makes it connected to proposal [0005 strict 116 | initializer 117 | lists](https://github.com/microsoft/hlsl-specs/blob/main/proposals/0005-strict-initializer-lists.md). 118 | 119 | HLSL 2021 & 202x have special rules for aggregate initializers such that the 120 | source-provided structure of braced initializer lists is ignored and an 121 | element-wise initialization is performed. This conflicts with objects having 122 | constructors, destructors, or user-provided conversion functions. It also 123 | conflicts with [`union` 124 | types](https://github.com/microsoft/hlsl-specs/blob/main/proposals/0004-unions.md). 125 | 126 | HLSL 202y adopts support for constructors and destructors, and C++'s rules for 127 | aggregate initialization. 128 | 129 | #### Other Mostly Free Features 130 | 131 | Other C++ features have made their way in via Clang's implementation preserving 132 | C++ constructs. A few notable features that we expect to standardize in HLSL 133 | 202y are: 134 | 135 | * [`constexpr` functions](https://github.com/microsoft/hlsl-specs/issues/74) 136 | * [`constexpr` variables](https://github.com/microsoft/hlsl-specs/issues/21) 137 | * [`auto` variable declarations](https://github.com/microsoft/hlsl-specs/issues/24) 138 | * `static_assert` 139 | * [`bit_cast`](https://github.com/microsoft/hlsl-specs/issues/318) 140 | * `public`, `private` and `protected` access specifiers. 141 | 142 | Additionally, we do have some features that we're experimenting with in Clang 143 | which may or not make the cut for HLSL 202y. Those include: 144 | * [C++ lambdas](https://github.com/microsoft/hlsl-specs/issues/21) 145 | * [`union` types](https://github.com/microsoft/hlsl-specs/blob/main/proposals/0004-unions.md) 146 | 147 | 148 | -------------------------------------------------------------------------------- /proposals/0022-hlsl-loop-unroll-factor.md: -------------------------------------------------------------------------------- 1 | # HLSL Loop Unroll Factor 2 | 3 | * Proposal: [0022](0022-hlsl-loop-unroll-factor.md) 4 | * Author(s): [Farzon Lotfi](https://github.com/farzonl) 5 | * Sponsor: [Farzon Lotfi](https://github.com/farzonl) 6 | * Status: **Accepted** 7 | * Planned Version: 202x 8 | * Impacted Projects: DXC & Clang 9 | 10 | ## Introduction 11 | 12 | This proposal seeks to unify the diverging behaviors between the agreed upon 13 | [spec for HLSL loop unroll](https://github.com/microsoft/hlsl-specs/pull/263) 14 | and the current behavior of DXC. 15 | 16 | The new spec wants to treat the unroll factor as a hint to the compiler for 17 | partial loop unroll. The current behavior in dxc is that the unroll factor 18 | specifies the maximum number of times the loop is to execute. 19 | 20 | The DXC behavior was determined to violate user expectations by overriding 21 | the existing loop termination conditions. Further the DXC behavior diverges 22 | from how both clang and openCL treat the loop unroll factor which would have 23 | made our port of HLSL loop unroll a bunch special cases instead of just 24 | syntactic sugar that could sit on top of the existing loop unroll 25 | implementations that exist in LLVM. 26 | 27 | ## Motivation 28 | The HLSL compilers transition to clang has resulted in a compat break between 29 | the [HLSL loop unroll implementation in clang](https://github.com/llvm/llvm-project/pull/93879) 30 | and the one in DXC. While there is an expectation that the new compiler will 31 | not be fully compatible with the previous compilers, These compat breaks should 32 | be minimized when possible. 33 | 34 | ## Proposed solution 35 | In [HLSL 202X](0020-hlsl-202x-202y.md) the DXC implementation of the loop 36 | unroll factor should no longer alter the number of iteration executions. 37 | Ideally the loop unroll factor will also become a compiler hint for partial 38 | loop unroll. If this can not be done because of concerns of invalid DXIL 39 | generation then the loop unroll factor as a feature should be removed from DXC. 40 | Removal in this case means ignoring the unroll factor and issuing a warning to 41 | inform the user. 42 | -------------------------------------------------------------------------------- /proposals/0023-cxx11-base.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Adopt C++11 Base 4 | 5 | * Proposal: [NNNN](NNNN-cxx11-base.md) 6 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 7 | * Sponsor: TBD 8 | * Status: **Under Consideration** 9 | * Planned Version: 202y 10 | 11 | ## Introduction 12 | 13 | In DXC HLSL is a set of feature extensions on top of a subset of C++98. C++98 14 | is now over 20 years old and most modern C++ users have adopted newer language 15 | constructs. This proposal suggests taking the small step of updating HLSL 202y's 16 | base C++ language to C++11. 17 | 18 | ## Motivation 19 | 20 | C++11 is over a decade old and introduced widely adopted features, many of which 21 | have been frequently requested additions for HLSL. 22 | 23 | ## Proposed solution 24 | 25 | Adopt a C++11 base language and include the following C++11 features in HLSL 202y: 26 | * auto 27 | * decltype 28 | * constexpr 29 | * C++11 scoped enumerations 30 | * variadic templates 31 | * user-defined literals 32 | * [C++11 attributes](/proposals/0002-cxx-attributes.md) 33 | * Lambda expressions 34 | * Static assert 35 | * Range-based for loops 36 | 37 | ## Alternatives considered 38 | 39 | ### C++20 40 | 41 | We could instead adopt an even more recent C++, like C++20. The main drawback of 42 | that is that it significantly increases the rapid divergence from DXC, and it 43 | gives us a longer list of features that we need to rectify against HLSL's 44 | language features. Adopting a C++11 base for 202y does not prevent later 45 | versions from adopting newer C++ base standards, but it does allow us to phase 46 | the changes in iteratively as HLSL evolves. 47 | 48 | ### Target HLSL 202x 49 | 50 | While the original Clang 3.7 release did support C++11 fully, the intrusive 51 | changes to support HLSL broke many of the basic features Clang uses for 52 | configuring language features and supporting language modes. To restore those 53 | parts of clang sufficiently to support a C++11 base in DXC would be non-trivial. 54 | For that reason this is proposed as a Clang-only HLSL 202y feature. 55 | 56 | 57 | -------------------------------------------------------------------------------- /proposals/0025-max-records-per-node.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | * Proposal: [0025](0025-max-records-per-node.md) 4 | * Author(s): [Anupama Chandrasekhar](https://github.com/anupamachandra), [Mike Apodaca](https://github.com/mapodaca-nv) 5 | * Sponsor: Damyan Pepper 6 | * Status: **Under Consideration** 7 | 8 | # [MaxRecordsPerNode(count)] Attribute for NodeOutputArray 9 | 10 | ## Introduction 11 | 12 | This specification describes the HLSL and DXIL details for a new [NodeArrayOutput](https://microsoft.github.io/DirectX-Specs/d3d/WorkGraphs.html#node-output-attributes) attribute `[MaxRecordsPerNode(count)]` that specifies the maximum number of records that can be output to a specific node in a node output array. See the [MaxRecordsPerNode]() specifications for more details. 13 | 14 | ## Motivation 15 | 16 | For `NodeArrayOutput`, the node output attribute `[MaxRecords(count)]` specifies the maximum number of records that can 17 | be output across the entire node array. This attribute alone is insufficient for determining how records are 18 | distributed across an output array. For example, consider an output node array specification of 19 | `[MaxRecords(N)][NodeArraySize(N)]`. All N records could be sent to one node in the array, or one record could be 20 | sent to each of the N nodes in the array, or the records could be spread in an arbitrary fashion across multiple nodes 21 | in the array. An implementation cannot distinguish these different use cases. 22 | 23 | When determining backing store memory requirements, an implementation must assume the worst-case of `MaxRecords` written 24 | to any single node in the output array. However, a common use-case is for a small number records to be written to 25 | select nodes in a very large array of nodes. Some implementations can take advantage of this knowledge to significantly 26 | reduce the backing store memory requirements while maintaining peak performance. 27 | 28 | ## Proposed solution 29 | 30 | We propose a new node output attribute called `MaxRecordsPerNode`. This parameter is only required for output node 31 | arrays. This attribute specifies the maximum number of records that can be written to any single output node within a 32 | node array. 33 | 34 | ## Detailed design 35 | 36 | ### HLSL Additions 37 | 38 | Add a new node output attribute: 39 | 40 | | Attribute | Required | Description | 41 | |:--- |:--------:|:------------| 42 | | `[MaxRecordsPerNode(count)]` | Y | For `NodeArrayOutput`, specifies the maximum number of records that can be output to a node within the array. Exceeding this results in undefined behavior. This attribute can be overridden via the `NumOutputOverrides / pOutputOverrides` option when constructing a work graph. This attribute has no impact on existing node output limits. | 43 | 44 | This attribute will be required starting with a future Shader Model version. 45 | Since this may cause compilation failures with existing Work Graphs, this will 46 | be a `DefaultError` warning assigned to a warning group named 47 | `hlsl-require-max-records-per-node` to allow a command-line override. 48 | The value of `MaxRecordsPerNode` will be set equal to `MaxRecords`. 49 | 50 | The compiler will also generate an error if the `MaxRecordsPerNode` value is greater than the `MaxRecords` in a HLSL shader. Note that `pMaxRecordsPerNode` may override this value and the runtime will validate the correctness in that case. See the feature [spec]() for more details. 51 | 52 | **Developer's note**: Implementations that do not support or ignore this attribute, will not be functionally impacted. 53 | 54 | ### Usage 55 | 56 | The following trivial example demonstrates using `MaxRecordsPerNode` for a thread launch node which distributes 57 | a single record across an array of 64 consumer thread launch nodes. 58 | 59 | ```cpp 60 | [Shader("node")] 61 | [NodeLaunch("thread")] 62 | [NodeIsProgramEntry] 63 | void DispatchNode( 64 | [MaxRecords(64)] // a maximum of 64 records are written to output node array, 65 | [MaxRecordsPerNode(1)] // but only 1 record is written to each node in the array 66 | [NodeArraySize(64)] NodeOutputArray ConsumerNodes ) 67 | { 68 | [unroll] for(uint i = 0; i < 64; ++i) 69 | { 70 | ThreadNodeOutputRecords outputRecord = ConsumerNodes[i].GetThreadNodeOutputRecords(1); 71 | ... 72 | outputRecord.OutputComplete(); 73 | } 74 | } 75 | ``` 76 | 77 | As mentioned above, some material shading algorithms have a similar pattern: a single node which makes a decision about 78 | which node(s) in a node array (materials) to execute, where the number of possible materials is large, but the number of 79 | records submitted to any specific node is small, relative to the size of the array. 80 | 81 | ### Interchange Format Additions 82 | 83 | A new metadata tag is added for MaxRecordsPerNode. 84 | 85 | |Tag |Tag Encoding |Value Type |Default | 86 | |:------------------ |:----------------|:--------------|:-----------| 87 | |kDxilNodeMaxRecordsPerNodeTag |`7` |`i32` |Required, See [HLSL Additions](#hlsl-additions) section for backward compatibility with older Shader Models | 88 | 89 | ### Runtime Additions 90 | 91 | The `MaxRecordsPerNode` information will be captured to RDAT. Similar to other Node attributes, add a `RDAT::NodeAttribKind` named `MaxRecordsPerNode`. 92 | 93 | ## Alternatives considered 94 | 95 | ### Parameter of MaxRecords 96 | 97 | Modify the definition for `MaxRecords` node output attribute: 98 | 99 | | attribute | required | description | 100 | |:--- |:--------:|:------------| 101 | | `[MaxRecords(count, maxRecordsPerNode)]` | Y (this or below attribute) | Given uint `count` declaration, the thread group can output `0...count` records to this output. The variant with `maxRecordsPerNode` is required for `NodeArrayOutput`, where `count` applies across all the output nodes in the array and `maxRecordsPerNode` specifies the maximum number of records that can be written to a single output node within the array. Exceeding these limits results in undefined behavior. The value of `maxRecordsPerNode` must be less-than or equal to the value of `count`. These attributes can be overridden via the `NumOutputOverrides / pOutputOverrides` option when constructing a work graph as part of the [definition of a node](). See [Node output limits](). | 102 | 103 | Note: if the specification is `MaxRecords(count, maxRecordsPerNode)`, then multiple outputs that share budget using 104 | `MaxRecordsSharedWith` **must** also share the same value for `maxRecordsPerNode`. While in many cases this might be 105 | correct, this locks this requirement into the spec and restricts an implementation's ability to distinguish cases where 106 | they are different. We therefore prefer the option of specifying `MaxRecordsPerNode(count)` as a separate attribute. 107 | 108 | ### Optional Attribute 109 | 110 | This attribute could be made optional, for maximum backward compatibility; i.e. existing SM6.8 Work Graphs compile with 111 | the newer Shader Model. When `MaxRecordsPerNode` is _not_ specified, the implicit value of `MaxRecordsPerNode` is 112 | equal to `MaxRecords`. This also avoids redundant attribute specifications for those usage models where the values of 113 | `MaxRecords` and `MaxRecordsPerNode` are identical. However, for performance reasons, this was made a required 114 | attribute with a compiler fall back for backward compatibilty. 115 | 116 | 117 | -------------------------------------------------------------------------------- /proposals/0030-dxil-vectors.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # DXIL Vectors 4 | 5 | --- 6 | 7 | * Proposal: [0030](0030-dxil-vectors.md) 8 | * Author(s): [Greg Roth](https://github.com/pow2clk) 9 | * Sponsor: [Greg Roth](https://github.com/pow2clk) 10 | * Status: **Under Consideration** 11 | * Planned Version: Shader Model 6.9 12 | 13 | ## Introduction 14 | 15 | While DXIL is intended and able to support language vectors, 16 | those vectors must be broken up into individual scalars to be valid DXIL. 17 | This feature introduces the ability to represent native vectors in DXIL for some uses. 18 | 19 | ## Motivation 20 | 21 | Although many GPUs support vector operations, DXIL has been unable to directly leverage those capabilities. 22 | Instead, it has scalarized all vector operations, losing their original representation. 23 | To restore those vector representations, platforms have had to rely on auto-vectorization to 24 | rematerialize vectors late in the compilation. 25 | Scalarization is a trivial compiler transformation that never fails, 26 | but auto-vectorization is a notoriously difficult compiler optimization that frequently generates sub-optimal code. 27 | Allowing DXIL to retain vectors as they appeared in source allows hardware that can utilize 28 | vector optimizations to do so more easily without penalizing hardware that requires scalarization. 29 | 30 | Native vector support can also help with the size of compiled DXIL programs. 31 | Vector operations can express in a single instruction operations that would have taken N instructions in scalar DXIL. 32 | This may allow reduced file sizes for compiled DXIL programs that utilize vectors. 33 | 34 | DXIL is based on LLVM 3.7 which already supports native vectors. 35 | These could only be used to a limited degree in DXIL library targets, and never for DXIL operations. 36 | This innate support is expected to make adding them a relatively low impact change to DXIL tools. 37 | 38 | ## Proposed solution 39 | 40 | Native vectors are allowed in DXIL version 1.9 or greater. 41 | These can be stored in allocas, static globals, groupshared variables, and SSA values. 42 | They can be loaded from or stored to raw buffers and used as arguments to a selection 43 | of element-wise intrinsic functions as well as the standard math operators. 44 | They cannot be used in shader signatures, constant buffers, typed buffer, or texture types. 45 | 46 | ## Detailed design 47 | 48 | ### Vectors in memory representations 49 | 50 | In their alloca and variable representations, vectors in DXIL will always be represented as vectors. 51 | Previously individual vectors would get scalarized into scalar arrays and arrays of vectors would be flattened 52 | into a one-dimensional scalar array with indexing to reflect the original intents. 53 | Individual vectors will now be represented as a single native vector and arrays of vectors will remain 54 | as arrays of native vectors, though multi-dimensional arrays will still be flattened to one dimension. 55 | 56 | Single-element vectors are generally not valid in DXIL. 57 | At the language level, they may be supported for corresponding intrinsic overloads, 58 | but such vectors should be represented as scalars in the final DXIL output. 59 | Since they only contain a single scalar, single-element vectors are 60 | informationally equivalent to actual scalars. 61 | Rather than include conversions to and from scalars and single-element vectors, 62 | it is cleaner and functionally equivalent to represent these as scalars in DXIL. 63 | The exception is in exported library functions, which need to maintain vector representations 64 | to correctly match overloads when linking. 65 | 66 | ### Changes to DXIL Intrinsics 67 | 68 | A new form of rawBufferLoad allows loading of full vectors instead of four scalars. 69 | The status integer for tiled resource access is loaded just as before. 70 | The returned vector value and the status indicator are grouped into a new `ResRet` helper structure type 71 | that the load intrinsic returns. 72 | 73 | ```asm 74 | ; overloads: SM6.9: f16|f32|i16|i32 75 | ; returns: status, vector 76 | declare %dx.types.ResRet.v[NUM][TY] @dx.op.rawBufferVectorLoad.v[NUM][TY]( 77 | i32, ; opcode 78 | %dx.types.Handle, ; resource handle 79 | i32, ; coordinate c0 (byteOffset) 80 | i32, ; coordinate c1 (elementOffset) 81 | i32) ; alignment 82 | ``` 83 | 84 | 85 | The return struct contains a single vector and a single integer representing mapped tile status. 86 | 87 | ```asm 88 | %dx.types.ResRet.v[NUM][TY] = type { vector, i32 } 89 | ``` 90 | 91 | Here and hereafter, `NUM` is the number of elements in the loaded vector, `TYPE` is the element type name, 92 | and `TY` is the corresponding abbreviated type name (e.g. `i64`, `f32`). 93 | 94 | #### Vector access 95 | 96 | Dynamic access to vectors were previously converted to array accesses. 97 | Native vectors can be dynamically accessed using `extractelement`, `insertelement`, or `getelementptr` operations. 98 | Previously usage of `extractelement` and `insertelement` in DXIL didn't allow dynamic index parameters. 99 | 100 | #### Elementwise intrinsics 101 | 102 | A selection of elementwise intrinsics are given additional native vector forms. 103 | The full list of intrinsics with elementwise overloads is listed in [Appendix 1](#appendix-1-new-elementwise-overloads). 104 | Elementwise intrinsics are those that perform their calculations irrespective of the location of the element 105 | in the vector or matrix arguments except insofar as that position corresponds to those of the other elements 106 | that might be used in the individual element calculations. 107 | An elementwise intrinsic `foo` that takes scalar or vector arguments could theoretically implement its vector version using a simple loop and the scalar intrinsic variant. 108 | 109 | ```c++ 110 | vector foo(vector a, vector b) { 111 | vector ret; 112 | for (int i = 0; i < NUM; i++) 113 | ret[i] = foo(a[i], b[i]); 114 | } 115 | ``` 116 | 117 | For example, `fma` is an elementwise intrinsic because it multiplies or adds each element of its argument vectors, 118 | but `cross` is not because it performs an operation on the vectors as units, 119 | pulling elements from different locations as the operation requires. 120 | 121 | The elementwise intrinsics that have native vector variants represent the 122 | unary, binary, and tertiary generic operations: 123 | 124 | ```asm 125 | <[NUM] x [TYPE]> @dx.op.unary.v[NUM][TY](i32 opcode, <[NUM] x [TYPE]> operand1) 126 | <[NUM] x [TYPE]> @dx.op.binary.v[NUM][[TY]](i32 opcode, <[NUM] x [TYPE]> operand1, <[NUM] x [TYPE]> operand2) 127 | <[NUM] x [TYPE]> @dx.op.tertiary.v[NUM][TY](i32 opcode, <[NUM] x [TYPE]> operand1, <[NUM] x [TYPE]> operand2, <[NUM] x [TYPE]> operand3) 128 | ``` 129 | 130 | The scalar variants of these DXIL intrinsics will remain unchanged and can be used in conjunction 131 | with the vector variants. 132 | This means that the same language-level vector (of any length) could be used 133 | in scalarized operations and native vector operations even within the same shader. 134 | 135 | ### Validation Changes 136 | 137 | Blanket validation errors for use of native vectors DXIL are removed. 138 | Specific disallowed usages of native vector types will be determined by 139 | examining arguments to operations and intrinsics and producing errors where appropriate. 140 | Aggregate types will be recursed into to identify any native vector components. 141 | 142 | Native vectors should produce validation errors when: 143 | 144 | * Used in cbuffers. 145 | * Used in unsupported intrinsics or operations as before, but made more specific to the operations. 146 | * Any usage in previous shader model shaders apart from exported library functions. 147 | 148 | Error should be produced for any representation of a single element vector outside of 149 | exported library functions. 150 | 151 | Specific errors might be generated for invalid overloads of `LoadInput` and `StoreOutput` 152 | as they represent usage of vectors in entry point signatures. 153 | 154 | ### Device Capability 155 | 156 | Devices that support Shader Model 6.9 will be required to fully support this feature. 157 | 158 | ## Testing 159 | 160 | ### Compilation Testing 161 | 162 | A compiler targeting shader model 6.9 should be able to represent vectors in the supported memory spaces 163 | in their native form and generate native calls for supported intrinsics. 164 | 165 | Test that appropriate output is produced for: 166 | 167 | * Supported intrinsics and operations will retain vector types. 168 | * Dynamic indexing of vectors produces the correct `extractelement`, `insertelement` 169 | operations with dynamic index parameters. 170 | 171 | ### Validation testing 172 | 173 | The DXIL 6.9 validator should allow native vectors in the supported memory and intrinsic uses. 174 | It should produce errors for uses in unsupported intrinsics, cbuffers, and typed buffers. 175 | 176 | Single-element vectors are allowed only as interfaces to library shaders. 177 | Other usages of a single element vector should produce a validation error. 178 | 179 | ### Execution testing 180 | 181 | Full runtime execution should be tested by using the native vector intrinsics using 182 | groupshared and non-groupshared memory. 183 | Calculations should produce the correct results in all cases for a range of vector sizes. 184 | In practice, this testing will largely represent verifying correct intrinsic output 185 | with the new shader model. 186 | 187 | ## Appendix 1: New Elementwise Overloads 188 | 189 | | Opcode | Name | Class | 190 | | ------ | -------------- | -------- | 191 | | 6 | FAbs | Unary | 192 | | 7 | Saturate | Unary | 193 | | 8 | IsNaN | IsSpecialFloat | 194 | | 9 | IsInf | IsSpecialFloat | 195 | | 10 | IsFinite | IsSpecialFloat | 196 | | 11 | IsNormal | IsSpecialFloat | 197 | | 12 | Cos | Unary | 198 | | 13 | Sin | Unary | 199 | | 14 | Tan | Unary | 200 | | 15 | Acos | Unary | 201 | | 16 | Asin | Unary | 202 | | 17 | Atan | Unary | 203 | | 18 | Hcos | Unary | 204 | | 19 | Hsin | Unary | 205 | | 20 | Htan | Unary | 206 | | 21 | Exp | Unary | 207 | | 22 | Frc | Unary | 208 | | 23 | Log | Unary | 209 | | 24 | Sqrt | Unary | 210 | | 25 | Rsqrt | Unary | 211 | | 26 | Round_ne | Unary | 212 | | 27 | Round_ni | Unary | 213 | | 28 | Round_pi | Unary | 214 | | 29 | Round_z | Unary | 215 | | 30 | Bfrev | Unary | 216 | | 31 | Countbits | UnaryBits | 217 | | 32 | FirstBitLo | UnaryBits | 218 | | 33 | FirstBitHi | UnaryBits | 219 | | 34 | FirstBitSHi | UnaryBits | 220 | | 35 | FMax | Binary | 221 | | 36 | FMin | Binary | 222 | | 37 | IMax | Binary | 223 | | 38 | IMin | Binary | 224 | | 39 | UMax | Binary | 225 | | 40 | UMin | Binary | 226 | | 46 | FMad | Tertiary | 227 | | 47 | Fma | Tertiary | 228 | | 48 | IMad | Tertiary | 229 | | 49 | UMad | Tertiary | 230 | | 83 | DerivCoarseX | Unary | 231 | | 84 | DerivCoarseY | Unary | 232 | | 85 | DerivFineX | Unary | 233 | | 86 | DerivFineY | Unary | 234 | | 115 | WaveActiveAllEqual | WaveActiveAllEqual | 235 | | 117 | WaveReadLaneAt | WaveReadLaneAt | 236 | | 118 | WaveReadLaneFirst | WaveReadLaneFirst | 237 | | 119 | WaveActiveOp | WaveActiveOp | 238 | | 120 | WaveActiveBit | WaveActiveBit | 239 | | 121 | WavePrefixOp | WavePrefixOp | 240 | | 122 | QuadReadLaneAt | QuadReadLaneAt | 241 | | 123 | QuadOp | QuadOp | 242 | | 124 | BitcastI16toF16 | BitcastI16toF16 | 243 | | 125 | BitcastF16toI16 | BitcastF16toI16 | 244 | | 126 | BitcastI32toF32 | BitcastI32toF32 | 245 | | 127 | BitcastF32toI32 | BitcastF32toI32 | 246 | | 128 | BitcastI64toF64 | BitcastI64toF64 | 247 | | 129 | BitcastF64toI64 | BitcastF64toI64 | 248 | | 165 | WaveMatch | WaveMatch | 249 | 250 | 251 | 252 | ## Acknowledgments 253 | 254 | * [Anupama Chandrasekhar](https://github.com/anupamachandra) and [Tex Riddell](https://github.com/tex3d) for foundational contributions to the design. 255 | 256 | 257 | -------------------------------------------------------------------------------- /proposals/0032-constructors.md: -------------------------------------------------------------------------------- 1 | # Constructors 2 | 3 | * Proposal: [0032](0032-constructors.md) 4 | * Author(s): [Chris Bieneman](https://github.com/llvm-beanz) 5 | * Sponsor: [Chris Bieneman](https://github.com/llvm-beanz) 6 | * Status: **Under Consideration** 7 | * Planned Version: 202y 8 | 9 | ## Introduction 10 | 11 | As user defined data structures get more common and complex, the absence of 12 | constructors and destructors is more and more awkward. This proposal seeks to 13 | bring the full features of C++ initialization and destruction into HLSL. 14 | 15 | ## Motivation 16 | 17 | Constructors are incredibly useful for ensuring data initialization and 18 | implementing common patterns like Resource-Acquisition-Is-Initialization (RAII). 19 | 20 | ## Proposed solution 21 | 22 | Introduce the following features to HLSL: 23 | * C++ Constructors and Destructors 24 | * C++ 11 Delegating Constructors 25 | * C++ 11 Default and Deleted methods 26 | * C++ 11 Default initializers 27 | * Clang __attribute__((constructor)) and __attribute__((destructor)) 28 | 29 | Constructor syntax will match C++ 11 constructor syntax including support for 30 | delegating constructors. It will be available on all user-defined data types 31 | that support constructors in C++. 32 | 33 | ## Detailed design 34 | 35 | ### Global Construction 36 | 37 | HLSL global constructors will be ordered following C++ conventions. 38 | Constant-evaluated initializers occur first, followed by non-constant 39 | initializers which are ordered by declaration order in the translation unit. 40 | 41 | Each entry function will call the global constructors before executing any 42 | further instructions and the global destructor immediately before returning. 43 | 44 | In library shaders, the entry translation unit's global constructors are 45 | executed after the linked library global constructors, and the entry's global 46 | destructors are executed before linked library global destructors. 47 | 48 | Non-trivial global constructors **will not** be stripped from library shaders. 49 | Meaning, an unused global with a non-trivial constructor will be linked into the 50 | final linked shader binary. This conforms to the C++ standard definitions for 51 | static storage duration (see: ISO C++ Standard _basic.stc.static_). 52 | 53 | Due to the inherent performance drawbacks of global construction, warnings will 54 | be issued by default for any code that introduces a non-trivial global 55 | constructor. 56 | 57 | ### Constructing Groupshared 58 | 59 | Constructor initialization of `groupshared` objects will be followed by a memory 60 | barrier and group sync. This comes with inherent performance costs, so shader 61 | authors should use constructors with `groupshared` objects sparingly. 62 | 63 | A `groupshared` user defined object that does not have a constructor, or has a 64 | constructor that does not initialize any of its fields, will not incur the 65 | memory barrier. 66 | 67 | Due to the inherent performance drawbacks of `groupshared` construction, 68 | warnings will be issued by default for any code that introduces a `groupshared` 69 | object constructor. 70 | 71 | ### Constructors and Semantic Annotations 72 | 73 | When a user defined data type contains members which are annotated with semantic 74 | attributes and the data structure is initialized as a global or as a parameter 75 | to the entry function, the semantic will be applied to the field after the 76 | default constructor executes. 77 | 78 | For example: 79 | 80 | ```c++ 81 | struct VSIn { 82 | uint ID : SV_VertexID; 83 | float F; 84 | 85 | VSIn() : ID(0), F(1.0) {} 86 | }; 87 | 88 | float4 main(in VSIn In) : SV_Position 89 | { 90 | // In.vid is SV_VertexID, In.f is 1.0 91 | VSIn In2; 92 | // In2.vid is 0, In.f is 1.0 93 | } 94 | ``` 95 | 96 | Currently HLSL requires that all members of a user defined data type passed into 97 | an entry function must have semantic annotations to initialize the structure. 98 | With the addition of constructors and default value initialization, HLSL will 99 | instead require that every field either have a semantic annotation, or a default 100 | initialization through either a default constructor or a default initializer. 101 | 102 | HLSL will also introduce default initialization and defaulted and deleted 103 | constructors. Default initialization is incompatible with HLSL annotations, and 104 | can only be used on variable declarations that either use C++ attributes for 105 | annotations, or have no annotation (see: 106 | [proposal for C++ Attributes](0002-cxx-attributes.md)). 107 | 108 | HLSL will adopt C++ rules for implicitly defining special member functions as 109 | defined in the C++ 11 specification under 110 | [`[special]`](https://timsong-cpp.github.io/cppwp/n3337/#special). This will 111 | include a default constructor, destructor, copy constructor, move constructor, 112 | and copy assignment operator, and move assignment operator. 113 | 114 | For example: 115 | 116 | ```c++ 117 | struct VSIn { 118 | uint ID : SV_VertexID = 2; // invalid 119 | uint ID = 2 : SV_VertexID; // invalid 120 | [[hlsl::SV_VertexID]] uint ID = 2; // valid 121 | float F = 1.0; // valid 122 | 123 | VSIn() = default; 124 | }; 125 | 126 | float4 main(in VSIn In) : SV_Position 127 | { 128 | // In.vid is SV_VertexID, In.f is 1.0 129 | VSIn In2; 130 | // In2.vid is 0, In.f is 1.0 131 | } 132 | ``` 133 | -------------------------------------------------------------------------------- /proposals/0033-dxil19.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # DXIL 1.9 4 | 5 | * Proposal: [0033](0033-dxil19.md) 6 | * Author(s): [Damyan Pepper](https://github.com/damyanp) 7 | * Sponsor: [Damyan Pepper](https://github.com/damyanp) 8 | * Status: **Under Review** 9 | * Planned Version: Shader Model 6.9 10 | 11 | ## Introduction 12 | 13 | Shader Model 6.9 introduces new features to HLSL which need representations in 14 | DXIL. This proposal provides an index of the new features: 15 | 16 | 17 | ## Opacity Micromaps 18 | 19 | [Proposal 0024] - Opacity Micromaps (OMM) 20 | 21 | This adds a new DXIL op, `AllocateRayQuery2` and some new flags. 22 | 23 | 24 | ## Shader Execution Reordering 25 | 26 | [Proposal 0027] - Shader Execution Reordering (SER) 27 | 28 | This adds a new DXIL type, `%dx.types.HitObject` and 30 new DXIL ops. 29 | 30 | 31 | ## DXIL Vectors 32 | 33 | [Proposal 0030] - DXIL Vectors 34 | 35 | This enables native vectors, as supported by LLVM 3.7, in DXIL 1.9. A new 36 | `rawBufferVectorLoad` opcode is added that loads an entire vector. Elementwise 37 | intrinsics are extended to accept vector arguments. 38 | 39 | The HLSL changes related to this feature can be found in [Proposal 0026] - HLSL 40 | Long Vector Type. 41 | 42 | 43 | ## Cooperative Vectors 44 | 45 | [Proposal 0029] - Cooperative Vector 46 | 47 | This enables hardware-accelerated multiplation of vectors with matrices. Four 48 | new opcodes are added - `matvecmul`, `matvecmuladd`, `outerproductaccumulate`, 49 | `vectoraccumulate`. 50 | 51 | The HLSL API related to this feature can be found in [Proposal 0031] - HLSL 52 | Vector / Matrix Operations. 53 | 54 | 55 | [Proposal 0024]: 0024-opacity-micromaps.md 56 | [Proposal 0026]: 0026-hlsl-long-vector-type.md 57 | [Proposal 0027]: 0027-shader-execution-reordering.md 58 | [Proposal 0029]: 0029-cooperative-vector.md 59 | [Proposal 0030]: 0030-dxil-vectors.md 60 | [Proposal 0031]: 0031-hlsl-vector-matrix-operations.md 61 | 62 | 63 | -------------------------------------------------------------------------------- /proposals/0034-vk-sampled-texture.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Vulkan Sampled Textures 4 | 5 | * Proposal: [0034](0034-vk-sampled-texture.md) 6 | * Author(s): [Cassandra Beckley](https://github.com/cassiebeckley) 7 | * Sponsor: [Steven Perron](https://github.com/s-perron) and TBD 8 | * Status: **Under Consideration** 9 | * Required Version: HLSL 2021 10 | 15 | 16 | ## Introduction 17 | 18 | We propose a new set of `vk::SampledTexture*` texture types representing 19 | Vulkan's combined image sampler types (`OpTypeSampledImage`). 20 | 21 | ## Motivation 22 | 23 | The [existing annotation](https://github.com/microsoft/DirectXShaderCompiler/wiki/Vulkan-combined-image-sampler-type) 24 | for combined image samplers (`[[vk::combinedImageSampler]]`) was designed with 25 | the explicit goal of avoiding defining new HLSL types and functions. This was 26 | intended to minimize the number of changes to the frontend needed to implement 27 | the feature. However, it is verbose, confusing for users, and requires a 28 | backend pass to pair up textures and samplers which is prone to subtle errors. 29 | We do not intend to implement it in upstream Clang. 30 | 31 | ## High-level description 32 | 33 | The `vk::SampledTexture*` types will have the same interface and methods as the 34 | existing `Texture*` types, with the exception that the methods will not take a 35 | sampler state argument. 36 | 37 | Consider this example pixel shader which uses a texture: 38 | 39 | ```hlsl 40 | Texture2D tex0 : register(t0); 41 | SamplerState s : register(s0); 42 | 43 | float4 main(float2 uv: TEXCOORD) : SV_Target { 44 | return tex0.Sample(s, uv); 45 | } 46 | ``` 47 | 48 | Using the proposed types, this could be rewritten to use a combined image 49 | sampler: 50 | 51 | ```hlsl 52 | vk::SampledTexture2D tex0 : register(t0); 53 | 54 | float4 main(float2 uv: TEXCOORD) : SV_Target { 55 | return tex0.Sample(uv); 56 | } 57 | ``` 58 | 59 | This is simpler and a more accurate representation of the underlying interface 60 | than using the existing annotation, which looks like: 61 | 62 | ```hlsl 63 | [[vk::combinedImageSampler]] 64 | Texture2D tex0 : register(t0); 65 | [[vk::combinedImageSampler]] 66 | SamplerState s : register(s0); 67 | 68 | float4 main(float2 uv: TEXCOORD) : SV_Target { 69 | return tex0.Sample(s, uv); 70 | } 71 | ``` 72 | 73 | A benefit of the `[[vk::combinedImageSampler]]` annotation is the ability to 74 | use the same code to represent a combined image sampler in Vulkan and a 75 | separate texture and sampler in DirectX. The new types will only be usable with 76 | Vulkan, but a similar effect can be produced by checking for the existence of 77 | the `__spirv__` macro. 78 | 79 | ## Detailed design 80 | 81 | ### HLSL Additions 82 | 83 | The following resource types will be added to the `vk` namespace: 84 | 85 | | HLSL Object | Type Parameters | 86 | |---------------------------|-----------------------------------| 87 | | `SampledTexture1D` | _type_ | 88 | | `SampledTexture1DArray` | _type_ | 89 | | `SampledTexture2D` | _type_ | 90 | | `SampledTexture2DArray` | _type_ | 91 | | `SampledTexture2DMS` | _type_, uint _samples_ | 92 | | `SampledTexture2DMSArray` | _type_, uint _samples_ | 93 | | `SampledTexture3D` | _type_ | 94 | | `SampledTextureCUBE` | _type_ | 95 | | `SampledTextureCUBEArray` | _type_ | 96 | 97 | As with the `Texture*` types, the _type_ parameter may be omitted, in which 98 | it will default to `float4`. Values of these types may be assigned to specific 99 | registers or annotated with the Vulkan binding annotations. 100 | 101 | The following builtin methods will be defined for these types: 102 | 103 | * `CalculateLevelOfDetail` 104 | * `CalculateLevelOfDetailUnclamped` 105 | * `Gather` 106 | * `GetDimensions` 107 | * `GetSamplePosition` 108 | * `Load` 109 | * `Sample` 110 | * `SampleBias` 111 | * `SampleCmp` 112 | * `SampleCmpLevelZero` 113 | * `SampleGrad` 114 | * `SampleLevel` 115 | 116 | They will have the same interface as the corresponding methods for the 117 | `Texture*` types, with the exception that they will not take a `SamplerState` 118 | or `SamplerComparisonState` argument. (SPIR-V does not have separate sampler 119 | types for comparison operations, and the combined sampler will be sufficient 120 | for all methods listed). 121 | 122 | `[[vk::combinedImageSampler]]` will be marked as deprecated in HLSL 2021, and 123 | removed in HLSL 202x. 124 | 125 | A new feature check `__has_feature(hlsl_vk_sampled_texture)` will be added to 126 | the preprocessor. 127 | 128 | ### Interchange Format Additions 129 | 130 | This proposal exists to better represent an existing feature of SPIR-V, and no 131 | changes to the specification will be required. Since this is a Vulkan-specific 132 | feature scoped to the `vk` namescape, no changes to the DXIL format or DXIL 133 | lowering will be required. 134 | 135 | The `vk::SampledTexture*` types will be lowered to SPIR-V `OpTypeSampledImage` 136 | type declarations, with an _Image Type_ operand which will be the `OpTypeImage` 137 | produced by lowering the equivalent `Texture*` type. 138 | 139 | The builtin methods will be lowered to the same instructions as the equivalent 140 | methods for `Texture*` types. SPIR-V instructions which operate on images take 141 | these images in one of two formats: either an `OpTypeImage`, for instructions 142 | which do not require a sampler, or an `OpTypeSampledImage`, for instructions 143 | which do. For instructions which require an `OpTypeImage`, we can obtain such 144 | a value by passing the `OpTypeSampledImage` value to the `OpImage` instruction. 145 | 146 | We will likely represent these types in LLVM IR for upstream Clang by the 147 | addition of a new "sampled" attribute for the resource type. 148 | 149 | ### Diagnostic Changes 150 | 151 | The `vk::SampledTexture*` types and builtin methods should provide the same 152 | diagnostics as the corresponding `Texture*` types. 153 | 154 | #### Validation Changes 155 | 156 | No additional changes to the SPIR-V validator will be required. 157 | 158 | ### Runtime Additions 159 | 160 | No runtime additions or information are required. 161 | 162 | #### Device Capability 163 | 164 | `OpTypeSampledImage` is a core feature of SPIR-V, and part of Vulkan since 1.0. 165 | It should be supported by all existing Vulkan hardware. No changes to either 166 | drivers or hardware will be needed. 167 | 168 | ## Testing 169 | 170 | The existing tests for the SPIR-V lowering of `Texture*` types can be expanded 171 | to ensure that `vk::SampledTexture` types exhibit the same behavior, in all 172 | cases. 173 | 174 | ## Alternatives considered 175 | 176 | We considered using a `vk::Sampled` template that would take a texture as a 177 | template parameter. For example, `vk::Sampled >`. We decided against 178 | this as it would require additional validation that the template parameter is a 179 | texture type, and because HLSL has an existing convention for resource types to 180 | have additional behavior by prepending information to the type name – for 181 | example, `Buffer` to `RWBuffer` and `RWStructuredBuffer`. 182 | 183 | We also considered using inline SPIR-V for implementation; however, doing so 184 | would require the ability to assign an HLSL-defined class an HLSL register 185 | and/or Vulkan location binding, and then use that register for a member 186 | variable of the class holding the low-level inline SPIR-V representation. We 187 | decided that such a mechanism would be too general, as new resource types in 188 | HLSL are rare and users should not have the ability to create them themselves. 189 | 190 | 191 | -------------------------------------------------------------------------------- /proposals/index.md: -------------------------------------------------------------------------------- 1 | # Current Active Proposals 2 | 3 | {% assign doclist = site.pages | sort: 'url' %} 4 | {% for doc in doclist %} 5 | {% if doc.name contains '.md' and doc.dir == '/proposals/' and doc.name != 'index.md' %} 6 | * [{{ doc.name }}]({{ doc.url | relative_url }}) 7 | {% endif %} 8 | {% endfor %} 9 | -------------------------------------------------------------------------------- /proposals/infra/INF-0005-validator-backcompat-testing.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Feature name 4 | 5 | ## Instructions 6 | 7 | * Proposal: [INF-0005](INF-0005-validator-backcompat-testing.md) 8 | * Author(s): [Damyan Pepper](https://github.com/damyanp) 9 | * Sponsor: [Damyan Pepper](https://github.com/damyanp) 10 | * Status: **Under Consideration** 11 | * Impacted Project(s): DXC 12 | 13 | ## Introduction 14 | 15 | We propose moving the DXC validator backwards compatability tests from a 16 | private, internal, repo to the public one, cleaning up the mechanisms that 17 | enable this as we go. 18 | 19 | ## Motivation 20 | 21 | Currently, internal builds of DXC perform various tests that involve running DXC 22 | against older versions of the validator (dxil.dll). This is to ensure that 23 | modifications to DXC (including modifications to the validator) don't break 24 | backwards compatability with previously released versions. In the past, the 25 | validator was closed source and so these tests were run from internal builds. 26 | 27 | We've recently [open sourced the validator](./INF-0004-validator-hashing.md) and 28 | as part of this work we want to make DXC default to using the built-in, 29 | "internal", validator rather than one loaded from a dll, and this breaks these 30 | tests. 31 | 32 | While we're fixing these tests, we're going to take this opportunity to move the 33 | back-compat testing into the public repo and simplify the infrastructure 34 | required to run them. 35 | 36 | 37 | ## Proposed solution 38 | 39 | ### How it works currently 40 | 41 | These tests only run for Windows x64 builds. The internal build pipeline runs 42 | `mm test --validator-backcompat-all`. This script has a list of old dxil.dll 43 | versions to test. The DLL's themselves are checked into the repo. Before running 44 | each test the dxil.dll is copied into directory next to dxc.exe, with the 45 | intention that this is the one that DXC will pick up. (Note: in the past we've 46 | accidentally packaged up and released one of these old dxil.dll.) 47 | 48 | The tests themselves are run via lit. 49 | 50 | Most of the tests assume that the external validator is used, although a small 51 | number explicitly set `-select-validator internal` so that when that test runs 52 | it uses the internal validator - effectively making the test pointless in the 53 | back compat suite. 54 | 55 | There are also TAEF tests that invoke the compiler via the API. We need to 56 | ensure that these continue to work. 57 | 58 | ### Proposed Changes 59 | 60 | The tests run via binaries downloaded from github releases and are integrated 61 | into the cmake build system so they can be run from a single target. 62 | 63 | 64 | ## Detailed design 65 | 66 | These tests are integrated into the build system and can be invoked via a cmake 67 | target. eg `cmake --build . --target check-validator-backwards-compatability`. 68 | This target is not run by default, since most developers won't want to download 69 | the binaries and run these tests. 70 | 71 | 72 | ### Binaries 73 | 74 | Rather than check the binaries in to source control, we can download them from 75 | github.com as zip files. `ExternalProject_Add` can be used to do this. 76 | 77 | ### Specifying which DXIL.dll to use 78 | 79 | The `-select-validator` option will be deprecated. As this is not documented, 80 | it should be ok to just remove it entirely. 81 | 82 | A new option, `-dxil-dll-path`, can be used to specify the full path to dxil.dll 83 | to use. Example path: `c:\dxc\build\old-releases\1.7.123\bin\x64\dxil.dll`. 84 | 85 | Setting the path to an empty string forces the internal validator to be used. 86 | 87 | If a dll path is specified and isn't found then the compiler will fail with an 88 | error. 89 | 90 | When invoked via dxc.exe, DXC will check for a new environment variable, 91 | `DXC_DXIL_DLL_PATH`, that specifies the full path to the dll. The command-line 92 | option takes precedance over the environment variable. This environment variable 93 | is not used when invoking the compile via the API since this could be abused to 94 | inject arbitrary DLLs into unsuspecting processes. 95 | 96 | When an external validator is used a warning diagnostic is emitted. Since the 97 | only expected use of this option is the backcompat tests, having this always 98 | appear in the test logs should be helpful when diagnosing issues. 99 | 100 | 101 | ### Invoking the tests 102 | 103 | The tests are invoked via `add_custom_command`, using `cmake -E env` to set the 104 | `DXC_DXIL_DLL_PATH` variable. 105 | 106 | ### New Tests 107 | 108 | As well as testing old external validators, we also need to run the same set of 109 | tests against current external validator. 110 | 111 | This means we need to test: 112 | 113 | * internal validator 114 | * latest external validator 115 | * previouslly released external validators 116 | 117 | ## Alternatives Considered 118 | 119 | ### Requirement for full path 120 | 121 | We considered allowing relative paths to specify the dll. However, best practice 122 | for loading DLLs is to use absolute paths and since in the expected scenarios 123 | for this functionality we know exactly which DLL we want to use the decision was 124 | made to require an absolute path to the DLL. 125 | 126 | 127 | ### Diagnostic when using External Validator 128 | 129 | We considered that we should only show the diagnostic when the compiler is 130 | invoked via dxc.exe and not when it is used via the API, on the basis that 131 | emitting a warning when the API is doing something that the user explicitly 132 | asked it to do is unusual. 133 | 134 | Another consideration was to only output the path to the validator in the case 135 | that validation failed. 136 | 137 | Since this API is only intended to be used scenarios for testing the compiler 138 | itself, the decision was made to always emit it in order to help with debugging 139 | via logs. 140 | 141 | 142 | 143 | ## Acknowledgments (Optional) 144 | 145 | * [Josh Batista](https://github.com/bob80905) 146 | * [Tex Riddell](https://github.com/tex3d) 147 | * [Chris Bieneman](https://github.com/llvm-beanz) 148 | 149 | 150 | -------------------------------------------------------------------------------- /proposals/infra/index.md: -------------------------------------------------------------------------------- 1 | # Current Active Proposals 2 | 3 | {% assign doclist = site.pages | sort: 'url' %} 4 | {% for doc in doclist %} 5 | {% if doc.name contains '.md' and doc.dir == '/proposals/' and doc.name != 'index.md' %} 6 | * [{{ doc.name }}]({{ doc.url | relative_url }}) 7 | {% endif %} 8 | {% endfor %} 9 | -------------------------------------------------------------------------------- /proposals/templates/basic-template.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Feature name 4 | 5 | ## Instructions 6 | 7 | > This template wraps at 80-columns. You don't need to match that wrapping, but 8 | > having some consistent column wrapping makes it easier to view diffs on 9 | > GitHub's review UI. Please wrap your lines to make it easier to review. 10 | 11 | > When filling out the template below for a new feature proposal, please do the 12 | > following first: 13 | 14 | > 1. exclude the "Planned Version", "PRs" and "Issues" from the header. 15 | > 2. Do not spend time writing the "Detailed design" until the feature has been 16 | > merged in the "Under Consideration" phase. 17 | > 3. Delete this Instructions section including the line below. 18 | 19 | --- 20 | 21 | * Proposal: [NNNN](NNNN-filename.md) 22 | * Author(s): [Author 1](https://github.com/author_username) 23 | * Sponsor: TBD 24 | * Status: **Under Consideration** 25 | 26 | *During the review process, add the following fields as needed:* 27 | 28 | * Planned Version: 20YY 29 | * PRs: [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/pull/NNNN) 30 | * Issues: 31 | [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/issues/NNNN) 32 | 33 | ## Introduction 34 | 35 | 10,000 ft view of the change being proposed. Try to keep to one paragraph and 36 | less than 10 sentences. 37 | 38 | ## Motivation 39 | 40 | Describe the problems users are currently facing that this feature addresses. 41 | Include concrete examples, links to related issues, and any relevant background. 42 | 43 | The point of this section is not to convince reviewers that you have a solution, 44 | but rather that HLSL has a problem that needs to be resolved. 45 | 46 | ## Proposed solution 47 | 48 | Describe your solution to the problem. Provide examples and describe how they 49 | work. Show how your solution is better than current workarounds: is it cleaner, 50 | safer, or more efficient? 51 | 52 | ## Detailed design 53 | 54 | _The detailed design is not required until the feature is under review._ 55 | 56 | This section should grow into a feature specification that will live in the 57 | specifications directory once complete. Each feature will need different levels 58 | of detail here, but some common things to think through are: 59 | 60 | * How is this feature represented in the grammar? 61 | * How does it work interact other HLSL features (semantics, buffers, etc)? 62 | * How does this interact with C++ features that aren't already in HLSL? 63 | * Does this have implications for existing HLSL source code compatibility? 64 | * Does this change require DXIL changes? 65 | * Can it be CodeGen'd to SPIR-V? 66 | 67 | ## Alternatives considered (Optional) 68 | 69 | If alternative solutions were considered, please provide a brief overview. This 70 | section can also be populated based on conversations that occur during 71 | reviewing. 72 | 73 | ## Acknowledgments (Optional) 74 | 75 | Take a moment to acknowledge the contributions of people other than the author 76 | and sponsor. 77 | 78 | 79 | -------------------------------------------------------------------------------- /proposals/templates/extension-template.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Feature name 4 | 5 | ## Instructions 6 | 7 | > This template is a guideline for documenting a platform or vendor extension. 8 | > For a feature to be a conforming extension it must not change language 9 | > behaviors. It can introduce new builtin functions, data types, and annotating 10 | > attributes, but cannot introduce new language behaviors or rules. 11 | > 12 | > This template wraps at 80-columns. You don't need to match that wrapping, but 13 | > having some consistent column wrapping makes it easier to view diffs on 14 | > GitHub's review UI. Please wrap your lines to make it easier to review. 15 | > 16 | > Delete this Instructions section including the line below. 17 | 18 | --- 19 | 20 | * Proposal: [NNNN](NNNN-filename.md) 21 | * Author(s): [Author 1](https://github.com/author_username) 22 | * Sponsor: TBD 23 | * Status: **Accepted** 24 | * Required Version: Shader Model X.Y, Vulkan X.Y, and/or HLSL 20XY 25 | * PRs: [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/pull/NNNN) 26 | * Issues: 27 | [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/issues/NNNN) 28 | 29 | ## Introduction 30 | 31 | 10,000 ft view of the change being proposed. Try to keep to one paragraph and 32 | less than 10 sentences. 33 | 34 | ## Motivation 35 | 36 | Describe the problems users are currently facing that this feature addresses. 37 | Include concrete examples, links to related issues, and any relevant background. 38 | 39 | The point of this section is not to convince reviewers that you have a solution, 40 | but rather that HLSL has a problem that needs to be resolved. 41 | 42 | If there is an existing extension that solves a similar use case explain why it 43 | is insufficient, and how this extension is an improvement. 44 | 45 | ## High-level description 46 | 47 | Describe your solution to the problem. Provide examples and describe how they 48 | work. Show how your solution is better than current workarounds: is it cleaner, 49 | safer, or more efficient? 50 | 51 | ## Detailed design 52 | 53 | This section should describe the feature in enough technical detail that someone 54 | other than the author could implement it. Each feature will need different levels 55 | of detail here, but some common things to think through are: 56 | 57 | ### HLSL Additions 58 | 59 | * What new APIs and data types are added? 60 | * How does it interact with different shader stages? 61 | * How does it work interact other HLSL features (semantics, buffers, etc)? 62 | * Does this have implications for existing HLSL source code compatibility? 63 | * How will users detect if the compiler supports this feature? 64 | 65 | ### Interchange Format Additions 66 | 67 | * What DXIL and/or SPIR-V changes does this change require? 68 | * What Metadata changes does this require? 69 | * How will each new API and data type be lowered to the target format? 70 | 71 | ### Diagnostic Changes 72 | 73 | * What additional errors or warnings does this introduce? 74 | * What existing errors or warnings does this remove? 75 | 76 | #### Validation Changes 77 | 78 | * What additional validation failures does this introduce? 79 | * What existing validation failures does this remove? 80 | 81 | ### Runtime Additions 82 | 83 | #### Runtime information 84 | 85 | * What information does the compiler need to provide for the runtime and how? 86 | 87 | #### Device Capability 88 | 89 | * How does it interact with other platform or vendor extension options? 90 | * What underlying target requirements are prerequisite for the feature? 91 | * What portions are require an existing or new optional feature? 92 | * Can this feature be supported through emulation or some other means 93 | in older drivers/runtimes? 94 | 95 | ## Testing 96 | 97 | * How will correct codegen for DXIL/SPIRV be tested? 98 | * How will the diagnostics be tested? 99 | * How will validation errors be tested? 100 | * How will validation of new DXIL elements be tested? 101 | * How will the execution results be tested? 102 | 103 | ## Alternatives considered (Optional) 104 | 105 | If alternative solutions were considered, please provide a brief overview. This 106 | section can also be populated based on conversations that occur during 107 | reviewing. Having these solutions and why they were rejected documented may save 108 | trouble from those who might want to suggest feedback or additional features that 109 | might build on this on. Even variations on the chosen solution can be interesting. 110 | 111 | ## Acknowledgments (Optional) 112 | 113 | Take a moment to acknowledge the contributions of people other than the author 114 | and sponsor. 115 | 116 | 117 | -------------------------------------------------------------------------------- /proposals/templates/infrastructure-template.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Feature name 4 | 5 | ## Instructions 6 | 7 | > This template wraps at 80-columns. You don't need to match that wrapping, but 8 | > having some consistent column wrapping makes it easier to view diffs on 9 | > GitHub's review UI. Please wrap your lines to make it easier to review. 10 | 11 | > When filling out the template below for a new feature proposal, please do the 12 | > following first: 13 | 14 | > 1. exclude the "Planned Version", "PRs" and "Issues" from the header. 15 | > 2. Do not spend time writing the "Detailed design" until the feature has been 16 | > merged in the "Under Consideration" phase. 17 | > 3. Delete this Instructions section including the line below. 18 | 19 | --- 20 | 21 | * Proposal: [NNNN](NNNN-filename.md) 22 | * Author(s): [Author 1](https://github.com/author_username) 23 | * Sponsor: TBD 24 | * Status: **Under Consideration** 25 | * Impacted Project(s): (DXC, Clang, etc) 26 | 27 | *During the review process, add the following fields as needed:* 28 | 29 | * PRs: [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/pull/NNNN) 30 | * Issues: 31 | [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/issues/NNNN) 32 | * Posts: [LLVM Discourse](https://discourse.llvm.org/) 33 | 34 | ## Introduction 35 | 36 | 10,000 ft view of the change being proposed. Try to keep to one paragraph and 37 | less than 10 sentences. 38 | 39 | ## Motivation 40 | 41 | Describe the problems users are currently facing that this feature addresses. 42 | Include concrete examples, links to related issues, and any relevant background. 43 | 44 | The point of this section is not to convince reviewers that you have a solution, 45 | but rather that a problem needs to be resolved. 46 | 47 | ## Proposed solution 48 | 49 | Describe your solution to the problem. Provide examples and describe how they 50 | work. Show how your solution is better than current workarounds: is it cleaner, 51 | safer, or more efficient? 52 | 53 | ## Detailed design 54 | 55 | _The detailed design is not required until the feature is under review._ 56 | 57 | This section should grow into a full specification that will provide enough 58 | information for someone who isn't the proposal author to implement the feature. 59 | It should also serve as the basis for documentation for the feature. Each 60 | feature will need different levels of detail here, but some common things to 61 | think through are: 62 | 63 | * Is there any potential for changed behavior? 64 | * Will this expose new interfaces that will have support burden? 65 | * How will this proposal be tested? 66 | * Does this require additional hardware/software/human resources? 67 | * What documentation should be updated or authored? 68 | 69 | ## Alternatives considered (Optional) 70 | 71 | If alternative solutions were considered, please provide a brief overview. This 72 | section can also be populated based on conversations that occur during 73 | reviewing. 74 | 75 | ## Acknowledgments (Optional) 76 | 77 | Take a moment to acknowledge the contributions of people other than the author 78 | and sponsor. 79 | 80 | 81 | -------------------------------------------------------------------------------- /proposals/templates/shader-model-feature-template.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | # Feature name 4 | 5 | ## Instructions 6 | 7 | > This template is a guideline for documenting a shader model feature. 8 | > Unlike language-only features, these require DXIL changes and thereby if not 9 | > hardware support, then at least hardware driver support. 10 | > The section titles are meant to be retained in the final product, 11 | > but the descriptions are to outline what should be in those sections 12 | > and should be replaced by the feature-specific text. 13 | > However, not all sections may be required for all features. 14 | {} 15 | > This template wraps at 80-columns. You don't need to match that wrapping, but 16 | > having some consistent column wrapping makes it easier to view diffs on 17 | > GitHub's review UI. Please wrap your lines to make it easier to review. 18 | > 19 | > When filling out the template below for a new feature proposal, please do the 20 | > following first: 21 | > 22 | > 1. Exclude the "Planned Version", "PRs" and "Issues" from the header. 23 | > 2. Do not spend time writing the "Detailed design" until the feature has been 24 | > merged in the "Under Consideration" phase. 25 | > 3. Delete this Instructions section including the line below. 26 | 27 | --- 28 | 29 | * Proposal: [NNNN](NNNN-filename.md) 30 | * Author(s): [Author 1](https://github.com/author_username) 31 | * Sponsor: TBD 32 | * Status: **Under Consideration** 33 | 34 | *During the review process, add the following fields as needed:* 35 | 36 | * Planned Version: Shader Model X.Y 37 | * PRs: [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/pull/NNNN) 38 | * Issues: 39 | [#NNNN](https://github.com/microsoft/DirectXShaderCompiler/issues/NNNN) 40 | 41 | ## Introduction 42 | 43 | 10,000 ft view of the change being proposed. Try to keep to one paragraph and 44 | less than 10 sentences. 45 | 46 | ## Motivation 47 | 48 | Describe the problems users are currently facing that this feature addresses. 49 | Include concrete examples, links to related issues, and any relevant background. 50 | 51 | The point of this section is not to convince reviewers that you have a solution, 52 | but rather that HLSL has a problem that needs to be resolved. 53 | 54 | ## Proposed solution 55 | 56 | Describe your solution to the problem. Provide examples and describe how they 57 | work. Show how your solution is better than current workarounds: is it cleaner, 58 | safer, or more efficient? 59 | 60 | ## Detailed design 61 | 62 | *The detailed design is not required until the feature is under review.* 63 | 64 | This section should grow into a feature specification that will live in the 65 | specifications directory once complete. Each feature will need different levels 66 | of detail here, but some common things to think through are: 67 | 68 | ### HLSL Additions 69 | 70 | * How is this feature represented in the grammar? 71 | * How does it interact with different shader stages? 72 | * How does it work interact other HLSL features (semantics, buffers, etc)? 73 | * How does this interact with C++ features that aren't already in HLSL? 74 | * Does this have implications for existing HLSL source code compatibility? 75 | 76 | ### Interchange Format Additions 77 | 78 | * What DXIL changes does this change require? 79 | * What Metadata changes does this require? 80 | * How will SPIRV be supported? 81 | 82 | ### Diagnostic Changes 83 | 84 | * What additional errors or warnings does this introduce? 85 | * What existing errors or warnings does this remove? 86 | 87 | #### Validation Changes 88 | 89 | * What additional validation failures does this introduce? 90 | * What existing validation failures does this remove? 91 | 92 | ### Runtime Additions 93 | 94 | #### Runtime information 95 | 96 | * What information does the compiler need to provide for the runtime and how? 97 | 98 | #### Device Capability 99 | 100 | * How does it interact with other Shader Model options? 101 | * What shader model and/or optional feature is prerequisite for the bulk of 102 | this feature? 103 | * What portions are only available if an existing or new optional feature 104 | is present? 105 | * Can this feature be supported through emulation or some other means 106 | in older shader models? 107 | 108 | ## Testing 109 | 110 | * How will correct codegen for DXIL/SPIRV be tested? 111 | * How will the diagnostics be tested? 112 | * How will validation errors be tested? 113 | * How will validation of new DXIL elements be tested? 114 | * How will the execution results be tested? 115 | 116 | ## Transition Strategy for Breaking Changes (Optional) 117 | 118 | * Newly-introduced errors that cause existing shaders to newly produce errors 119 | fall into two categories: 120 | * Changes that produce errors from already broken shaders that previously 121 | worked due to a flaw in the compiler. 122 | * Changes that break previously valid shaders due to changes in what the compiler 123 | accepts related to this feature. 124 | * It's not always obvious which category a new error falls into 125 | * Trickier still are changes that alter codegen of existing shader code. 126 | 127 | * If there are changes that will change how existing shaders compile, 128 | what transition support will we provide? 129 | * New compilation failures should have a clear error message and ideally a FIXIT 130 | * Changes in codegen should include a warning and possibly a rewriter 131 | * Errors that are produced for previously valid shader code would give ample 132 | notice to developers that the change is coming and might involve rollout stages 133 | 134 | * Note that changes that allow shaders that failed to compile before to compile 135 | require testing that the code produced is appropriate, but they do not require 136 | any special transition support. In these cases, this section might be skipped. 137 | 138 | ## Alternatives considered (Optional) 139 | 140 | If alternative solutions were considered, please provide a brief overview. This 141 | section can also be populated based on conversations that occur during 142 | reviewing. Having these solutions and why they were rejected documented may save 143 | trouble from those who might want to suggest feedback or additional features that 144 | might build on this on. Even variations on the chosen solution can be interesting. 145 | 146 | ## Acknowledgments (Optional) 147 | 148 | Take a moment to acknowledge the contributions of people other than the author 149 | and sponsor. 150 | 151 | 152 | -------------------------------------------------------------------------------- /resources/HLSL.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/microsoft/hlsl-specs/36ac9489c3d95e7a7cd5c4a732ef689c09e589a9/resources/HLSL.png -------------------------------------------------------------------------------- /specs/language/CMakeLists.txt: -------------------------------------------------------------------------------- 1 | project(hlsl NONE) 2 | cmake_minimum_required(VERSION 3.15) 3 | 4 | find_package(LATEX REQUIRED COMPONENTS) 5 | 6 | if (NOT MAKEGLOSSARIES_COMPILER) 7 | get_filename_component(LATEX_DIR ${PDFLATEX_COMPILER} DIRECTORY) 8 | find_program(MAKEGLOSSARIES_COMPILER makeglossaries HINTS ${LATEX_DIR}) 9 | endif() 10 | 11 | if (NOT MAKEGLOSSARIES_COMPILER) 12 | message(FATAL_ERROR "Could not find makeglossaries") 13 | endif() 14 | 15 | if (NOT PANDOC_COMPILER) 16 | find_program(PANDOC_COMPILER pandoc) 17 | endif() 18 | 19 | set(intermediate_dir ${CMAKE_BINARY_DIR}/tmp/) 20 | 21 | message(STATUS "Generating targets for: ${PROJECT_NAME}") 22 | set(main_file ${CMAKE_CURRENT_SOURCE_DIR}/${PROJECT_NAME}.tex) 23 | set(out_dir ${CMAKE_BINARY_DIR}) 24 | 25 | add_custom_target(${PROJECT_NAME}-dirs 26 | COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/html 27 | COMMENT "Creating directories for ${PROJECT_NAME}") 28 | 29 | add_custom_target(${PROJECT_NAME}-prebuild 30 | COMMAND ${PDFLATEX_COMPILER} 31 | -output-directory ${CMAKE_BINARY_DIR} 32 | -draftmode -interaction=nonstopmode 33 | ${main_file} 34 | COMMENT "Prebuilding ${PROJECT_NAME}" 35 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 36 | DEPENDS ${main_file} ${PROJECT_NAME}-dirs) 37 | add_custom_target(${PROJECT_NAME}-glossaries 38 | COMMAND ${MAKEGLOSSARIES_COMPILER} -d ${CMAKE_BINARY_DIR} ${PROJECT_NAME} 39 | COMMENT "Prebuilding ${PROJECT_NAME} Glossaries" 40 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 41 | DEPENDS ${main_file} ${PROJECT_NAME}-prebuild) 42 | add_custom_target(pdf 43 | COMMAND ${PDFLATEX_COMPILER} 44 | -output-directory ${CMAKE_BINARY_DIR} 45 | ${main_file} 46 | # It is not a mistake that this is repeated. TeX compilers are 47 | # dumb. The first run generates the ToC and the second run is 48 | # required to ensure the references are all correct. 49 | COMMAND ${PDFLATEX_COMPILER} 50 | -output-directory ${CMAKE_BINARY_DIR} 51 | ${main_file} 52 | COMMENT "Assembling ${PROJECT_NAME}.pdf" 53 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 54 | DEPENDS ${main_file} ${PROJECT_NAME}-prebuild ${PROJECT_NAME}-glossaries) 55 | 56 | add_custom_target(html 57 | COMMAND ${PANDOC_COMPILER} ${main_file} -f latex -t html --table-of-contents=true -s -o ${CMAKE_BINARY_DIR}/html/hlsl.html 58 | COMMENT "Generating HTML" 59 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 60 | DEPENDS ${main_file} ${PROJECT_NAME}-prebuild ${PROJECT_NAME}-glossaries ${PROJECT_NAME}-dirs) 61 | -------------------------------------------------------------------------------- /specs/language/declarations.tex: -------------------------------------------------------------------------------- 1 | \Ch{Declarations}{Decl} 2 | \Sec{Preamble}{Decl.Pre} 3 | \p Declarations generally specify how names are to be interpreted. Declarations have the form 4 | \begin{grammar} 5 | \define{declaration-seq}\br 6 | \textit{declaration}\br 7 | \textit{declaration-seq declaration} 8 | 9 | \define{declaration}\br 10 | \textit{name-declaration}\br 11 | \textit{special-declaration}\br 12 | \textit{empty-declaration} 13 | 14 | \define{name-declaration}\br 15 | \textit{variable-declaration}\br 16 | \textit{function-declaration}\br 17 | \textit{namespace-declaration}\br 18 | \textit{record-declaration}\br 19 | \textit{template-declaration}\br 20 | \textit{type-alias-declaration}\br 21 | ... 22 | 23 | \define{special-declaration}\br 24 | \textit{export-declaration-group}\br 25 | \textit{cbuffer-declaration-group}\br 26 | ... 27 | 28 | \define{empty-declaration} \terminal{;} 29 | 30 | \end{grammar} 31 | 32 | \Sec{Specifiers}{Decl.Spec} 33 | \Sub{General}{Decl.Spec.General} 34 | \p The specifiers that can be used in a declaration are 35 | \begin{grammar} 36 | \define{decl-specifier}\br 37 | \textit{function-specifier}\br 38 | ... 39 | \end{grammar} 40 | 41 | \Sub{Function specifiers}{Decl.Spec.Fct} 42 | 43 | \p A \textit{function-specifier} can be used only in a function declaration. 44 | 45 | \begin{grammar} 46 | \define{function-specifier}\br 47 | \texttt{export}\br 48 | \end{grammar} 49 | 50 | \p The \texttt{export} specifier denotes that the function has program linkage (\ref{Basic.Linkage.Program}). 51 | 52 | \p The \texttt{export} specifier cannot be used on functions directly or indirectly within an unnamed namespace. 53 | 54 | \p Functions with program linkage can also be specified in \textit{export-declaration-group} (\ref{Decl.Export}). 55 | 56 | \p If a function is declared with an \texttt{export} specifier then all redeclarations of the same function must also use the \texttt{export} specifier or be part of \textit{export-declaration-group} (\ref{Decl.Export}). 57 | 58 | \Sec{Declarators}{Decl.Decl} 59 | \Sec{Initializers}{Decl.Init} 60 | 61 | \p The process of initialization described in this section applies to all 62 | initializers regardless of the context. 63 | 64 | \begin{grammar} 65 | \define{initializer}\br 66 | brace-or-equal-initializer\br 67 | \terminal{(} expression-list \terminal{)}\br 68 | 69 | \define{brace-or-equal-initializer}\br 70 | \terminal{=} initializer-clause\br 71 | braced-init-list\br 72 | 73 | \define{initializer-clause}\br 74 | assignment-expression\br 75 | braced-init-list\br 76 | 77 | \define{braced-init-list}\br 78 | \terminal{\{} initializer-list \opt{\terminal{,}} \terminal{\}}\br 79 | \terminal{\{} \terminal{\}}\br 80 | 81 | \define{initializer-list}\br 82 | initializer-clause\br 83 | initializer-list \terminal{,} initializer-clause\br 84 | \end{grammar} 85 | 86 | \Sub{Aggregate Initialization}{Decl.Init.Agg} 87 | 88 | \p An \textit{aggregate} is a vector, matrix, array, or class. 89 | 90 | \p The subobjects of an aggregate have a defined order. For vectors and arrays 91 | the order is increasing subscript order. For matrices it is increasing subscript 92 | order with the subscript nesting such that in the notation 93 | \texttt{Mat[M][N]}, the ordering is \(Mat[0][0]...Mat[0][N]... 94 | Mat[M][0]...Mat[M][N]\). For classes the order is base class, followed by member 95 | subobjects in declaration order. 96 | 97 | \p A \textit{flattened ordering} of subobjects can be produced by performing a 98 | depth-first traversal of the subobjects of an object following the defined 99 | subobject ordering. 100 | 101 | \p Each \textit{braced initializer list} is comprised of zero or more 102 | \textit{initializer-clause} expressions, which is either another braced 103 | initializer list or an expression which generates a value that either is or can 104 | be implicitly converted to an rvalue. Each assignment-expression is an object, 105 | which may be a scalar or aggregate type. A \textit{flattened initializer 106 | sequence} is a sequence of expressions constructed by a depth-first traversal 107 | over each assignment-expression in an initializer-list and performing a 108 | depth-first traversal accessing each subobject of the assignment-expression. 109 | 110 | \p If the target object is an array of unknown size, the object is assumed to 111 | have \(m\) possible elements during parsing, where \(m>0\). 112 | 113 | \p An initializer-list is a valid initializer if for each element 114 | \(E_{n \bmod m}\) in the target object's flattened ordering there is a 115 | corresponding expression \(E_n\) in the flattened initializer sequence, which 116 | can be implicitly converted to the element's type. For arrays of unknown size, 117 | the total number of expressions in the flattened initializer sequence must be a 118 | multiple of the array's base element type. 119 | 120 | \p An initializer-list is invalid if the flattened initializer sequence contains 121 | more or fewer elements than the target object's flattened ordering, or if any 122 | initializer \(I_n\) cannot be implicitly converted to the corresponding element 123 | \(E_n\)'s type. 124 | 125 | \Sec{Function Definitions}{Decl.Function} 126 | \Sec{Attributes}{Decl.Attr} 127 | \Sub{Semantic Annotations}{Decl.Attr.Semantic} 128 | \Sub{Entry Attributes}{Decl.Attr.Entry} 129 | 130 | \Sec{Export Declarations}{Decl.Export} 131 | 132 | \p One or more functions with \textit{external linkage} can be also specified in the form of 133 | 134 | \begin{grammar} 135 | \define{export-declaration-group}\br 136 | \texttt{export} \terminal{\{} \opt{function-declaration-seq} \terminal{\}}\br 137 | 138 | \define{function-declaration-seq}\br 139 | \textit{function-declaration} \opt{function-declaration-seq} 140 | \end{grammar} 141 | 142 | \p The \texttt{export} specifier denotes that every \textit{function-declaration} included in \textit{function-declaration-seq} has \textit{external linkage} (\ref{Basic.Linkage.External}). 143 | 144 | \p The \textit{export-declaration-group} declaration cannot appear directly or indirectly within an unnamed namespace. 145 | 146 | \p Functions with \textit{external linkage} can also be declared with an \texttt{export} specifier (\ref{Decl.Spec.Fct}). 147 | 148 | \p If a function is part of an \textit{export-declaration-group} then all redeclarations of the same function must also be part on a \textit{export-declaration-group} or be declared with an \texttt{export} specifier (\ref{Decl.Spec.Fct}). 149 | -------------------------------------------------------------------------------- /specs/language/glossary.tex: -------------------------------------------------------------------------------- 1 | \makeglossaries 2 | 3 | \newacronym{hlsl}{HLSL}{High Level Shader Language} 4 | \newacronym{dxc}{DXC}{DirectX Shader Compiler} 5 | \newacronym{fxc}{FXC}{Legacy DirectX Shader Compiler} 6 | \newacronym{c}{C}{C Programming Language} 7 | \newacronym{cpp}{C++}{C++ Programming Language} 8 | \newacronym{api}{API}{Application Programming Interface} 9 | \newacronym{spmd}{SPMD}{Single Program Multiple Data} 10 | \newacronym{simd}{SIMD}{Single Instruction Multiple Data} 11 | \newacronym{simt}{SIMT}{Single Instruction Multiple Thread} 12 | 13 | \newglossaryentry{spirv} 14 | { 15 | name={SPIR-V}, 16 | description={SPIR-V is a portable intermediate representation designed by the 17 | Khronos Group for representing GPU programs} 18 | } 19 | 20 | \newglossaryentry{dx} 21 | { 22 | name={DirectX}, 23 | description={DirectX is the multimedia \acrshort{api} introduced with Windows 24 | 95.} 25 | } 26 | 27 | \newglossaryentry{isoC} 28 | { 29 | name={ISO C standard (2011)}, 30 | description={ISO/IEC 9899:2011: Standard for Programming Language C.} 31 | } 32 | 33 | \newglossaryentry{isoC23} 34 | { 35 | name={ISO C standard (2023)}, 36 | description={ISO/IEC 9899:2023: Standard for Programming Language C.} 37 | } 38 | 39 | \newglossaryentry{isoCPP} 40 | { 41 | name={ISO C++ standard (2011)}, 42 | description={ISO/IEC 14882:2011: Standard for Programming Language C++.} 43 | } 44 | 45 | \newglossaryentry{IEEE754} 46 | { 47 | name={IEEE Standard 754}, 48 | description={IEEE Standard For Floating Point Arithmetic} 49 | } 50 | 51 | \newglossaryentry{sm} 52 | { name={Shader Model}, description={Versioned hardware description included as 53 | part of the DirectX specification, which is used for code generation to a 54 | common set of features across a range of vendors.} 55 | } 56 | 57 | \newglossaryentry{lane}{ 58 | name={Lane}, 59 | description={The computation performed on a single element as described in the 60 | \acrshort{spmd} program. Also called: thread.} 61 | } 62 | 63 | \newglossaryentry{wave}{ 64 | name={Wave}, 65 | description={A group of \gls{lane}s which execute together. The number of 66 | \gls{lane}s in a Wave varies by hardware implementation. Also called: warp, 67 | SIMD-group, subgroup, or wavefront.} 68 | } 69 | 70 | \newglossaryentry{quad}{ 71 | name={Quad}, 72 | description={A group of four \gls{lane}s which form a cluster of adjacent 73 | computations in the data topology. Also called: quad-group or quad-wave. } 74 | } 75 | 76 | \newglossaryentry{threadgroup}{ 77 | name={Thread Group}, 78 | description={A group of \gls{lane}s which may be subdivided into one or more 79 | \gls{wave}s and comprise a larger computation. Also known as: group, 80 | workgroup, block or thread block.} 81 | } 82 | 83 | \newglossaryentry{dispatch}{ 84 | name={Dispatch}, 85 | description={A group of one or more \gls{threadgroup}s which comprise the 86 | largest unit of a shader execution. Also called: grid, compute space or index 87 | space.} 88 | } 89 | -------------------------------------------------------------------------------- /specs/language/hlsl.tex: -------------------------------------------------------------------------------- 1 | \documentclass[oneside]{book} 2 | \usepackage[utf8]{inputenc} 3 | \usepackage[english]{babel} 4 | \usepackage{nameref} 5 | \usepackage[acronym,numberedsection=nameref,toc]{glossaries} 6 | \usepackage{multicol} 7 | \usepackage[marginparwidth=75pt, margin=2cm]{geometry} 8 | \usepackage{listings} 9 | \usepackage{marginnote} 10 | \usepackage{parskip} 11 | \usepackage{titlesec} 12 | \usepackage{enumitem} 13 | \usepackage[hidelinks]{hyperref} 14 | \usepackage{tikz} 15 | \usetikzlibrary{arrows,automata,positioning} 16 | 17 | \titleformat{\chapter} 18 | {\LARGE\bfseries}{\thechapter}{10pt}{} 19 | \titlespacing{\chapter}{0pt}{0pt}{10pt} 20 | 21 | \renewcommand{\familydefault}{\sfdefault} 22 | 23 | \setcounter{secnumdepth}{3} % number subsections 24 | \newcommand{\Ch}[2]{\chapter[#1]{#1\hfill[#2]}\label{#2}} 25 | \newcommand{\Sec}[2]{\section[#1]{#1\hfill[#2]}\label{#2}} 26 | \newcommand{\Sub}[2]{\subsection[#1]{#1\hfill[#2]}\label{#2}} 27 | \newcommand{\SubSub}[2]{\subsubsection[#1]{#1\hfill[#2]}\label{#2}} 28 | 29 | \input{glossary} 30 | 31 | \title{High-Level Shader Language Specification\\ 32 | \normalsize{Working Draft}} 33 | 34 | 35 | \newenvironment{note} 36 | {\begin{center} 37 | \begin{tabular}{|p{0.9\textwidth}|} 38 | \hline\\ 39 | } 40 | { 41 | \\\\\hline 42 | \end{tabular} 43 | \end{center} 44 | } 45 | 46 | \usepackage{titleps} 47 | \newpagestyle{body}{ 48 | \sethead{}{}{\sectiontitle} 49 | \setfoot{}{}{Working Draft} 50 | } 51 | \pagestyle{body} 52 | 53 | \setcounter{secnumdepth}{3} 54 | \newcommand{\parnum}{\textbf{\arabic{parcount}}} 55 | 56 | \setlength\parindent{0cm} 57 | 58 | \newcommand{\newparcounter}[1]{ 59 | \newcounter{#1} 60 | \counterwithin{#1}{chapter} 61 | \counterwithin{#1}{section} 62 | \counterwithin{#1}{subsection} 63 | \counterwithin{#1}{subsubsection} 64 | } 65 | 66 | \newparcounter{parcount} 67 | \newcommand\p{% 68 | \stepcounter{parcount}% 69 | \parnum \hspace{1em}% 70 | } 71 | 72 | \newenvironment{parnumbers}{% 73 | \par% 74 | \everypar{\noindent \stepcounter{parcount}\parnum \hspace{1em}}% 75 | }{} 76 | 77 | \newcommand{\Par}[2]{\paragraph[#1]{#1\hfill[#2]\\}\label{#2}\p} 78 | 79 | \begin{document} 80 | \input{macros} 81 | 82 | \maketitle 83 | 84 | \tableofcontents 85 | \input{introduction} 86 | \input{lex} 87 | 88 | \input{basic} 89 | \input{conversions} 90 | \input{expressions} 91 | \input{statements} 92 | \input{declarations} 93 | \input{overloading} 94 | \input{resources} 95 | 96 | \input{placeholders} % Declare placeholder references 97 | 98 | \clearpage 99 | 100 | \printglossary[type=\acronymtype] 101 | \printglossary 102 | 103 | \end{document} 104 | -------------------------------------------------------------------------------- /specs/language/macros.tex: -------------------------------------------------------------------------------- 1 | %%------------------------------------------------------------------------------ 2 | %% General formatting 3 | %%------------------------------------------------------------------------------ 4 | 5 | \newcommand{\keyword}[1]{{\texttt{#1}}} 6 | 7 | %%------------------------------------------------------------------------------ 8 | %% Grammar formatting 9 | %%------------------------------------------------------------------------------ 10 | 11 | \newlength{\GrammarIndent} 12 | \setlength{\GrammarIndent}{\leftmargini} 13 | \newlength{\GrammarInc} 14 | \setlength{\GrammarInc}{\GrammarIndent} 15 | \newlength{\GrammarRest} 16 | \setlength{\GrammarRest}{2\GrammarIndent} 17 | 18 | \newenvironment{grammar} { 19 | \newcommand{\define}[1]{{\textit{##1}\textnormal{:}}} 20 | \newcommand{\terminal}[1]{{\texttt{##1}}} 21 | \newcommand{\br}{\hfill\\*} 22 | \newcommand{\opt}[1]{{##1\textsubscript{\textit{opt}}}} 23 | 24 | \renewcommand{\texttt}[1]{{\small\ttfamily\upshape ##1}} 25 | 26 | \newcommand{\grammarindentfirst}{\GrammarIndent} 27 | \newcommand{\grammarindentinc}{\GrammarInc} 28 | \newcommand{\grammarindentrest}{\GrammarRest} 29 | \itshape 30 | 31 | \begin{grammarlist} 32 | \item\relax 33 | }{ 34 | \end{grammarlist} 35 | } 36 | 37 | \newlist{grammarlist}{itemize}{1} 38 | \setlist[grammarlist]{ 39 | parsep=1ex, partopsep=0pt, itemsep=0pt, topsep=0pt, label={}, 40 | leftmargin=\grammarindentrest, listparindent=-\grammarindentinc, 41 | itemindent=\listparindent 42 | } 43 | 44 | \lstloadlanguages{C++} % TODO: Consider defining an HLSL language... 45 | \lstnewenvironment{HLSL} 46 | {\lstset{language=C++, 47 | basicstyle=\small, 48 | xleftmargin=1em}}{} 49 | -------------------------------------------------------------------------------- /specs/language/placeholders.tex: -------------------------------------------------------------------------------- 1 | % This file contains chapter and section references to speculative headings that 2 | % haven't been written yet. The specific names and ordering aren't expected to 3 | % match exactly this in the final specification. These are mostly here so that 4 | % forward references can be inserted into the specification as it is being 5 | % written to force updating the references as they change. 6 | 7 | \Ch{Classes}{Classes} 8 | \Sec{Static Members}{Classes.Static} 9 | \Sec{Conversions}{Classes.Conversions} 10 | \Ch{Templates}{Template} 11 | \Sec{Template Instantiation}{Template.Inst} 12 | \Sec{Partial Ordering of Function Templates}{Template.Func.Order} 13 | \Ch{Intangible Types}{Intangible} 14 | \Ch{Runtime}{Runtime} 15 | -------------------------------------------------------------------------------- /specs/language/statements.tex: -------------------------------------------------------------------------------- 1 | \Ch{Statements}{Stmt} 2 | \begin{grammar} 3 | \define{statement}\br 4 | labeled-statement\br 5 | \opt{attribute-specifier-sequence} expression-statement\br 6 | \opt{attribute-specifier-sequence} compound-statement\br 7 | \opt{attribute-specifier-sequence} iteration-statement\br 8 | \opt{attribute-specifier-sequence} selection-statement\br 9 | declaration-statement 10 | \end{grammar} 11 | \Sec{Label Statements}{Stmt.Label} 12 | \p The optional \textit{attribute-specifier-sequence} applies to the statement 13 | that immediately follows it. 14 | \Sec{Attributes}{Stmt.Attr} 15 | \Sub{Unroll Attribute}{Stmt.Attr.Unroll} 16 | \p The \textit{[unroll]} attribute is only valid when applied to 17 | \textit{iteration-statements}. It is used to indicate that 18 | \textit{iteration-statements} like \texttt{for}, \texttt{while} and 19 | \texttt{do while} can be unrolled. This attribute qualifier can be used to 20 | specify full unrolling or partial unrolling by a specified amount. This is a 21 | compiler hint and the compiler may ignore this directive. 22 | 23 | \p The unroll attribute may optionally have an unroll factor represented as a 24 | single argument \texttt{n} that is an integer constant expression value 25 | greater than zero. If n is not specified, the compiler determines the 26 | unrolling factor for the loop. The \textit{[unroll]} attribute can not be 27 | applied to the same \textit{iteration-statement} as the \texttt{[loop]} 28 | attribute. 29 | 30 | \Sub{Loop Attribute}{Stmt.Attr.Loop} 31 | \p The Attribute \texttt{[loop]} tells the compiler to execute each iteration 32 | of the loop. In other words, its a hint to indicate a loop should not be 33 | unrolled. Therefore it is not compatible with the \texttt{[unroll]} attribute. 34 | --------------------------------------------------------------------------------