From 4f1867e662112a747f143a41478f3b8886eb0c2b Mon Sep 17 00:00:00 2001 From: Ryan Pavlik Date: Wed, 20 Sep 2023 11:25:42 -0500 Subject: [PATCH] OpenXR Specification 1.0.30 (2023-09-20) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This release is primarily a quality improvement release, fixing a range of issues in the registry and specification, in addition to a new vendor extension and an updated vendor extension. - Registry - Add missing enum tags for enum-sized array struct members. (internal MR 2731) - Fix EGL “get proc addr” function pointer typedef. (internal MR 2939) - New vendor extension: XR_YVR_controller_interaction (internal MR 2841) - XR_BD_controller_interaction: Add support for G3 devices (internal MR 2872) - Fix specification errors highlighted by fixed tooling. (internal MR 2923) - Specification - Clarify how prior frame state is reset when a session starts running. (internal MR 2759, internal issue 2029) - Clean up normative language in FB vendor extensions. (internal MR 2563) - Clean up normative language in the Rendering chapter. (internal MR 2801) - Fix formatting and markup errors in the loader design document. (internal MR 2866) - Fix generated broken links from valid usage in ref pages to the next chain fundamentals. (internal MR 2931, internal issue 1369) - Fix broken links and update URLs in specification, extension process, style guide, and loader doc. (internal MR 2935) - New vendor extension specification: XR_YVR_controller_interaction (internal MR 2841) - XR_BD_controller_interaction: Add support for G3 devices (internal MR 2872) - XR_EXT_debug_utils: Fix XML to reflect that XrDebugUtilsMessengerCallbackDataEXT parameters messageId and functionName are optional. (internal MR 2864) - scripts: Fix member name lookups in entity_db, enabling numerous spec warnings that had been hidden. (internal MR 2923) - Fix specification errors (core and extension) highlighted by fixed tooling. (internal MR 2923) GitOrigin-RevId: f7a0c0f3691f0c7b0a239cb34e41d01042d5a02a --- .reuse/dep5 | 6 +- CHANGELOG.Docs.md | 48 +++++++ specification/Makefile | 9 +- specification/config/attribs.adoc | 31 ++++- specification/config/copyright-spec.adoc | 2 +- specification/current_version.ini | 2 +- specification/registry/registry.sch | 1 + specification/registry/xr.xml | 119 ++++++++++++++---- specification/scripts/genRef.py | 7 +- specification/scripts/spec_tools/entity_db.py | 2 +- specification/scripts/validitygenerator.py | 4 +- specification/scripts/xrconventions.py | 2 +- .../bd/bd_controller_interaction.adoc | 44 +++++-- .../ext/ext_active_action_set_priority.adoc | 4 +- .../ext/ext_conformance_automation.adoc | 2 + .../extensions/ext/ext_debug_utils.adoc | 3 + .../extensions/ext/ext_plane_detection.adoc | 21 ++-- .../extensions/fb/fb_body_tracking.adoc | 8 +- .../fb/fb_composition_layer_settings.adoc | 3 +- .../extensions/fb/fb_eye_tracking_social.adoc | 2 +- .../extensions/fb/fb_face_tracking.adoc | 4 +- .../fb/fb_hand_tracking_capsules.adoc | 2 +- .../extensions/fb/fb_hand_tracking_mesh.adoc | 16 +-- .../extensions/fb/fb_keyboard_tracking.adoc | 3 + .../extensions/fb/fb_passthrough.adoc | 12 +- .../extensions/fb/fb_render_model.adoc | 7 +- .../htcx/htcx_vive_tracker_interaction.adoc | 18 ++- .../extensions/khr/khr_vulkan_enable2.adoc | 32 ++--- .../meta/meta_virtual_keyboard.adoc | 2 +- .../chapters/extensions/ml/ml_compat.adoc | 6 +- .../msft_composition_layer_reprojection.adoc | 5 + .../msft/msft_controller_model.adoc | 5 +- .../varjo/varjo_marker_tracking.adoc | 1 + .../yvr/yvr_controller_interaction.adoc | 83 ++++++++++++ .../sources/chapters/introduction.adoc | 2 +- specification/sources/chapters/rendering.adoc | 93 +++++++------- specification/sources/chapters/session.adoc | 2 + .../sources/chapters/view_configurations.adoc | 13 +- .../sources/extprocess/extension_process.adoc | 13 +- .../sources/styleguide/extensions.adoc | 31 ++--- specification/sources/styleguide/markup.adoc | 30 ++--- specification/sources/styleguide/naming.adoc | 6 +- .../sources/styleguide/styleguide.adoc | 2 + specification/sources/styleguide/writing.adoc | 27 ++-- 44 files changed, 515 insertions(+), 220 deletions(-) create mode 100755 specification/sources/chapters/extensions/yvr/yvr_controller_interaction.adoc diff --git a/.reuse/dep5 b/.reuse/dep5 index 3df6553a..c905fc9a 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -1,7 +1,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Upstream-Name: OpenXR Upstream-Contact: Ryan Pavlik -Source: https://khronos.org/registry/OpenXR/ +Source: https://registry.khronos.org/OpenXR/ Files: changes/conformance/* changes/registry/* @@ -54,8 +54,8 @@ Comment: Unmodified, vendored copy of a subset of the tiny-gltf repo v2.8.9 Files: src/external/d3dx12/* Copyright: Copyright (c) Microsoft Corporation. License: MIT -Comment: Unmodified, vendored copy of DirectX-Headers commit da7aedb - of https://github.com/microsoft/DirectX-Headers filtered to just d3dx12 headers +Comment: Unmodified, vendored copy of d3dx12.h from directx-vs-templates commit 86b9c45 + This repo includes ifdefs to improve compatibility with older Windows SDK verions. Files: src/external/mikktspace/* Copyright: 2011 by Morten S. Mikkelsen diff --git a/CHANGELOG.Docs.md b/CHANGELOG.Docs.md index be7bc993..cc6e3354 100644 --- a/CHANGELOG.Docs.md +++ b/CHANGELOG.Docs.md @@ -17,6 +17,54 @@ 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.0.30 (2023-09-20) + +This release is primarily a quality improvement release, fixing a range of +issues in the registry and specification, in addition to a new vendor extension +and an updated vendor extension. + +- Registry + - Add missing enum tags for enum-sized array struct members. + ([internal MR 2731](https://gitlab.khronos.org/openxr/openxr/merge_requests/2731)) + - Fix EGL "get proc addr" function pointer typedef. + ([internal MR 2939](https://gitlab.khronos.org/openxr/openxr/merge_requests/2939)) + - New vendor extension: `XR_YVR_controller_interaction` + ([internal MR 2841](https://gitlab.khronos.org/openxr/openxr/merge_requests/2841)) + - `XR_BD_controller_interaction`: Add support for G3 devices + ([internal MR 2872](https://gitlab.khronos.org/openxr/openxr/merge_requests/2872)) + - Fix specification errors highlighted by fixed tooling. + ([internal MR 2923](https://gitlab.khronos.org/openxr/openxr/merge_requests/2923)) +- Specification + - Clarify how prior frame state is reset when a session starts running. + ([internal MR 2759](https://gitlab.khronos.org/openxr/openxr/merge_requests/2759), + [internal issue 2029](https://gitlab.khronos.org/openxr/openxr/issues/2029)) + - Clean up normative language in FB vendor extensions. + ([internal MR 2563](https://gitlab.khronos.org/openxr/openxr/merge_requests/2563)) + - Clean up normative language in the Rendering chapter. + ([internal MR 2801](https://gitlab.khronos.org/openxr/openxr/merge_requests/2801)) + - Fix formatting and markup errors in the loader design document. + ([internal MR 2866](https://gitlab.khronos.org/openxr/openxr/merge_requests/2866)) + - Fix generated broken links from valid usage in ref pages to the next chain + fundamentals. + ([internal MR 2931](https://gitlab.khronos.org/openxr/openxr/merge_requests/2931), + [internal issue 1369](https://gitlab.khronos.org/openxr/openxr/issues/1369)) + - Fix broken links and update URLs in specification, extension process, style + guide, and loader doc. + ([internal MR 2935](https://gitlab.khronos.org/openxr/openxr/merge_requests/2935)) + - New vendor extension specification: `XR_YVR_controller_interaction` + ([internal MR 2841](https://gitlab.khronos.org/openxr/openxr/merge_requests/2841)) + - `XR_BD_controller_interaction`: Add support for G3 devices + ([internal MR 2872](https://gitlab.khronos.org/openxr/openxr/merge_requests/2872)) + - `XR_EXT_debug_utils`: Fix XML to reflect that + `XrDebugUtilsMessengerCallbackDataEXT` parameters `messageId` and + `functionName` are optional. + ([internal MR 2864](https://gitlab.khronos.org/openxr/openxr/merge_requests/2864)) + - scripts: Fix member name lookups in `entity_db`, enabling numerous spec + warnings that had been hidden. + ([internal MR 2923](https://gitlab.khronos.org/openxr/openxr/merge_requests/2923)) + - Fix specification errors (core and extension) highlighted by fixed tooling. + ([internal MR 2923](https://gitlab.khronos.org/openxr/openxr/merge_requests/2923)) + ## OpenXR Specification 1.0.29 (2023-08-25) This release contains several fixes to the specification, as well as diff --git a/specification/Makefile b/specification/Makefile index fcf69338..c9f16147 100644 --- a/specification/Makefile +++ b/specification/Makefile @@ -32,7 +32,7 @@ ifneq (,$(strip $(VERY_STRICT))) ASCIIDOC := $(ASCIIDOC) --failure-level WARN endif -SPECREVISION = 1.0.29 +SPECREVISION = 1.0.30 REVISION_COMPONENTS = $(subst ., ,$(SPECREVISION)) MAJORMINORVER = $(word 1,$(REVISION_COMPONENTS)).$(word 2,$(REVISION_COMPONENTS)) @@ -57,7 +57,7 @@ PYAPIMAP := $(GENDIR)/apimap.py RBAPIMAP := $(GENDIR)/apimap.rb METADIR := $(GENDIR)/meta -VK_REF_PAGE_ROOT := https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html +VK_REF_PAGE_ROOT := https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ MAKE_RELATIVE = $(patsubst $(CURDIR)/%,%,$(1)) @@ -406,7 +406,7 @@ MANSOURCES = $(CORESOURCES) $(VENSOURCES) $(KHRSOURCES) MANGENERATED = $(wildcard $(REFPATH)/*) MANHTML = $(MANSOURCES:$(REFPATH)/%.txt=$(MANHTMLDIR)/%.html) MANDEPS = $(GENINCLUDE) $(GENDEPENDS) -HTML_SPEC_RELATIVE ?= ../../$(SPEC_FILENAME_STEM).html +HTML_SPEC_RELATIVE ?= ../../html/$(SPEC_FILENAME_STEM).html # Asciidoctor options to build refpages # @@ -421,8 +421,7 @@ ADOCREFOPTS = -a stylesheet=khronos.css \ -a refprefix='refpage.' \ -a isrefpage \ -a html_spec_relative='$(HTML_SPEC_RELATIVE)' \ - -a imagesdir=$(CURDIR)/sources \ - -a vkRefPageRoot='$(VK_REF_PAGE_ROOT)' + -a imagesdir=$(CURDIR)/sources # 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))))))))))))))))))))))))))) diff --git a/specification/config/attribs.adoc b/specification/config/attribs.adoc index cadcdbeb..734efcc6 100644 --- a/specification/config/attribs.adoc +++ b/specification/config/attribs.adoc @@ -66,7 +66,36 @@ ifndef::backend-html5[] :wbro: endif::backend-html5[] - // Placeholders for synchronization block text :externsynctitle: Thread Safety :externsyncprefix: Access to + +// next chain link to avoid broken links in ref pages +// This section is not in a ref page so cross-file-links is not the right attribute to check. +ifdef::doctype-manpage[] +:uri-next-chain: {html_spec_relative}#valid-usage-for-structure-pointer-chains +endif::doctype-manpage[] +ifndef::doctype-manpage[] +:uri-next-chain: #valid-usage-for-structure-pointer-chains +endif::doctype-manpage[] + +// URIs used in the spec: +// If it's in the main spec and extracted to the ref pages, put it here. + +// OpenXR URIs +:uri-openxr-registry-root: https://registry.khronos.org/OpenXR +:uri-openxr-ratified-spec: {uri-openxr-registry-root}/specs/1.0-khr/html/xrspec.html +:uri-github-openxr-docs: https://github.com/KhronosGroup/OpenXR-Docs + +// glTF URIs +:uri-gltf2: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html +:uri-gltf2-basisu: https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_basisu + +// Vulkan URIs +:uri-vk-ref-page-root: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html +:uri-vkCreateInstance: {uri-vk-ref-page-root}/vkCreateInstance.html +:uri-VkInstanceCreateInfo: {uri-vk-ref-page-root}/VkInstanceCreateInfo.html +:uri-VkAllocationCallbacks: {uri-vk-ref-page-root}/VkAllocationCallbacks.html +:uri-vkCreateDevice: {uri-vk-ref-page-root}/vkCreateDevice.html +:uri-VkDeviceCreateInfo: {uri-vk-ref-page-root}/VkDeviceCreateInfo.html +:uri-VkAllocationCallbacks: {uri-vk-ref-page-root}/VkAllocationCallbacks.html diff --git a/specification/config/copyright-spec.adoc b/specification/config/copyright-spec.adoc index a832d74f..cf4a1611 100644 --- a/specification/config/copyright-spec.adoc +++ b/specification/config/copyright-spec.adoc @@ -35,7 +35,7 @@ trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos Intellectual Property Rights Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this Specification; see -https://www.khronos.org/adopters. +https://www.khronos.org/adopters . endif::ratified_core_spec[] // Enabled in all other builds diff --git a/specification/current_version.ini b/specification/current_version.ini index 208d0e9d..aef3c559 100644 --- a/specification/current_version.ini +++ b/specification/current_version.ini @@ -10,4 +10,4 @@ # Similarly, update specification/scripts/extensionmetadocgenerator.py as well. MAJOR=1 MINOR=0 -PATCH=29 +PATCH=30 diff --git a/specification/registry/registry.sch b/specification/registry/registry.sch index c00fb132..957146cc 100644 --- a/specification/registry/registry.sch +++ b/specification/registry/registry.sch @@ -848,6 +848,7 @@ '/interaction_profiles/ml/ml2_controller', '/interaction_profiles/bytedance/pico_neo3_controller', '/interaction_profiles/bytedance/pico4_controller', + '/interaction_profiles/bytedance/pico_g3_controller', '/interaction_profiles/facebook/touch_controller_pro' )"/> diff --git a/specification/registry/xr.xml b/specification/registry/xr.xml index add5a2c7..7bbddee4 100644 --- a/specification/registry/xr.xml +++ b/specification/registry/xr.xml @@ -82,7 +82,6 @@ maintained in the default branch of the Khronos OpenXR GitHub project. - @@ -132,7 +131,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. updates them automatically by processing a line at a time. --> // OpenXR current version number. -#define XR_CURRENT_API_VERSION XR_MAKE_VERSION(1, 0, 29) +#define XR_CURRENT_API_VERSION XR_MAKE_VERSION(1, 0, 30) - typedef void *(*PFN_xrEglGetProcAddressMNDX)(const char *name); + typedef PFN_xrVoidFunction (*PFN_xrEglGetProcAddressMNDX)(const char *name); XrStructureType type @@ -1491,7 +1490,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrStructureType type const void* next XrSpatialGraphNodeTypeMSFT nodeType - uint8_t nodeId[XR_GUID_SIZE_MSFT] + uint8_t nodeId[XR_GUID_SIZE_MSFT] XrPosef pose @@ -1508,7 +1507,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrStructureType type void* next - uint8_t nodeId[XR_GUID_SIZE_MSFT] + uint8_t nodeId[XR_GUID_SIZE_MSFT] XrPosef poseInNodeSpace @@ -1890,8 +1889,8 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrStructureType type void* next - char parentNodeName[XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT] - char nodeName[XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT] + char parentNodeName[XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT] + char nodeName[XR_MAX_CONTROLLER_MODEL_NODE_NAME_SIZE_MSFT] XrStructureType type @@ -2281,7 +2280,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrStructureType type void* next uint32_t vendorId - char modelName[XR_MAX_RENDER_MODEL_NAME_SIZE_FB] + char modelName[XR_MAX_RENDER_MODEL_NAME_SIZE_FB] XrRenderModelKeyFB modelKey uint32_t modelVersion XrRenderModelFlagsFB flags @@ -2508,7 +2507,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. uint64_t trackedKeyboardId XrVector3f size XrKeyboardTrackingFlagsFB flags - char name[XR_MAX_KEYBOARD_TRACKING_NAME_SIZE_FB] + char name[XR_MAX_KEYBOARD_TRACKING_NAME_SIZE_FB] XrStructureType type @@ -2631,12 +2630,12 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrStructureType type const void* next - XrColor4f textureColorMap[XR_PASSTHROUGH_COLOR_MAP_MONO_SIZE_FB] + XrColor4f textureColorMap[XR_PASSTHROUGH_COLOR_MAP_MONO_SIZE_FB] XrStructureType type const void* next - uint8_t textureColorMap[XR_PASSTHROUGH_COLOR_MAP_MONO_SIZE_FB] + uint8_t textureColorMap[XR_PASSTHROUGH_COLOR_MAP_MONO_SIZE_FB] XrStructureType type @@ -5102,7 +5101,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrResult xrSetColorSpaceFB XrSession session - const XrColorSpaceFB colorspace + const XrColorSpaceFB colorSpace @@ -5524,7 +5523,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. XrResult xrSetMarkerTrackingPredictionVARJO XrSession session uint64_t markerId - XrBool32 enabled + XrBool32 enable @@ -6272,6 +6271,18 @@ maintained in the default branch of the Khronos OpenXR GitHub project. + + + + + + + + + + + + @@ -6316,6 +6327,32 @@ maintained in the default branch of the Khronos OpenXR GitHub project. + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -6619,7 +6656,7 @@ maintained in the default branch of the Khronos OpenXR GitHub project. - + @@ -10510,10 +10547,11 @@ maintained in the default branch of the Khronos OpenXR GitHub project. - + + @@ -10530,6 +10568,13 @@ maintained in the default branch of the Khronos OpenXR GitHub project. + + + + + + + @@ -10538,19 +10583,22 @@ maintained in the default branch of the Khronos OpenXR GitHub project. + + + - - - - + + + + @@ -11384,10 +11432,33 @@ maintained in the default branch of the Khronos OpenXR GitHub project. - + - - + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/specification/scripts/genRef.py b/specification/scripts/genRef.py index 5a72a6ac..04184010 100644 --- a/specification/scripts/genRef.py +++ b/specification/scripts/genRef.py @@ -882,15 +882,14 @@ def genExtension(baseDir, extpath, name, info): fp = open(pageName, 'w', encoding='utf-8') # OpenXR-specific - sections = OrderedDict() - sections['Specification'] = 'See link:{html_spec_relative}#%s[ %s] in the main specification for complete information.' % ( - name, name) + ref_page_sections = OrderedDict() + ref_page_sections['Specification'] = f'See link:{{html_spec_relative}}#{name}[{name}] in the main specification for complete information.' refPageShell(name, "{} extension".format(ext_type), fp, appbody, - sections=sections, + sections=ref_page_sections, tail_content=tail_content) # Restore leveloffset for boilerplate in refPageTail diff --git a/specification/scripts/spec_tools/entity_db.py b/specification/scripts/spec_tools/entity_db.py index 99a7d62e..e408c0a6 100644 --- a/specification/scripts/spec_tools/entity_db.py +++ b/specification/scripts/spec_tools/entity_db.py @@ -287,7 +287,7 @@ def getMemberNames(self, commandOrStruct): ret = [] for member in members: name_tag = member.find('name') - if name_tag: + if name_tag is not None: ret.append(name_tag.text) return ret diff --git a/specification/scripts/validitygenerator.py b/specification/scripts/validitygenerator.py index b121f705..5b18c112 100644 --- a/specification/scripts/validitygenerator.py +++ b/specification/scripts/validitygenerator.py @@ -1086,8 +1086,8 @@ def makeStructureExtensionPointer(self, blockname, param): self.logMsg( 'diag', 'makeStructureExtensionPointer: struct', struct, 'IS NOT required') - entry += '{} must: be {} or a valid pointer to the <>'.format( - self.makeParameterName(param_name), self.null) + link = "link:{uri-next-chain}[next structure in a structure chain]" + entry += f'{self.makeParameterName(param_name)} must: be {self.null} or a valid pointer to the {link}' if not extensionstructs: return entry entry += '. See also: ' diff --git a/specification/scripts/xrconventions.py b/specification/scripts/xrconventions.py index 2d59c0c5..0c650699 100644 --- a/specification/scripts/xrconventions.py +++ b/specification/scripts/xrconventions.py @@ -205,7 +205,7 @@ def specURL(self, spectype='api'): instead. N.b. this may need to change on a per-refpage basis if there are multiple documents involved. """ - return 'https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html' + return 'https://registry.khronos.org/OpenXR/specs/1.0/html/xrspec.html' @property def xml_api_name(self): diff --git a/specification/sources/chapters/extensions/bd/bd_controller_interaction.adoc b/specification/sources/chapters/extensions/bd/bd_controller_interaction.adoc index d1ea0e13..80e37bf1 100644 --- a/specification/sources/chapters/extensions/bd/bd_controller_interaction.adoc +++ b/specification/sources/chapters/extensions/bd/bd_controller_interaction.adoc @@ -5,20 +5,20 @@ include::{generated}/meta/XR_BD_controller_interaction.adoc[] *Last Modified Date*:: - 2023-01-04 + 2023-08-10 IP Status*:: No known IP claims. *Contributors*:: Baolin Fu, Bytedance + - Oliver Xu, Bytedance + - Berton Jia, Bytedance + Shanliang Xu, Bytedance + + Zhanrui Jia, Bytedance *Overview* -This extension defines the interaction profile for PICO Neo3 and PICO 4 -Controllers. +This extension defines the interaction profile for PICO Neo3, PICO 4, and +PICO G3 Controllers. *BD(Bytedance) Controller interaction profile* @@ -30,7 +30,12 @@ Interaction profile path for PICO 4: * pathname:/interaction_profiles/bytedance/pico4_controller -Valid for user paths for both pico_neo3_controller and pico4_controller: +Interaction profile path for PICO G3: + +* pathname:/interaction_profiles/bytedance/pico_g3_controller + +Valid for user paths for pico_neo3_controller, pico4_controller, and +pico_g3_controller: * pathname:/user/hand/left * pathname:/user/hand/right @@ -91,11 +96,28 @@ use) * subpathname:/input/aim/pose * subpathname:/output/haptic +Supported component paths for pico_g3_controller: + +* subpathname:/input/trigger/click +* subpathname:/input/trigger/value +* subpathname:/input/menu/click +* subpathname:/input/grip/pose +* subpathname:/input/aim/pose +* subpathname:/input/thumbstick +* subpathname:/input/thumbstick/click + Be careful with the following difference: -* pico_neo3_controller supports /input/menu/click both on /user/hand/left - and /user/hand/right. -* pico4_controller supports /input/menu/click only on /user/hand/left. +* pico_neo3_controller supports subpathname:/input/menu/click both on + pathname:/user/hand/left and pathname:/user/hand/right. +* pico4_controller supports subpathname:/input/menu/click only on + pathname:/user/hand/left. +* pico_g3_controller has only one physical controller. + When designing suggested bindings for this interaction profile, you may: + suggest bindings for both pathname:/user/hand/left and + pathname:/user/hand/right. + However, only one of them will be active at a given time, so do not design + interactions that require simultaneous use of both hands. *New Object Types* @@ -116,3 +138,7 @@ Be careful with the following difference: * Revision 1, 2023-01-04 (Baolin Fu) ** Initial extension description + +* Revision 2, 2023-08-10 (Shanliang Xu) + +** Add support for G3 devices diff --git a/specification/sources/chapters/extensions/ext/ext_active_action_set_priority.adoc b/specification/sources/chapters/extensions/ext/ext_active_action_set_priority.adoc index f9d9901b..625f0e0a 100644 --- a/specification/sources/chapters/extensions/ext/ext_active_action_set_priority.adoc +++ b/specification/sources/chapters/extensions/ext/ext_active_action_set_priority.adoc @@ -56,8 +56,8 @@ include::{generated}/api/structs/XrActiveActionSetPrioritiesEXT.txt[] * pname:next is code:NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension. -* pname:countActionSetPriorities is an integer specifying the number of - valid elements in the actionSetPriorities array. +* pname:actionSetPriorityCount is an integer specifying the number of valid + elements in the actionSetPriorities array. * pname:actionSetPriorities is a pointer to an array that maps action sets to their active priority numbers. If an action set is specified multiple times, the runtime may: return diff --git a/specification/sources/chapters/extensions/ext/ext_conformance_automation.adoc b/specification/sources/chapters/extensions/ext/ext_conformance_automation.adoc index 7ba99852..5e3fddc8 100644 --- a/specification/sources/chapters/extensions/ext/ext_conformance_automation.adoc +++ b/specification/sources/chapters/extensions/ext/ext_conformance_automation.adoc @@ -206,6 +206,8 @@ include::{appendices}/conformance_automation_warning.adoc[] * pname:session must: be a valid session handle. * pname:topLevelPath must: be a valid top level path. * pname:inputSourcePath must: be a valid input source path. +* pname:space must: be a valid slink:XrSpace. +* pname:pose must: be a valid slink:XrPosef. **** include::{generated}/validity/protos/xrSetInputDeviceLocationEXT.txt[] diff --git a/specification/sources/chapters/extensions/ext/ext_debug_utils.adoc b/specification/sources/chapters/extensions/ext/ext_debug_utils.adoc index a195342a..cf33e6f2 100644 --- a/specification/sources/chapters/extensions/ext/ext_debug_utils.adoc +++ b/specification/sources/chapters/extensions/ext/ext_debug_utils.adoc @@ -902,3 +902,6 @@ None * Revision 4, 2021-04-04 (Ryan Pavlik) ** Fix missing error code. ** Improve formatting. +* Revision 5, 2023-07-25 (John Kearney, Meta) +** XrDebugUtilsMessengerCallbackDataEXT parameters messageId and + functionName to be optional. diff --git a/specification/sources/chapters/extensions/ext/ext_plane_detection.adoc b/specification/sources/chapters/extensions/ext/ext_plane_detection.adoc index 8ea75767..7e7a5909 100644 --- a/specification/sources/chapters/extensions/ext/ext_plane_detection.adoc +++ b/specification/sources/chapters/extensions/ext/ext_plane_detection.adoc @@ -208,14 +208,15 @@ slink:XrPlaneDetectorBeginInfoEXT::pname:baseSpace, slink:XrPlaneDetectorBeginInfoEXT::pname:time, slink:XrPlaneDetectorBeginInfoEXT::pname:boundingBoxPose and slink:XrPlaneDetectorBeginInfoEXT::pname:boundingBoxExtent. -The runtime must: resolve the location defined by pname:baseSpace at the -time of the call. +The runtime must: resolve the location defined by +slink:XrPlaneDetectorBeginInfoEXT::pname:baseSpace at the time of the call. The slink:XrPlaneDetectorBeginInfoEXT::pname:boundingBoxPose is the pose of the center of the box defined by slink:XrPlaneDetectorBeginInfoEXT::pname:boundingBoxExtent. The runtime must: return ename:XR_ERROR_SPACE_NOT_LOCATABLE_EXT if the -pname:baseSpace is not locatable at the time of the call. +slink:XrPlaneDetectorBeginInfoEXT::pname:baseSpace is not locatable at the +time of the call. include::{generated}/validity/protos/xrBeginPlaneDetectionEXT.txt[] -- @@ -233,8 +234,8 @@ include::{generated}/api/structs/XrPlaneDetectorBeginInfoEXT.txt[] * pname:next is code:NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension. -* pname:baseSpace is the slink:XrSpace that the pname:boundingBox is defined - in. +* pname:baseSpace is the slink:XrSpace that the pname:boundingBoxPose is + defined in. * pname:time is an basetype:XrTime at which to detect the planes. * pname:orientationCount the number of elements in the pname:orientations. * pname:orientations an array of elink:XrPlaneDetectorOrientationEXT. @@ -386,9 +387,10 @@ include::{generated}/api/structs/XrPlaneDetectorLocationsEXT.txt[] * pname:planeLocationCapacityInput is the capacity of the array, or 0 to indicate a request to retrieve the required capacity. * pname:planeLocationCountOutput is the number of planes, or the required - capacity in the case that pname:planeCapacityInput is insufficient. + capacity in the case that pname:planeLocationCapacityInput is + insufficient. * pname:planeLocations is an array of slink:XrPlaneDetectorLocationEXT. - It can: be code:NULL if pname:planeCapacityInput is 0. + It can: be code:NULL if pname:planeLocationCapacityInput is 0. * See <> chapter for a detailed description of retrieving the required pname:planeLocations size. **** @@ -405,6 +407,9 @@ include::{generated}/api/structs/XrPlaneDetectorLocationEXT.txt[] .Member Descriptions **** +* pname:type is the elink:XrStructureType of this structure. +* pname:next is code:NULL or a pointer to the next structure in a structure + chain. * pname:planeId is a code:uint64_t unique identifier of the plane. The planeId should: remain the same for the duration of the slink:XrPlaneDetectorEXT handle for a physical plane. @@ -421,7 +426,7 @@ include::{generated}/api/structs/XrPlaneDetectorLocationEXT.txt[] * pname:pose is an slink:XrPosef defining the position and orientation of the origin of a plane within the reference frame of the corresponding slink:XrPlaneDetectorGetInfoEXT::pname:baseSpace. -* pname:extent is the extent of the plane along the x-axis (width) and +* pname:extents is the extent of the plane along the x-axis (width) and z-axis (height) centered on the pname:pose. * pname:orientation is the detected orientation of the plane. * pname:semanticType elink:XrPlaneDetectorSemanticTypeEXT type of the plane. diff --git a/specification/sources/chapters/extensions/fb/fb_body_tracking.adoc b/specification/sources/chapters/extensions/fb/fb_body_tracking.adoc index c247e53d..ab937a13 100755 --- a/specification/sources/chapters/extensions/fb/fb_body_tracking.adoc +++ b/specification/sources/chapters/extensions/fb/fb_body_tracking.adoc @@ -234,8 +234,8 @@ systems that have only limited ability to track finger positions must: use the information available to them to emulate an unobstructed range of motion. -The runtime must: update the pname:jointLocations array ordered so that the -application can index elements using the corresponding body joint enum (e.g. +The runtime must: update the pname:jointLocations array ordered so that it +is indexed using the corresponding body joint enum (e.g. elink:XrBodyJointFB) as described by elink:XrBodyJointSetFB when creating the slink:XrBodyTrackerFB. For example, when the slink:XrBodyTrackerFB is created with @@ -425,7 +425,7 @@ while (1) { CHK_XR(pfnLocateBodyJointsFB(bodyTracker, &locateInfo, &locations)); if (locations.isActive) { - // The returned joint location array can be directly indexed with + // The returned joint location array is directly indexed with // XrBodyJointFB enum. const XrPosef &indexTip = jointLocations[XR_BODY_JOINT_LEFT_HAND_INDEX_TIP_FB].pose; @@ -435,7 +435,7 @@ while (1) { ==== Conventions of body joints -[open,refpage='XrBodyJointFB',type='enums',desc='The name of body joints that can be tracked',xrefs=''] +[open,refpage='XrBodyJointFB',type='enums',desc='Trackable body joints',xrefs=''] -- This extension defines 70 joints for body tracking: 18 core body joints + 52 hand joints. diff --git a/specification/sources/chapters/extensions/fb/fb_composition_layer_settings.adoc b/specification/sources/chapters/extensions/fb/fb_composition_layer_settings.adoc index 6b1c6b5b..3bde10f2 100644 --- a/specification/sources/chapters/extensions/fb/fb_composition_layer_settings.adoc +++ b/specification/sources/chapters/extensions/fb/fb_composition_layer_settings.adoc @@ -61,7 +61,8 @@ include::{generated}/api/structs/XrCompositionLayerSettingsFB.txt[] * pname:next is code:NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension. -* pname:flags is a bitmask of elink:XrCompositionLayerSettingsFlagBitsFB. +* pname:layerFlags is a bitmask of + elink:XrCompositionLayerSettingsFlagBitsFB. **** slink:XrCompositionLayerSettingsFB contains additional flags to indicate diff --git a/specification/sources/chapters/extensions/fb/fb_eye_tracking_social.adoc b/specification/sources/chapters/extensions/fb/fb_eye_tracking_social.adoc index 4e446c61..df27c912 100644 --- a/specification/sources/chapters/extensions/fb/fb_eye_tracking_social.adoc +++ b/specification/sources/chapters/extensions/fb/fb_eye_tracking_social.adoc @@ -164,7 +164,7 @@ include::{generated}/api/protos/xrGetEyeGazesFB.txt[] * pname:eyeTracker is an slink:XrEyeTrackerFB previously created by flink:xrCreateEyeTrackerFB. * pname:gazeInfo is the information to get eye gaze. -* pname:eyeTracker is a pointer to slink:XrEyeGazesFB receiving the returned +* pname:eyeGazes is a pointer to slink:XrEyeGazesFB receiving the returned eye poses and confidence. **** diff --git a/specification/sources/chapters/extensions/fb/fb_face_tracking.adoc b/specification/sources/chapters/extensions/fb/fb_face_tracking.adoc index 43587bad..9b241f46 100755 --- a/specification/sources/chapters/extensions/fb/fb_face_tracking.adoc +++ b/specification/sources/chapters/extensions/fb/fb_face_tracking.adoc @@ -34,7 +34,7 @@ When the application access has been allowed, the runtime may: set pname:isValid on the supplied slink:XrFaceExpressionStatusFB structure to ename:XR_TRUE. -Some permission systems may control access to the eye tracking separately +Some permission systems may: control access to the eye tracking separately from access to the face tracking, even though the eyes are part of the face. In case the user denied tracking of the eyes, yet, allowed tracking of the face, then the runtime must: set the pname:isEyeFollowingBlendshapesValid @@ -392,7 +392,7 @@ while (1) { This extension defines 63 blend shapes for tracking facial expressions. -[open,refpage='XrFaceExpressionFB',type='enums',desc='The name of blend shapes that can be tracked',xrefs=''] +[open,refpage='XrFaceExpressionFB',type='enums',desc='The names of trackable blend shapes',xrefs=''] -- include::{generated}/api/enums/XrFaceExpressionFB.txt[] diff --git a/specification/sources/chapters/extensions/fb/fb_hand_tracking_capsules.adoc b/specification/sources/chapters/extensions/fb/fb_hand_tracking_capsules.adoc index d1292c9c..198201b6 100644 --- a/specification/sources/chapters/extensions/fb/fb_hand_tracking_capsules.adoc +++ b/specification/sources/chapters/extensions/fb/fb_hand_tracking_capsules.adoc @@ -57,7 +57,7 @@ It describes a collision capsule associated with a hand joint. * pname:points are the two points defining the capsule length. * pname:radius is the radius of the capsule. * pname:joint is the hand joint that drives this capsule's transform. - Multiple capsules can be attached to the same joint. + Multiple capsules may: be attached to the same joint. **** include::{generated}/validity/structs/XrHandCapsuleFB.txt[] diff --git a/specification/sources/chapters/extensions/fb/fb_hand_tracking_mesh.adoc b/specification/sources/chapters/extensions/fb/fb_hand_tracking_mesh.adoc index fae079e9..12481c37 100644 --- a/specification/sources/chapters/extensions/fb/fb_hand_tracking_mesh.adoc +++ b/specification/sources/chapters/extensions/fb/fb_hand_tracking_mesh.adoc @@ -18,7 +18,7 @@ poses but no mechanism to render a skinned hand mesh. This extension allows: * An application to get a skinned hand mesh and a bind pose skeleton that - can be used to render a hand object driven by the joints from the + can: be used to render a hand object driven by the joints from the apiext:XR_EXT_hand_tracking extension. * Control the scale of the hand joints returned by apiext:XR_EXT_hand_tracking. @@ -106,8 +106,8 @@ include::{generated}/api/structs/XrHandTrackingMeshFB.txt[] pname:jointCapacityInput, pname:vertexCapacityInput, or pname:indexCapacityInput is insufficient. * pname:indices is an array of triangle indices. -* See the < section for a detailed description of - retrieving the required array sizes in the "struct form" as used here. +* See the <> section for a detailed description of + retrieving the array sizes in the "struct form" as used here. **** All arrays are application-allocated, and all may: be code:NULL if any of @@ -144,15 +144,15 @@ include::{generated}/api/structs/XrHandTrackingScaleFB.txt[] chain. No such structures are defined in core OpenXR or this extension. * pname:sensorOutput is an output value: the currently measured scale as - would be applied without passing this structure. + otherwise applied without passing this structure. * pname:currentOutput is an output value: the effective output that the bind - skeleton is getting on the current call, which may be subject to + skeleton is getting on the current call, which may: be subject to filtering, scaling, or validation. -* pname:overrideHandScale indicates whether the runtime should scale the +* pname:overrideHandScale indicates whether the runtime must: scale the output of this flink:xrLocateHandJointsEXT call according to pname:overrideValueInput -* pname:overrideValueInput is an optional input value, enabled only when the - pname:overrideHandScale parameter is set. +* pname:overrideValueInput is an optional: input value, enabled only when + the pname:overrideHandScale parameter is set. Setting this to 1.0 and setting pname:overrideHandScale to code:true will give the joints in mesh binding scale. **** diff --git a/specification/sources/chapters/extensions/fb/fb_keyboard_tracking.adoc b/specification/sources/chapters/extensions/fb/fb_keyboard_tracking.adoc index 6276b514..ec5f2b55 100644 --- a/specification/sources/chapters/extensions/fb/fb_keyboard_tracking.adoc +++ b/specification/sources/chapters/extensions/fb/fb_keyboard_tracking.adoc @@ -137,6 +137,9 @@ include::{generated}/api/structs/XrKeyboardSpaceCreateInfoFB.txt[] .Member Descriptions **** +* pname:type is the elink:XrStructureType of this structure. +* pname:next is code:NULL or a pointer to the next structure in a structure + chain. * pname:trackedKeyboardId abstract identifier describing the type of keyboard to track. **** diff --git a/specification/sources/chapters/extensions/fb/fb_passthrough.adoc b/specification/sources/chapters/extensions/fb/fb_passthrough.adoc index 0ee98267..919d97ee 100644 --- a/specification/sources/chapters/extensions/fb/fb_passthrough.adoc +++ b/specification/sources/chapters/extensions/fb/fb_passthrough.adoc @@ -239,6 +239,7 @@ It contains parameters used to specify a new passthrough layer. * pname:next is code:NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR or this extension. +* pname:passthrough an slink:XrPassthroughFB handle. * pname:flags elink:XrPassthroughFlagsFB that specify additional behavior. * pname:purpose elink:XrPassthroughLayerPurposeFB that specifies the layer's purpose. @@ -267,8 +268,8 @@ the actual passthrough contents. additional behavior. * pname:space is the slink:XrSpace that specifies the layer's space - must: be dlink:XR_NULL_HANDLE. -* pname:layer is the slink:XrPassthroughLayerFB that defines this layer's - behavior. +* pname:layerHandle is the slink:XrPassthroughLayerFB that defines this + layer's behavior. **** include::{generated}/validity/structs/XrCompositionLayerPassthroughFB.txt[] @@ -680,7 +681,7 @@ include::{generated}/api/protos/xrDestroyGeometryInstanceFB.txt[] .Parameter Descriptions **** -* pname:geometryInstance is the slink:XrGeometryInstanceFB to be destroyed. +* pname:instance is the slink:XrGeometryInstanceFB to be destroyed. **** Destroys an slink:XrGeometryInstanceFB handle. @@ -700,9 +701,8 @@ include::{generated}/api/protos/xrGeometryInstanceSetTransformFB.txt[] .Parameter Descriptions **** -* pname:geometryInstance is the slink:XrGeometryInstanceFB to get the - transform. -* pname:transform is the slink:XrGeometryInstanceTransformFB to be set. +* pname:instance is the slink:XrGeometryInstanceFB to get the transform. +* pname:transformation is the slink:XrGeometryInstanceTransformFB to be set. **** Sets an slink:XrGeometryInstanceTransformFB transform on an diff --git a/specification/sources/chapters/extensions/fb/fb_render_model.adoc b/specification/sources/chapters/extensions/fb/fb_render_model.adoc index 40c2f62d..8068848b 100755 --- a/specification/sources/chapters/extensions/fb/fb_render_model.adoc +++ b/specification/sources/chapters/extensions/fb/fb_render_model.adoc @@ -4,9 +4,6 @@ include::{generated}/meta/XR_FB_render_model.adoc[] -:uri-fb-gltf2: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html -:uri-fb-gltf2-basisu: https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_basisu - *Contributors*:: Leonard Tsai, Meta + Xiang Wei, Meta + @@ -360,9 +357,9 @@ flink:xrLoadRenderModelFB is used to load the GLTF model data using a valid pname:modelKey. flink:xrLoadRenderModelFB loads the model as a byte buffer containing the GLTF in the binary format (GLB). -The GLB data must: conform to the glTF 2.0 format defined at {uri-fb-gltf2} +The GLB data must: conform to the glTF 2.0 format defined at {uri-gltf2}. The GLB may: contain texture data in a format that requires the use of the -`KHR_texture_basisu` GLTF extension defined at {uri-fb-gltf2-basisu}. +`KHR_texture_basisu` GLTF extension defined at {uri-gltf2-basisu}. Therefore, the application should: ensure it can handle this extension. If the device for the requested model is disconnected or does not match the diff --git a/specification/sources/chapters/extensions/htcx/htcx_vive_tracker_interaction.adoc b/specification/sources/chapters/extensions/htcx/htcx_vive_tracker_interaction.adoc index 26003abe..cd96e9c0 100644 --- a/specification/sources/chapters/extensions/htcx/htcx_vive_tracker_interaction.adoc +++ b/specification/sources/chapters/extensions/htcx/htcx_vive_tracker_interaction.adoc @@ -192,18 +192,16 @@ include::{generated}/api/protos/xrEnumerateViveTrackerPathsHTCX.txt[] .Parameter Descriptions **** * pname:instance is an instance previously created. -* pname:pathsCapacityInput is the capacity of the pname:viveTrackerPaths, or - `0` to retrieve the required capacity. -* pname:pathsCountOutput is a pointer to the count of - slink:XrViveTrackerPathsHTCX pname:viveTrackerPaths written, or a pointer - to the required capacity in the case that pname:pathsCapacityInput is +* pname:pathCapacityInput is the capacity of the pname:paths, or `0` to + retrieve the required capacity. +* pname:pathCountOutput is a pointer to the count of + slink:XrViveTrackerPathsHTCX pname:paths written, or a pointer to the + required capacity in the case that pname:pathsCapacityInput is insufficient. -* pname:viveTrackerPaths is a pointer to an array of - slink:XrViveTrackerPathsHTCX VIVE tracker paths, but can: be code:NULL if - pname:pathsCapacityInput is `0`. +* pname:paths is a pointer to an array of slink:XrViveTrackerPathsHTCX VIVE + tracker paths, but can: be code:NULL if pname:pathsCapacityInput is `0`. * See <> chapter for a - detailed description of retrieving the required pname:viveTrackerPaths - size. + detailed description of retrieving the required pname:paths size. **** flink:xrEnumerateViveTrackerPathsHTCX enumerates all connected VIVE trackers diff --git a/specification/sources/chapters/extensions/khr/khr_vulkan_enable2.adoc b/specification/sources/chapters/extensions/khr/khr_vulkan_enable2.adoc index b283f09a..5259a24a 100644 --- a/specification/sources/chapters/extensions/khr/khr_vulkan_enable2.adoc +++ b/specification/sources/chapters/extensions/khr/khr_vulkan_enable2.adoc @@ -4,8 +4,6 @@ include::{generated}/meta/XR_KHR_vulkan_enable2.adoc[] -:vkRefPageRoot: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html - *Last Modified Date*:: 2020-05-04 *IP Status*:: @@ -21,6 +19,7 @@ include::{generated}/meta/XR_KHR_vulkan_enable2.adoc[] Robert Menzel, NVIDIA + Paulo Gomes, Samsung Electronics + + ==== Overview This extension enables the use of the Vulkan graphics API in an OpenXR @@ -118,10 +117,10 @@ include::{generated}/validity/structs/XrGraphicsRequirementsVulkan2KHR.txt[] ===== Vulkan Instance Creation + Second, a compatible sname:VkInstance must: be created. The flink:xrCreateVulkanInstanceKHR entry point is a wrapper around -link:{vkRefPageRoot}/vkCreateInstance.html[vkCreateInstance] intended for -this purpose. +link:{uri-vkCreateInstance}[vkCreateInstance] intended for this purpose. When called, the runtime must: aggregate the requirements specified by the application with its own requirements and forward the sname:VkInstance creation request to the fname:vkCreateInstance function pointer returned by @@ -167,11 +166,11 @@ include::{generated}/api/structs/XrVulkanInstanceCreateInfoKHR.txt[] * pname:pfnGetInstanceProcAddr is a function pointer to fname:vkGetInstanceProcAddr or a compatible entry point. * pname:vulkanCreateInfo is the - link:{vkRefPageRoot}/VkInstanceCreateInfo.html[sname:VkInstanceCreateInfo - as specified by Vulkan]. + link:{uri-VkInstanceCreateInfo}[sname:VkInstanceCreateInfo as specified by + Vulkan]. * pname:vulkanAllocator is the - link:{vkRefPageRoot}/VkAllocationCallbacks.html[sname:VkAllocationCallbacks - as specified by Vulkan]. + link:{uri-VkAllocationCallbacks}[sname:VkAllocationCallbacks as specified + by Vulkan]. **** include::{generated}/validity/structs/XrVulkanInstanceCreateInfoKHR.txt[] @@ -239,6 +238,9 @@ include::{generated}/api/structs/XrVulkanGraphicsDeviceGetInfoKHR.txt[] .Member Descriptions **** +* pname:type is the elink:XrStructureType of this structure. +* pname:next is code:NULL or a pointer to the next structure in a structure + chain. * pname:systemId is an basetype:XrSystemId handle for the system which will be used to create a session. * pname:vulkanInstance is a valid Vulkan sname:VkInstance. @@ -251,8 +253,7 @@ include::{generated}/validity/structs/XrVulkanGraphicsDeviceGetInfoKHR.txt[] Fourth, a compatible sname:VkDevice must: be created. The flink:xrCreateVulkanDeviceKHR entry point is a wrapper around -link:{vkRefPageRoot}/vkCreateDevice.html[vkCreateDevice] intended for this -purpose. +link:{uri-vkCreateDevice}[vkCreateDevice] intended for this purpose. When called, the runtime must: aggregate the requirements specified by the application with its own requirements and forward the sname:VkDevice creation request to the fname:vkCreateDevice function pointer returned by @@ -287,6 +288,9 @@ include::{generated}/api/structs/XrVulkanDeviceCreateInfoKHR.txt[] .Member Descriptions **** +* pname:type is the elink:XrStructureType of this structure. +* pname:next is code:NULL or a pointer to the next structure in a structure + chain. * pname:systemId is an basetype:XrSystemId handle for the system which will be used to create a session. * pname:createFlags is a bitmask of elink:XrVulkanDeviceCreateFlagBitsKHR @@ -294,11 +298,11 @@ include::{generated}/api/structs/XrVulkanDeviceCreateInfoKHR.txt[] fname:vkGetInstanceProcAddr or a compatible entry point. * pname:vulkanPhysicalDevice must: match flink:xrGetVulkanGraphicsDeviceKHR. * pname:vulkanCreateInfo is the - link:{vkRefPageRoot}/VkDeviceCreateInfo.html[sname:VkDeviceCreateInfo as - specified by Vulkan]. + link:{uri-VkDeviceCreateInfo}[sname:VkDeviceCreateInfo as specified by + Vulkan]. * pname:vulkanAllocator is the - link:{vkRefPageRoot}/VkAllocationCallbacks.html[sname:VkAllocationCallbacks - as specified by Vulkan]. + link:{uri-VkAllocationCallbacks}[sname:VkAllocationCallbacks as specified + by Vulkan]. **** If the pname:vulkanPhysicalDevice parameter does not match the output of diff --git a/specification/sources/chapters/extensions/meta/meta_virtual_keyboard.adoc b/specification/sources/chapters/extensions/meta/meta_virtual_keyboard.adoc index a22eae76..792b2309 100644 --- a/specification/sources/chapters/extensions/meta/meta_virtual_keyboard.adoc +++ b/specification/sources/chapters/extensions/meta/meta_virtual_keyboard.adoc @@ -705,7 +705,7 @@ include::{generated}/api/protos/xrChangeVirtualKeyboardTextContextMETA.txt[] .Parameter Descriptions **** * pname:keyboard is the slink:XrVirtualKeyboardMETA handle. -* pname:info is the slink:XrVirtualKeyboardTextContextChangeInfoMETA +* pname:changeInfo is the slink:XrVirtualKeyboardTextContextChangeInfoMETA detailing prior input text context to the runtime. **** diff --git a/specification/sources/chapters/extensions/ml/ml_compat.adoc b/specification/sources/chapters/extensions/ml/ml_compat.adoc index 5b3c6df2..c2db8978 100644 --- a/specification/sources/chapters/extensions/ml/ml_compat.adoc +++ b/specification/sources/chapters/extensions/ml/ml_compat.adoc @@ -73,9 +73,9 @@ include::{generated}/api/protos/xrCreateSpaceFromCoordinateFrameUIDML.txt[] The service that created the underlying slink:XrCoordinateSpaceCreateInfoML::pname:cfuid must: remain active for the lifetime of the slink:XrSpace. -If flink:xrLocateSpace is called on a space created from a pname:cfuid from -a no-longer-active service, the runtime may: set -slink:XrSpaceLocation::pname:locationFlags to 0. +If flink:xrLocateSpace is called on a space created from an +slink:XrCoordinateSpaceCreateInfoML::pname:cfuid from a no-longer-active +service, the runtime may: set slink:XrSpaceLocation::pname:locationFlags to 0. slink:XrSpace handles are destroyed using flink:xrDestroySpace. diff --git a/specification/sources/chapters/extensions/msft/msft_composition_layer_reprojection.adoc b/specification/sources/chapters/extensions/msft/msft_composition_layer_reprojection.adoc index 857a3379..dd1af793 100644 --- a/specification/sources/chapters/extensions/msft/msft_composition_layer_reprojection.adoc +++ b/specification/sources/chapters/extensions/msft/msft_composition_layer_reprojection.adoc @@ -170,6 +170,11 @@ include::{generated}/api/structs/XrCompositionLayerReprojectionPlaneOverrideMSFT .Parameter Descriptions **** +* pname:type is the elink:XrStructureType of this structure. + +* pname:next is code:NULL or a pointer to the next structure in a structure + chain. + * pname:position describes the position of the focus plane represented in the corresponding slink:XrCompositionLayerProjection::pname:space. diff --git a/specification/sources/chapters/extensions/msft/msft_controller_model.adoc b/specification/sources/chapters/extensions/msft/msft_controller_model.adoc index d63cafe3..8d7f6d5c 100644 --- a/specification/sources/chapters/extensions/msft/msft_controller_model.adoc +++ b/specification/sources/chapters/extensions/msft/msft_controller_model.adoc @@ -4,8 +4,6 @@ include::{generated}/meta/XR_MSFT_controller_model.adoc[] -:uri-msft-gltf2: https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html - *Contributors*:: Bryce Hutchings, Microsoft + Darryl Gough, Microsoft + @@ -109,11 +107,12 @@ controller model. [open,refpage='xrLoadControllerModelMSFT',desc='Load controller render model',type='protos'] -- + The flink:xrLoadControllerModelMSFT function loads the controller model as a byte buffer containing a binary form of glTF (a.k.a GLB file format) for the controller. The binary glTF data must: conform to glTF 2.0 format defined at -{uri-msft-gltf2}. +{uri-gltf2}. include::{generated}/api/protos/xrLoadControllerModelMSFT.txt[] diff --git a/specification/sources/chapters/extensions/varjo/varjo_marker_tracking.adoc b/specification/sources/chapters/extensions/varjo/varjo_marker_tracking.adoc index eaa9e839..d407ab00 100644 --- a/specification/sources/chapters/extensions/varjo/varjo_marker_tracking.adoc +++ b/specification/sources/chapters/extensions/varjo/varjo_marker_tracking.adoc @@ -234,6 +234,7 @@ include::{generated}/api/structs/XrEventDataMarkerTrackingUpdateVARJO.txt[] No such structures are defined in core OpenXR or this extension. * pname:markerId unique identifier of the marker that has been updated. * pname:isActive the tracking state of the marker. +* pname:isPredicted the prediction state of the marker. * pname:time the time of the marker update. **** diff --git a/specification/sources/chapters/extensions/yvr/yvr_controller_interaction.adoc b/specification/sources/chapters/extensions/yvr/yvr_controller_interaction.adoc new file mode 100755 index 00000000..48e18b72 --- /dev/null +++ b/specification/sources/chapters/extensions/yvr/yvr_controller_interaction.adoc @@ -0,0 +1,83 @@ +// Copyright (c) 2023 YVR. +// +// SPDX-License-Identifier: CC-BY-4.0 + +include::{generated}/meta/XR_YVR_controller_interaction.adoc[] + +*Last Modified Date*:: + 2023-07-12 + +*IP Status*:: + No known IP claims. + +*Contributors*:: + Pengpeng Zhang, YVR + + Xuanyu Chen, YVR + +*Overview* + +This extension defines a new interaction profile for the YVR Controller, +including but not limited to YVR1 and YVR2 Controller. + +*YVR Controller interaction profile* + +Interaction profile path: + +* pathname:/interaction_profiles/yvr/touch_controller_yvr + +Valid for user paths: + +* pathname:/user/hand/left +* pathname:/user/hand/right + +This interaction profile represents the input sources and haptics on the YVR +Controller. + +Supported component paths: + +* On pathname:/user/hand/left only: +** subpathname:/input/x/click +** subpathname:/input/x/touch +** subpathname:/input/y/click +** subpathname:/input/y/touch +** subpathname:/input/menu/click + +* On pathname:/user/hand/right only: +** subpathname:/input/a/click +** subpathname:/input/a/touch +** subpathname:/input/b/click +** subpathname:/input/b/touch +** subpathname:/input/system/click (may: not be available for application + use) + +* On both: +** subpathname:/input/squeeze/click +** subpathname:/input/trigger/value +** subpathname:/input/trigger/touch +** subpathname:/input/thumbstick/x +** subpathname:/input/thumbstick/y +** subpathname:/input/thumbstick/click +** subpathname:/input/thumbstick/touch +** subpathname:/input/grip/pose +** subpathname:/input/aim/pose +** subpathname:/output/haptic + +*New Object Types* + +*New Flag Types* + +*New Enum Constants* + +*New Enums* + +*New Structures* + +*New Functions* + +*Issues* + +*Version History* + +* Revision 1, 2023-07-12 (Pengpeng Zhang) + +** Initial extension description diff --git a/specification/sources/chapters/introduction.adoc b/specification/sources/chapters/introduction.adoc index 4f9ddee9..3888fc15 100644 --- a/specification/sources/chapters/introduction.adoc +++ b/specification/sources/chapters/introduction.adoc @@ -20,7 +20,7 @@ technologies, head mounted devices, and input modalities. The canonical version of the Specification is available in the official OpenXR Registry, located at URL -http://www.khronos.org/registry/openxr/ +{uri-openxr-registry-root} === What is OpenXR? diff --git a/specification/sources/chapters/rendering.adoc b/specification/sources/chapters/rendering.adoc index 3159bedb..a2b5e723 100644 --- a/specification/sources/chapters/rendering.adoc +++ b/specification/sources/chapters/rendering.adoc @@ -23,9 +23,9 @@ if possible. Swapchain images can: be 2D or 2D Array. -Rendering operations involving composition of submitted layers should be -assumed to be internally performed by the runtime in linear color space. -Images submitted in sRGB color space must be created using an API-specific +Rendering operations involving composition of submitted layers are assumed +to be internally performed by the runtime in linear color space. +Images submitted in sRGB color space must: be created using an API-specific sRGB format (e.g. ename:DXGI_FORMAT_R8G8B8A8_UNORM_SRGB, ename:GL_SRGB8_ALPHA8, ename:VK_FORMAT_R8G8B8A8_SRGB) to apply automatic sRGB-to-linear conversion when read by the runtime. @@ -34,8 +34,8 @@ All other formats will be treated as linear values. [NOTE] .Note ==== -OpenXR applications should avoid submitting linear encoded 8 bit color data -(e.g. ename:DXGI_FORMAT_R8G8B8A8_UNORM) whenever possible as it may result +OpenXR applications should: avoid submitting linear encoded 8 bit color data +(e.g. ename:DXGI_FORMAT_R8G8B8A8_UNORM) whenever possible as it may: result in color banding. Gritz, L. and d'Eon, E. 2007. @@ -95,7 +95,7 @@ endif::XR_KHR_opengl_enable,XR_KHR_opengles_enable[] ifdef::XR_KHR_d3d11_enable,XR_KHR_d3d12_enable[] With a Direct3D-based graphics API, flink:xrEnumerateSwapchainFormats never returns typeless formats (e.g. ename:DXGI_FORMAT_R8G8B8A8_TYPELESS). -Only concrete formats are returned, and only concrete formats may be +Only concrete formats are returned, and only concrete formats may: be specified by applications for swapchain creation. endif::XR_KHR_d3d11_enable,XR_KHR_d3d12_enable[] @@ -122,7 +122,7 @@ include::{generated}/api/protos/xrCreateSwapchain.txt[] Creates an slink:XrSwapchain handle. The returned swapchain handle may: be subsequently used in API calls. -Multiple slink:XrSwapchain handles may exist simultaneously, up to some +Multiple slink:XrSwapchain handles may: exist simultaneously, up to some limit imposed by the runtime. The slink:XrSwapchain handle must: be eventually freed via the flink:xrDestroySwapchain function. @@ -168,7 +168,7 @@ include::{generated}/api/structs/XrSwapchainCreateInfo.txt[] the graphics API's maximum limit. * pname:height is the height of the image, must: not be `0` or greater than the graphics API's maximum limit. -* pname:faceCount is the number of faces, which can be either `6` (for +* pname:faceCount is the number of faces, which must: be either `6` (for cubemaps) or `1`. * pname:arraySize is the number of array layers in the image or `1` for a 2D image, must: not be `0` or greater than the graphics API's maximum limit. @@ -259,15 +259,13 @@ endif::XR_KHR_d3d11_enable,XR_KHR_d3d12_enable[] Swapchains will be created with graphics API-specific flags appropriate to the type of underlying image and its usage. -Extensions may exist to further assist the runtime in choosing how to create -swapchains. Runtimes must: honor underlying graphics API limits when creating resources. ifdef::XR_KHR_d3d11_enable,XR_KHR_d3d12_enable[] flink:xrEnumerateSwapchainFormats never returns typeless formats (e.g. code:DXGI_FORMAT_R8G8B8A8_TYPELESS). -Only concrete formats are returned, and only concrete formats may be +Only concrete formats are returned, and only concrete formats may: be specified by applications for swapchain creation. endif::XR_KHR_d3d11_enable,XR_KHR_d3d12_enable[] @@ -294,7 +292,7 @@ Swapchain images are acquired, waited on, and released by index, but the number of images in a swapchain is implementation-defined. Additionally, rendering to images requires access to the underlying image primitive of the graphics API being used. -Applications may query and cache the images at any time after swapchain +Applications may: query and cache the images at any time after swapchain creation. [open,refpage='xrEnumerateSwapchainImages',desc='Gets images from an XrSwapchain',type='protos',xrefs='xrCreateSwapchain XrSwapchainImageBaseHeader'] @@ -339,7 +337,7 @@ ename:XR_ERROR_VALIDATION_FAILURE. [NOTE] .Note ==== -Under a typical memory model, a runtime must treat the supplied pointer as +Under a typical memory model, a runtime must: treat the supplied pointer as an opaque blob beginning with slink:XrSwapchainImageBaseHeader, until after it has verified the pname:type. ==== @@ -363,22 +361,20 @@ include::{generated}/api/structs/XrSwapchainImageBaseHeader.txt[] No such structures are defined in core OpenXR. **** -The slink:XrSwapchainImageBaseHeader is a base structure that can be -overridden by a graphics API-specific stext:XrSwapchainImage* child -structure. +The slink:XrSwapchainImageBaseHeader is a base structure that is extended by +graphics API-specific stext:XrSwapchainImage* child structures. include::{generated}/validity/structs/XrSwapchainImageBaseHeader.txt[] -- -Before an application can start building graphics API command buffers that -refer to an image in a swapchain, it must acquire the image from the -swapchain. -The acquire operation determines the index of the next image that will be -used in the swapchain. +Before an application builds graphics API command buffers that refer to an +image in a swapchain, it must: acquire the image from the swapchain. +The acquire operation determines the index of the next image to be used in +the swapchain. The order in which images are acquired is undefined. The runtime must: allow the application to acquire more than one image from -a single swapchain at a time, for example if the application implements a -multiple frame deep rendering pipeline. +a single (non-static) swapchain at a time, for example if the application +implements a multiple frame deep rendering pipeline. [open,refpage='xrAcquireSwapchainImage',desc='Acquire a swapchain image',type='protos',xrefs='xrCreateSwapchain xrEnumerateSwapchainImages xrWaitSwapchainImage xrReleaseSwapchainImage xrDestroySwapchain'] -- @@ -408,6 +404,12 @@ pname:swapchain created with the ename:XR_SWAPCHAIN_CREATE_STATIC_IMAGE_BIT set in slink:XrSwapchainCreateInfo::pname:createFlags and this function has been successfully called previously for this swapchain. +This function only provides the index of the swapchain image, for example +for use in recording command buffers. +It does not wait for the image to be usable by the application. +The application must: call flink:xrWaitSwapchainImage for each "acquire" +call before submitting graphics commands that write to the image. + include::{generated}/validity/protos/xrAcquireSwapchainImage.txt[] -- @@ -447,15 +449,15 @@ include::{generated}/api/protos/xrWaitSwapchainImage.txt[] structure. **** -Before an application can begin writing to a swapchain image, it must first -wait on the image to avoid writing to it before the compositor has finished +Before an application begins writing to a swapchain image, it must: first +wait on the image, to avoid writing to it before the compositor has finished reading from it. flink:xrWaitSwapchainImage will implicitly wait on the oldest acquired swapchain image which has not yet been successfully waited on. Once a swapchain image has been successfully waited on without timeout, the app must: release before waiting on the next acquired swapchain image. -This function may block for longer than the timeout specified in +This function may: block for longer than the timeout specified in slink:XrSwapchainImageWaitInfo due to scheduling or contention. If the timeout expires without the image becoming available for writing, @@ -490,7 +492,7 @@ include::{generated}/api/structs/XrSwapchainImageWaitInfo.txt[] * pname:next is code:NULL or a pointer to the next structure in a structure chain. No such structures are defined in core OpenXR. -* pname:timeout indicates how many nanoseconds the call should block waiting +* pname:timeout indicates how many nanoseconds the call may: block waiting for the image to become available for writing. **** @@ -504,11 +506,11 @@ image which has been acquired. The swapchain image must: have been successfully waited on without timeout before it is released. flink:xrEndFrame will use the most recently released swapchain image. -In each frame submitted to the compositor only one image index from each +In each frame submitted to the compositor, only one image index from each swapchain will be used. Note that in case the swapchain contains 2D image arrays, one array is -referenced per swapchain index and thus the whole image array can be used in -one frame. +referenced per swapchain index and thus the whole image array may: be used +in one frame. [open,refpage='xrReleaseSwapchainImage',desc='Release a swapchain image',type='protos',xrefs='xrCreateSwapchain xrEnumerateSwapchainImages xrAcquireSwapchainImage xrWaitSwapchainImage xrDestroySwapchain'] -- @@ -601,9 +603,9 @@ flink:xrLocateViews returns an array of slink:XrView elements, one for each view of the specified view configuration type, along with an slink:XrViewState containing additional state data shared across all views. The eye each view corresponds to is statically defined in -<> in case the -application wants to apply eye-specific rendering traits. -The slink:XrViewState and slink:XrView member data may change on subsequent +elink:XrViewConfigurationType in case the application wants to apply +eye-specific rendering traits. +The slink:XrViewState and slink:XrView member data may: change on subsequent calls to flink:xrLocateViews, and so applications must: not assume it to be constant. @@ -624,6 +626,9 @@ include::{generated}/api/structs/XrViewLocateInfo.txt[] .Member Descriptions **** +* pname:type is the elink:XrStructureType of this structure. +* pname:next is code:NULL or a pointer to the next structure in a structure + chain. * pname:viewConfigurationType is elink:XrViewConfigurationType to query for. * pname:displayTime is the time for which the view poses are predicted. * pname:space is the slink:XrSpace in which the pname:pose in each @@ -766,11 +771,12 @@ the runtime predicts a composited frame will be displayed. The runtime may: affect this computation by changing the return values and throttling of flink:xrWaitFrame in response to feedback from frame submission and completion times in flink:xrEndFrame. -An application must: eventually match each flink:xrWaitFrame call with one -call to flink:xrBeginFrame. A subsequent flink:xrWaitFrame call must: block until the previous frame has been begun with flink:xrBeginFrame and must: unblock independently of the corresponding call to flink:xrEndFrame. +Refer to flink:xrBeginSession for details on how a transition to +<> resets the frame function call order. + When less than one frame interval has passed since the previous return from flink:xrWaitFrame, the runtime should: block until the beginning of the next frame interval. @@ -804,13 +810,13 @@ pname:session <>. .Note ==== The engine simulation should: advance based on the display time. -Every stage in the engine pipeline should use the exact same display time +Every stage in the engine pipeline should: use the exact same display time for one particular application-generated frame. An accurate and consistent display time across all stages and threads in the engine pipeline is important to avoid object motion judder. -If the application has multiple pipeline stages, the application should pass -its computed display time through its pipeline, as flink:xrWaitFrame must be -called only once per frame. +If the application has multiple pipeline stages, the application should: +pass its computed display time through its pipeline, as flink:xrWaitFrame +must: be called only once per frame. ==== include::{generated}/validity/protos/xrWaitFrame.txt[] @@ -934,10 +940,11 @@ flink:xrWaitFrame. The runtime must: return the error code ename:XR_ERROR_CALL_ORDER_INVALID if there was no corresponding successful call to flink:xrWaitFrame. - The runtime must: return the success code ename:XR_FRAME_DISCARDED if a prior flink:xrBeginFrame has been called without an intervening call to flink:xrEndFrame. +Refer to flink:xrBeginSession for details on how a transition to +<> resets the frame function call order. The runtime must: return ename:XR_ERROR_SESSION_NOT_RUNNING if the pname:session <>. @@ -992,7 +999,7 @@ synchronization guarantees. An accurate predicted display time is very important to avoid black pull-in by reprojection and to reduce motion judder in case the runtime does not implement a translational reprojection. -Reprojection should never display images before the display refresh period +Reprojection should: never display images before the display refresh period they were predicted for, even if they are completed early, because this will cause motion judder just the same. In other words, the better the predicted display time, the less latency @@ -1003,6 +1010,8 @@ Every call to flink:xrEndFrame must: be preceded by a successful call to flink:xrBeginFrame. Failure to do so must: result in ename:XR_ERROR_CALL_ORDER_INVALID being returned by flink:xrEndFrame. +Refer to flink:xrBeginSession for details on how a transition to +<> resets the frame function call order. slink:XrFrameEndInfo may: reference swapchains into which the application has rendered for this frame. From each slink:XrSwapchain only one image index is implicitly referenced @@ -1010,7 +1019,7 @@ per frame, the one corresponding to the last call to flink:xrReleaseSwapchainImage. However, a specific swapchain (and by extension a specific swapchain image index) may: be referenced in slink:XrFrameEndInfo multiple times. -This can be used for example to render a side by side image into a single +This can: be used for example to render a side by side image into a single swapchain image and referencing it twice with differing image rectangles in different layers. diff --git a/specification/sources/chapters/session.adoc b/specification/sources/chapters/session.adoc index 75946506..6665febc 100644 --- a/specification/sources/chapters/session.adoc +++ b/specification/sources/chapters/session.adoc @@ -333,6 +333,8 @@ given frame to determine whether that frame will be visible to the user. Runtime session frame state must: start in a reset state when a session transitions to <> so that no state is carried over from when the same session was previously running. +Frame state in this context includes flink:xrWaitFrame, flink:xrBeginFrame, +and flink:xrEndFrame call order enforcement. If pname:primaryViewConfigurationType in pname:beginInfo is not supported by the basetype:XrSystemId used to create the pname:session, the runtime must: diff --git a/specification/sources/chapters/view_configurations.adoc b/specification/sources/chapters/view_configurations.adoc index dd5c8d2a..76483b2a 100644 --- a/specification/sources/chapters/view_configurations.adoc +++ b/specification/sources/chapters/view_configurations.adoc @@ -88,12 +88,13 @@ include::{generated}/api/protos/xrEnumerateViewConfigurations.txt[] * pname:instance is the instance from which pname:systemId was retrieved. * pname:systemId is the basetype:XrSystemId whose view configurations will be enumerated. -* pname:viewConfigurationsTypeCapacityInput is the capacity of the - pname:viewConfigurations array, or 0 to indicate a request to retrieve the - required capacity. -* pname:viewConfigurationsTypeCountOutput is a pointer to the count of - pname:viewConfigurations written, or a pointer to the required capacity in - the case that pname:viewConfigurationsTypeCapacityInput is insufficient. +* pname:viewConfigurationTypeCapacityInput is the capacity of the + pname:viewConfigurationTypes array, or 0 to indicate a request to retrieve + the required capacity. +* pname:viewConfigurationTypeCountOutput is a pointer to the count of + pname:viewConfigurationTypes written, or a pointer to the required + capacity in the case that pname:viewConfigurationsTypeCapacityInput is + insufficient. * pname:viewConfigurationsTypes is a pointer to an array of elink:XrViewConfigurationType values, but can: be code:NULL if pname:viewConfigurationsTypeCapacityInput is 0. diff --git a/specification/sources/extprocess/extension_process.adoc b/specification/sources/extprocess/extension_process.adoc index 2d0450e2..de4665bd 100644 --- a/specification/sources/extprocess/extension_process.adoc +++ b/specification/sources/extprocess/extension_process.adoc @@ -13,6 +13,8 @@ :imagewidth: 800 :fullimagewidth: width="800" +include::{config}/attribs.adoc[] + Extensions are a method for runtimes or API layers to expose groups of functionality upon opt-in by the application. To help understand how OpenXR extensions are created and supported, this @@ -182,8 +184,8 @@ manner as Khronos members. However, extensions must still be registered with Khronos. Extension authors/vendors should register an author ID with Khronos through -submitting a merge request to the <> -project on GitHub. +submitting a merge request to the +link:{uri-github-openxr-docs}[KhronosGroup/OpenXR-Docs] project on GitHub. The author ID must be used for any extensions that author registers. The same mechanism will be used to request registration of extensions or API layers with Khronos, as described below. @@ -359,6 +361,8 @@ Unlike the `KHR` extension approval process: [[bitmasks]] ==== Extending Bitmasks +:uri-styleguide-reserving: {uri-openxr-registry-root}/specs/1.0/styleguide.html#extensions-reserving-bitmask-values + Vendor and multi-vendor extensions must: not add new bits directly to a core or KHR bit mask, due to the limited number of bits available to express functionality. @@ -372,9 +376,8 @@ Similarly, vendor and multi-vendor `EXT` extensions must: not add to any other similarly-limited spaces in the spec. The `XR_SWAPCHAIN_USAGE_INPUT_ATTACHMENT_BIT_MND` bit was added before this policy was established, and is left as a historical artifact. -See also -https://www.khronos.org/registry/OpenXR/specs/1.0/styleguide.html#extensions-reserving-bitmask-values[the -Style Guide discussion of this]. +See also link:{uri-styleguide-reserving}[the Style Guide discussion of +this]. Regular enums are not subject to this restriction, as a dedicated range in each enum is assigned to each extension based on extension number. diff --git a/specification/sources/styleguide/extensions.adoc b/specification/sources/styleguide/extensions.adoc index 79ff81a5..c5602cfd 100644 --- a/specification/sources/styleguide/extensions.adoc +++ b/specification/sources/styleguide/extensions.adoc @@ -2,6 +2,8 @@ // // SPDX-License-Identifier: CC-BY-4.0 +:uri-extprocess: {uri-openxr-registry-root}/specs/1.0/extprocess.html + [[extensions]] = API Layers & Extensions @@ -11,9 +13,7 @@ It is concerned with mechanical processes and registration, while fine-grained naming conventions are included in the <>. The organizational processes behind extension creation are in a separate -document, the -https://www.khronos.org/registry/OpenXR/specs/1.0/extprocess.html[OpenXR -Working Group Extension Processes]. +document, the {uri-extprocess}[OpenXR Working Group Extension Processes]. == Introduction @@ -204,7 +204,7 @@ section above. The canonical definition of the OpenXR APIs is kept in an XML file known as the *OpenXR registry*. The registry is kept in `specification/registry/xr.xml` of the -<> project. +link:{uri-github-openxr-docs}[KhronosGroup/OpenXR-Docs] project. The registry contains reserved author IDs, core and extension interface definitions, definitions of individual commands and structures, and other @@ -230,7 +230,7 @@ provided. Extension authors will be able to create an account on GitHub and register an author ID with Khronos through the -<> project. +link:{uri-github-openxr-docs}[KhronosGroup/OpenXR-Docs] project. The author ID must be used for any extensions that author registers. The same mechanism will be used to request registration of extensions or API layers with Khronos, as described below. @@ -253,7 +253,7 @@ faith. OpenXR implementers must report a valid vendor ID for their implementation when queried by fname:xrGetSystemProperties, as described in the -<>. +link:{uri-openxr-ratified-spec}[OpenXR API Specification]. If there is no valid USB vendor ID defined for the physical device, implementations must obtain a Khronos vendor ID. @@ -416,8 +416,9 @@ from the Vulkan 1.0 core Specification source. ==== For example, the `XR_KHR_opengl_enable` extension is documented in the -`main` branch of the GitHub `<>` -project and internal GitLab. +`main` branch of the GitHub +link:{uri-github-openxr-docs}[KhronosGroup/OpenXR-Docs] project and internal +GitLab. However, specifications generated from this branch will only include the extension when the Makefile is invoked appropriately. @@ -813,7 +814,8 @@ extensions must define two additional tokens. specification, and differences in this version number maintain full compatibility, as defined in the link:html/xrspec.html#fundamentals-versionnum[API Version Numbers and - Semantics] section of the <>. + Semantics] section of the link:{uri-openxr-ratified-spec}[OpenXR API + Specification]. [NOTE] .Note @@ -894,8 +896,8 @@ interfaces appear in `openxr_platform.h` and are protected by `#ifdefs`. flink:xrGetInstanceProcAddr can be used in order to obtain function pointer addresses for core and extension commands (per the description in the -"`Command Function Pointers`" section of the <>). +"`Command Function Pointers`" section of the +link:{uri-openxr-ratified-spec}[OpenXR API Specification]). Different OpenXR API loaders can choose to statically export functions for some or all of the core OpenXR API commands, and can statically export functions for some or all extension commands. @@ -923,8 +925,8 @@ ways: Extensions modifying the behavior of existing commands should provide additional parameters by using the pname:next field of an existing structure, pointing to a new structure defined by the extension, as -described in the "`Valid Usage`" section of the <>. +described in the "`Valid Usage`" section of the +link:{uri-openxr-ratified-spec}[OpenXR API Specification]. Extension structures defined by multiple extensions affecting the same structure can be chained together in this fashion. Any structure which can be chained in this fashion must begin with the @@ -957,8 +959,7 @@ specification. Validation of such extended structure chains is automatically generated from the registry, as described in the description of attr:structextends in -link:https://www.khronos.org/registry/vulkan/specs/1.2/registry.html[the -registry schema document for Vulkan]. +link:{uri-schema-vulkan}[the registry schema document for Vulkan]. Take the following XML structure example: diff --git a/specification/sources/styleguide/markup.adoc b/specification/sources/styleguide/markup.adoc index 8b3ba418..13055da8 100644 --- a/specification/sources/styleguide/markup.adoc +++ b/specification/sources/styleguide/markup.adoc @@ -365,8 +365,8 @@ In the <> diagram, the diagram represents This section discusses Asciidoc macros used in the document. In addition to the macros defined by asciidoc itself, additional macros are -defined by the <> and Reference Page -configuration files. +defined by the link:{uri-openxr-ratified-spec}[OpenXR API Specification] and +Reference Page configuration files. [[markup-macros-api]] @@ -454,8 +454,8 @@ table: the OpenXR C macro in the macro argument. Example: dlink{cl}XR_NULL_HANDLE -> dlink:XR_NULL_HANDLE. There are only a few macros in the OpenXR API, described in the - "`e`" appendix of the <> + "`e`" appendix of the link:{uri-openxr-ratified-spec}[OpenXR + API Specification] | dname{cl} | Formats the macro argument like dlink{cl}. Does not generate a cross-reference. @@ -543,7 +543,7 @@ code:NULL Glossary terms are currently marked up using underscore markup where they are defined in the documents, as well as being added to the formal Glossary -appendix in the <>. +appendix in the link:{uri-openxr-ratified-spec}[OpenXR API Specification]. However, we will probably change to using custom macros soon, to enable linkage between the glossary and definitions in the spec body. @@ -557,14 +557,14 @@ _Glossary terms_ === Normative Terminology Normative terminology is precisely defined in section 1.6 of the -<>, and is used to visually tag terms -which express mandatory and optional behavior of OpenXR implementations, and -of applications using OpenXR. - -Whenever one of these terms appears in the <>, it must be tagged using the macros, to indicate that its -use has been carefully considered and is consistent with the definitions in -section 1.6. +link:{uri-openxr-ratified-spec}[OpenXR API Specification], and is used to +visually tag terms which express mandatory and optional behavior of OpenXR +implementations, and of applications using OpenXR. + +Whenever one of these terms appears in the +link:{uri-openxr-ratified-spec}[OpenXR API Specification], it must be tagged +using the macros, to indicate that its use has been carefully considered and +is consistent with the definitions in section 1.6. This is extremely important for determining IP that is in and out of Scope during Ratification reviews. The normative terminology macros are defined in the following table: @@ -614,7 +614,7 @@ not required: Implementations are not mandated to support functionality which is not required, but if they do, they must behave as described by the -<>. +link:{uri-openxr-ratified-spec}[OpenXR API Specification]. The term _functionality_ includes API features, extensions, and layers. [[markup-informative]] @@ -735,7 +735,7 @@ There are a variety of common terms that have several equivalent word choices. Always use the words in the first column instead of the alternate terms. This list may not be comprehensive; when in doubt, be guided by the existing -<>. +link:{uri-openxr-ratified-spec}[OpenXR API Specification]. .Word Choices [width="100%",options="header"] diff --git a/specification/sources/styleguide/naming.adoc b/specification/sources/styleguide/naming.adoc index ec3365f5..2c9a5ffd 100644 --- a/specification/sources/styleguide/naming.adoc +++ b/specification/sources/styleguide/naming.adoc @@ -389,9 +389,9 @@ to the end of the name. [[naming-abbreviations]] == Common Abbreviations -Abbreviations and acronyms are sometimes used in the <> and the OpenXR API where they are considered clear and -commonplace. +Abbreviations and acronyms are sometimes used in the +link:{uri-openxr-ratified-spec}[OpenXR API Specification] and the OpenXR API +where they are considered clear and commonplace. All such abbreviations used in the core API are defined here. Extensions should also use these abbreviations where appropriate. diff --git a/specification/sources/styleguide/styleguide.adoc b/specification/sources/styleguide/styleguide.adoc index 6b71cc40..db9e5129 100644 --- a/specification/sources/styleguide/styleguide.adoc +++ b/specification/sources/styleguide/styleguide.adoc @@ -26,6 +26,8 @@ include::{config}/copyright-ccby.adoc[] <<<< +:uri-schema-vulkan: https://registry.khronos.org/vulkan/specs/1.3/registry.html + [[introduction]] = Introduction diff --git a/specification/sources/styleguide/writing.adoc b/specification/sources/styleguide/writing.adoc index 4111b77c..b627aef7 100644 --- a/specification/sources/styleguide/writing.adoc +++ b/specification/sources/styleguide/writing.adoc @@ -161,18 +161,20 @@ This list is not intended to be complete. [[writing-describing]] == Describing Commands and Parameters -The <> describes API commands followed by -descriptions of their parameters, which are usually simple scalar types, -handles or pointers to OpenXR objects or arrays of objects, enumerated types -specifying values or bitmasks which affect the operation of a command; or -structures containing combinations of scalar types and objects. +The link:{uri-openxr-ratified-spec}[OpenXR API Specification] describes API +commands followed by descriptions of their parameters, which are usually +simple scalar types, handles or pointers to OpenXR objects or arrays of +objects, enumerated types specifying values or bitmasks which affect the +operation of a command; or structures containing combinations of scalar +types and objects. The templates and examples shown and annotated here are based on the -<>. +link:{uri-openxr-ratified-spec}[OpenXR API Specification]. Do not vary from them without compelling need. -Normative parts of the <> should describe -_what_ something does, rather than _how_ or _why_ an application would want -to use it or _how_ or _why_ a runtime should implement it. +Normative parts of the link:{uri-openxr-ratified-spec}[OpenXR API +Specification] should describe _what_ something does, rather than _how_ or +_why_ an application would want to use it or _how_ or _why_ a runtime should +implement it. When explicitly allowed by the Specification, the reserved value code:NULL may: be used for pointer parameters and members, and the reserved value @@ -199,7 +201,7 @@ fname:xrCreateInstance`". Explanations of _why_ and _how_ should largely be confined to reference documentation, sample code, tutorials, and other such documents. Occasional non-normative explanations can be included in the -<> using +link:{uri-openxr-ratified-spec}[OpenXR API Specification] using <>. @@ -314,8 +316,9 @@ error. == An Example Command Description The <> is a sample based on the -<>, and describes a command in enough -detail to see the different usage patterns and layout / markup used. +link:{uri-openxr-ratified-spec}[OpenXR API Specification], and describes a +command in enough detail to see the different usage patterns and layout / +markup used. Informative notes discussing markup and guidelines are interspersed with the example description to explain how and why it looks as it does.