OpenXR SDK 1.0.20 (2021-10-04)

This release includes a proposed cross-vendor OpenXR loader for Android,
Android build system for hello_xr, and a number of new vendor
extensions.

-   Registry
    -   Add new XR_HTCX_vive_tracker_interaction provisional vendor
        extension. (internal MR 1983)
    -   Add new XR_VARJO_marker_tracking vendor extension. (internal MR
        2129)
    -   Add new XR_FB_triangle_mesh vendor extension. (internal MR 2130)
    -   Add new XR_FB_passthrough vendor extension. (internal MR 2130)
    -   Reserve vendor extensions for Facebook. (internal MR 2131)
    -   Reserve a vendor extension for Almalence. (OpenXR-Docs PR 99)
    -   XR_FB_color_space: Fix XML markup to indicate that
        XrSystemColorSpacePropertiesFB is chained to XrSystemProperties.
        (internal MR 2143)
-   SDK
    -   Loader specification: Describe a cross-vendor loader for use on
        Android. (internal MR 1949, internal issue 1425)
    -   hello_xr: Add Android build system, using new cross-vendor
        loader, and make some improvements/fixes. (internal MR 1949,
        internal issue 1425)
    -   loader: Implement cross-vendor loader for Android, with AAR
        Prefab packaging. (internal MR 1949, internal issue 1425)

Author: rpavlik

.appveyor.yml

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

.azure-pipelines/openxr-sdk-source.yml

@@ -21,7 +21,7 @@ stages:
       - job: loader_docs
         pool:
           vmImage: "ubuntu-latest"
-        container: khronosgroup/docker-images:openxr-base.202102
+        container: khronosgroup/docker-images:openxr-base.202110
         steps:
           - script: make loader
             workingDirectory: specification
@@ -34,7 +34,7 @@ stages:
       - job: archive
         pool:
           vmImage: "ubuntu-latest"
-        container: khronosgroup/docker-images:openxr-base.202102
+        container: khronosgroup/docker-images:openxr-base.202110
         steps:
           - script: make loader
             workingDirectory: specification
@@ -62,7 +62,7 @@ stages:
               presentationBackend: wayland
         pool:
           vmImage: "ubuntu-latest"
-        container: khronosgroup/docker-images:openxr-sdk
+        container: khronosgroup/docker-images:openxr-sdk.202102
         steps:
           - task: DownloadPipelineArtifact@2
             displayName: Download archived OpenXR-SDK

.azure-pipelines/openxr-sdk.yml

@@ -14,3 +14,5 @@ stages:
   - stage: Build
     jobs:
       - template: shared/build_jobs.yml
+        parameters:
+          isSdkSourceRepo: false

.azure-pipelines/shared/build_jobs.yml

@@ -5,7 +5,7 @@ parameters:
   - name: sourceDir
     type: string
     default: "$(System.DefaultWorkingDirectory)"
-  - name: isSdk
+  - name: isSdkSourceRepo
     type: boolean
     default: true
 
@@ -96,7 +96,7 @@ jobs:
 
   - job: combine_artifacts
     dependsOn: windows_build
-    condition: ${{ eq(parameters.isSdk, true) }}
+    condition: ${{ eq(parameters.isSdkSourceRepo, true) }}
     displayName: "Organize artifacts"
     pool:
       vmImage: "windows-latest"

.gitignore

@@ -58,3 +58,7 @@ local.properties
 !.markdownlint.yaml
 !.proclamation.json
 !.reuse
+
+# Output artifact
+*.aar
+*.pom

.reuse/dep5

@@ -7,11 +7,34 @@ Files: changes/*
 Copyright: 2019-2021, The Khronos Group Inc.
 License: CC-BY-4.0
 
+Files: src/tests/hello_xr/android_resources/vulkan/mipmap-xxhdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/vulkan/mipmap-mdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/vulkan/mipmap-xhdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/vulkan/mipmap-hdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/vulkan/mipmap-xxxhdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/opengles/mipmap-xxhdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/opengles/mipmap-mdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/opengles/mipmap-xhdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/opengles/mipmap-hdpi/ic_helloxr_launcher.png
+       src/tests/hello_xr/android_resources/opengles/mipmap-xxxhdpi/ic_helloxr_launcher.png
+Copyright: Copyright (c) 2020-2021 The Khronos Group Inc.
+  Copyright (c) 2020, Google
+License: Apache-2.0
+Comment: Based on a Material Icons asset ("emoji-people") with added text
+  in "Miriam Libre" Bold, converted to path, and manually simplified.
+  Rasterized with Android Studio.
+
 Files: src/external/jsoncpp/*
 Copyright: 2007-2010 Baptiste Lepilleur and The JsonCpp Authors
 License: MIT OR LicenseRef-jsoncpp-public-domain
 Comment: Unmodified, vendored copy of jsoncpp 1.8.4
 
+Files: src/external/jnipp/*
+Copyright: 2016-2020, Mitchell Dowd
+  2020, Collabora, Ltd.
+License: MIT
+Comment: Ryan Pavlik at Collabora's fork
+
 Files: external/python/jinja2/*
   external/python/Jinja2-2.10.3.dist-info/*
 Copyright: 2013-2019 by the Jinja team
@@ -43,3 +66,14 @@ Files: specification/sources/chapters/extensions/ext/ext_performance_settings.ad
 Copyright: 2017-2020, The Khronos Group Inc.
 License: CC-BY-4.0
 Comment: In-line license comments requested, https://gitlab.khronos.org/openxr/openxr/-/issues/1419
+
+Files: src/conformance/platform_specific/android_resources/mipmap-hdpi/*
+  src/conformance/platform_specific/android_resources/mipmap-mdpi/*
+  src/conformance/platform_specific/android_resources/mipmap-xhdpi/*
+  src/conformance/platform_specific/android_resources/mipmap-xxhdpi/*
+  src/conformance/platform_specific/android_resources/mipmap-xxxhdpi/*
+Copyright: 2020, The Khronos Group Inc.
+  2020, Google
+License: Apache-2.0
+Comment: Generated .png versions of an icon, created in Android Studio
+  based on a Material Icons asset.

CHANGELOG.SDK.md

@@ -19,6 +19,39 @@ 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.0.20 (2021-10-04)
+
+This release includes a proposed cross-vendor OpenXR loader for Android, Android
+build system for hello_xr, and a number of new vendor extensions.
+
+- Registry
+  - Add new `XR_HTCX_vive_tracker_interaction` provisional vendor extension.
+    ([internal MR 1983](https://gitlab.khronos.org/openxr/openxr/merge_requests/1983))
+  - Add new `XR_VARJO_marker_tracking` vendor extension.
+    ([internal MR 2129](https://gitlab.khronos.org/openxr/openxr/merge_requests/2129))
+  - Add new `XR_FB_triangle_mesh` vendor extension.
+    ([internal MR 2130](https://gitlab.khronos.org/openxr/openxr/merge_requests/2130))
+  - Add new `XR_FB_passthrough` vendor extension.
+    ([internal MR 2130](https://gitlab.khronos.org/openxr/openxr/merge_requests/2130))
+  - Reserve vendor extensions for Facebook.
+    ([internal MR 2131](https://gitlab.khronos.org/openxr/openxr/merge_requests/2131))
+  - Reserve a vendor extension for Almalence.
+    ([OpenXR-Docs PR 99](https://github.com/KhronosGroup/OpenXR-Docs/pull/99))
+  - XR_FB_color_space: Fix XML markup to indicate that
+    `XrSystemColorSpacePropertiesFB` is chained to `XrSystemProperties`.
+    ([internal MR 2143](https://gitlab.khronos.org/openxr/openxr/merge_requests/2143))
+- SDK
+  - Loader specification: Describe a cross-vendor loader for use on Android.
+    ([internal MR 1949](https://gitlab.khronos.org/openxr/openxr/merge_requests/1949),
+    [internal issue 1425](https://gitlab.khronos.org/openxr/openxr/issues/1425))
+  - hello_xr: Add Android build system, using new cross-vendor loader, and make
+    some improvements/fixes.
+    ([internal MR 1949](https://gitlab.khronos.org/openxr/openxr/merge_requests/1949),
+    [internal issue 1425](https://gitlab.khronos.org/openxr/openxr/issues/1425))
+  - loader: Implement cross-vendor loader for Android, with AAR Prefab packaging.
+    ([internal MR 1949](https://gitlab.khronos.org/openxr/openxr/merge_requests/1949),
+    [internal issue 1425](https://gitlab.khronos.org/openxr/openxr/issues/1425))
+
 ## OpenXR SDK 1.0.19 (2021-08-24)
 
 This release features a number of new or updated vendor extensions, as well as

CMakeLists.txt

@@ -42,6 +42,65 @@ if(BUILD_FORCE_GENERATION AND NOT PYTHON_EXECUTABLE)
     message(FATAL_ERROR "BUILD_FORCE_GENERATION requires Python")
 endif()
 
+string(TOUPPER "${CMAKE_GENERATOR_PLATFORM}" CMAKE_GENERATOR_PLATFORM_UPPER)
+
+# Artifact organization
+if(WIN32 OR ANDROID)
+    option(INSTALL_TO_ARCHITECTURE_PREFIXES "Install platform-specific files to architecture-specific directories, for packaging" OFF)
+endif()
+
+if(WIN32 AND INSTALL_TO_ARCHITECTURE_PREFIXES)
+    unset(_UWP_SUFFIX)
+    if(CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
+        set(_UWP_SUFFIX _uwp)
+    endif()
+    if(CMAKE_GENERATOR_PLATFORM_UPPER MATCHES "ARM.*")
+        if(CMAKE_SIZEOF_VOID_P EQUAL 8)
+            set(_PLATFORM ARM64)
+        else()
+            set(_PLATFORM ARM)
+        endif()
+    else()
+        if(CMAKE_SIZEOF_VOID_P EQUAL 8)
+            set(_PLATFORM x64)
+        else()
+            set(_PLATFORM Win32)
+        endif()
+    endif()
+
+    include(GNUInstallDirs)
+    set(CMAKE_INSTALL_BINDIR ${_PLATFORM}${_UWP_SUFFIX}/${CMAKE_INSTALL_BINDIR})
+    set(CMAKE_INSTALL_LIBDIR ${_PLATFORM}${_UWP_SUFFIX}/${CMAKE_INSTALL_LIBDIR})
+
+elseif(ANDROID AND INSTALL_TO_ARCHITECTURE_PREFIXES)
+    # This organizes things like a prefab module
+    set(PREFAB_INSTALL_DIR prefab)
+    set(PREFAB_MODULE_INSTALL_DIR ${PREFAB_INSTALL_DIR}/modules/openxr_loader)
+    set(CMAKE_INSTALL_LIBDIR ${PREFAB_MODULE_INSTALL_DIR}/libs/android.${ANDROID_ABI} CACHE STRING "Where to install libraries")
+    set(CMAKE_INSTALL_BINDIR ${CMAKE_INSTALL_LIBDIR})
+    set(CMAKE_INSTALL_INCDIR ${PREFAB_MODULE_INSTALL_DIR}/include)
+
+    unset(NDK_MAJOR_VERSION)
+    if(CMAKE_ANDROID_NDK)
+        file(STRINGS "${CMAKE_ANDROID_NDK}/source.properties" NDK_PROPERTIES)
+        foreach(_line ${NDK_PROPERTIES})
+            if("${_line}" MATCHES "Pkg.Revision = ([0-9]+)[.]([0-9]+)[.]([0-9]+)")
+                set(NDK_MAJOR_VERSION ${CMAKE_MATCH_1})
+            endif()
+        endforeach()
+    else()
+        message(FATAL_ERROR "Please set CMAKE_ANDROID_NDK to your NDK root!")
+    endif()
+    if(NDK_MAJOR_VERSION)
+        message(STATUS "Building using NDK major version ${NDK_MAJOR_VERSION}")
+    else()
+        message(FATAL_ERROR "Could not parse the major version from ${CMAKE_ANDROID_NDK}/source.properties")
+    endif()
+
+elseif(NOT ANDROID)
+    include(GNUInstallDirs)
+endif()
+
 add_subdirectory(include)
 add_subdirectory(src)
 
@@ -68,4 +127,8 @@ if(BASH_COMMAND AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/specification/Makefile")
     endif()
 endif()
 
-install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE" DESTINATION share/doc/openxr)
+if(ANDROID AND INSTALL_TO_ARCHITECTURE_PREFIXES)
+    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE" DESTINATION META-INF COMPONENT License)
+else()
+    install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE" DESTINATION share/doc/openxr COMPONENT License)
+endif()

include/openxr/CMakeLists.txt

@@ -91,7 +91,11 @@ else()
     )
 endif()
 set_target_properties(generate_openxr_header PROPERTIES FOLDER ${CODEGEN_FOLDER})
+if(NOT CMAKE_INSTALL_INCDIR)
+    set(CMAKE_INSTALL_INCDIR include)
+endif()
 
 INSTALL(FILES ${INSTALL_HEADERS}
-    DESTINATION include/openxr
+    DESTINATION ${CMAKE_INSTALL_INCDIR}/openxr
+    COMPONENT Headers
 )

specification/Makefile

@@ -44,7 +44,7 @@ ifneq (,$(strip $(VERY_STRICT)))
 ASCIIDOC := $(ASCIIDOC) --failure-level WARN
 endif
 
-SPECREVISION = 1.0.19
+SPECREVISION = 1.0.20
 REVISION_COMPONENTS = $(subst ., ,$(SPECREVISION))
 MAJORMINORVER = $(word 1,$(REVISION_COMPONENTS)).$(word 2,$(REVISION_COMPONENTS))
 
@@ -65,6 +65,8 @@ SPECTOOLS     := $(SCRIPTS)/spec_tools
 XRAPI         := scripts/xrapi.py
 METADIR       := sources/chapters/extensions/meta
 
+VK_REF_PAGE_ROOT := https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html
+
 # Gets built automatically
 ASCIIDOCTOR_TARGETS :=
 
@@ -96,7 +98,9 @@ default:
 	$(ECHO) "all:              build as many of these as possible: header header-test html pdf styleguide loader build-examples check-spec-links"
 
 	@if [ -d sources/chapters ] && [ -d loader ]; then \
-	    echo "release:          build header html pdf manhtmlpages and copy output to an OpenXR-Registry-like layout"; fi
+	    echo "release-htmlpdf:  build html pdf and copy output to an OpenXR-Registry-like layout"; \
+	    echo "release:          build html pdf manhtmlpages loader styleguide extprocess and copy output to an OpenXR-Registry-like layout"; \
+	fi
 
 	$(ECHO) "reflow:           reflow AsciiDoctor source files in-place"
 	$(ECHO) "clean_dirt:       remove intermediate files"
@@ -107,6 +111,9 @@ default:
 	$(ECHO) "Pass VERBOSE=1 to invoke asciidoctor with the --verbose option and genxr.py without the -q option"
 	$(ECHO) "Pass STRICT=1 to invoke asciidoctor with the --failure-level ERROR option"
 	$(ECHO) "Pass VERY_STRICT=1 to invoke asciidoctor with the --failure-level WARN option"
+	$(ECHO) "Pass RELEASE=1 to turn off all asciidoctor date/timestamps for a reproducible release build"
+	@if [ -d sources/chapters ] && [ -d loader ]; then \
+	    echo "Pass some string for RELEASE_SPECS_SUFFIX to add a suffix to the version-numbered directory for the release targets"; fi
 
 ################################################
 # Store our build configuration in a file, and force re-generation if it changes.
@@ -277,8 +284,10 @@ $(EXTPROCESSGUIDE): $(EXTPROCESSSRC)
 
 COMMONDOCS = $(SPECSRC) $(SPECFILES) $(GENINCLUDE) $(GENDEPENDS)
 
+SPEC_FILENAME_STEM := openxr
+
 ## HTML
-HTMLSPEC      := $(OUTDIR)/openxr.html
+HTMLSPEC      := $(OUTDIR)/$(SPEC_FILENAME_STEM).html
 html: $(HTMLSPEC)
 
 # Use the AsciiDoctor rule
@@ -291,8 +300,8 @@ $(HTMLSPEC): $(COMMONDOCS)
 $(HTMLSPEC): POSTPROCESS=$(QUIET)$(PYTHON) $(SCRIPTS)/genanchorlinks.py $@ $@
 
 ## PDF
-PDFSPEC       := $(OUTDIR)/openxr.pdf
-PDFA4SPEC       := $(OUTDIR)/openxr.a4.pdf
+PDFSPEC       := $(OUTDIR)/$(SPEC_FILENAME_STEM).pdf
+PDFA4SPEC     := $(OUTDIR)/$(SPEC_FILENAME_STEM).a4.pdf
 
 pdf pdfLetter: $(PDFSPEC)
 pdfA4: $(PDFA4SPEC)
@@ -326,11 +335,8 @@ ifeq ($(GITBRANCH),)
 GITBRANCH  := $(shell echo `git symbolic-ref --short HEAD`)
 endif
 GITREMARK  ?= from git branch: $(GITBRANCH)
-SPECREMARK ?= $(GITREMARK) \
-             commit: $(shell echo `git log -1 --format="%H"`)
 
 ATTRIBOPTS   = -a revnumber="$(SPECREVISION)" \
-               -a revdate="$(SPECDATE)" \
                -a revremark="$(SPECREMARK)" \
                -a apititle="$(APITITLE)" \
                -a stem=latexmath \
@@ -342,6 +348,20 @@ ATTRIBOPTS   = -a revnumber="$(SPECREVISION)" \
 
 ADOCOPTS = --doctype book -a data-uri -r $(CURDIR)/scripts/openxr-macros.rb $(ATTRIBOPTS)
 
+ifneq (,$(strip $(RELEASE)))
+# No dates or internal commit hashes in release builds for reproducibility
+ATTRIBOPTS   += -a revdate!
+ATTRIBOPTS   += -a last-update-label!
+ATTRIBOPTS   += -a reproducible
+SPECREMARK   ?= $(GITREMARK)
+
+else
+ATTRIBOPTS   += -a revdate="$(SPECDATE)"
+SPECREMARK   ?= $(GITREMARK) \
+                commit: $(shell echo `git log -1 --format="%H"`)
+
+endif
+
 ifneq (,$(strip $(KHRONOS_SPEC_LICENSED)))
 # Enable photo of JP in dedication: not CC-BY-4.0,
 # so only used in generated docs now.
@@ -390,10 +410,13 @@ MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt
 MANGENERATED = $(filter-out $(MANCOPYRIGHT),$(wildcard $(MANDIR)/*))
 MANHTML      = $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
 MANDEPS      = $(MANCOPYRIGHT) $(GENINCLUDE) $(GENDEPENDS)
+HTML_SPEC_RELATIVE ?= ../../$(SPEC_FILENAME_STEM).html
 MANATTRIBOPTS := -a stylesheet=khronos.css \
-				-a stylesdir=$(CURDIR)/config \
-				-a html_spec_relative='../../openxr.html' \
-				-a imagesdir=$(CURDIR)/sources
+				 -a stylesdir=$(CURDIR)/config \
+				 -a html_spec_relative='$(HTML_SPEC_RELATIVE)' \
+				 -a imagesdir=$(CURDIR)/sources \
+				 -a vkRefPageRoot='$(VK_REF_PAGE_ROOT)'
+
 
 # Pure makefile lowercase function, generated by a script.
 make_lower = $(subst A,a,$(subst B,b,$(subst C,c,$(subst D,d,$(subst E,e,$(subst F,f,$(subst G,g,$(subst H,h,$(subst I,i,$(subst J,j,$(subst K,k,$(subst L,l,$(subst M,m,$(subst N,n,$(subst O,o,$(subst P,p,$(subst Q,q,$(subst R,r,$(subst S,s,$(subst T,t,$(subst U,u,$(subst V,v,$(subst W,w,$(subst X,x,$(subst Y,y,$(subst Z,z,$(1)))))))))))))))))))))))))))
@@ -514,16 +537,23 @@ all:
 
 ################################################
 # Meta build for releases. Also copies into approximately the right layout for the OpenXR-Registry repo.
-REGISTRYOUTDIR = $(OUTDIR)/../registry-release/specs/$(MAJORMINORVER)
-release: header html pdf manhtmlpages loader styleguide extprocess
+REGISTRYOUTDIR = $(OUTDIR)/../registry-release/specs/$(MAJORMINORVER)$(RELEASE_SPECS_SUFFIX)
+
+$(REGISTRYOUTDIR):
+	$(QUIET)$(MKDIR) $@
+
+$(REGISTRYOUTDIR)/pdf $(REGISTRYOUTDIR)/html $(REGISTRYOUTDIR)/man: $(REGISTRYOUTDIR)
+	$(QUIET)$(MKDIR) $@
+
+release-htmlpdf: html pdf $(REGISTRYOUTDIR)/pdf $(REGISTRYOUTDIR)/html
 	-asciidoctor-pdf-optimize $(PDFSPEC)
-	$(QUIET)$(MKDIR) $(REGISTRYOUTDIR)/pdf
 	$(QUIET)$(CP) $(PDFSPEC) $(REGISTRYOUTDIR)/pdf/xrspec.pdf
-	$(QUIET)$(MKDIR) $(REGISTRYOUTDIR)/html
 	$(QUIET)$(CP) $(HTMLSPEC) $(REGISTRYOUTDIR)/html/xrspec.html
-	$(QUIET)$(CP) $(OUTDIR)/styleguide.html $(OUTDIR)/extprocess.html $(REGISTRYOUTDIR)
-	$(QUIET)$(MKDIR) $(REGISTRYOUTDIR)/man
+.PHONY: release-htmlpdf
+release: release-htmlpdf manhtmlpages loader styleguide extprocess $(REGISTRYOUTDIR) $(REGISTRYOUTDIR)/man
+	$(QUIET)$(CP) $(OUTDIR)/styleguide.html $(OUTDIR)/extprocess.html $(OUTDIR)/loader.html $(REGISTRYOUTDIR)
 	$(QUIET)$(CP) -R $(MANHTMLDIR) $(REGISTRYOUTDIR)/man/html
+.PHONY: release
 
 ################################################
 ## Clean targets