status-im
/
OpenXR-Docs
mirror of https://github.com/status-im/OpenXR-Docs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

OpenXR 1.0.1 release (2-August-2019) 

Patch release for the 1.0 series.

Updates version to 1.0.1.

### Public issues

- #25 - Fix `make all` in the absence of styleguide and loader doc.
- #26 - Proposal for unbounded space and spatial anchor extensions (vendor extensions)

### Internal issues

- Replace remaining mentions of "app" with "application" (internal MR 1468)
- Makefile cleanups (internal MR 1469, 1489)
- Typographical fixes (internal MR 1490)
- Reserve Oculus extension numbers (internal MR 1493)
- Add Monado headless (vendor extension) (internal MR 1482)
- Generated header files removed from `OpenXR-Docs` repo.

### New extensions

- `XR_MND_headless`
- `XR_MSFT_spatial_anchor`
- `XR_MSFT_unbounded_reference_space`
This commit is contained in:
Ryan Pavlik 2019-08-02 19:20:10 -05:00
parent 7db1a0895b
commit f6cc330fc9
25 changed files with 702 additions and 3353 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
CHANGELOG.Docs.md
View File

@ -9,7 +9,33 @@ collecting together the resolution of many Khronos internal issues,
along with any public pull requests that have been accepted.
This changelog only lists changes that affect the registry,
headers, and/or specification
headers, and/or specification text.
## OpenXR 1.0.1 release (2-August-2019)
Patch release for the 1.0 series.
Updates version to 1.0.1.
### Public issues
- #25 - Fix `make all` in the absence of styleguide and loader doc.
- #26 - Proposal for unbounded space and spatial anchor extensions (vendor extensions)
### Internal issues
- Replace remaining mentions of "app" with "application" (internal MR 1468)
- Makefile cleanups (internal MR 1469, 1489)
- Typographical fixes (internal MR 1490)
- Reserve Oculus extension numbers (internal MR 1493)
- Add Monado headless (vendor extension) (internal MR 1482)
- Generated header files removed from `OpenXR-Docs` repo.
### New extensions
- `XR_MND_headless`
- `XR_MSFT_spatial_anchor`
- `XR_MSFT_unbounded_reference_space`
## OpenXR 1.0.0 release (29-July-2019)

2
README.adoc
View File

@ -26,7 +26,7 @@ README.adoc This file
COPYING.md Copyright and licensing information
CODE_OF_CONDUCT.md Code of Conduct
specification/ Specification - files to generate the spec
include/openxr/ OpenXR headers, generated from the Registry
include/openxr/ Static OpenXR header (not generated from the Registry)
```
== Building the Specification and Reference Pages, and Regenerating Headers

1538
include/openxr/openxr.h
View File

File diff suppressed because it is too large Load Diff

383
include/openxr/openxr_platform.h
View File

@ -1,383 +0,0 @@
#ifndef OPENXR_PLATFORM_H_
#define OPENXR_PLATFORM_H_ 1
/*
** Copyright (c) 2017-2019 The Khronos Group Inc.
**
** Licensed under the Apache License, Version 2.0 (the "License");
** you may not use this file except in compliance with the License.
** You may obtain a copy of the License at
**
** http://www.apache.org/licenses/LICENSE-2.0
**
** Unless required by applicable law or agreed to in writing, software
** distributed under the License is distributed on an "AS IS" BASIS,
** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
** See the License for the specific language governing permissions and
** limitations under the License.
*/
/*
** This header is generated from the Khronos OpenXR XML API Registry.
**
*/
#include "openxr.h"
#ifdef __cplusplus
extern "C" {
#endif
#ifdef XR_USE_PLATFORM_ANDROID
#define XR_KHR_android_thread_settings 1
#define XR_KHR_android_thread_settings_SPEC_VERSION 5
#define XR_KHR_ANDROID_THREAD_SETTINGS_EXTENSION_NAME "XR_KHR_android_thread_settings"
typedef enum XrAndroidThreadTypeKHR {
XR_ANDROID_THREAD_TYPE_APPLICATION_MAIN_KHR = 1,
XR_ANDROID_THREAD_TYPE_APPLICATION_WORKER_KHR = 2,
XR_ANDROID_THREAD_TYPE_RENDERER_MAIN_KHR = 3,
XR_ANDROID_THREAD_TYPE_RENDERER_WORKER_KHR = 4,
XR_ANDROID_THREAD_TYPE_MAX_ENUM_KHR = 0x7FFFFFFF
} XrAndroidThreadTypeKHR;
typedef XrResult (XRAPI_PTR *PFN_xrSetAndroidApplicationThreadKHR)(XrSession session, XrAndroidThreadTypeKHR threadType, uint32_t threadId);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrSetAndroidApplicationThreadKHR(
XrSession session,
XrAndroidThreadTypeKHR threadType,
uint32_t threadId);
#endif
#endif /* XR_USE_PLATFORM_ANDROID */
#ifdef XR_USE_PLATFORM_ANDROID
#define XR_KHR_android_surface_swapchain 1
#define XR_KHR_android_surface_swapchain_SPEC_VERSION 4
#define XR_KHR_ANDROID_SURFACE_SWAPCHAIN_EXTENSION_NAME "XR_KHR_android_surface_swapchain"
typedef XrResult (XRAPI_PTR *PFN_xrCreateSwapchainAndroidSurfaceKHR)(XrSession session, const XrSwapchainCreateInfo* info, XrSwapchain* swapchain, jobject* surface);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrCreateSwapchainAndroidSurfaceKHR(
XrSession session,
const XrSwapchainCreateInfo* info,
XrSwapchain* swapchain,
jobject* surface);
#endif
#endif /* XR_USE_PLATFORM_ANDROID */
#ifdef XR_USE_PLATFORM_ANDROID
#define XR_KHR_android_create_instance 1
#define XR_KHR_android_create_instance_SPEC_VERSION 3
#define XR_KHR_ANDROID_CREATE_INSTANCE_EXTENSION_NAME "XR_KHR_android_create_instance"
typedef struct XrInstanceCreateInfoAndroidKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
void* XR_MAY_ALIAS applicationVM;
void* XR_MAY_ALIAS applicationActivity;
} XrInstanceCreateInfoAndroidKHR;
#endif /* XR_USE_PLATFORM_ANDROID */
#ifdef XR_USE_GRAPHICS_API_VULKAN
#define XR_KHR_vulkan_swapchain_format_list 1
#define XR_KHR_vulkan_swapchain_format_list_SPEC_VERSION 2
#define XR_KHR_VULKAN_SWAPCHAIN_FORMAT_LIST_EXTENSION_NAME "XR_KHR_vulkan_swapchain_format_list"
typedef struct XrVulkanSwapchainFormatListCreateInfoKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
uint32_t viewFormatCount;
const VkFormat* viewFormats;
} XrVulkanSwapchainFormatListCreateInfoKHR;
#endif /* XR_USE_GRAPHICS_API_VULKAN */
#ifdef XR_USE_GRAPHICS_API_OPENGL
#define XR_KHR_opengl_enable 1
#define XR_KHR_opengl_enable_SPEC_VERSION 7
#define XR_KHR_OPENGL_ENABLE_EXTENSION_NAME "XR_KHR_opengl_enable"
#ifdef XR_USE_PLATFORM_WIN32
typedef struct XrGraphicsBindingOpenGLWin32KHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
HDC hDC;
HGLRC hGLRC;
} XrGraphicsBindingOpenGLWin32KHR;
#endif // XR_USE_PLATFORM_WIN32
#ifdef XR_USE_PLATFORM_XLIB
typedef struct XrGraphicsBindingOpenGLXlibKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
Display* xDisplay;
uint32_t visualid;
GLXFBConfig glxFBConfig;
GLXDrawable glxDrawable;
GLXContext glxContext;
} XrGraphicsBindingOpenGLXlibKHR;
#endif // XR_USE_PLATFORM_XLIB
#ifdef XR_USE_PLATFORM_XCB
typedef struct XrGraphicsBindingOpenGLXcbKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
xcb_connection_t* connection;
uint32_t screenNumber;
xcb_glx_fbconfig_t fbconfigid;
xcb_visualid_t visualid;
xcb_glx_drawable_t glxDrawable;
xcb_glx_context_t glxContext;
} XrGraphicsBindingOpenGLXcbKHR;
#endif // XR_USE_PLATFORM_XCB
#ifdef XR_USE_PLATFORM_WAYLAND
typedef struct XrGraphicsBindingOpenGLWaylandKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
struct wl_display* display;
} XrGraphicsBindingOpenGLWaylandKHR;
#endif // XR_USE_PLATFORM_WAYLAND
typedef struct XrSwapchainImageOpenGLKHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
uint32_t image;
} XrSwapchainImageOpenGLKHR;
typedef struct XrGraphicsRequirementsOpenGLKHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
XrVersion minApiVersionSupported;
XrVersion maxApiVersionSupported;
} XrGraphicsRequirementsOpenGLKHR;
typedef XrResult (XRAPI_PTR *PFN_xrGetOpenGLGraphicsRequirementsKHR)(XrInstance instance, XrSystemId systemId, XrGraphicsRequirementsOpenGLKHR* graphicsRequirements);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrGetOpenGLGraphicsRequirementsKHR(
XrInstance instance,
XrSystemId systemId,
XrGraphicsRequirementsOpenGLKHR* graphicsRequirements);
#endif
#endif /* XR_USE_GRAPHICS_API_OPENGL */
#ifdef XR_USE_GRAPHICS_API_OPENGL_ES
#define XR_KHR_opengl_es_enable 1
#define XR_KHR_opengl_es_enable_SPEC_VERSION 6
#define XR_KHR_OPENGL_ES_ENABLE_EXTENSION_NAME "XR_KHR_opengl_es_enable"
#ifdef XR_USE_PLATFORM_ANDROID
typedef struct XrGraphicsBindingOpenGLESAndroidKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
EGLDisplay display;
EGLConfig config;
EGLContext context;
} XrGraphicsBindingOpenGLESAndroidKHR;
#endif // XR_USE_PLATFORM_ANDROID
typedef struct XrSwapchainImageOpenGLESKHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
uint32_t image;
} XrSwapchainImageOpenGLESKHR;
typedef struct XrGraphicsRequirementsOpenGLESKHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
XrVersion minApiVersionSupported;
XrVersion maxApiVersionSupported;
} XrGraphicsRequirementsOpenGLESKHR;
typedef XrResult (XRAPI_PTR *PFN_xrGetOpenGLESGraphicsRequirementsKHR)(XrInstance instance, XrSystemId systemId, XrGraphicsRequirementsOpenGLESKHR* graphicsRequirements);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrGetOpenGLESGraphicsRequirementsKHR(
XrInstance instance,
XrSystemId systemId,
XrGraphicsRequirementsOpenGLESKHR* graphicsRequirements);
#endif
#endif /* XR_USE_GRAPHICS_API_OPENGL_ES */
#ifdef XR_USE_GRAPHICS_API_VULKAN
#define XR_KHR_vulkan_enable 1
#define XR_KHR_vulkan_enable_SPEC_VERSION 6
#define XR_KHR_VULKAN_ENABLE_EXTENSION_NAME "XR_KHR_vulkan_enable"
typedef struct XrGraphicsBindingVulkanKHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
VkInstance instance;
VkPhysicalDevice physicalDevice;
VkDevice device;
uint32_t queueFamilyIndex;
uint32_t queueIndex;
} XrGraphicsBindingVulkanKHR;
typedef struct XrSwapchainImageVulkanKHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
VkImage image;
} XrSwapchainImageVulkanKHR;
typedef struct XrGraphicsRequirementsVulkanKHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
XrVersion minApiVersionSupported;
XrVersion maxApiVersionSupported;
} XrGraphicsRequirementsVulkanKHR;
typedef XrResult (XRAPI_PTR *PFN_xrGetVulkanInstanceExtensionsKHR)(XrInstance instance, XrSystemId systemId, uint32_t bufferCapacityInput, uint32_t* bufferCountOutput, char* buffer);
typedef XrResult (XRAPI_PTR *PFN_xrGetVulkanDeviceExtensionsKHR)(XrInstance instance, XrSystemId systemId, uint32_t bufferCapacityInput, uint32_t* bufferCountOutput, char* buffer);
typedef XrResult (XRAPI_PTR *PFN_xrGetVulkanGraphicsDeviceKHR)(XrInstance instance, XrSystemId systemId, VkInstance vkInstance, VkPhysicalDevice* vkPhysicalDevice);
typedef XrResult (XRAPI_PTR *PFN_xrGetVulkanGraphicsRequirementsKHR)(XrInstance instance, XrSystemId systemId, XrGraphicsRequirementsVulkanKHR* graphicsRequirements);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrGetVulkanInstanceExtensionsKHR(
XrInstance instance,
XrSystemId systemId,
uint32_t bufferCapacityInput,
uint32_t* bufferCountOutput,
char* buffer);
XRAPI_ATTR XrResult XRAPI_CALL xrGetVulkanDeviceExtensionsKHR(
XrInstance instance,
XrSystemId systemId,
uint32_t bufferCapacityInput,
uint32_t* bufferCountOutput,
char* buffer);
XRAPI_ATTR XrResult XRAPI_CALL xrGetVulkanGraphicsDeviceKHR(
XrInstance instance,
XrSystemId systemId,
VkInstance vkInstance,
VkPhysicalDevice* vkPhysicalDevice);
XRAPI_ATTR XrResult XRAPI_CALL xrGetVulkanGraphicsRequirementsKHR(
XrInstance instance,
XrSystemId systemId,
XrGraphicsRequirementsVulkanKHR* graphicsRequirements);
#endif
#endif /* XR_USE_GRAPHICS_API_VULKAN */
#ifdef XR_USE_GRAPHICS_API_D3D11
#define XR_KHR_D3D11_enable 1
#define XR_KHR_D3D11_enable_SPEC_VERSION 4
#define XR_KHR_D3D11_ENABLE_EXTENSION_NAME "XR_KHR_D3D11_enable"
typedef struct XrGraphicsBindingD3D11KHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
ID3D11Device* device;
} XrGraphicsBindingD3D11KHR;
typedef struct XrSwapchainImageD3D11KHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
ID3D11Texture2D* texture;
} XrSwapchainImageD3D11KHR;
typedef struct XrGraphicsRequirementsD3D11KHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
LUID adapterLuid;
D3D_FEATURE_LEVEL minFeatureLevel;
} XrGraphicsRequirementsD3D11KHR;
typedef XrResult (XRAPI_PTR *PFN_xrGetD3D11GraphicsRequirementsKHR)(XrInstance instance, XrSystemId systemId, XrGraphicsRequirementsD3D11KHR* graphicsRequirements);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrGetD3D11GraphicsRequirementsKHR(
XrInstance instance,
XrSystemId systemId,
XrGraphicsRequirementsD3D11KHR* graphicsRequirements);
#endif
#endif /* XR_USE_GRAPHICS_API_D3D11 */
#ifdef XR_USE_GRAPHICS_API_D3D12
#define XR_KHR_D3D12_enable 1
#define XR_KHR_D3D12_enable_SPEC_VERSION 5
#define XR_KHR_D3D12_ENABLE_EXTENSION_NAME "XR_KHR_D3D12_enable"
typedef struct XrGraphicsBindingD3D12KHR {
XrStructureType type;
const void* XR_MAY_ALIAS next;
ID3D12Device* device;
ID3D12CommandQueue* queue;
} XrGraphicsBindingD3D12KHR;
typedef struct XrSwapchainImageD3D12KHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
ID3D12Resource* texture;
} XrSwapchainImageD3D12KHR;
typedef struct XrGraphicsRequirementsD3D12KHR {
XrStructureType type;
void* XR_MAY_ALIAS next;
LUID adapterLuid;
D3D_FEATURE_LEVEL minFeatureLevel;
} XrGraphicsRequirementsD3D12KHR;
typedef XrResult (XRAPI_PTR *PFN_xrGetD3D12GraphicsRequirementsKHR)(XrInstance instance, XrSystemId systemId, XrGraphicsRequirementsD3D12KHR* graphicsRequirements);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrGetD3D12GraphicsRequirementsKHR(
XrInstance instance,
XrSystemId systemId,
XrGraphicsRequirementsD3D12KHR* graphicsRequirements);
#endif
#endif /* XR_USE_GRAPHICS_API_D3D12 */
#ifdef XR_USE_PLATFORM_WIN32
#define XR_KHR_win32_convert_performance_counter_time 1
#define XR_KHR_win32_convert_performance_counter_time_SPEC_VERSION 1
#define XR_KHR_WIN32_CONVERT_PERFORMANCE_COUNTER_TIME_EXTENSION_NAME "XR_KHR_win32_convert_performance_counter_time"
typedef XrResult (XRAPI_PTR *PFN_xrConvertWin32PerformanceCounterToTimeKHR)(XrInstance instance, const LARGE_INTEGER* performanceCounter, XrTime* time);
typedef XrResult (XRAPI_PTR *PFN_xrConvertTimeToWin32PerformanceCounterKHR)(XrInstance instance, XrTime time, LARGE_INTEGER* performanceCounter);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrConvertWin32PerformanceCounterToTimeKHR(
XrInstance instance,
const LARGE_INTEGER* performanceCounter,
XrTime* time);
XRAPI_ATTR XrResult XRAPI_CALL xrConvertTimeToWin32PerformanceCounterKHR(
XrInstance instance,
XrTime time,
LARGE_INTEGER* performanceCounter);
#endif
#endif /* XR_USE_PLATFORM_WIN32 */
#ifdef XR_USE_TIMESPEC
#define XR_KHR_convert_timespec_time 1
#define XR_KHR_convert_timespec_time_SPEC_VERSION 1
#define XR_KHR_CONVERT_TIMESPEC_TIME_EXTENSION_NAME "XR_KHR_convert_timespec_time"
typedef XrResult (XRAPI_PTR *PFN_xrConvertTimespecTimeToTimeKHR)(XrInstance instance, const struct timespec* timespecTime, XrTime* time);
typedef XrResult (XRAPI_PTR *PFN_xrConvertTimeToTimespecTimeKHR)(XrInstance instance, XrTime time, struct timespec* timespecTime);
#ifndef XR_NO_PROTOTYPES
XRAPI_ATTR XrResult XRAPI_CALL xrConvertTimespecTimeToTimeKHR(
XrInstance instance,
const struct timespec* timespecTime,
XrTime* time);
XRAPI_ATTR XrResult XRAPI_CALL xrConvertTimeToTimespecTimeKHR(
XrInstance instance,
XrTime time,
struct timespec* timespecTime);
#endif
#endif /* XR_USE_TIMESPEC */
#ifdef __cplusplus
}
#endif
#endif

1004
include/openxr/openxr_reflection.h
View File

File diff suppressed because it is too large Load Diff

24
open-in-docker.sh
View File

@ -16,19 +16,17 @@
# https://github.com/KhronosGroup/DockerContainers
# This image/tag is generated from https://github.com/KhronosGroup/DockerContainers/blob/master/Dockerfile.openxr
# Purpose: Spec (pdf/html) generation
IMAGE_NAME=khronosgroup/docker-images:openxr
MOUNTPOINT=/openxr
MOUNTPOINT=$(pwd)
set -e
(
cd $(dirname $0)
# docker pull $IMAGE_NAME
uid=$(id -u)
gid=$(id -g)
USER_ID_ARGS="-e USER_ID=$uid -e GROUP_ID=$gid"
docker run -it --rm \
${USER_ID_ARGS} \
-e CONTAINER_CWD=$MOUNTPOINT \
--mount type=bind,source=$(pwd),target=$MOUNTPOINT \
$IMAGE_NAME
)
# docker pull $IMAGE_NAME
uid=$(id -u)
gid=$(id -g)
USER_ID_ARGS="-e USER_ID=$uid -e GROUP_ID=$gid"
docker run -it --rm \
${USER_ID_ARGS} \
-e CONTAINER_CWD=$MOUNTPOINT \
--mount type=bind,source=$MOUNTPOINT,target=$MOUNTPOINT \
$IMAGE_NAME "$@"

502
specification/Makefile
View File

@ -30,6 +30,8 @@ GENXR_ARGS += $(GENXR_OPTIONS) -registry $(REGISTRY)
ifneq (,$(strip $(VERBOSE)))
ASCIIDOC := $(ASCIIDOC) --verbose
else
GENXR_ARGS += -q
endif
ifneq (,$(strip $(STRICT)))
@ -41,121 +43,255 @@ ifneq (,$(strip $(VERY_STRICT)))
ASCIIDOC := $(ASCIIDOC) --failure-level WARN
endif
SPECREVISION = 1.0.0
SPECREVISION = 1.0.1
REVISION_COMPONENTS = $(subst ., ,$(SPECREVISION))
MAJORMINORVER = $(word 1,$(REVISION_COMPONENTS)).$(word 2,$(REVISION_COMPONENTS))
# Target directory for output files.
OUTDIR ?= $(CURDIR)/out/$(MAJORMINORVER)
OUTDIR ?= out/$(MAJORMINORVER)
# Target directory for generated files.
# This is shorthand; can't be moved because the spec source
# files expect to find these here.
GENDIR = $(CURDIR)/generated
GENDIR = generated
# Generator scripts and options
# GENOPTS can be e.g. '-noprotect'
GENOPTS =
HEADER_DIR = $(OUTDIR)/openxr
HEADER = $(HEADER_DIR)/openxr.h
PLATHEAD = $(HEADER_DIR)/openxr_platform.h
REFLECTHEAD = $(HEADER_DIR)/openxr_reflection.h
HTMLSPEC = $(OUTDIR)/openxr.html
PDFSPEC = $(OUTDIR)/openxr.pdf
REGISTRYOUTDIR = $(OUTDIR)/../registry-release/specs/$(MAJORMINORVER)
METADIR = sources/chapters/extensions/meta
MANDIR := man
SCRIPTS := ./scripts
SPECTOOLS := $(SCRIPTS)/spec_tools
XRAPI := scripts/xrapi.py
METADIR := sources/chapters/extensions/meta
# Gets built automatically
ASCIIDOCTOR_TARGETS :=
default:
$(ECHO) "Makefile help - targets:"
$(ECHO) "header: build OpenXR header"
$(ECHO) "header-test: test-compile the OpenXR header"
$(ECHO) "html: HTML version of OpenXR spec"
$(ECHO) "pdf: PDF version of OpenXR spec (Letter [8.5 x 11] paper size)"
$(ECHO) "pdfA4: PDF version of OpenXR spec (A4 paper size)"
# $(ECHO) "manhtml: HTML version of OpenXR man pages"
# $(ECHO) "manpdf: PDF version of OpenXR man pages"
$(ECHO) "manhtmlpages: HTML separate per-feature reference pages"
$(ECHO) "styleguide: HTML version of styleguide"
$(ECHO) "loader: HTML version of the loader doc"
$(ECHO) "build-examples: try compiling all examples"
$(ECHO) "check-spec-links: run the checkMarkup and checkSpecLinks scripts"
$(ECHO) "all: build header header-test html pdf styleguide loader build-examples check-spec-links"
$(ECHO) "release: build header html pdf manhtmlpages and copy output to an OpenXR-Registry-like layout"
@if [ -d sources/chapters ]; then \
echo "html: HTML version of OpenXR spec"; \
echo "pdf: PDF version of OpenXR spec (Letter [8.5 x 11] paper size)"; \
echo "pdfA4: PDF version of OpenXR spec (A4 paper size)"; \
echo "manhtmlpages: HTML separate per-feature reference pages"; \
echo "build-examples: try compiling all examples"; \
echo "check-spec-links: run the checkMarkup and checkSpecLinks scripts"; \
fi
@if [ -f sources/test.c ]; then \
echo "header-test: test-compile the OpenXR header"; fi
@if [ -d sources/styleguide ]; then \
echo "styleguide: HTML version of styleguide"; fi
@if [ -d loader ]; then \
echo "loader: HTML version of the loader doc"; fi
$(ECHO) "all: build as many of these as possible: header header-test html pdf styleguide loader build-examples check-spec-links"
@if [ -d sources/chapters ] && [ -d loader ]; then \
echo "release: build header html pdf manhtmlpages and copy output to an OpenXR-Registry-like layout"; fi
$(ECHO) "clean_dirt: remove intermediate files"
$(ECHO) "clean: remove targets and intermediate files"
$(ECHO) ""
$(ECHO) "Variables controlling options:"
$(ECHO) "Pass QUIET= to disable quiet mode (echos all commands)"
$(ECHO) "Pass VERBOSE=1 to invoke asciidoctor with the --verbose option"
$(ECHO) "Pass VERBOSE=1 to invoke asciidoctor with the --verbose option and genxr.py without the -q option"
$(ECHO) "Pass STRICT=1 to invoke asciidoctor with the --failure-level ERROR option"
$(ECHO) "Pass VERY_STRICT=1 to invoke asciidoctor with the --failure-level WARN option"
################################################
# Store our build configuration in a file, and force re-generation if it changes.
# Most common thing that changes is the extension list.
APITITLE ?= OpenXR
EXTS := $(sort $(EXTENSIONS))
CONFIG_STAMP_FN := $(OUTDIR)/config-stamp
# This is the stuff stored/checked
STAMP_DATA := $(EXTS) "$(APITITLE)"
# Depend on this target to force checking the config for changes.
config_stamp:
$(QUIET)$(MKDIR) $(dir $(CONFIG_STAMP_FN))
$(QUIET)if ! $(PYTHON) $(SCRIPTS)/check_stamp.py $(CONFIG_STAMP_FN) $(STAMP_DATA); then $(MAKE) clean_generated; fi
.PHONY: config_stamp
################################################
## OpenXR header file targets
# Autogenerate openxr header from XML API description
# Python and XML files on which openxr.h depends
header: $(HEADER)
# Directory to build headers into
$(OUTDIR)/openxr:
$(QUIET)$(MKDIR) $@
REGISTRY = ./registry/xr.xml
GENXR = ./scripts/genxr.py
XRH_DEPENDS = $(REGISTRY) $(GENXR) ./scripts/reg.py ./scripts/generator.py $(OUTDIR)/openxr
# OpenXR header target
$(HEADER): $(XRH_DEPENDS) $(PLATHEAD)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) -o $(HEADER_DIR) openxr.h
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) -o $(HEADER_DIR) openxr_platform.h
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) -o $(HEADER_DIR) openxr_reflection.h
HEADER_DIR := $(OUTDIR)/openxr
HEADER := $(HEADER_DIR)/openxr.h
PLATHEAD := $(HEADER_DIR)/openxr_platform.h
REFLECTHEAD := $(HEADER_DIR)/openxr_reflection.h
GENHEADERS := $(HEADER) $(PLATHEAD) $(REFLECTHEAD)
DEFINESHEAD := $(HEADER_DIR)/openxr_platform_defines.h
# Platform header (just copy)
$(PLATHEAD): $(OUTDIR)/openxr
$(QUIET)$(CP) ../include/openxr/openxr_platform_defines.h $(HEADER_DIR)
$(DEFINESHEAD): ../include/openxr/openxr_platform_defines.h
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(CP) $< $@
# Named target to geneate all headers
header: $(GENHEADERS) $(DEFINESHEAD)
.PHONY: header
TESTSRC := sources/test.c
# Test that openxr.h compiles
header-test: $(HEADER)
$(CC) -Wall -pedantic -std=c99 -c -I$(OUTDIR) sources/test.c
$(CXX) -Wall -c -std=c++98 -I$(OUTDIR) sources/test.c
$(CXX) -Wall -c -std=c++11 -I$(OUTDIR) sources/test.c
header-test: header $(TESTSRC)
$(CC) -Wall -pedantic -std=c99 -c -I$(OUTDIR) $(TESTSRC)
$(CXX) -Wall -c -std=c++98 -I$(OUTDIR) $(TESTSRC)
$(CXX) -Wall -c -std=c++11 -I$(OUTDIR) $(TESTSRC)
rm test.o
.PHONY: header-test
################################################
# Generated files: headers or includes referenced in spec.
# Some nominal targets are just "stamp" files generated.
REGISTRY := registry/xr.xml
GENXR := $(SCRIPTS)/genxr.py
BASIC_GENERATED_DEPENDS := \
$(REGISTRY) \
$(GENXR) \
$(SCRIPTS)/reg.py \
$(SCRIPTS)/generator.py \
$(SPECTOOLS)/util.py \
$(SCRIPTS)/conventions.py \
$(SCRIPTS)/xrconventions.py \
config_stamp \
Makefile
# Stamp files for the generated includes
GENSTAMPS := \
$(GENDIR)/api/apiinc \
$(GENDIR)/validity/validinc \
$(GENDIR)/hostsynctable/hostsyncinc \
$(METADIR)/extinc \
# The actual generated index
GENDEPENDS := $(GENSTAMPS) $(GENDIR)/index.adoc
# The rule for every genxr-generated file
$(GENDEPENDS) $(GENHEADERS) $(XRAPI): $(BASIC_GENERATED_DEPENDS)
$(ECHO) "[genxr] $(REGISTRY) -> $@"
@if [ "x$(STAMP_NOTE)" != "x" ]; then echo " $(STAMP_NOTE)"; fi
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o $(@D) $(@F)
# Print an extra note for stamp files
$(GENSTAMPS): STAMP_NOTE = (and additional files in $(@D))
# Extra deps
$(GENDIR)/api/apiinc: $(SCRIPTS)/docgenerator.py
$(GENDIR)/validity/validinc: $(SCRIPTS)/validitygenerator.py $(SPECTOOLS)/validity.py $(SPECTOOLS)/attributes.py $(SPECTOOLS)/data_structures.py
$(XRAPI): $(SCRIPTS)/pygenerator.py $(SCRIPTS)/docgenerator.py
$(GENHEADERS): $(SCRIPTS)/cgenerator.py
$(REFLECTHEAD): $(SCRIPTS)/creflectiongenerator.py $(SCRIPTS)/jinja_helpers.py
# The actual generated files depend on their stamp file.
GENAPI = $(wildcard $(GENDIR)/api/*/[A-Za-z]*.txt)
$(GENAPI): $(GENDIR)/api/apiinc
GENVALIDITY = $(wildcard $(GENDIR)/validity/*/[A-Za-z]*.txt)
$(GENVALIDITY): $(GENDIR)/validity/validinc
GENSYNC := \
$(GENDIR)/hostsynctable/implicit.txt \
$(GENDIR)/hostsynctable/parameterlists.txt \
$(GENDIR)/hostsynctable/parameters.txt
$(GENSYNC): $(GENDIR)/hostsynctable/hostsyncinc
GENMETA = $(wildcard $(METADIR)/extinc/[A-Za-z]*.adoc)
$(GENMETA): $(METADIR)/extinc
# The actual generated include files
GENINCLUDE = $(GENAPI) $(GENVALIDITY) $(GENSYNC) $(GENMETA)
.PHONY: generated
generated: $(GENDEPENDS)
################################################
# OpenXR Style Guide
SPECSRC = sources/openxr.adoc
SPECFILES = $(wildcard sources/chapters/[A-Za-z]*.adoc)
STYLEGUIDE = $(OUTDIR)/styleguide.html
STYLESRC = sources/styleguide/styleguide.txt
STYLEFILES = $(wildcard sources/styleguide/[A-Za-z]*.txt)
styleguide: $(STYLEGUIDE)
# Use the AsciiDoctor rule
ASCIIDOCTOR_TARGETS += $(STYLEGUIDE)
# Target-specific variables and deps customizing the AsciiDoctor rule
$(STYLEGUIDE): SPECSRC=$(STYLESRC)
$(STYLEGUIDE): LOGFILE=$(OUTDIR)/adoc_styleguide_stderr.txt
$(STYLEGUIDE): $(STYLESRC) $(STYLEFILES) $(GENDIR)/api/apiinc
################################################
# OpenXR Loader Guide
LOADERGUIDE = $(OUTDIR)/loader.html
LOADERSRC = loader/loader.adoc
LOADERFILES = $(wildcard loader/[A-Za-z]*.adoc)
loader: $(LOADERGUIDE)
# Use the AsciiDoctor rule
ASCIIDOCTOR_TARGETS += $(LOADERGUIDE)
# Target-specific variables and deps customizing the AsciiDoctor rule
$(LOADERGUIDE): SPECSRC=$(LOADERSRC)
$(LOADERGUIDE): LOGFILE=$(OUTDIR)/adoc_loader_stderr.txt
$(LOADERGUIDE): $(LOADERSRC) $(LOADERFILES)
################################################
## Specification targets
COMMONDOCS = $(SPECSRC) $(SPECFILES) $(GENINCLUDE) $(GENDEPENDS)
## HTML
HTMLSPEC := $(OUTDIR)/openxr.html
html: $(HTMLSPEC)
pdf pdfLetter:
$(MAKE) PAGESIZE=LETTER $(PDFSPEC)
pdfA4:
$(MAKE) PAGESIZE=A4 $(PDFSPEC)
manhtml: $(HTMLMAN)
manpdf: $(PDFMAN)
SPECSRC = sources/openxr.adoc
SPECFILES = $(wildcard sources/chapters/[A-Za-z]*.adoc)
# Use the AsciiDoctor rule
ASCIIDOCTOR_TARGETS += $(LOADERGUIDE)
HOSTSYNCPATH = $(GENDIR)/hostsynctable
HOSTSYNCDEPEND = $(HOSTSYNCPATH)/hostsyncinc
INDEXDEPEND = $(GENDIR)
INDEXNAME = index.adoc
GENDEPENDS = $(GENDIR)/api/apiinc $(GENDIR)/validity/validinc $(METADIR)/extinc $(INDEXDEPEND)/$(INDEXNAME) $(HOSTSYNCDEPEND)
GENINCLUDE = $(wildcard $(GENDIR)/api/*/[A-Za-z]*.txt $(GENDIR)/validity/*/[A-Za-z]*.txt $(HOSTSYNCPATH)/*/[A-Za-z]*.txt)
COMMONDOCS = $(SPECSRC) $(SPECFILES) $(GENINCLUDE) $(GENDEPENDS) $(OUTDIR)
# Target-specific variables and deps customizing the AsciiDoctor rule
$(HTMLSPEC): LOGFILE=$(OUTDIR)/adoc_html_stderr.txt
$(HTMLSPEC): EXTRA_ARGS=--backend html5
$(HTMLSPEC): $(COMMONDOCS)
.PHONY: generated
generated: $(COMMONDOCS)
## PDF
PDFSPEC := $(OUTDIR)/openxr.pdf
PDFA4SPEC := $(OUTDIR)/openxr.a4.pdf
pdf pdfLetter: $(PDFSPEC)
pdfA4: $(PDFA4SPEC)
# Use the AsciiDoctor rule
ASCIIDOCTOR_TARGETS += $(PDFSPEC) $(PDFA4SPEC)
# Target-specific variables and deps customizing the AsciiDoctor rule
$(PDFSPEC) $(PDFA4SPEC): LOGFILE=$(OUTDIR)/adoc_pdf_stderr.txt
$(PDFSPEC) $(PDFA4SPEC): BACKEND_ARGS=--backend pdf --require asciidoctor-pdf
$(PDFSPEC): PAGESIZE=LETTER
$(PDFA4SPEC): PAGESIZE=A4
$(PDFSPEC) $(PDFA4SPEC): $(COMMONDOCS)
################################################
## Shared asciidoctor rule
EXTS := $(sort $(EXTENSIONS))
EXTATTRIBS := $(foreach ext,$(EXTS),-a $(ext))
EXTOPTIONS := $(foreach ext,$(EXTS),-extension $(ext))
# Generate Asciidoc attributes for spec revision remark.
APITITLE ?= OpenXR
# Spell out RFC2822 format as not all date commands support -R
SPECDATE = $(shell echo `date -u "+%a, %d %b %Y %T %z"`)
@ -182,48 +318,35 @@ ATTRIBOPTS = -a revnumber="$(SPECREVISION)" \
ADOCOPTS = --doctype book -a data-uri -r $(CURDIR)/scripts/openxr-macros.rb $(ATTRIBOPTS)
$(HTMLSPEC): $(COMMONDOCS)
# Default to html5
BACKEND_ARGS=--backend html5
# AsciiDoctor rule - customized by the places where these are described
$(HTMLSPEC) $(PDFSPEC) $(PDFA4SPEC) $(STYLEGUIDE) $(LOADERGUIDE):
$(ECHO) "[asciidoctor] $(SPECSRC) -> $@"
$(QUIET)$(MKDIR) $(@D)
$(QUIET)if [ $$(uname -s | cut -c 1-6) == "CYGWIN" ]; then \
HTMLSPEC_DOS=$$(cygpath -w $@) ;\
OUTSPEC_DOS=$$(cygpath -w $@) ;\
SPECSRC_DOS=$$(cygpath -w $(SPECSRC)) ;\
ATTRIBOPTS_DOS='$(ATTRIBOPTS)' ;\
ADOCOPTS_DOS="--doctype book -a data-uri -r $$(cygpath -w $(CURDIR)/scripts/openxr-macros.rb) $$ATTRIBOPTS_DOS" ;\
HTML_BATCH_FILE=$$(cygpath -w $$(mktemp)).bat ;\
echo $(ASCIIDOC) $$ADOCOPTS_DOS --backend html5 --out-file $$HTMLSPEC_DOS $$SPECSRC_DOS > $$HTML_BATCH_FILE ;\
CMD /C $$HTML_BATCH_FILE ;\
rm -f $$HTML_BATCH_FILE ;\
BATCH_FILE=$$(cygpath -w $$(mktemp)).bat ;\
echo $(ASCIIDOC) $$ADOCOPTS_DOS $(BACKEND_ARGS) --out-file $$OUTSPEC_DOS $$SPECSRC_DOS > $$BATCH_FILE ;\
CMD /C $$BATCH_FILE ;\
rm -f $$BATCH_FILE ;\
else \
$(ASCIIDOC) $(ADOCOPTS) --backend html5 --out-file $@ $(SPECSRC) 2>&1 | tee $(OUTDIR)/adoc_html_stderr.txt ;\
if [ -s $(OUTDIR)/adoc_html_stderr.txt ]; then \
$(ASCIIDOC) $(ADOCOPTS) $(BACKEND_ARGS) --out-file $@ $(SPECSRC) 2>&1 | tee $(LOGFILE) ;\
if [ -s $(LOGFILE) ]; then \
false; \
else \
rm $(OUTDIR)/adoc_html_stderr.txt; \
rm $(LOGFILE); \
fi; \
fi
$(PDFSPEC): $(COMMONDOCS)
$(QUIET)if [ $$(uname -s | cut -c 1-6) == "CYGWIN" ]; then \
PDFSPEC_DOS=$$(cygpath -w $@) ;\
SPECSRC_DOS=$$(cygpath -w $(SPECSRC)) ;\
ATTRIBOPTS_DOS='$(ATTRIBOPTS)' ;\
ADOCOPTS_DOS="--doctype book -a data-uri -r $$(cygpath -w $(CURDIR)/scripts/openxr-macros.rb) $$ATTRIBOPTS_DOS" ;\
PDF_BATCH_FILE=$$(cygpath -w $$(mktemp)).bat ;\
echo $(ASCIIDOC) $$ADOCOPTS_DOS --backend pdf --require asciidoctor-pdf --out-file $$PDFSPEC_DOS $$SPECSRC_DOS > $$PDF_BATCH_FILE ;\
CMD /C $$PDF_BATCH_FILE ;\
rm -f $$PDF_BATCH_FILE ;\
else \
$(ASCIIDOC) $(ADOCOPTS) --backend pdf --require asciidoctor-pdf --out-file $@ $(SPECSRC) 2>&1 | tee $(OUTDIR)/adoc_pdf_stderr.txt ;\
if [ -s $(OUTDIR)/adoc_pdf_stderr.txt ]; then \
false; \
else \
rm $(OUTDIR)/adoc_pdf_stderr.txt; \
fi; \
fi
################################################
# Reference "man" pages extracted from spec
MANDIR := man
MANHTMLDIR = $(OUTDIR)/man/html
KHRSOURCES = $(wildcard $(MANDIR)/*KHR.txt)
MACROSOURCES = $(wildcard $(MANDIR)/XR_*[A-Z][A-Z].txt)
@ -232,9 +355,9 @@ CORESOURCES = $(filter-out $(KHRSOURCES) $(VENSOURCES),$(wildcard $(MANDIR)/[Xx
MANSOURCES = $(CORESOURCES) $(VENSOURCES) $(KHRSOURCES)
MANCOPYRIGHT = $(MANDIR)/copyright-ccby.txt $(MANDIR)/footer.txt
MANGENERATED = $(filter-out $(MANCOPYRIGHT),$(wildcard $(MANDIR)/*))
MANHTML = $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
MANDEPS = $(MANCOPYRIGHT) $(GENINCLUDE) $(GENDEPENDS)
MANATTRIBOPTS = -a stylesheet=khronos.css \
MANHTML = $(MANSOURCES:$(MANDIR)/%.txt=$(MANHTMLDIR)/%.html)
MANDEPS = $(MANCOPYRIGHT) $(GENINCLUDE) $(GENDEPENDS)
MANATTRIBOPTS := -a stylesheet=khronos.css \
-a stylesdir=$(CURDIR)/config \
-a html_spec_relative='../../openxr.html' \
@ -248,172 +371,57 @@ make_extension_source = sources/chapters/extensions/$(word 1,$(subst _, ,$(1)))/
# Call make_extension_source on every enabled extension, after lowercasing and stripping the leading XR prefix.
EXTENSION_SOURCES := $(foreach ext,$(patsubst xr_%,%,$(EXTENSIONS_LOWER)),$(call make_extension_source,$(ext)))
# This is a generated python script used by genRef
# in the process of extracting man page sources.
# So, it must be generated before we can run genRef
scripts/xrapi.py: $(XRH_DEPENDS)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o scripts xrapi.py
# Generation of ref page asciidoctor sources by extraction from the
# specification.
#
# Should have a proper dependency causing the man page sources to be
# generated by running genRef (once), but adding $(MANSOURCES) to the
# targets causes genRef to run once/target.
#
# So, we treat the apispec.txt file as the "stamp" for genRef.
#
# Should pass in $(EXTOPTIONS) to determine which pages to generate,
# which requires a matching update to genRef.
# For now, all core and extension ref pages are extracted by genRef.py.
LOGFILE = man/logfile
man/apispec.txt: $(SPECFILES) $(EXTENSION_SOURCES) ./scripts/genRef.py ./scripts/reflib.py ./scripts/xrapi.py
$(QUIET)$(PYTHON) ./scripts/genRef.py -log $(LOGFILE) -registry $(REGISTRY) $(EXTOPTIONS) $(SPECFILES) $(EXTENSION_SOURCES)
# Treating the all-in-one ref page source apispec.txt as the "stamp" for genRef.
LOGFILE := man/logfile
man/apispec.txt: $(SPECFILES) $(EXTENSION_SOURCES) $(SCRIPTS)/genRef.py $(SCRIPTS)/reflib.py $(SCRIPTS)/xrapi.py
$(ECHO) "[genRef.py] $(REGISTRY) and spec -> $@"
$(ECHO) " (and additional files in $(@D))"
$(QUIET)$(PYTHON) $(SCRIPTS)/genRef.py -log $(LOGFILE) -registry $(REGISTRY) $(EXTOPTIONS) $(SPECFILES) $(EXTENSION_SOURCES)
$(QUIET)grep "ERROR:" $(LOGFILE)
# The recursive $(MAKE) is an apparently unavoidable hack, since the
# actual list of man page sources isn't known until after
# man/apispec.txt is generated.
manhtmlpages: man/apispec.txt
$(MAKE) buildmanpages
$(QUIET)$(MAKE) buildmanpages
buildmanpages: $(MANHTML) $(MANHTMLDIR)/openxr.html
# This is the single-page ref page.
# Manually defining doctype-manpage so that we can use "book" style but still enable the refpage-only portions.
$(MANHTMLDIR)/openxr.html: man/apispec.txt $(MANDEPS)
$(ECHO) "[asciidoctor] $< -> $@"
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(ASCIIDOC) -b html5 $(MANATTRIBOPTS) $(ADOCOPTS) -a doctype-manpage -d book -o $@ $<
# This is all the individual-page ref pages.
$(MANHTML): $(MANHTMLDIR)/%.html: $(MANDIR)/%.txt $(MANDEPS)
$(QUIET)$(MKDIR) $(MANHTMLDIR)
$(ECHO) "[asciidoctor] $< -> $@"
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(ASCIIDOC) -b html5 $(MANATTRIBOPTS) $(ADOCOPTS) -a cross-file-links -d manpage -o $@ $<
#manpdf: $(OUTDIR)/apispec.pdf
#$(OUTDIR)/apispec.pdf: $(SPECVERSION) man/apispec.txt $(MANCOPYRIGHT) $(SVGFILES) $(GENINCLUDE) $(GENDEPENDS)
# $(QUIET)$(MKDIR) $(OUTDIR)
# $(QUIET)$(MKDIR) $(PDFMATHDIR)
# $(QUIET)$(ASCIIDOC) -b pdf -a html_spec_relative='html/vkspec.html' $(ADOCOPTS) $(ADOCPDFOPTS) -o $@ man/apispec.txt
#ifndef GS_EXISTS
# $(QUIET) echo "Warning: Ghostscript not installed, skipping pdf optimization"
#else
# $(QUIET)$(CURDIR)/config/optimize-pdf $@
# $(QUIET)rm $@
# $(QUIET)mv $(OUTDIR)/apispec-optimized.pdf $@
#endif
#manhtml: $(OUTDIR)/apispec.html
#$(OUTDIR)/apispec.html: KATEXDIR = katex
#$(OUTDIR)/apispec.html: $(SPECVERSION) man/apispec.txt $(MANCOPYRIGHT) $(SVGFILES) $(GENINCLUDE) $(GENDEPENDS) katexinst
# $(QUIET)$(MKDIR) $(OUTDIR)
# $(QUIET)$(ASCIIDOC) -b html5 -a html_spec_relative='html/vkspec.html' $(ADOCOPTS) $(ADOCHTMLOPTS) -o $@ man/apispec.txt
################################################
# Generated include files referenced in spec
# Extension dependency script
# The nominal targets here are just "stamp" files generated
# at the same time as the real outputs of these commands.
# Generated files for spec
$(GENDIR)/api/apiinc: $(XRH_DEPENDS)
DEPSCRIPT = $(SCRIPTS)/make_ext_dependency.py
DEPSCRIPTOUT := out/extDependency.sh
$(DEPSCRIPTOUT): $(REGISTRY) $(DEPSCRIPT)
$(ECHO) "[mk_ext_dep] $(REGISTRY) -> $@"
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o $(GENDIR)/api apiinc
$(GENDIR)/validity/validinc: $(XRH_DEPENDS)
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o $(GENDIR)/validity validinc
$(HOSTSYNCDEPEND): $(XRH_DEPENDS)
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o $(HOSTSYNCPATH) hostsyncinc
$(INDEXDEPEND)/$(INDEXNAME): $(XRH_DEPENDS)
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o $(INDEXDEPEND) $(INDEXNAME)
XRM_DEPENDS = $(REGISTRY) $(GENXR) ./scripts/reg.py ./scripts/generator.py
$(METADIR)/extinc: $(XRM_DEPENDS)
$(QUIET)$(MKDIR) $(@D)
$(QUIET)$(PYTHON) $(GENXR) $(GENXR_ARGS) $(EXTOPTIONS) -o $(METADIR) extinc
# Every generated include snippet depends on registry and scripts.
$(GENINCLUDE): $(XRH_DEPENDS)
DEPSCRIPT = ./scripts/make_ext_dependency.py
generated/extDependency.sh: $(REGISTRY) $(DEPSCRIPT)
$(QUIET)$(PYTHON) $(DEPSCRIPT) -registry $(REGISTRY) \
-outscript $@
################################################
# OpenXR Style Guide
STYLEGUIDE = $(OUTDIR)/styleguide.html
STYLESRC = sources/styleguide/styleguide.txt
STYLEFILES = $(wildcard sources/styleguide/[A-Za-z]*.txt)
styleguide: $(STYLEGUIDE)
$(STYLEGUIDE): $(STYLESRC) $(STYLEFILES) $(GENDIR)/api/apiinc
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)if [ $$(uname -s | cut -c 1-6) == "CYGWIN" ]; then \
STYLESPEC_DOS=$$(cygpath -w $@) ;\
STYLESRC_DOS=$$(cygpath -w $(SPECSRC)) ;\
ATTRIBOPTS_DOS='$(ATTRIBOPTS)' ;\
ADOCOPTS_DOS="--doctype book -a data-uri -r $$(cygpath -w $(CURDIR)/scripts/openxr-macros.rb) $$ATTRIBOPTS_DOS" ;\
STYLE_BATCH_FILE=$$(cygpath -w $$(mktemp)).bat ;\
echo $(ASCIIDOC) -b html5 $$ADOCOPTS_DOS -o $$STYLESPEC_DOS $$STYLESRC_DOS > $$STYLE_BATCH_FILE ;\
CMD /C $$STYLE_BATCH_FILE ;\
rm -f $$STYLE_BATCH_FILE ;\
else \
$(ASCIIDOC) -b html5 $(ADOCOPTS) -o $@ $(STYLESRC) ;\
fi
################################################
# OpenXR Loader Guide
LOADERGUIDE = $(OUTDIR)/loader.html
LOADERSRC = loader/loader.adoc
LOADERFILES = $(wildcard loader/[A-Za-z]*.adoc)
loader: $(LOADERGUIDE)
$(LOADERGUIDE): $(LOADERSRC) $(LOADERFILES)
$(QUIET)$(MKDIR) $(OUTDIR)
$(QUIET)if [ $$(uname -s | cut -c 1-6) == "CYGWIN" ]; then \
SPEC_DOS=$$(cygpath -w $@) ;\
SRC_DOS=$$(cygpath -w $(LOADERSRC)) ;\
ATTRIBOPTS_DOS='$(ATTRIBOPTS)' ;\
ADOCOPTS_DOS="--doctype book -a data-uri -r $$(cygpath -w $(CURDIR)/scripts/openxr-macros.rb) $$ATTRIBOPTS_DOS" ;\
BATCH_FILE=$$(cygpath -w $$(mktemp)).bat ;\
echo $(ASCIIDOC) -b html5 $$ADOCOPTS_DOS -o $$SPEC_DOS $$SRC_DOS > $$BATCH_FILE ;\
CMD /C $$BATCH_FILE ;\
rm -f $$BATCH_FILE ;\
else \
$(ASCIIDOC) -b html5 $(ADOCOPTS) -o $@ $(LOADERSRC) ;\
fi
$(QUIET)$(PYTHON) $(DEPSCRIPT) -registry $< -outscript $@
################################################
# Embedded example code
# Script that extracts code to .cpp and .c files, and
# generates an associated makefile
EXAMPLES_SCRIPT = $(CURDIR)/scripts/extract_code.py
EXAMPLES_SCRIPT = $(SCRIPTS)/extract_code.py
# The makefile generated by extract_code.py
EXAMPLES_MAKEFILE = $(CURDIR)/examples.mk
# Only include the generated makefile if we are building neither clean nor default
ifneq ($(MAKECMDGOALS),clean)
ifneq ($(MAKECMDGOALS),)
-include $(EXAMPLES_MAKEFILE)
endif
endif
ifeq (,$(GENERATED_CPP))
# If we didn't include the generated makefile (on purpose or because it hasn't been generated),
# just add dummy rules to generate it.
EXAMPLES_MAKEFILE = examples.mk
ifeq ($(strip $(QUIET)),@)
EXTRACT_QUIET := --quiet
@ -422,11 +430,10 @@ endif
$(EXAMPLES_MAKEFILE): $(EXAMPLES_SCRIPT)
$(QUIET)$(PYTHON) $< --makefile=$@ --line_numbers $(EXTRACT_QUIET)
build-examples: $(EXAMPLES_MAKEFILE)
build-examples: $(EXAMPLES_MAKEFILE) $(HEADER)
$(QUIET)$(MAKE) -f $(EXAMPLES_MAKEFILE)
.PHONY: build-examples
endif
################################################
# Check Markup, Check Spec Links, check XML schema
CHECK_MARKUP_SCRIPT = $(CURDIR)/checkMarkup
@ -442,21 +449,28 @@ check-spec-links:
$(QUIET)$(CHECK_MARKUP_SCRIPT) -Werror
$(QUIET)$(PYTHON) $(CHECK_SPEC_LINKS_SCRIPT)
$(QUIET)env FAIL_IF_COULD_NOT_VALIDATE=false ./checkXml.sh
$(QUIET)$(PYTHON) $(CURDIR)/scripts/xml_consistency.py
$(QUIET)$(PYTHON) $(SCRIPTS)/xml_consistency.py
.PHONY: check-spec-links
################################################
# Meta "build approximately everything spec-specific required to pass CI" target
# recursive to cause csl to run first for better errors messages, without adding bogus depends.
all:
$(QUIET)$(MAKE) check-spec-links # recursive to cause csl to run first for better errors messages, without adding bogus depends.
$(QUIET)$(MAKE) header header-test html pdf styleguide loader build-examples
$(QUIET)if [ -f $(SPECSRC) ]; then $(MAKE) check-spec-links; fi
$(QUIET)$(MAKE) header
$(QUIET)if [ -f $(TESTSRC) ]; then $(MAKE) header-test; fi
$(QUIET)if [ -f $(SPECSRC) ]; then $(MAKE) html pdf build-examples; fi
$(QUIET)if [ -f $(STYLESRC) ]; then $(MAKE) styleguide; fi
$(QUIET)if [ -f $(LOADERSRC) ]; then $(MAKE) loader; fi
$(ECHO) ""
$(ECHO) "Target 'all': Completed specification build and basic checks successfully."
.PHONY: all
################################################
# Meta build for releases. Also copies into approximately the right layout for the OpenXR-Registry repo.
REGISTRYOUTDIR = $(OUTDIR)/../registry-release/specs/$(MAJORMINORVER)
release: header html pdf manhtmlpages loader
$(QUIET)$(MKDIR) $(REGISTRYOUTDIR)/pdf
$(QUIET)$(CP) $(PDFSPEC) $(REGISTRYOUTDIR)/pdf/xrspec.pdf
@ -483,9 +497,9 @@ clean_generated:
# Clean generated targets as well as intermediates.
clean clobber: clean_dirt clean_generated
$(RM) $(HEADER) $(PLATHEAD) $(HTMLSPEC) $(PDFSPEC) $(STYLEGUIDE) $(LOADERGUIDE)
$(RM) $(HEADER) $(PLATHEAD) $(REFLECTHEAD) $(DEFINESHEAD) $(HTMLSPEC) $(PDFSPEC) $(PDFA4SPEC) $(STYLEGUIDE) $(LOADERGUIDE) $(DEPSCRIPTOUT) config_stamp
# Clean up extracted code
$(RM) $(EXAMPLES_MAKEFILE) $(GENERATED_C) $(C_OBJECTS) $(GENERATED_CPP) $(CPP_OBJECTS)
if [ -f $(EXAMPLES_MAKEFILE) ]; then $(MAKE) -f $(EXAMPLES_MAKEFILE) clean-examples; fi
$(RM) $(EXAMPLES_MAKEFILE)
# Clean up man pages
$(RMRF) $(MANHTMLDIR)
find $(CURDIR)/sources/chapters/ -name "*.cpp" -o -name "*.c" -o -name "*.o" | xargs $(RM)

2
specification/current_version.ini
View File

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

7
specification/makeAllExts
View File

@ -26,14 +26,11 @@ set -e
(
cd $(dirname $0)
# Generate extension lists from xr.xml
python3 scripts/make_ext_dependency.py -outscript=generated/extDependency.sh
# make generated/extDependency.sh || exit
make out/extDependency.sh || exit
# Load extension lists
source generated/extDependency.sh
rm generated/extDependency.sh
source out/extDependency.sh
make clean_generated
make EXTENSIONS="$allExts" APITITLE="(with all published extensions)" $*
)

9
specification/makeExt
View File

@ -31,12 +31,10 @@ set -e
(
cd $(dirname $0)
# Generate extension lists from xr.xml
python3 scripts/make_ext_dependency.py -outscript=generated/extDependency.sh
# make generated/extDependency.sh || exit
make out/extDependency.sh || exit
# Load extension lists
source generated/extDependency.sh
rm generated/extDependency.sh
source out/extDependency.sh
extension=$1
shift
@ -58,9 +56,6 @@ set -e
fi
done
# There have been requests for this to be optional.
make clean_generated
# Something weird in bash quoting requires this two-step process to define
# EXTENSIONS to make.
args="${!required[@]}"

8
specification/makeKHR
View File

@ -26,14 +26,10 @@ set -e
(
cd $(dirname $0)
# Generate extension lists from xr.xml
python3 scripts/make_ext_dependency.py -outscript=generated/extDependency.sh
# make generated/extDependency.sh || exit
make out/extDependency.sh || exit
# Load extension lists
source generated/extDependency.sh
rm generated/extDependency.sh
source out/extDependency.sh
make clean_generated
make EXTENSIONS="$khrExts" APITITLE="(with all KHR extensions)" $*
)

8
specification/makeKHRAndKHX
View File

@ -26,14 +26,10 @@ set -e
(
cd $(dirname $0)
# Generate extension lists from xr.xml
python3 scripts/make_ext_dependency.py -outscript=generated/extDependency.sh
# make generated/extDependency.sh || exit
make out/extDependency.sh || exit
# Load extension lists
source generated/extDependency.sh
rm generated/extDependency.sh
source out/extDependency.sh
make clean_generated
make EXTENSIONS="$khrExts $khxExts" APITITLE="(with all KHR and KHX extensions)" $*
)

23
specification/registry/xr.xml
View File

@ -49,6 +49,7 @@ maintained in the master branch of the Khronos OpenXR GitHub project.
<tag name="INTEL" author="Intel" contact="Javier Martinez @javier"/>
<tag name="KHR" author="Khronos" contact="Nick Whiting @whitingn"/>
<tag name="LUNARG" author="LunarG" contact="Mark Young @marky_lunarg, Karl Schultz @karlschultz"/>
<tag name="MND" author="Monado Project" contact="Ryan Pavlik @rpavlik"/>
<tag name="MSFT" author="Microsoft" contact="Alex Turner @alexturn, Yin Li @yl_msft, Bryce Hutchings @brycehutchings, Lachlan Ford @laford_msft, Minmin Gong @gongminmin "/>
<tag name="NV" author="NVIDIA Corporation" contact="Satish Salian @ssalian, Robert Menzel"/>
<tag name="OCULUS" author="Oculus" contact="Cass Everitt @casseveritt, Paul Pedriana @ppedriana"/>
@ -111,7 +112,7 @@ maintained in the master 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, 0, 0)</type>
#define <name>XR_CURRENT_API_VERSION</name> <type>XR_MAKE_VERSION</type>(1, 0, 1)</type>
<!--
NOTE: For avoidance of ambiguity, there should only be 1 <name> tag immediately in
@ -2323,5 +2324,25 @@ maintained in the master branch of the Khronos OpenXR GitHub project.
</require>
</extension>
<extension name="XR_OCULUS_extension_41" number="41" type="instance" supported="disabled">
<require>
<enum value="1" name="XR_OCULUS_extension_41_SPEC_VERSION"/>
<enum value="&quot;XR_OCULUS_extension_41&quot;" name="XR_OCULUS_EXTENSION_41_EXTENSION_NAME"/>
</require>
</extension>
<extension name="XR_OCULUS_extension_42" number="42" type="instance" supported="disabled">
<require>
<enum value="1" name="XR_OCULUS_extension_42_SPEC_VERSION"/>
<enum value="&quot;XR_OCULUS_extension_42&quot;" name="XR_OCULUS_EXTENSION_42_EXTENSION_NAME"/>
</require>
</extension>
<extension name="XR_MND_headless" number="43" type="instance" supported="openxr">
<require>
<enum value="1" name="XR_MND_headless_SPEC_VERSION"/>
<enum value="&quot;XR_MND_headless&quot;" name="XR_MND_HEADLESS_EXTENSION_NAME"/>
</require>
</extension>
</extensions>
</registry>

47
specification/scripts/check_stamp.py Executable file
View File

@ -0,0 +1,47 @@
#!/usr/bin/env python3
# Copyright (c) 2019 The Khronos Group Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# Author: Ryan Pavlik <ryan.pavlik@collabora.com>
"""Pass a filename and any arguments. Will use those arguments to create a stamp file to monitor for changes."""
import sys
from pathlib import Path
def check_stamp(fn, args):
new_contents = ",".join(str(x) for x in args).strip()
write_stamp = True
p = Path(fn)
if p.exists():
with open(fn, 'r', encoding='utf-8') as fp:
stamp_contents = fp.read().strip()
if stamp_contents == new_contents:
write_stamp = False
else:
print("Build configuration options have changed - forcing clean_generated")
if write_stamp:
with open(fn, 'w', encoding='utf-8') as fp:
fp.write(new_contents)
fp.flush()
return write_stamp
if __name__ == "__main__":
stamp = sys.argv[1]
data = sys.argv[2:]
# print("Stamp name:", stamp)
# print("Data:", data)
if check_stamp(sys.argv[1], sys.argv[2:]):
sys.exit(1)

27
specification/scripts/extract_code.py
View File

@ -280,24 +280,25 @@ gen: {script}
makefile=makefile,
script=Path(__file__),
extra=extra_arg,
inputs=' '.join(str(infile) for infile in self.generated_files),
inputs=' '.join(str(infile)
for infile in self.generated_files),
deps=deps_string))
for fn, gen in self.generated_files.items():
f.write('{stem}: {files}\n.PHONY: {stem}\n'.format(
stem=fn.stem, files=' '.join(str(g.with_suffix('.o')) for g in gen)))
width = max(len(generated.name) for generated in self.origins)
if self.origins:
width = max(len(generated.name) for generated in self.origins)
for generated, origin in self.origins.items():
pad = ' ' * (width - len(generated.name))
origin_file, origin_line = origin
if generated.suffix == '.cpp':
compiler = '[c++] '
else:
compiler = '[cc] '
origin_str = '{} {} {} extracted from {}:{}'.format(compiler, generated.name, pad,
origin_file, origin_line)
f.write('{obj}: ORIGIN := {originstr}\n'.format(
obj=generated.with_suffix('.o'), originstr=origin_str))
for generated, origin in self.origins.items():
origin_file, origin_line = origin
if generated.suffix == '.cpp':
compiler = '[c++] '
else:
compiler = '[cc] '
origin_str = '{} {} extracted from {}:{}'.format(compiler, generated.name.ljust(width),
origin_file, origin_line)
f.write('{obj}: ORIGIN := {originstr}\n'.format(
obj=generated.with_suffix('.o'), originstr=origin_str))
if __name__ == "__main__":

6
specification/sources/chapters/extensions/khr/khr_composition_layer_depth.adoc
View File

@ -59,13 +59,13 @@ include::../../../../generated/api/structs/XrCompositionLayerDepthInfoKHR.txt[]
with the requirement here that [eq]#maxDepth {geq} minDepth#.
* pname:nearZ is the positive distance in meters of the pname:minDepth value
in the depth swapchain.
Apps may: use a pname:nearZ that is greater than pname:farZ to indicate
depth values are reversed.
Applications may: use a pname:nearZ that is greater than pname:farZ to
indicate depth values are reversed.
pname:nearZ can be infinite.
* pname:farZ is the positive distance in meters of the pname:maxDepth value
in the depth swapchain.
pname:farZ can be infinite.
Apps must: not use the same value as pname:nearZ.
Applications must: not use the same value as pname:nearZ.
****
slink:XrCompositionLayerDepthInfoKHR contains the information needed to

71
specification/sources/chapters/extensions/mnd/mnd_headless.adoc Normal file
View File

@ -0,0 +1,71 @@
include::../meta/XR_MND_headless.adoc[]
*Last Modified Date*::
2019-07-25
*IP Status*::
No known IP claims.
*Contributors*::
Ryan Pavlik, Collabora
// "This submission is provided subject to and covered by the Khronos Group Intellectual
// Property ("IP") Rights Policy. No other rights are granted by this submission, and
// Khronos may elect to exercise its Copyright license to incorporate this submission into
// other works it controls as it desires."
:INCS-VAR: ../../../../generated
*Overview*
Some applications may wish to access XR interaction devices without
presenting any image content on the display(s).
This extension provides a mechanism for writing such an application using
the OpenXR API.
It modifies the specification in the following ways, without adding any new
named entities.
* When this extension is enabled, an application may: call
flink:xrCreateSession without an stext:XrGraphicsBinding* structure in its
pname:next chain.
In this case, the runtime must: create a "headless" session that does not
interact with the display.
* In a headless session, the session state should: proceed to
ename:XR_SESSION_STATE_READY directly from ename:XR_SESSION_STATE_IDLE.
* In a headless session, the
slink:XrSessionBeginInfo::pname:primaryViewConfigurationType must: be
ignored and may: be `0`.
* In a headless session, the session state proceeds to
ename:XR_SESSION_STATE_SYNCHRONIZED, then ename:XR_SESSION_STATE_VISIBLE
and ename:XR_SESSION_STATE_FOCUSED, after the call to
flink:xrBeginSession.
The application does not need to call flink:xrWaitFrame,
flink:xrBeginFrame, or flink:xrEndFrame, unlike with non-headless
sessions.
* In a headless session, flink:xrEnumerateSwapchainFormats must: return
ename:XR_SUCCESS but enumerate `0` formats.
Because flink:xrWaitFrame is not required, an application using a headless
session should: sleep periodically to avoid consuming all available system
resources in a busy-wait loop.
*New Object Types*
*New Flag Types*
*New Enum Constants*
*New Enums*
*New Structures*
*New Functions*
*Issues*
* Not all devices with which this would be useful fit into one of the
existing elink:XrFormFactor values.
*Version History*
* Revision 1, 2019-07-25 (Ryan Pavlik)
** Initial version reflecting Monado prototype.

101
specification/sources/chapters/extensions/msft/msft_spatial_anchor.adoc
View File

@ -4,24 +4,26 @@ include::../meta/XR_MSFT_spatial_anchor.adoc[]
[open,refpage='XrSpatialAnchorMSFT',type='handles',desc='Represents a spatial anchor']
--
This extension allows an application to create a **spatial anchor**,
an arbitrary freespace point in the user's physical environment that will then
This extension allows an application to create a **spatial anchor**, an
arbitrary freespace point in the user's physical environment that will then
be tracked by the runtime.
The runtime should: then adjust the position and orientation of that anchor's origin
over time as needed, independently of all other spaces and anchors, to ensure that it
maintains its original mapping to the real world.
The runtime should: then adjust the position and orientation of that
anchor's origin over time as needed, independently of all other spaces and
anchors, to ensure that it maintains its original mapping to the real world.
include::../../../../generated/api/handles/XrSpatialAnchorMSFT.txt[]
Spatial anchors are often used in combination with an `UNBOUNDED_MSFT` reference space.
`UNBOUNDED_MSFT` reference spaces adjust their origin as necessary
to keep the viewer's coordinates relative to the space's origin stable.
Such adjustments maintain the visual stability of content currently near the viewer,
but may cause content placed far from the viewer to drift in its alignment to the real world
by the time the user moves close again.
By creating an `XrSpatialAnchorMSFT` where a piece of content is placed and then always
rendering that content relative to its anchor's space,
an application can ensure that each piece of content stays at a fixed location in the environment.
Spatial anchors are often used in combination with an `UNBOUNDED_MSFT`
reference space.
`UNBOUNDED_MSFT` reference spaces adjust their origin as necessary to keep
the viewer's coordinates relative to the space's origin stable.
Such adjustments maintain the visual stability of content currently near the
viewer, but may cause content placed far from the viewer to drift in its
alignment to the real world by the time the user moves close again.
By creating an `XrSpatialAnchorMSFT` where a piece of content is placed and
then always rendering that content relative to its anchor's space, an
application can ensure that each piece of content stays at a fixed location
in the environment.
--
@ -34,24 +36,25 @@ include::../../../../generated/api/protos/xrCreateSpatialAnchorMSFT.txt[]
.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:createInfo is a pointer to an slink:XrSpatialAnchorCreateInfoMSFT structure
containing information about how to create the anchor.
* pname:createInfo is a pointer to an slink:XrSpatialAnchorCreateInfoMSFT
structure containing information about how to create the anchor.
* pname:session is a pointer to a handle in which the created
slink:XrSpatialAnchorMSFT is returned.
****
Creates an slink:XrSpatialAnchorMSFT handle representing a spatial anchor
that will track a fixed location in the physical world over time.
That real-world location is specified by the position and orientation of
the specified pname:pose within pname:space at pname:time.
That real-world location is specified by the position and orientation of the
specified pname:pose within pname:space at pname:time.
If pname:space cannot be located relative to the environment at the moment
of the call to flink:xrCreateSpatialAnchorMSFT, the runtime must: return ename:XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT.
of the call to flink:xrCreateSpatialAnchorMSFT, the runtime must: return
ename:XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT.
After the anchor is created, the runtime should: then adjust its position
and orientation over time relative to other spaces so as to maintain maximum alignment
to its original real-world location, even if that changes the anchor's
relationship to the original pname:space used to initialize it.
and orientation over time relative to other spaces so as to maintain maximum
alignment to its original real-world location, even if that changes the
anchor's relationship to the original pname:space used to initialize it.
include::../../../../generated/validity/protos/xrCreateSpatialAnchorMSFT.txt[]
--
@ -66,7 +69,8 @@ include::../../../../generated/api/structs/XrSpatialAnchorCreateInfoMSFT.txt[]
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to an extension-specific structure.
* pname:space is a handle to the slink:XrSpace in which pname:pose is specified.
* pname:space is a handle to the slink:XrSpace in which pname:pose is
specified.
* pname:pose is the slink:XrPosef within pname:space at pname:time that
specifies the point in the real world used to initialize the new anchor.
* pname:time is the basetype:XrTime at which pname:pose will be evaluated
@ -85,21 +89,24 @@ include::../../../../generated/api/protos/xrCreateSpatialAnchorSpaceMSFT.txt[]
.Parameter Descriptions
****
* pname:session is a handle to an slink:XrSession.
* pname:createInfo is a pointer to an slink:XrSpatialAnchorSpaceCreateInfoMSFT structure
containing information about how to create the anchor.
* pname:space is a pointer to a handle in which the created
slink:XrSpace is returned.
* pname:createInfo is a pointer to an
slink:XrSpatialAnchorSpaceCreateInfoMSFT structure containing information
about how to create the anchor.
* pname:space is a pointer to a handle in which the created slink:XrSpace is
returned.
****
Creates an slink:XrSpace handle based on a spatial anchor.
Application can: provide an slink:XrPosef to define the position and
orientation of the new space's origin relative to the anchor's natural origin.
orientation of the new space's origin relative to the anchor's natural
origin.
Multiple slink:XrSpace handles may exist for a given slink:XrSpatialAnchorMSFT simultaneously,
up to some limit imposed by the runtime.
Multiple slink:XrSpace handles may exist for a given
slink:XrSpatialAnchorMSFT simultaneously, up to some limit imposed by the
runtime.
The slink:XrSpace handle must be eventually freed via the
flink:xrDestroySpace function or by destroying the parent slink:XrSpatialAnchorMSFT
handle.
flink:xrDestroySpace function or by destroying the parent
slink:XrSpatialAnchorMSFT handle.
include::../../../../generated/validity/protos/xrCreateSpatialAnchorSpaceMSFT.txt[]
--
@ -114,10 +121,11 @@ include::../../../../generated/api/structs/XrSpatialAnchorSpaceCreateInfoMSFT.tx
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to an extension-specific structure.
* pname:anchor is a handle to an slink:XrSpatialAnchorMSFT previously created with
flink:xrCreateSpatialAnchorMSFT.
* pname:anchor is a handle to an slink:XrSpatialAnchorMSFT previously
created with flink:xrCreateSpatialAnchorMSFT.
* pname:poseInAnchorSpace is an slink:XrPosef defining the position and
orientation of the new space's origin relative to the anchor's natural origin.
orientation of the new space's origin relative to the anchor's natural
origin.
****
include::../../../../generated/validity/structs/XrSpatialAnchorSpaceCreateInfoMSFT.txt[]
@ -131,13 +139,14 @@ include::../../../../generated/api/protos/xrDestroySpatialAnchorMSFT.txt[]
.Parameter Descriptions
****
* pname:anchor is a handle to an slink:XrSpatialAnchorMSFT previously created by
flink:xrCreateSpatialAnchorMSFT.
* pname:anchor is a handle to an slink:XrSpatialAnchorMSFT previously
created by flink:xrCreateSpatialAnchorMSFT.
****
slink:XrSpatialAnchorMSFT handles are destroyed using flink:xrDestroySpatialAnchorMSFT.
By destroying an anchor, the runtime can: stop spending resources used to maintain tracking
for that anchor's origin.
slink:XrSpatialAnchorMSFT handles are destroyed using
flink:xrDestroySpatialAnchorMSFT.
By destroying an anchor, the runtime can: stop spending resources used to
maintain tracking for that anchor's origin.
include::../../../../generated/validity/protos/xrDestroySpatialAnchorMSFT.txt[]
--
@ -150,11 +159,17 @@ slink:XrSpatialAnchorMSFT
*New Enum Constants*
ename:XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT
elink:XrObjectType enumeration is extended with:
ename:XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
* ename:XR_OBJECT_TYPE_SPATIAL_ANCHOR_MSFT
ename:XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT
elink:XrStructureType enumeration is extended with:
* ename:XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_MSFT
elink:XrResult enumeration is extended with:
* ename:XR_ERROR_CREATE_SPATIAL_ANCHOR_FAILED_MSFT
*New Enums*

81
specification/sources/chapters/extensions/msft/msft_unbounded_reference_space.adoc
View File

@ -2,37 +2,41 @@ include::../meta/XR_MSFT_unbounded_reference_space.adoc[]
*Overview*
This extension allows an application to create an `UNBOUNDED_MSFT` reference space.
This reference space enables the viewer to move freely through a complex environment,
often many meters from where they started, while always optimizing
for coordinate system stability near the viewer.
This is done by allowing the origin of the reference space to drift as necessary
to keep the viewer's coordinates relative to the space's origin stable.
This extension allows an application to create an `UNBOUNDED_MSFT` reference
space.
This reference space enables the viewer to move freely through a complex
environment, often many meters from where they started, while always
optimizing for coordinate system stability near the viewer.
This is done by allowing the origin of the reference space to drift as
necessary to keep the viewer's coordinates relative to the space's origin
stable.
To create an `UNBOUNDED_MSFT` reference space, the application can:
pass ename:XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT to flink:xrCreateReferenceSpace.
To create an `UNBOUNDED_MSFT` reference space, the application can: pass
ename:XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT to
flink:xrCreateReferenceSpace.
The `UNBOUNDED_MSFT` reference space establishes a world-locked origin,
gravity-aligned to exclude pitch and roll, with +Y up, +X to the right,
and -Z forward.
This space begins with an arbitrary initial position and orientation, which the
runtime may: define to be either the initial position at app launch or
gravity-aligned to exclude pitch and roll, with +Y up, +X to the right, and
-Z forward.
This space begins with an arbitrary initial position and orientation, which
the runtime may: define to be either the initial position at app launch or
some other initial zero position.
Unlike a `STAGE` reference space, the runtime may: place the origin of an `UNBOUNDED_MSFT`
reference space at any height, rather than fixing it at the floor.
This is because the viewer may move through various rooms and levels of their
environment, each of which has a different floor height.
Unlike a `STAGE` reference space, the runtime may: place the origin of an
`UNBOUNDED_MSFT` reference space at any height, rather than fixing it at the
floor.
This is because the viewer may move through various rooms and levels of
their environment, each of which has a different floor height.
Runtimes should: not automatically adjust the position of the origin when
the viewer moves to a room with a different floor height.
`UNBOUNDED_MSFT` space is useful when an app needs to render *world-scale* content
that spans beyond the bounds of a single `STAGE`,
for example, an entire floor or multiple floors of a building.
`UNBOUNDED_MSFT` space is useful when an app needs to render *world-scale*
content that spans beyond the bounds of a single `STAGE`, for example, an
entire floor or multiple floors of a building.
An `UNBOUNDED_MSFT` space maintains stability near the viewer by slightly adjusting
its origin over time. The runtime must: not queue the
slink:XrEventDataReferenceSpaceChangePending event in response to these
minor adjustments.
An `UNBOUNDED_MSFT` space maintains stability near the viewer by slightly
adjusting its origin over time.
The runtime must: not queue the slink:XrEventDataReferenceSpaceChangePending
event in response to these minor adjustments.
When views, controllers or other spaces experience tracking loss relative to
the `UNBOUNDED_MSFT` space, runtimes should: continue to provide inferred or
@ -50,26 +54,35 @@ inferred or last-known in this way.
When tracking is recovered, runtimes should: snap the pose of other spaces
back into position relative to the `UNBOUNDED_MSFT` space's original origin.
However, if tracking recovers into a new tracking volume in which the
original origin can no longer be located (e.g. the viewer moved through
a dark hallway and regained tracking in a new room), the runtime may: recenter
the origin arbitrarily, for example moving the origin to coincide with the viewer.
original origin can no longer be located (e.g. the viewer moved through a
dark hallway and regained tracking in a new room), the runtime may: recenter
the origin arbitrarily, for example moving the origin to coincide with the
viewer.
If such recentering occurs, the runtime must: queue the
slink:XrEventDataReferenceSpaceChangePending event with pname:poseValid set to false.
slink:XrEventDataReferenceSpaceChangePending event with pname:poseValid set
to false.
If the viewer moves far enough away from the origin of an `UNBOUNDED_MSFT`
reference space that floating point error would introduce noticeable error
when locating the viewer within that space, the runtime may: recenter the
space's origin to a new location closer to the viewer.
If such recentering occurs, the runtime must: queue the
slink:XrEventDataReferenceSpaceChangePending event with pname:poseValid set
to true.
Runtimes must: support the `UNBOUNDED_MSFT` reference space when this
extension is enabled.
If the viewer moves far enough away from the origin of an `UNBOUNDED_MSFT` reference space
that floating point error would introduce noticeable error when locating the viewer
within that space, the runtime may: recenter the space's origin to a new location
closer to the viewer. If such recentering occurs, the runtime must: queue the
slink:XrEventDataReferenceSpaceChangePending event with pname:poseValid set to true.
Runtimes must: support the `UNBOUNDED_MSFT` reference space when this extension is enabled.
*New Object Types*
*New Flag Types*
*New Enum Constants*
ename:XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT
elink:XrReferenceSpaceType enumeration is extended with:
* ename:XR_REFERENCE_SPACE_TYPE_UNBOUNDED_MSFT
*New Enums*

10
specification/sources/chapters/fundamentals.adoc
View File

@ -208,7 +208,7 @@ of runtimes, graphics platforms, or operating systems.
Therefore, an application should: first query which extensions are available
before enabling.
The application queries the available list of extensions using the the
The application queries the available list of extensions using the
flink:xrEnumerateInstanceExtensionProperties function.
Once an application determines which target extensions are supported, it
can: enable some subset of them during the call to flink:xrCreateInstance.
@ -644,11 +644,11 @@ the two categories below.
.Return Code Categories
****
* Successful completion codes are returned when a function needs to
communicate success or status information.
All successful completion codes are non-negative values.
communicate success or status information.
All successful completion codes are non-negative values.
* Run time error codes are returned when a function needs to communicate a
failure that could only be detected at run time.
All run time error codes are negative values.
failure that could only be detected at run time.
All run time error codes are negative values.
****
[open,refpage='XrResult',desc='Result codes',type='enums']

25
specification/sources/chapters/rendering.adoc
View File

@ -711,7 +711,7 @@ 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 xrWaitFrame must be
its computed display time through its pipeline, as flink:xrWaitFrame must be
called only once per frame.
====
@ -1299,12 +1299,13 @@ their assets and rendering techniques differently based on the blend mode
they choose.
For example, a black shadow rendered using the
ename:XR_ENVIRONMENT_BLEND_MODE_ADDITIVE blend mode will appear transparent,
and so an app in that mode may: render a glow as a grounding effect around
the black shadow to ensure the shadow can be seen.
Similarly, an app designed for ename:XR_ENVIRONMENT_BLEND_MODE_ADDITIVE
rendering may: choose to leave garbage in their alpha channel as a side
effect of a rendering optimization, but this garbage would appear as visible
display artifacts if the environment blend mode was instead
and so an application in that mode may: render a glow as a grounding effect
around the black shadow to ensure the shadow can be seen.
Similarly, an application designed for
ename:XR_ENVIRONMENT_BLEND_MODE_ADDITIVE rendering may: choose to leave
garbage in their alpha channel as a side effect of a rendering optimization,
but this garbage would appear as visible display artifacts if the
environment blend mode was instead
ename:XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND.
Not all systems will support all environment blend modes.
@ -1317,14 +1318,14 @@ ename:XR_ENVIRONMENT_BLEND_MODE_ALPHA_BLEND modes.
For devices that can support multiple environment blend modes, such as AR
phones with video passthrough, the runtime may: optimize power consumption
on the device in response to the environment blend mode that the app chooses
each frame.
For example, if an app on a video passthrough phone knows that it is
on the device in response to the environment blend mode that the application
chooses each frame.
For example, if an application on a video passthrough phone knows that it is
currently rendering a 360-degree background covering all screen pixels, it
can submit frames with an environment blend mode of
ename:XR_ENVIRONMENT_BLEND_MODE_OPAQUE, saving the runtime the cost of
compositing a camera-based underlay of the physical world behind the app's
layers.
compositing a camera-based underlay of the physical world behind the
application's layers.
[open,refpage='xrEnumerateEnvironmentBlendModes',desc='Lists environment blend modes',type='protos',xrefs='XrEnvironmentBlendMode']

26
specification/sources/chapters/session.adoc
View File

@ -26,15 +26,15 @@ Once the runtime is synchronized with the application's frame loop and ready
to display its frames, the session will move into the
ename:XR_SESSION_STATE_SYNCHRONIZED state.
For frames where flink:xrWaitFrame returns an slink:XrFrameState with
pname:shouldRender set to true, the app should render its composition layers
and submit them to flink:xrEndFrame.
pname:shouldRender set to true, the application should render its
composition layers and submit them to flink:xrEndFrame.
If the application desires to leave a running session, it should call the
flink:xrRequestExitSession function to request that the runtime transition
its session to the ename:XR_SESSION_STATE_STOPPING state as soon as
possible.
Once the app reaches the ename:XR_SESSION_STATE_STOPPING state, it can call
flink:xrEndSession to stop the XR session, after which the session will
transition through ename:XR_SESSION_STATE_IDLE to the
Once the application reaches the ename:XR_SESSION_STATE_STOPPING state, it
can call flink:xrEndSession to stop the XR session, after which the session
will transition through ename:XR_SESSION_STATE_IDLE to the
ename:XR_SESSION_STATE_EXITING state.
[[session_running]]A session is considered **running** after a successful
@ -392,7 +392,7 @@ The application does this by successfully calling flink:xrBeginSession and
then running its frame loop by calling flink:xrWaitFrame, flink:xrBeginFrame
and flink:xrEndFrame in a loop.
If the runtime wishes to return the session to the
ename:XR_SESSION_STATE_IDLE state, it must: wait until the app calls
ename:XR_SESSION_STATE_IDLE state, it must: wait until the application calls
flink:xrBeginSession.
After returning from the flink:xrBeginSession call, the runtime may then
immediately transition forward through the
@ -428,13 +428,13 @@ frames.
The application should: continue running its frame loop, rendering and
submitting its composition layers, although it may wish to pause its
experience, as users cannot interact with the application at this time.
It is important for apps to continue rendering when visible, even when they
do not have focus, so the user continues to see something reasonable
underneath modal pop-ups.
Runtimes should: make input actions inactive during while the app is
unfocused, and apps should react to an inactive input action by skipping
rendering of that action's input avatar (depictions of hands or other
tracked objects controlled by the user).
It is important for applications to continue rendering when visible, even
when they do not have focus, so the user continues to see something
reasonable underneath modal pop-ups.
Runtimes should: make input actions inactive during while the application is
unfocused, and applications should react to an inactive input action by
skipping rendering of that action's input avatar (depictions of hands or
other tracked objects controlled by the user).
Receiving the ename:XR_SESSION_STATE_FOCUSED state indicates that the
application has synchronized its frame loop with the runtime, the session's

33
specification/sources/chapters/spaces.adoc
View File

@ -109,11 +109,11 @@ Runtimes must: support this reference space.
gravity-aligned to exclude pitch and roll, with +Y up, +X to the right,
and -Z forward.
This space locks in both its initial position and orientation, which the
runtime may: define to be either the initial position at app launch or
some other calibrated zero position.
runtime may: define to be either the initial position at application
launch or some other calibrated zero position.
+
`LOCAL` space is useful when an app needs to render *seated-scale* content
that is not positioned relative to the physical floor.
`LOCAL` space is useful when an application needs to render *seated-scale*
content that is not positioned relative to the physical floor.
+
When a user needs to recenter `LOCAL` space, a runtime may: offer some
system-level recentering interaction that is transparent to the application,
@ -150,12 +150,12 @@ Runtimes must: support this reference space.
The runtime may: not be able to locate spaces relative to the `STAGE`
reference space if the user has not yet defined one within the
runtime-specific UI.
Apps can use flink:xrGetReferenceSpaceBoundsRect to determine the extents
of the `STAGE` reference space's XZ bounds rectangle, if defined.
Applications can use flink:xrGetReferenceSpaceBoundsRect to determine the
extents of the `STAGE` reference space's XZ bounds rectangle, if defined.
+
`STAGE` space is useful when an app needs to render *standing-scale* content
(no bounds) or *room-scale* content (with bounds) that is relative to the
physical floor.
`STAGE` space is useful when an application needs to render *standing-scale*
content (no bounds) or *room-scale* content (with bounds) that is relative
to the physical floor.
+
When the user redefines the origin or bounds of the current `STAGE` space,
or the runtime otherwise switches to a new `STAGE` definition, the runtime
@ -207,7 +207,8 @@ pname:bounds will be set to 0.
The returned extents are expressed relative to the natural origin of the
provided elink:XrReferenceSpaceType and must: not incorporate any origin
offsets specified by the app during calls to flink:xrCreateReferenceSpace.
offsets specified by the application during calls to
flink:xrCreateReferenceSpace.
The runtime must: return ename:XR_ERROR_REFERENCE_SPACE_UNSUPPORTED if the
elink:XrReferenceSpaceType passed in pname:createInfo is not supported by
@ -244,16 +245,16 @@ runtime otherwise switching to a different space definition.
The reference space change must: only take effect for flink:xrLocateSpace or
flink:xrLocateViews calls whose basetype:XrTime parameter is greater than or
equal to the pname:changeTime provided in that event.
Runtimes should: provide a pname:changeTime to apps that allows for a deep
render pipeline to present frames that are already in flight using the
previous definition of the space.
Runtimes should: provide a pname:changeTime to applications that allows for
a deep render pipeline to present frames that are already in flight using
the previous definition of the space.
Runtimes should: choose a pname:changeTime that is midway between the
pname:displayTime of future frames to avoid threshold issues with apps that
calculate future frame times using pname:displayPeriod.
pname:displayTime of future frames to avoid threshold issues with
applications that calculate future frame times using pname:displayPeriod.
The pname:pose provided here must: only describe the change in the natural
origin of the reference space and must: not incorporate any origin offsets
specified by the app during calls to flink:xrCreateReferenceSpace.
specified by the application during calls to flink:xrCreateReferenceSpace.
If the runtime does not know the location of the space's new origin relative
to its previous origin, pname:poseValid must: be false, and the position and
orientation of pname:poseInPreviousSpace are undefined.

4
specification/sources/chapters/system.adoc
View File

@ -28,8 +28,8 @@ simultaneously.
[[form_factor_description]]
=== Form Factors
The first step in selecting a system is for the app to request its desired
**form factor**.
The first step in selecting a system is for the application to request its
desired **form factor**.
The form factor defines how the display(s) moves in the environment relative
to the user's head and how the user will interact with the XR experience.
A runtime may: support multiple form factors, such as on a mobile phone that

82
tox.ini Normal file
View File

@ -0,0 +1,82 @@
# tox (https://tox.readthedocs.io/) is a tool for running tests
# in multiple virtualenvs. This configuration file will run the
# test suite on all supported python versions. To use it, "pip install tox"
# and then run "tox" from this directory.
# Currently used primarily to configure Python linting tools.
[tox]
envlist = py34, py35, py36
[testenv]
deps =
pytest
commands =
pytest
[flake8]
ignore =
E402, # module level import not at top of file
# Needed since we adjust the python search path for now.
E221, # multiple spaces before operator
E222, # multiple spaces after operator
# (for alignment - can probably rework to avoid this and reduce string concat)
# Things that can be auto-fixed with a code formatter
E121, # continuation line under-indented for hanging indent
E126, # continuation line over-indented for hanging indent
E127, # continuation line over-indented for visual indent
E128, # continuation line under-indented for visual indent
E201, # whitespace after '['
E202, # whitespace before ']'
E203, # whitespace before ','
E225, # missing whitespace around operator
E226, # missing whitespace around arithmetic operator
E231, # missing whitespace after ,
E241, # multiple spaces after ','
E251, # unexpected spaces around keyword / parameter equals
E261, # at least two spaces before inline comment
E265, # block comment should start with '# '
E3 # blank line things
# Things to fix eventually but probably harmless
; E501, # line too long - allowed because we can override line length
W503, # line break before binary operator
W504, # line break after binary operator
max-line-length = 160
max-complexity = 20
[pycodestyle]
ignore =
E402, # module level import not at top of file
# Needed since we adjust the python search path for now.
E221, # multiple spaces before operator
E222, # multiple spaces after operator
# (for alignment - can probably rework to avoid this and reduce string concat)
# Things that can be auto-fixed with a code formatter
E121, # continuation line under-indented for hanging indent
E126, # continuation line over-indented for hanging indent
E127, # continuation line over-indented for visual indent
E128, # continuation line under-indented for visual indent
E201, # whitespace after '['
E202, # whitespace before ']'
E203, # whitespace before ','
E225, # missing whitespace around operator
E226, # missing whitespace around arithmetic operator
E231, # missing whitespace after ,
E241, # multiple spaces after ','
E251, # unexpected spaces around keyword / parameter equals
E261, # at least two spaces before inline comment
E265, # block comment should start with '# '
E3 # blank line things
# Things to fix eventually but probably harmless
E501, # line too long
W503, # line break before binary operator
W504, # line break after binary operator