OpenXR SDK 1.1.37 (2024-05-23)

This release primarily adds new defines for easier use of both OpenXR
1.0 and 1.1 with up-to-date headers, some documentation improvements,
and improvements for Android, including support for using the “API Dump”
and “Validation” API layers in your own APK during the development
process.

-   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)
-   SDK
    -   Addition: Ship open-in-docker.sh script for use building the
        loader design doc. (internal MR 3352, internal issue 2283,
        OpenXR-SDK-Source issue 476)
    -   Fix: Fix references to Docker container in spec build
        instructions and clarify that most parts do not apply to the
        SDK-Source repo. (internal MR 3352, internal issue 2283,
        OpenXR-SDK-Source issue 476)
    -   Fix: Do not load all Android app-supplied layers as explicit,
        but rather as their actual type. (OpenXR-SDK-Source PR 475,
        internal issue 2284)
    -   Improvement: Use new XR_API_VERSION_1_0 and XR_API_VERSION_1_1
        defines. (internal MR 3329, internal issue 2254)
    -   Improvement: Add Android support to “api_dump” and
        “core_validation” API layers. (internal MR 3330)

GitOrigin-RevId: b84815a669b7ab8721ff5117872d8af17b601754

Author: rpavlik

.appveyor.yml

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-version: 1.1.36.{build}
+version: 1.1.37.{build}
 image: Visual Studio 2017
 
 

.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.SDK.md

@@ -21,6 +21,56 @@ along with any public pull requests that have been accepted.
 In this repository in particular, since it is primarily software,
 pull requests may be integrated as they are accepted even between periodic updates.
 
+## OpenXR SDK 1.1.37 (2024-05-23)
+
+This release primarily adds new defines for easier use of both OpenXR 1.0 and
+1.1 with up-to-date headers, some documentation improvements, and improvements
+for Android, including support for using the "API Dump" and "Validation" API
+layers in your own APK during the development process.
+
+- 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))
+- SDK
+  - Addition: Ship `open-in-docker.sh` script for use building the loader design
+    doc.
+    ([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))
+  - Fix: Fix references to Docker container in spec build instructions and clarify
+    that most parts do not apply to the SDK-Source repo.
+    ([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))
+  - Fix: Do not load all Android app-supplied layers as explicit, but rather as
+    their actual type.
+    ([OpenXR-SDK-Source PR 475](https://github.com/KhronosGroup/OpenXR-SDK-Source/pull/475),
+    [internal issue 2284](https://gitlab.khronos.org/openxr/openxr/issues/2284))
+  - Improvement: Use new `XR_API_VERSION_1_0` and `XR_API_VERSION_1_1` defines.
+    ([internal MR 3329](https://gitlab.khronos.org/openxr/openxr/merge_requests/3329),
+    [internal issue 2254](https://gitlab.khronos.org/openxr/openxr/issues/2254))
+  - Improvement: Add Android support to "api_dump" and "core_validation" API
+    layers.
+    ([internal MR 3330](https://gitlab.khronos.org/openxr/openxr/merge_requests/3330))
+
 ## OpenXR SDK 1.1.36 (2024-04-15)
 
 This is a substantial update to the OpenXR specification. The OpenXR loader in

changes/sdk/pr.475.gh.OpenXR-SDK-Source.md

@@ -154,6 +154,7 @@ getSDKSourceFilenames() {
         checkCodespell \
         CMakeLists.txt \
         format_file.sh \
+        open-in-docker.sh \
         LICENSE \
         openxr-codespell.exclude \
         runClangFormat.sh \

maintainer-scripts/common.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# Copyright (c) 2019-2024, The Khronos Group Inc.
+# Copyright (c) 2019 Collabora, Ltd.
+# SPDX-License-Identifier: Apache-2.0
+
+# Start the docker image named below, for spec generation, etc.
+# Mounts this directory as the mountpoint mentioned below,
+# and logs you in as a normal user whose user ID and group ID match
+# your outside-of-container user, thus avoiding mangling permissions.
+# Container is automatically removed when you exit it.
+
+# The docker images used are published here:
+# https://hub.docker.com/r/khronosgroup/docker-images/tags
+#
+# with their dockerfile located at:
+# https://github.com/KhronosGroup/DockerContainers
+
+# 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.20240412
+MOUNTPOINT=$(pwd)
+
+set -e
+# docker pull $IMAGE_NAME
+uid=$(id -u)
+gid=$(id -g)
+docker run -it --rm \
+    --entrypoint /root/entrypoint.openxr.sh \
+    -e "USER_ID=$uid" \
+    -e "GROUP_ID=$gid" \
+    -e "CONTAINER_CWD=$MOUNTPOINT" \
+    -v "$MOUNTPOINT:$MOUNTPOINT" \
+    $IMAGE_NAME "$@"

open-in-docker.sh

@@ -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/Makefile

@@ -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