OpenXR Specification 1.1.37 (2024-05-23)

This release adds new defines for easier use of both OpenXR 1.0 and 1.1
with up-to-date headers, as well as some minor fixes, cleanups, and
clarifications.

-   Registry
    -   Addition: New XR_API_VERSION_1_0 and XR_API_VERSION_1_1 defines
        to allow applications to easily specify OpenXR “major” and
        “minor” version while passing through the “patch” version.
        (internal MR 3329, internal MR 3354, internal issue 2254)
    -   Addition: Register Razer vendor ID. (internal MR 3340)
    -   Fix: Add “palm_pose” to “touch_controller_pro” and
        “touch_controller_plus” in XML. (internal MR 3363)
    -   Improvement: Add Schematron rule to avoid triggering edge cases
        of vendor tags ending with X. (internal MR 3341)
    -   Reservation: Reserve extension numbers for a few new EXT
        extensions. (internal MR 3285, internal MR 3292)
    -   Update: Bump version of XR_FB_composition_layer_alpha_blend due
        to spec text clarification. (internal MR 3317)
-   Specification
    -   Addition: Document new XR_API_VERSION_1_0 and XR_API_VERSION_1_1
        macros/defines. (internal MR 3354, internal issue 2254)
    -   Fix: Typo in “Buffer Size Parameters” section. (internal MR
        3322)
    -   Fix: Resolve several diagrams shown cropped in browsers.
        (internal MR 3355)
    -   Fix: Correct formatting of versions in some generated spec text.
        (internal MR 3362)
    -   Fix: Adjust specification release build process to restore
        internal links in PDF. (internal MR 3371, OpenXR-Docs issue 170)
    -   Improvement: Resize and optimize images to reduce spec page
        size. (internal MR 2833, internal MR 3355)
    -   Improvement: Add in missing explicit section anchors. (internal
        MR 3322)
    -   Improvement: Fix references to Docker container in spec build
        instructions. (internal MR 3352, internal issue 2283,
        OpenXR-SDK-Source issue 476)
    -   Improvement: Inline several SVG diagrams to support searchable
        and screen- reader-accessible text. (internal MR 3355)
    -   Improvement: General script cleanups and improvements. (internal
        MR 3362)
    -   Update: Bump version of XR_FB_composition_layer_alpha_blend due
        to spec text clarification. (internal MR 3317)

GitOrigin-RevId: b84815a669b7ab8721ff5117872d8af17b601754

.gitattributes

@@ -25,8 +25,9 @@
 *.png     binary
 
 # git-lfs big files
-*.pdf filter=lfs diff=lfs merge=lfs -text
-*.glb filter=lfs diff=lfs merge=lfs -text
+*.pdf                    filter=lfs diff=lfs merge=lfs -text
+*.glb                    filter=lfs diff=lfs merge=lfs -text
+src/conformance/**/*.png filter=lfs diff=lfs merge=lfs -text
 
 # Shell/python scripts that don't end in .sh
 specification/makeAllExts           eol=lf

.gitignore

@@ -21,6 +21,7 @@ generated-includes
 cmake_install.cmake
 cmake_uninstall.cmake
 cmake-build-*
+specification/vendor/bundle/
 
 # Marker file for a snapshot build
 SNAPSHOT

.proclamation.json

@@ -22,10 +22,6 @@
             "news_filename": "CHANGELOG.Docs.md",
             "template": "changes/template.md",
             "sections": {
-                "Major Update": {
-                    "directory": "changes/major",
-                    "sort_by_prefix": true
-                },
                 "Registry": {
                     "directory": "changes/registry",
                     "sort_by_prefix": true

CHANGELOG.Docs.md

@@ -17,6 +17,65 @@ any public pull requests that have been accepted.
 This changelog only lists changes that affect the registry,
 headers, and/or specification text.
 
+## OpenXR Specification 1.1.37 (2024-05-23)
+
+This release adds new defines for easier use of both OpenXR 1.0 and 1.1 with
+up-to-date headers, as well as some minor fixes, cleanups, and clarifications.
+
+- Registry
+  - Addition: New `XR_API_VERSION_1_0` and `XR_API_VERSION_1_1` defines to allow
+    applications to easily specify OpenXR "major" and "minor" version while passing
+    through the "patch" version.
+    ([internal MR 3329](https://gitlab.khronos.org/openxr/openxr/merge_requests/3329),
+    [internal MR 3354](https://gitlab.khronos.org/openxr/openxr/merge_requests/3354),
+    [internal issue 2254](https://gitlab.khronos.org/openxr/openxr/issues/2254))
+  - Addition: Register Razer vendor ID.
+    ([internal MR 3340](https://gitlab.khronos.org/openxr/openxr/merge_requests/3340))
+  - Fix: Add "palm_pose" to "touch_controller_pro" and "touch_controller_plus" in
+    XML.
+    ([internal MR 3363](https://gitlab.khronos.org/openxr/openxr/merge_requests/3363))
+  - Improvement: Add Schematron rule to avoid triggering edge cases of vendor tags
+    ending with X.
+    ([internal MR 3341](https://gitlab.khronos.org/openxr/openxr/merge_requests/3341))
+  - Reservation: Reserve extension numbers for a few new EXT extensions.
+    ([internal MR 3285](https://gitlab.khronos.org/openxr/openxr/merge_requests/3285),
+    [internal MR 3292](https://gitlab.khronos.org/openxr/openxr/merge_requests/3292))
+  - Update: Bump version of `XR_FB_composition_layer_alpha_blend` due to spec text
+    clarification.
+    ([internal MR 3317](https://gitlab.khronos.org/openxr/openxr/merge_requests/3317))
+- Specification
+  - Addition: Document new `XR_API_VERSION_1_0` and `XR_API_VERSION_1_1`
+    macros/defines.
+    ([internal MR 3354](https://gitlab.khronos.org/openxr/openxr/merge_requests/3354),
+    [internal issue 2254](https://gitlab.khronos.org/openxr/openxr/issues/2254))
+  - Fix: Typo in "Buffer Size Parameters" section.
+    ([internal MR 3322](https://gitlab.khronos.org/openxr/openxr/merge_requests/3322))
+  - Fix: Resolve several diagrams shown cropped in browsers.
+    ([internal MR 3355](https://gitlab.khronos.org/openxr/openxr/merge_requests/3355))
+  - Fix: Correct formatting of versions in some generated spec text.
+    ([internal MR 3362](https://gitlab.khronos.org/openxr/openxr/merge_requests/3362))
+  - Fix: Adjust specification release build process to restore internal links in
+    PDF.
+    ([internal MR 3371](https://gitlab.khronos.org/openxr/openxr/merge_requests/3371),
+    [OpenXR-Docs issue 170](https://github.com/KhronosGroup/OpenXR-Docs/issues/170))
+  - Improvement: Resize and optimize images to reduce spec page size.
+    ([internal MR 2833](https://gitlab.khronos.org/openxr/openxr/merge_requests/2833),
+    [internal MR 3355](https://gitlab.khronos.org/openxr/openxr/merge_requests/3355))
+  - Improvement: Add in missing explicit section anchors.
+    ([internal MR 3322](https://gitlab.khronos.org/openxr/openxr/merge_requests/3322))
+  - Improvement: Fix references to Docker container in spec build instructions.
+    ([internal MR 3352](https://gitlab.khronos.org/openxr/openxr/merge_requests/3352),
+    [internal issue 2283](https://gitlab.khronos.org/openxr/openxr/issues/2283),
+    [OpenXR-SDK-Source issue 476](https://github.com/KhronosGroup/OpenXR-SDK-Source/issues/476))
+  - Improvement: Inline several SVG diagrams to support searchable and screen-
+    reader-accessible text.
+    ([internal MR 3355](https://gitlab.khronos.org/openxr/openxr/merge_requests/3355))
+  - Improvement: General script cleanups and improvements.
+    ([internal MR 3362](https://gitlab.khronos.org/openxr/openxr/merge_requests/3362))
+  - Update: Bump version of `XR_FB_composition_layer_alpha_blend` due to spec text
+    clarification.
+    ([internal MR 3317](https://gitlab.khronos.org/openxr/openxr/merge_requests/3317))
+
 ## OpenXR Specification 1.1.36 (2024-04-15)
 
 This is a substantial update to the OpenXR specification.

open-in-docker.sh

@@ -17,7 +17,7 @@
 
 # This image/tag is generated from https://github.com/KhronosGroup/DockerContainers/blob/main/openxr.Dockerfile
 # Purpose: Spec (pdf/html) generation
-IMAGE_NAME=khronosgroup/docker-images:openxr.20231010.1
+IMAGE_NAME=khronosgroup/docker-images:openxr.20240412
 MOUNTPOINT=$(pwd)
 
 set -e

specification/Gemfile

@@ -7,3 +7,9 @@ source 'https://rubygems.org'
 gem 'asciidoctor', '~>2.0.10'
 gem 'rouge'
 gem 'asciidoctor-pdf', '1.6.2'
+
+# Temporary fix
+# https://stackoverflow.com/questions/71392585/asciidoctor-pdf-cannot-load-such-file-matrix-loaderror#comment132483860_71392586
+gem "matrix", "~> 0.4"
+
+gem 'hexapdf'

specification/Makefile

@@ -7,7 +7,13 @@ SHELL = /usr/bin/env bash
 QUIET      ?= @
 VERYQUIET  ?= @
 PYTHON	   ?= python3
+ifneq (,$(strip $(BUNDLER)))
+ASCIIDOC   ?= bundle exec asciidoctor --trace
+HEXAPDF    ?= bundle exec hexapdf
+else
 ASCIIDOC   ?= asciidoctor
+HEXAPDF    ?= hexapdf
+endif
 RM          = rm -f
 RMRF        = rm -rf
 MKDIR       = mkdir -p
@@ -33,7 +39,7 @@ endif
 VERSIONS := XR_VERSION_1_0 XR_VERSION_1_1 XR_LOADER_VERSION_1_0
 VERSIONOPTIONS := $(foreach version,$(VERSIONS),-feature $(version))
 
-SPECREVISION = 1.1.36
+SPECREVISION = 1.1.37
 REVISION_COMPONENTS = $(subst ., ,$(SPECREVISION))
 MAJORMINORVER = $(word 1,$(REVISION_COMPONENTS)).$(word 2,$(REVISION_COMPONENTS))
 
@@ -343,7 +349,7 @@ pdfA4: $(PDFA4SPEC)
 ASCIIDOCTOR_TARGETS += $(PDFSPEC) $(PDFA4SPEC)
 
 # Target-specific variables and deps customizing the AsciiDoctor rule
-$(PDFSPEC) $(PDFA4SPEC): BACKEND_ARGS=--backend pdf --require asciidoctor-pdf -a compress  -r ./scripts/pdf-index-customizer.rb
+$(PDFSPEC) $(PDFA4SPEC): BACKEND_ARGS=--backend pdf --require asciidoctor-pdf -a compress --require ./scripts/pdf-index-customizer.rb
 $(PDFSPEC): PAGESIZE=LETTER
 $(PDFA4SPEC): PAGESIZE=A4
 $(PDFSPEC) $(PDFA4SPEC): $(COMMONDOCS)
@@ -647,14 +653,17 @@ $(REGISTRYOUTDIR)/headers/openxr: | $(REGISTRYOUTDIR)/headers
 	$(QUIET)$(MKDIR) "$@"
 
 release-htmlpdf: html pdf $(REGISTRYOUTDIR)/pdf $(REGISTRYOUTDIR)/html
-	-asciidoctor-pdf-optimize $(PDFSPEC)
-	$(QUIET)$(CP) $(PDFSPEC) $(REGISTRYOUTDIR)/pdf/$(SPEC_FILENAME_STEM).pdf
+	$(ECHO) "[hexapdf]     $(call MAKE_RELATIVE,$(REGISTRYOUTDIR)/pdf/$(SPEC_FILENAME_STEM).pdf)"
+	$(QUIET)$(HEXAPDF) optimize --force $(PDFSPEC) $(REGISTRYOUTDIR)/pdf/$(SPEC_FILENAME_STEM).pdf
+	$(ECHO) "[cp]          $(call MAKE_RELATIVE,$(REGISTRYOUTDIR)/html/$(SPEC_FILENAME_STEM).html)"
 	$(QUIET)$(CP) $(HTMLSPEC) $(REGISTRYOUTDIR)/html/$(SPEC_FILENAME_STEM).html
 .PHONY: release-htmlpdf
 
 
 release: release-htmlpdf manhtmlpages loader styleguide extprocess | $(REGISTRYOUTDIR) $(REGISTRYOUTDIR)/man
+	$(ECHO) "[cp]          $(call MAKE_RELATIVE,$(REGISTRYOUTDIR))/{styleguide,extprocess,loader}.html"
 	$(QUIET)$(CP) $(OUTDIR)/styleguide.html $(OUTDIR)/extprocess.html $(OUTDIR)/loader.html $(REGISTRYOUTDIR)
+	$(ECHO) "[cp]          $(REGISTRYOUTDIR)/man/html"
 	$(QUIET)$(CP) -R $(MANHTMLDIR) $(REGISTRYOUTDIR)/man/html
 .PHONY: release
 

specification/README.md

@@ -8,10 +8,13 @@ SPDX-License-Identifier: CC-BY-4.0
 
 Before building the specification, install the necessary prerequisite tools as described later in this document.
 
-You may instead choose to use the `open-in-docker.sh` script,
-which will mount the repository in a container built from an image with all the necessary tools installed.
-See that script for more details.
-You can find the associated Dockerfile at https://github.com/KhronosGroup/DockerContainers/blob/master/Dockerfile.openxr
+You may instead choose to use the `open-in-docker.sh` script, available in the
+OpenXR-Docs (spec source) and OpenXR-SDK-Source (SDK, for loader docs build)
+repo as well as the internal monorepo. This script which will mount the
+repository in a container built from an image with all the necessary tools
+installed: these are regularly pushed to Docker Hub. See that script for more
+details. You can find the associated Dockerfile at
+<https://github.com/KhronosGroup/DockerContainers/blob/main/openxr.Dockerfile>
 
 ## Conditional Inclusion of Extensions
 
@@ -91,6 +94,10 @@ specified by the Makefile variable `$(OUTDIR)` (by default,
 It is recommended to build these targets using a "helper" script from above,
 unless you want to only build the core spec without any extensions.
 
+Most of these are not supported if building in `OpenXR-SDK-Source`: this
+repository is mostly software, and the only contained AsciiDoc content is the
+loader design document source.
+
 These targets are currently supported.
 
 * API spec:
@@ -119,6 +126,10 @@ For example:
 make styleguide
 ```
 
+Many of these are not supported if building in `OpenXR-SDK-Source`: this
+repository is mostly software, and the only contained AsciiDoc content is the
+loader design document source.
+
 * "OpenXR Documentation and Extensions" guide (aka Style Guide):
   * `styleguide` - Single-file HTML5 in `$(OUTDIR)/styleguide.html`
 * OpenXR Extensions Process guide:
@@ -219,7 +230,8 @@ parts you don't use) completely before trying to install.
 > Asciidoctor-pdf versions before `1.5.0.alpha15` have issues with multi-page
 valid usage blocks, in that the background only renders for the first page.
 `alpha.15` fixes this issue (as well as a few others); do not use prior
-versions.
+versions. On the other hand, versions later than 1.6.2 break our index
+customization script, so 1.6.2 is ideal.
 
 Only the `asciidoctor` and `rouge` gems (and their dependencies) are needed if
 you do not intend to build PDF versions of the spec and supporting documents.
@@ -230,6 +242,14 @@ people submitting MRs with substantial changes to the Specification are
 responsible for verifying that their branches build *both* `html` and `pdf`
 targets.
 
+The easiest way to get the right version of these gems is to use "bundler":
+
+```sh
+bundle install
+```
+
+Then, pass `BUNDLER=1` to each `make` (or wrapper script) invocation.
+
 ### Platforms and System Packages
 
 #### Windows

specification/config/svgo-config.mjs

@@ -0,0 +1,35 @@
+// Copyright 2024, The Khronos Group Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+const regBadFonts = /Helvetica|Arial|Arimo|ArimoMT/g;
+
+const fixFonts = {
+  name: "fixFonts",
+  params: {
+    paramName: "paramValue",
+  },
+  fn: (ast, params, info) => {
+    return {
+      element: {
+        enter: (node) => {
+          if (node.attributes.style != null) {
+            node.attributes.style = node.attributes.style.replace(
+              regBadFonts,
+              "sans-serif"
+            );
+          }
+          if (node.attributes["font-family"] != null) {
+            node.attributes["font-family"] = node.attributes[
+              "font-family"
+            ].replace(regBadFonts, "sans-serif");
+          }
+        },
+      },
+    };
+  },
+};
+export default {
+  multipass: true,
+  plugins: [fixFonts, "preset-default", fixFonts],
+};

specification/current_version.ini

@@ -10,4 +10,4 @@
 # Similarly, update specification/scripts/extensionmetadocgenerator.py as well.
 MAJOR=1
 MINOR=1
-PATCH=36
+PATCH=37

specification/registry/registry.sch

@@ -6,6 +6,19 @@
 
          SPDX-License-Identifier: Apache-2.0
     -->
+
+    <sch:pattern name="Vendor tag naming requirements">
+        <sch:rule context="tags/tag">
+            <!-- Our tooling treats a trailing X in a vendor tag as an experimental version, this will cause  -->
+            <!-- problems if someone adds a vendor tag that ends in X. -->
+            <!-- Please see gitlab merge request !2518 for more details. -->
+            <sch:assert test="not(ends-with(@name, 'X'))">
+                Vendor tag cannot end in "X" but got <sch:value-of select="@name" />
+            </sch:assert>
+        </sch:rule>
+    </sch:pattern>
+
+
     <sch:pattern name="Extension uniqueness and basic requirements">
         <!-- https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html#extensions -->
         <sch:rule context="extensions/extension">