OpenXR Specification 1.1.38 (2024-06-09)

This is a fairly small release, with one new extension and a handful of
fixes.

-   Registry
    -   Addition: New multi-vendor extension:
        XR_EXT_composition_layer_inverted_alpha (internal MR 3085,
        internal MR 3385)
    -   Chore: Reserve an extension for Logitech. (internal MR 3384)
    -   Chore: Register author tag for Deep Mirror. (OpenXR-Docs PR 171)
    -   Fix: XrCompositionLayerPassthroughFB has a “parentstruct” of
        XrCompositionLayerBaseHeader (it is based on this type), rather
        than “structextends” (in the next chain). Bump extension
        revision. (internal MR 3305)
    -   Fix: XR_EXT_plane_detection: Fix extents description and plane
        axis to match CTS and implementations. (internal MR 3374,
        internal issue 2281)
    -   Fix: Correct typo in XR_FB_keyboard_tracking flag description.
        (internal MR 3393)
-   Specification
    -   Addition: New multi-vendor extension specification:
        XR_EXT_composition_layer_inverted_alpha (internal MR 3085)
    -   Addition: Support emitting more comment attributes/elements from
        XML, and enable it for standalone headers. (internal MR 3377)
    -   Fix: Note errata regarding third field name in
        XrCompositionLayerPassthroughFB. Bump extension revision due to
        XML fix. (internal MR 3305)
    -   Fix: XR_EXT_plane_detection: Fix extents description and plane
        axis to match CTS and implementations. (internal MR 3374,
        internal issue 2281)
    -   Fix: Correct typo in XR_FB_keyboard_tracking flag description.
        (internal MR 3393)
    -   Fix: Correct typo in loader design document. (internal MR 3393)

GitOrigin-RevId: fd4ad294a24169b4db555022859a02dd5bebcd2f

CHANGELOG.Docs.md

@@ -17,6 +17,47 @@ 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.38 (2024-06-09)
+
+This is a fairly small release, with one new extension and a handful of fixes.
+
+- Registry
+  - Addition: New multi-vendor extension: `XR_EXT_composition_layer_inverted_alpha`
+    ([internal MR 3085](https://gitlab.khronos.org/openxr/openxr/merge_requests/3085),
+    [internal MR 3385](https://gitlab.khronos.org/openxr/openxr/merge_requests/3385))
+  - Chore: Reserve an extension for Logitech.
+    ([internal MR 3384](https://gitlab.khronos.org/openxr/openxr/merge_requests/3384))
+  - Chore: Register author tag for Deep Mirror.
+    ([OpenXR-Docs PR 171](https://github.com/KhronosGroup/OpenXR-Docs/pull/171))
+  - Fix: `XrCompositionLayerPassthroughFB` has a "parentstruct" of
+    `XrCompositionLayerBaseHeader` (it is based on this type), rather than
+    "structextends" (in the next chain). Bump extension revision.
+    ([internal MR 3305](https://gitlab.khronos.org/openxr/openxr/merge_requests/3305))
+  - Fix: `XR_EXT_plane_detection`: Fix extents description and plane axis to match
+    CTS and implementations.
+    ([internal MR 3374](https://gitlab.khronos.org/openxr/openxr/merge_requests/3374),
+    [internal issue 2281](https://gitlab.khronos.org/openxr/openxr/issues/2281))
+  - Fix: Correct typo in `XR_FB_keyboard_tracking` flag description.
+    ([internal MR 3393](https://gitlab.khronos.org/openxr/openxr/merge_requests/3393))
+- Specification
+  - Addition: New multi-vendor extension specification:
+    `XR_EXT_composition_layer_inverted_alpha`
+    ([internal MR 3085](https://gitlab.khronos.org/openxr/openxr/merge_requests/3085))
+  - Addition: Support emitting more comment attributes/elements from XML, and
+    enable it for standalone headers.
+    ([internal MR 3377](https://gitlab.khronos.org/openxr/openxr/merge_requests/3377))
+  - Fix: Note errata regarding third field name in
+    `XrCompositionLayerPassthroughFB`. Bump extension revision due to XML fix.
+    ([internal MR 3305](https://gitlab.khronos.org/openxr/openxr/merge_requests/3305))
+  - Fix: `XR_EXT_plane_detection`: Fix extents description and plane axis to match
+    CTS and implementations.
+    ([internal MR 3374](https://gitlab.khronos.org/openxr/openxr/merge_requests/3374),
+    [internal issue 2281](https://gitlab.khronos.org/openxr/openxr/issues/2281))
+  - Fix: Correct typo in `XR_FB_keyboard_tracking` flag description.
+    ([internal MR 3393](https://gitlab.khronos.org/openxr/openxr/merge_requests/3393))
+  - Fix: Correct typo in loader design document.
+    ([internal MR 3393](https://gitlab.khronos.org/openxr/openxr/merge_requests/3393))
+
 ## 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

checkCodespell

@@ -44,13 +44,15 @@ CODESPELL_IGNORE=${CODESPELL_IGNORE:-${DEFAULT_CODESPELL_IGNORE}}
 # .Nd is used for a description in a mandoc manpage.
 # ba is from a regex
 # unknwn is a header file name
-# Wee, Ser, Nuber, Blok are names
-IGNORE_WORDS="lod,nd,ba,unknwn,wee,ser,nuber,blok,rouge,implementor,implementors"
+# Wee, Ser, Nuber, Blok, DeVault are names
+# rouge is a word (and our source code highlighter)
+# implementors is just how we spell it
+IGNORE_WORDS="lod,nd,ba,unknwn,wee,ser,nuber,blok,devault,rouge,implementor,implementors"
 
 # Add to this to exclude individual files or directories (comma-delimited)
 # - Skipping external code.
-# - Skipping binary files.
-SKIP="${ROOT}/src/external,${ROOT}/src/conformance/framework/catch2,*.pyc,*.png,*.jpg,*.svg,*.otf"
+# - Skipping binary and data files.
+SKIP="${ROOT}/src/external,${ROOT}/src/conformance/framework/catch2,*.pyc,*.png,*.jpg,*.svg,*.otf,*.slvs"
 
 # Args that get passed if no args are provided to this script.
 # -q4 to silence "UINT  ==> UNIT  | disabled due to being a data type"

specification/Makefile

@@ -39,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.37
+SPECREVISION = 1.1.38
 REVISION_COMPONENTS = $(subst ., ,$(SPECREVISION))
 MAJORMINORVER = $(word 1,$(REVISION_COMPONENTS)).$(word 2,$(REVISION_COMPONENTS))
 

specification/current_version.ini

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

specification/registry/registry.sch

@@ -294,8 +294,9 @@
             <sch:let name="should_be_shared_with_parent" value="not($field_num > $parent_member_count)"/>
             <sch:let name="matching_parent_field" value="$parentstruct/member[position() = $field_num]" />
             <sch:let name="matching_parent_field_name" value="$matching_parent_field/name/text()" />
+            <sch:let name="is_exception" value="$struct_name = 'XrCompositionLayerPassthroughFB' and $field_name = 'flags'"/>
 
-            <sch:assert test="$field_name = $matching_parent_field_name or not($should_be_shared_with_parent)">
+            <sch:assert test="$field_name = $matching_parent_field_name or not($should_be_shared_with_parent) or $is_exception">
                 <sch:value-of select="$struct_name"/>: field <sch:value-of select="$field_name"/> (field number <sch:value-of select="$field_num"/>) should have matching name to the corresponding parent field, but does not: <sch:value-of select="$matching_parent_field_name"/>. Please make them match.
             </sch:assert>
 

specification/registry/xr.xml

@@ -135,7 +135,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project.
         updates them automatically by processing a line at a time.
         -->
         <type category="define">// OpenXR current version number.
-#define <name>XR_CURRENT_API_VERSION</name> <type>XR_MAKE_VERSION</type>(1, 1, 37)</type>
+#define <name>XR_CURRENT_API_VERSION</name> <type>XR_MAKE_VERSION</type>(1, 1, 38)</type>
 
         <!--
         Defines for a fixed major.minor version of OpenXR preserving the shared patch version.
@@ -2840,7 +2840,7 @@ typedef XrResult (XRAPI_PTR *<name>PFN_xrCreateApiLayerInstance</name>)(
             <member><type>XrPassthroughFlagsFB</type>        <name>flags</name></member>
             <member><type>XrPassthroughLayerPurposeFB</type> <name>purpose</name></member>
         </type>
-        <type category="struct" name="XrCompositionLayerPassthroughFB" structextends="XrCompositionLayerBaseHeader">
+        <type category="struct" name="XrCompositionLayerPassthroughFB" parentstruct="XrCompositionLayerBaseHeader">
             <member values="XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_FB"><type>XrStructureType</type> <name>type</name></member>
             <member>const <type>void</type>*             <name>next</name></member>
             <member><type>XrCompositionLayerFlags</type> <name>flags</name></member>
@@ -4743,15 +4743,15 @@ typedef XrResult (XRAPI_PTR *<name>PFN_xrCreateApiLayerInstance</name>)(
     <!-- flags for XR_FB_keyboard_tracking query state -->
     <enums name="XrKeyboardTrackingFlagBitsFB" type="bitmask">
         <enum bitpos="0" name="XR_KEYBOARD_TRACKING_EXISTS_BIT_FB"    comment="indicates that the system has a physically tracked keyboard to report.  If not set then no other bits should be considered to be valid or meaningful.  If set either XR_KEYBOARD_TRACKING_LOCAL_BIT_FB or XR_KEYBOARD_TRACKING_REMOTE_BIT_FB must also be set."/>
-        <enum bitpos="1" name="XR_KEYBOARD_TRACKING_LOCAL_BIT_FB"     comment="indicates that the physically tracked keyboard is intended to be used in a local pairing with the system.  Mutally exclusive with XR_KEYBOARD_TRACKING_REMOTE_BIT_FB."/>
-        <enum bitpos="2" name="XR_KEYBOARD_TRACKING_REMOTE_BIT_FB"    comment="indicates that the physically tracked keyboard is intended to be used while paired to a separate remote computing device. Mutally exclusive with XR_KEYBOARD_TRACKING_LOCAL_BIT_FB."/>
+        <enum bitpos="1" name="XR_KEYBOARD_TRACKING_LOCAL_BIT_FB"     comment="indicates that the physically tracked keyboard is intended to be used in a local pairing with the system.  Mutually exclusive with XR_KEYBOARD_TRACKING_REMOTE_BIT_FB."/>
+        <enum bitpos="2" name="XR_KEYBOARD_TRACKING_REMOTE_BIT_FB"    comment="indicates that the physically tracked keyboard is intended to be used while paired to a separate remote computing device. Mutually exclusive with XR_KEYBOARD_TRACKING_LOCAL_BIT_FB."/>
         <enum bitpos="3" name="XR_KEYBOARD_TRACKING_CONNECTED_BIT_FB" comment="indicates that the physically tracked keyboard is actively connected to the headset and capable of sending key data"/>
     </enums>
 
     <!-- flags for XR_FB_keyboard_tracking query -->
     <enums name="XrKeyboardTrackingQueryFlagBitsFB" type="bitmask">
-        <enum bitpos="1" name="XR_KEYBOARD_TRACKING_QUERY_LOCAL_BIT_FB"  comment="indicates the query is for the physically tracked keyboard that is intended to be used in a local pairing with the System. Mutally exclusive with XR_KEYBOARD_TRACKING_QUERY_REMOTE_BIT_FB."/>
-        <enum bitpos="2" name="XR_KEYBOARD_TRACKING_QUERY_REMOTE_BIT_FB" comment="indicates the query is for the physically tracked keyboard that may be connected to a separate remote computing device. Mutally exclusive with XR_KEYBOARD_TRACKING_QUERY_LOCAL_BIT_FB."/>
+        <enum bitpos="1" name="XR_KEYBOARD_TRACKING_QUERY_LOCAL_BIT_FB"  comment="indicates the query is for the physically tracked keyboard that is intended to be used in a local pairing with the System. Mutually exclusive with XR_KEYBOARD_TRACKING_QUERY_REMOTE_BIT_FB."/>
+        <enum bitpos="2" name="XR_KEYBOARD_TRACKING_QUERY_REMOTE_BIT_FB" comment="indicates the query is for the physically tracked keyboard that may be connected to a separate remote computing device. Mutually exclusive with XR_KEYBOARD_TRACKING_QUERY_LOCAL_BIT_FB."/>
     </enums>
 
     <!-- flags for XR_FB_space_warp -->
@@ -9801,7 +9801,7 @@ typedef XrResult (XRAPI_PTR *<name>PFN_xrCreateApiLayerInstance</name>)(
 
     <extension name="XR_FB_passthrough" number="119" type="instance" supported="openxr">
         <require>
-            <enum value="3"                                     name="XR_FB_passthrough_SPEC_VERSION"/>
+            <enum value="4"                                     name="XR_FB_passthrough_SPEC_VERSION"/>
             <enum value="&quot;XR_FB_passthrough&quot;"         name="XR_FB_PASSTHROUGH_EXTENSION_NAME"/>
 
             <enum offset="0"          extends="XrStructureType" name="XR_TYPE_SYSTEM_PASSTHROUGH_PROPERTIES_FB"/>
@@ -12867,7 +12867,7 @@ typedef XrResult (XRAPI_PTR *<name>PFN_xrCreateApiLayerInstance</name>)(
 
     <extension name="XR_EXT_plane_detection" number="430" type="instance" supported="openxr">
         <require>
-            <enum value="1"                                  name="XR_EXT_plane_detection_SPEC_VERSION"/>
+            <enum value="2"                                  name="XR_EXT_plane_detection_SPEC_VERSION"/>
             <enum value="&quot;XR_EXT_plane_detection&quot;" name="XR_EXT_PLANE_DETECTION_EXTENSION_NAME"/>
 
             <enum offset="0" dir="-" extends="XrResult"      name="XR_ERROR_SPACE_NOT_LOCATABLE_EXT"               comment="The space passed to the function was not locatable."/>
@@ -13834,10 +13834,12 @@ typedef XrResult (XRAPI_PTR *<name>PFN_xrCreateApiLayerInstance</name>)(
         </require>
     </extension>
 
-    <extension name="XR_META_extension_555" number="555" type="instance" supported="disabled">
+    <extension name="XR_EXT_composition_layer_inverted_alpha" number="555" type="instance" supported="openxr">
         <require>
-            <enum value="1"                                 name="XR_META_extension_555_SPEC_VERSION"/>
-            <enum value="&quot;XR_META_extension_555&quot;" name="XR_META_extension_555_EXTENSION_NAME"/>
+            <enum value="1"                                                   name="XR_EXT_composition_layer_inverted_alpha_SPEC_VERSION"/>
+            <enum value="&quot;XR_EXT_composition_layer_inverted_alpha&quot;" name="XR_EXT_COMPOSITION_LAYER_INVERTED_ALPHA_EXTENSION_NAME"/>
+            <enum bitpos="3" extends="XrCompositionLayerFlagBits"             name="XR_COMPOSITION_LAYER_INVERTED_ALPHA_BIT_EXT"            comment="Indicates that the texture alpha channel stores transparency instead of opacity, and is to be inverted before layer blending."/>
+            <!-- Addition to core bitmask from EXT approved by WG 14-March-2024 -->
         </require>
     </extension>
 
@@ -15285,6 +15287,13 @@ typedef XrResult (XRAPI_PTR *<name>PFN_xrCreateApiLayerInstance</name>)(
         </require>
     </extension>
 
+    <extension name="XR_LOGITECH_extension_746" number="746" type="instance" supported="disabled">
+        <require>
+            <enum value="1"                                     name="XR_LOGITECH_extension_746_SPEC_VERSION"/>
+            <enum value="&quot;XR_LOGITECH_extension_746&quot;" name="XR_LOGITECH_EXTENSION_746_EXTENSION_NAME"/>
+        </require>
+    </extension>
+
     </extensions>
 
 </registry>

specification/scripts/cgenerator.py

@@ -361,6 +361,10 @@ def genType(self, typeinfo, name, alias):
                 if category == 'define' and self.misracppstyle():
                     body = body.replace("(uint32_t)", "static_cast<uint32_t>")
             if body:
+                comment = typeElem.get('comment')
+                if comment and self.genOpts.emitComments:
+                    body = self.makeCComment(comment) + body
+
                 # Add extra newline after multi-line entries.
                 if '\n' in body[0:-1]:
                     body += '\n'
@@ -428,10 +432,14 @@ def genStruct(self, typeinfo, typeName, alias):
 
         typeElem = typeinfo.elem
 
+        body = ''
+        comment = typeElem.get('comment')
+        if comment and self.genOpts.emitComments:
+            body += self.makeCComment(comment)
+
         if alias:
-            body = f"typedef {alias} {typeName};\n"
+            body += f"typedef {alias} {typeName};\n"
         else:
-            body = ''
             (protect_begin, protect_end) = self.genProtectString(typeElem.get('protect'))
             if protect_begin:
                 body += protect_begin
@@ -451,9 +459,12 @@ def genStruct(self, typeinfo, typeName, alias):
             body += f" {typeName} {{\n"
 
             targetLen = self.getMaxCParamTypeLength(typeinfo)
-            for member in typeElem.findall('.//member'):
-                body += self.makeCParamDecl(member, targetLen + 4)
-                body += ';\n'
+            for elem in list(typeElem):
+                if elem.tag == 'member':
+                    body += self.makeCParamDecl(elem, targetLen + 4)
+                    body += ';\n'
+                elif elem.tag == 'comment' and self.genOpts.emitComments:
+                    body += self.makeCComment(elem.text, indents = 1)
             body += f"}} {typeName};\n"
             if protect_end:
                 body += protect_end