flightgear/3rdparty/osgXR/docs/API.md

osgXR API Documentation
=======================

The osgXR API is currently considered unstable, however it is versioned. Only
matching minor version numbers should be expected to be source and binary
compatible with one another.

The osgXR headers can be found in [include/osgXR/](../include/osgXR/).

The initial version of this library exposed ``<osgXR/OpenXRDisplay>`` for
configuring a view for VR, and ``<osgXR/osgXR>`` with a convenience wrapper
``osgXR::setupViewerDefaults`` to set up VR automatically based on environment
variables. This worked for most simple OpenSceneGraph examples, however for real
projects something more capable is needed, so it is likely these will be removed
in a future version (they are not currently working due to the new
``XRState::update()`` based state machine).

It is instead recommended to extend the ``osgXR::Manager`` class from
``<osgXR/Manager>`` and implement the callbacks.

## <[osgXR/Action](../include/osgXR/Action)>

This header provides the ``osgXR::Action`` base class, and the
``osgXR::ActionBoolean``, ``osgXR::ActionFloat``, ``osgXR::ActionVector2f``,
``osgXR::ActionPose`` and ``osgXR::ActionVibration`` classes which an
application can use to define OpenXR actions, read input state, and send haptic
output.

## <[osgXR/ActionSet](../include/osgXR/ActionSet)>

This header provides the ``osgXR::ActionSet`` class which an application uses
to group actions into groups which can be separately activated and deactivated.

## <[osgXR/CompositionLayer](../include/osgXR/CompositionLayer)>

This header provides the ``osgXR::CompositionLayer`` base class, from which
other composition layer classes are derived. It provides generic composition
layer capabilities such as visibility, ordering, and alpha blending modes.

## <[osgXR/CompositionLayerQuad](../include/osgXR/CompositionLayerQuad)>

This header provides the ``osgXR::CompositionLayerQuad`` class which an
application can use to control an OpenXR runtime composited quad in the VR
space.

## <[osgXR/InteractionProfile](../include/osgXR/InteractionProfile)>

This header provides the ``osgXR::InteractionProfile`` class which an
application uses to suggest bindings between OpenXR actions and the physical
interactions of a given OpenXR controller profile.

## <[osgXR/Manager](../include/osgXR/Manager)>

This header provides the ``osgXR::Manager`` class which an application can
extend to implement a VR manager class. Virtual callbacks tell the application
which camera views are required to implement VR, and an ``update()`` function
gives osgXR a chance to incrementally bring up or tear down VR.

## <[osgXR/Mirror](../include/osgXR/Mirror)>

This header provides the ``osgXR::Mirror`` class which an application can use to
register a desktop mirror of the VR view.

## <[osgXR/MirrorSettings](../include/osgXR/MirrorSettings)>

This header provides the ``osgXR::MirrorSettings`` class which encapsulates
configuration data for desktop mirrors of VR views.

## <[osgXR/OpenXRDisplay](../include/osgXR/OpenXRDisplay)>

This header provides the ``osgXR::OpenXRDisplay`` ViewConfig class. It is
largely replaced by ``osgXR::Manager``.

## <[osgXR/Settings](../include/osgXR/Settings)>

This header provides the ``osgXR::Settings`` class which encapsulates all the VR
configuration data.

## <[osgXR/Subaction](../include/osgXR/Subaction)>

This header provides the ``osgXR::Subaction`` class which an application can
use to represent OpenXR subaction paths (top level user paths), which allow a
single OpenXR action to represent the same action on both hands. It can be
passed to other action related classes to filter actions by hand, and it can be
extended by the application to implement a callback for InteractionProfile
changes.

## <[osgXR/SubImage](../include/osgXR/SubImage)>

This header provides the simple ``osgXR::SubImage`` class which wraps a
``osgXR::Swapchain`` smart pointer and describes a rectangular area within each
swapchain image. An application can optionally use this to specify what sub-part
of a swapchain image should be rendered by a CompositionLayer.

## <[osgXR/Swapchain](../include/osgXR/Swapchain)>

This header provides the ``osgXR::Swapchain`` class which represents a chain of
images which are passed to the OpenXR runtime. These can be attached to a camera
to allow it to be rendered into, and also attached to a mirror object to allow
the resulting texture (which switches every frame) to be used for further
rendering.

## <[osgXR/View](../include/osgXR/View)>

This header provides the ``osgXR::View`` class which represents a view of the
world which ``osgXR::Manager`` will request to be configured by the application.

## <[osgXR/osgXR](../include/osgXR/osgXR)>

This header provides convenience functions for quick and easy integration of VR
capabilities into a simple OpenSceneGraph application or example. It is
recommended ``osgXR::Manager`` be used instead for most projects.

### osgXR::setupViewerDefaults()

This sets up VR on the provided viewer based on the content of the following
environment variables:
 * ``OSGXR=1``                  enables VR.
 * ``OSGXR_MODE=SLAVE_CAMERAS`` forces the use of separate slave cameras per view.
 * ``OSGXR_MODE=SCENE_VIEW``    forces the use of OpenSceneGraph's SceneView stereo (default).
 * ``OSGXR_SWAPCHAIN=MULTIPLE`` forces the use of separate swapchains per view.
 * ``OSGXR_SWAPCHAIN=SINGLE``   forces the use of a single swapchain containing all views.
 * ``OSGXR_UNITS_PER_METER=10`` allows the scale of the environment to be controlled.
 * ``OSGXR_VALIDATION_LAYER=1`` enables the OpenXR validation layer (off by default).
 * ``OSGXR_DEPTH_INFO=1``       enables passing of depth information to OpenXR (off by default).
 * ``OSGXR_MIRROR=NONE``        use a blank screen as the default mirror.
 * ``OSGXR_MIRROR=LEFT``        use OpenXR view 0 (left) as the default mirror.
 * ``OSGXR_MIRROR=RIGHT``       use OpenXR view 1 (right) as the default mirror.
 * ``OSGXR_MIRROR=LEFT_RIGHT``  use both left and right views side by side as the default mirror.