// Copyright (c) 2016-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[introduction]]
== Introduction

This chapter is informative except for the section on
<<introduction-terminology,Normative Terminology>>.

This document, referred to as the "OpenXR Specification" or just the
"Specification" hereafter, describes OpenXR: what it is, how it acts, and
what is required to implement it.
We assume that the reader has a basic understanding of computer graphics and
the technologies involved in virtual and augmented reality.
This means familiarity with the essentials of computer graphics algorithms
and terminology, modern GPUs (Graphic Processing Units), tracking
technologies, head mounted devices, and input modalities.

The canonical version of the Specification is available in the official
OpenXR Registry, located at URL

{uri-openxr-registry-root}

[[introduction-what-is-openxr]]
=== What is OpenXR?

OpenXR is an API (Application Programming Interface) for XR applications.
XR refers to a continuum of real-and-virtual combined environments generated
by computers through human-machine interaction and is inclusive of the
technologies associated with virtual reality (VR), augmented reality (AR)
and mixed reality (MR).
OpenXR is the interface between an application and an in-process or
out-of-process "XR runtime system", or just "runtime" hereafter.
The runtime may handle such functionality as frame composition, peripheral
management, and raw tracking information.

Optionally, a runtime may support device layer plugins which allow access to
a variety of hardware across a commonly defined interface.

[[introduction-programmer-view]]
=== The Programmer's View of OpenXR

To the application programmer, OpenXR is a set of functions that interface
with a runtime to perform commonly required operations such as accessing
controller/peripheral state, getting current and/or predicted tracking
positions, and submitting rendered frames.

A typical OpenXR program begins with a call to create an instance which
establishes a connection to a runtime.
Then a call is made to create a system which selects for use a physical
display and a subset of input, tracking, and graphics devices.
Subsequently a call is made to create buffers into which the application
will render one or more views using the appropriate graphics APIs for the
platform.
Finally calls are made to create a session and begin the application's XR
rendering loop.

[[introduction-implementor-view]]
=== The Implementor's View of OpenXR

To the runtime implementor, OpenXR is a set of functions that control the
operation of the XR system and establishes the lifecycle of a XR
application.

The implementor's task is to provide a software library on the host which
implements the OpenXR API, while mapping the work for each OpenXR function
to the graphics hardware as appropriate for the capabilities of the device.

[[introduction-our-view]]
=== Our View of OpenXR

We view OpenXR as a mechanism for interacting with VR/AR/MR systems in a
platform-agnostic way.

We expect this model to result in a specification that satisfies the needs
of both programmers and runtime implementors.
It does not, however, necessarily provide a model for implementation.
A runtime implementation must: produce results conforming to those produced
by the specified methods, but may: carry out particular procedures in ways
that are more efficient than the one specified.


[[introduction-bugs]]
=== Filing Bug Reports
Issues with and bug reports on the OpenXR Specification and the API Registry
can: be filed in the Khronos OpenXR GitHub repository, located at URL

https://github.com/KhronosGroup/OpenXR-Docs

Please tag issues with appropriate labels, such as "`Specification`", "`Ref
Pages`" or "`Registry`", to help us triage and assign them appropriately.
Unfortunately, GitHub does not currently let users who do not have write
access to the repository set GitHub labels on issues.
In the meantime, they can: be added to the title line of the issue set in
brackets, e.g. "`[Specification]`".

[[introduction-document-conventions]]
=== Document Conventions

The OpenXR specification is intended for use by both implementors of the API
and application developers seeking to make use of the API, forming a
contract between these parties.
Specification text may address either party; typically the intended audience
can be inferred from context, though some sections are defined to address
only one of these parties.
(For example, Valid Usage sections only address application developers).
Any requirements, prohibitions, recommendations or options defined by
normative terminology are imposed only on the audience of that text.

[[introduction-terminology]]
==== Normative Terminology

The key words must:, required:, should:, may:, and optional: in this
document, when denoted as above, are to be interpreted as described in RFC
2119:

https://tools.ietf.org/html/rfc2119

*must*:: When used alone, this word, or the term *required*, means that the
definition is an absolute requirement of the specification.
When followed by *not* ("`must: not`" ), the phrase means that the
definition is an absolute prohibition of the specification.

*should*:: When used alone, this word means that there may exist valid
reasons in particular circumstances to ignore a particular item, but the
full implications must be understood and carefully weighed before choosing a
different course.
When followed by *not* ("`should: not`"), the phrase means that there may
exist valid reasons in particular circumstances when the particular behavior
is acceptable or even useful, but the full implications should: be
understood and the case carefully weighed before implementing any behavior
described with this label.

*may*:: This word, or the adjective *optional*, means that an item is truly
optional.
One vendor may choose to include the item because a particular marketplace
requires it or because the vendor feels that it enhances the product while
another vendor may omit the same item.

The additional terms can: and cannot: are to be interpreted as follows:

*can*:: This word means that the particular behavior described is a valid
choice for an application, and is never used to refer to runtime behavior.

*cannot*:: This word means that the particular behavior described is not
achievable by an application, for example, an entry point does not exist.

[NOTE]
======
There is an important distinction between *cannot* and *must not*, as used
in this Specification.
*Cannot* means something the application literally is unable to express or
accomplish through the API, while *must not* means something that the
application is capable of expressing through the API, but that the
consequences of doing so are undefined and potentially unrecoverable for the
runtime.
======
