5bf9a32437
Update 3rdparty/osgXR to version 0.3.9, which gets us better handling of quirks and window closure, and the ability to create quad composition layers which will be particularly useful for the loading screen when flightgear isn't so good at timely frame updates.
129 lines
5.9 KiB
Markdown
129 lines
5.9 KiB
Markdown
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.
|