OSVR-Core  0.6-1962-g59773924
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
ClientKit

The ClientKit library exposes a C API, with header-only C++ wrappers, to write applications using the framework. More...

Modules

 C++ wrappers for ClientKit
 The header-only C++ wrappers around the ClientKit C API.
 

Namespaces

 osvr::clientkit
 Contains C++ header-only wrappers for the ClientKit C API.Use of these wrappers is optional: they duplicate functionality found in the C API as they are implemented in headers on top of the C API. However, they also provide a much cleaner, low-boilerplate interface for the most common operations.
 

Classes

struct  OSVR_IncrementalQuaternion
 The quaternion represents the incremental rotation taking place over a period of dt seconds. Use of dt (which does not necessarily have to be 1, as other velocity/acceleration representations imply) and an incremental quaternion allows device reports to be scaled to avoid aliasing. More...
 
struct  OSVR_VelocityState
 Struct for combined velocity state. More...
 
struct  OSVR_AccelerationState
 Struct for combined acceleration state. More...
 
struct  OSVR_PositionReport
 Report type for a position callback on a tracker interface. More...
 
struct  OSVR_OrientationReport
 Report type for an orientation callback on a tracker interface. More...
 
struct  OSVR_PoseReport
 Report type for a pose (position and orientation) callback on a tracker interface. More...
 
struct  OSVR_VelocityReport
 Report type for a velocity (linear and angular) callback on a tracker interface. More...
 
struct  OSVR_LinearVelocityReport
 Report type for a linear velocity callback on a tracker interface. More...
 
struct  OSVR_AngularVelocityReport
 Report type for an angular velocity callback on a tracker interface. More...
 
struct  OSVR_AccelerationReport
 Report type for an acceleration (linear and angular) callback on a tracker interface. More...
 
struct  OSVR_LinearAccelerationReport
 Report type for a linear acceleration callback on a tracker interface. More...
 
struct  OSVR_AngularAccelerationReport
 Report type for an angular acceleration callback on a tracker interface. More...
 
struct  OSVR_ButtonReport
 Report type for a callback on a button interface. More...
 
struct  OSVR_AnalogReport
 Report type for a callback on an analog interface. More...
 
struct  OSVR_Location2DReport
 Report type for 2D location. More...
 
struct  OSVR_DirectionReport
 Report type for 3D Direction vector. More...
 
struct  OSVR_EyeTracker3DState
 State for 3D gaze report. More...
 
struct  OSVR_EyeTracker3DReport
 Report type for 3D gaze report. More...
 
struct  OSVR_EyeTracker2DReport
 Report type for 2D location report. More...
 
struct  OSVR_EyeTrackerBlinkReport
 Report type for a blink event. More...
 
struct  OSVR_NaviVelocityReport
 Report type for an navigation velocity callback on a tracker interface. More...
 
struct  OSVR_NaviPositionReport
 Report type for an navigation position callback on a tracker interface. More...
 

Typedefs

typedef struct
OSVR_ClientContextObject * 
OSVR_ClientContext
 Opaque handle that should be retained by your application. You need only and exactly one. More...
 
typedef struct
OSVR_ClientInterfaceObject * 
OSVR_ClientInterface
 Opaque handle to an interface used for registering callbacks and getting status. More...
 
typedef unsigned char OSVR_ImageBufferElement
 Type for raw buffer access to image data.
 

Functions

OSVR_ClientContext osvrClientInit (const char applicationIdentifier[], uint32_t flags=0)
 Initialize the library. More...
 
OSVR_ReturnCode osvrClientUpdate (OSVR_ClientContext ctx)
 Updates the state of the context - call regularly in your mainloop. More...
 
OSVR_ReturnCode osvrClientCheckStatus (OSVR_ClientContext ctx)
 Checks to see if the client context is fully started up and connected properly to a server. More...
 
OSVR_ReturnCode osvrClientShutdown (OSVR_ClientContext ctx)
 Shutdown the library. More...
 
void osvrClientLog (OSVR_ClientContext ctx, OSVR_LogLevel severity, const char *message)
 Log a message from the client.
 
OSVR_ReturnCode osvrClientGetInterface (OSVR_ClientContext ctx, const char path[], OSVR_ClientInterface *iface)
 Get the interface associated with the given path. More...
 
OSVR_ReturnCode osvrClientFreeInterface (OSVR_ClientContext ctx, OSVR_ClientInterface iface)
 Free an interface object before context closure. More...
 
OSVR_ReturnCode osvrClientGetStringParameterLength (OSVR_ClientContext ctx, const char path[], size_t *len)
 Get the length of a string parameter associated with the given path. More...
 
OSVR_ReturnCode osvrClientGetStringParameter (OSVR_ClientContext ctx, const char path[], char *buf, size_t len)
 Get a string parameter associated with the given path. More...
 
void osvrClientAttemptServerAutoStart ()
 Ensures the OSVR server process/thread is running. Call once per process. The server may or may not actually start successfully as a result of this call. Continue to check client context status to determine if the client context has connected successfully.
 
void osvrClientReleaseAutoStartedServer ()
 Ensures any OSVR server-related resources in the client are released. Call once per process.
 
OSVR_ReturnCode osvrClientSetRoomRotationUsingHead (OSVR_ClientContext ctx)
 Updates the internal "room to world" transformation (applied to all tracker data for this client context instance) based on the user's head orientation, so that the direction the user is facing becomes -Z to your application. Only rotates about the Y axis (yaw). More...
 
OSVR_ReturnCode osvrClientClearRoomToWorldTransform (OSVR_ClientContext ctx)
 Clears/resets the internal "room to world" transformation back to an identity transformation - that is, clears the effect of any other manipulation of the room to world transform. More...
 

Display API

typedef struct
OSVR_DisplayConfigObject * 
OSVR_DisplayConfig
 Opaque type of a display configuration.
 
OSVR_ReturnCode osvrClientGetDisplay (OSVR_ClientContext ctx, OSVR_DisplayConfig *disp)
 Allocates a display configuration object populated with data from the OSVR system. More...
 
OSVR_ReturnCode osvrClientFreeDisplay (OSVR_DisplayConfig disp)
 Frees a display configuration object. The corresponding context must still be open. More...
 
OSVR_ReturnCode osvrClientCheckDisplayStartup (OSVR_DisplayConfig disp)
 Checks to see if a display is fully configured and ready, including having received its first pose update. More...
 
OSVR_ReturnCode osvrClientGetNumDisplayInputs (OSVR_DisplayConfig disp, OSVR_DisplayInputCount *numDisplayInputs)
 A display config can have one or more display inputs to pass pixels over (HDMI/DVI connections, etc): retrieve the number of display inputs in the current configuration. More...
 
OSVR_ReturnCode osvrClientGetDisplayDimensions (OSVR_DisplayConfig disp, OSVR_DisplayInputCount displayInputIndex, OSVR_DisplayDimension *width, OSVR_DisplayDimension *height)
 Retrieve the pixel dimensions of a given display input for a display config. More...
 
OSVR_ReturnCode osvrClientGetNumViewers (OSVR_DisplayConfig disp, OSVR_ViewerCount *viewers)
 A display config can have one (or theoretically more) viewers: retrieve the viewer count. More...
 
OSVR_ReturnCode osvrClientGetViewerPose (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_Pose3 *pose)
 Get the pose of a viewer in a display config. More...
 
OSVR_ReturnCode osvrClientGetNumEyesForViewer (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount *eyes)
 Each viewer in a display config can have one or more "eyes" which have a substantially similar pose: get the count. More...
 
OSVR_ReturnCode osvrClientGetViewerEyePose (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_Pose3 *pose)
 Get the "viewpoint" for the given eye of a viewer in a display config. More...
 
OSVR_ReturnCode osvrClientGetViewerEyeViewMatrixd (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_MatrixConventions flags, double *mat)
 Get the view matrix (inverse of pose) for the given eye of a viewer in a display config - matrix of doubles. More...
 
OSVR_ReturnCode osvrClientGetViewerEyeViewMatrixf (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_MatrixConventions flags, float *mat)
 Get the view matrix (inverse of pose) for the given eye of a viewer in a display config - matrix of floats. More...
 
OSVR_ReturnCode osvrClientGetNumSurfacesForViewerEye (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount *surfaces)
 Each eye of each viewer in a display config has one or more surfaces (aka "screens") on which content should be rendered. More...
 
OSVR_ReturnCode osvrClientGetRelativeViewportForViewerEyeSurface (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, OSVR_ViewportDimension *left, OSVR_ViewportDimension *bottom, OSVR_ViewportDimension *width, OSVR_ViewportDimension *height)
 Get the dimensions/location of the viewport within the display input for a surface seen by an eye of a viewer in a display config. (This does not include other video inputs that may be on a single virtual desktop, etc. or explicitly account for display configurations that use multiple video inputs. It does not necessarily indicate that a viewport in the sense of glViewport must be created with these parameters, though the parameter order matches for convenience.) More...
 
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceDisplayInputIndex (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, OSVR_DisplayInputCount *displayInput)
 Get the index of the display input for a surface seen by an eye of a viewer in a display config. More...
 
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceProjectionMatrixd (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, double near, double far, OSVR_MatrixConventions flags, double *matrix)
 Get the projection matrix for a surface seen by an eye of a viewer in a display config. (double version) More...
 
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceProjectionMatrixf (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, float near, float far, OSVR_MatrixConventions flags, float *matrix)
 Get the projection matrix for a surface seen by an eye of a viewer in a display config. (float version) More...
 
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceProjectionClippingPlanes (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, double *left, double *right, double *bottom, double *top)
 Get the clipping planes (positions at unit distance) for a surface seen by an eye of a viewer in a display config. More...
 
OSVR_ReturnCode osvrClientDoesViewerEyeSurfaceWantDistortion (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, OSVR_CBool *distortionRequested)
 Determines if a surface seen by an eye of a viewer in a display config requests some distortion to be performed. More...
 
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceRadialDistortionPriority (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, OSVR_DistortionPriority *priority)
 Returns the priority/availability of radial distortion parameters for a surface seen by an eye of a viewer in a display config. More...
 
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceRadialDistortion (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, OSVR_SurfaceCount surface, OSVR_RadialDistortionParameters *params)
 Returns the radial distortion parameters, if known/requested, for a surface seen by an eye of a viewer in a display config. More...
 

State types

typedef OSVR_Vec3 OSVR_PositionState
 Type of position state.
 
typedef OSVR_Quaternion OSVR_OrientationState
 Type of orientation state.
 
typedef OSVR_Pose3 OSVR_PoseState
 Type of pose state.
 
typedef OSVR_Vec3 OSVR_LinearVelocityState
 Type of linear velocity state.
 
typedef struct
OSVR_IncrementalQuaternion 
OSVR_IncrementalQuaternion
 The quaternion represents the incremental rotation taking place over a period of dt seconds. Use of dt (which does not necessarily have to be 1, as other velocity/acceleration representations imply) and an incremental quaternion allows device reports to be scaled to avoid aliasing.
 
typedef OSVR_IncrementalQuaternion OSVR_AngularVelocityState
 Type of angular velocity state: an incremental quaternion, providing the incremental rotation taking place due to velocity over a period of dt seconds.
 
typedef struct OSVR_VelocityState OSVR_VelocityState
 Struct for combined velocity state.
 
typedef OSVR_Vec3 OSVR_LinearAccelerationState
 Type of linear acceleration state.
 
typedef OSVR_IncrementalQuaternion OSVR_AngularAccelerationState
 Type of angular acceleration state.
 
typedef struct
OSVR_AccelerationState 
OSVR_AccelerationState
 Struct for combined acceleration state.
 
typedef uint8_t OSVR_ButtonState
 Type of button state.
 
typedef double OSVR_AnalogState
 Type of analog channel state.
 
#define OSVR_BUTTON_PRESSED   (1)
 OSVR_ButtonState value indicating "button down".
 
#define OSVR_BUTTON_NOT_PRESSED   (0)
 OSVR_ButtonState value indicating "button up".
 

Report types

typedef struct OSVR_PositionReport OSVR_PositionReport
 Report type for a position callback on a tracker interface.
 
typedef struct
OSVR_OrientationReport 
OSVR_OrientationReport
 Report type for an orientation callback on a tracker interface.
 
typedef struct OSVR_PoseReport OSVR_PoseReport
 Report type for a pose (position and orientation) callback on a tracker interface.
 
typedef struct OSVR_VelocityReport OSVR_VelocityReport
 Report type for a velocity (linear and angular) callback on a tracker interface.
 
typedef struct
OSVR_LinearVelocityReport 
OSVR_LinearVelocityReport
 Report type for a linear velocity callback on a tracker interface.
 
typedef struct
OSVR_AngularVelocityReport 
OSVR_AngularVelocityReport
 Report type for an angular velocity callback on a tracker interface.
 
typedef struct
OSVR_AccelerationReport 
OSVR_AccelerationReport
 Report type for an acceleration (linear and angular) callback on a tracker interface.
 
typedef struct
OSVR_LinearAccelerationReport 
OSVR_LinearAccelerationReport
 Report type for a linear acceleration callback on a tracker interface.
 
typedef struct
OSVR_AngularAccelerationReport 
OSVR_AngularAccelerationReport
 Report type for an angular acceleration callback on a tracker interface.
 
typedef struct OSVR_ButtonReport OSVR_ButtonReport
 Report type for a callback on a button interface.
 
typedef struct OSVR_AnalogReport OSVR_AnalogReport
 Report type for a callback on an analog interface.
 
typedef OSVR_Vec2 OSVR_Location2DState
 Type of location within a 2D region/surface, in normalized coordinates (in range [0, 1] in standard OSVR coordinate system)
 
typedef struct
OSVR_Location2DReport 
OSVR_Location2DReport
 Report type for 2D location.
 
typedef OSVR_Vec3 OSVR_DirectionState
 Type of unit directional vector in 3D with no particular origin.
 
typedef struct OSVR_DirectionReport OSVR_DirectionReport
 Report type for 3D Direction vector.
 
typedef OSVR_PositionState OSVR_EyeGazeBasePoint3DState
 Type of eye gaze direction in 3D which contains 3D vector (position) containing gaze base point of the user's respective eye in 3D device coordinates.
 
typedef OSVR_Location2DState OSVR_EyeGazePosition2DState
 Type of eye gaze position in 2D which contains users's gaze/point of regard in normalized display coordinates (in range [0, 1] in standard OSVR coordinate system)
 
typedef OSVR_DirectionState OSVR_EyeGazeDirectionState
 Type of 3D vector (direction vector) containing the normalized gaze direction of user's respective eye.
 
typedef struct
OSVR_EyeTracker3DState 
OSVR_EyeTracker3DState
 State for 3D gaze report.
 
typedef struct
OSVR_EyeTracker3DReport 
OSVR_EyeTracker3DReport
 Report type for 3D gaze report.
 
typedef OSVR_Location2DState OSVR_EyeTracker2DState
 State for 2D location report.
 
typedef struct
OSVR_EyeTracker2DReport 
OSVR_EyeTracker2DReport
 Report type for 2D location report.
 
typedef OSVR_ButtonState OSVR_EyeTrackerBlinkState
 State for a blink event.
 
typedef struct
OSVR_EyeTrackerBlinkReport 
OSVR_EyeTrackerBlinkReport
 Report type for a blink event.
 
typedef OSVR_Vec2 OSVR_NaviVelocityState
 Type of Navigation Velocity state.
 
typedef OSVR_Vec2 OSVR_NaviPositionState
 Type of Navigation Position state.
 
typedef struct
OSVR_NaviVelocityReport 
OSVR_NaviVelocityReport
 Report type for an navigation velocity callback on a tracker interface.
 
typedef struct
OSVR_NaviPositionReport 
OSVR_NaviPositionReport
 Report type for an navigation position callback on a tracker interface.
 
#define OSVR_EYE_BLINK   (1)
 OSVR_EyeTrackerBlinkState value indicating an eyes blink had occurred.
 
#define OSVR_EYE_NO_BLINK   (0)
 OSVR_EyeTrackerBlinkState value indicating eyes are not blinking.
 

Detailed Description

The ClientKit library exposes a C API, with header-only C++ wrappers, to write applications using the framework.

Just as with PluginKit, when possible, the C++ wrappers are recommended.

The C++ wrappers do require some version of the Boost headers to be available. For Windows, the official binaries are recommended.

See examples:

Typedef Documentation

typedef struct OSVR_ClientContextObject* OSVR_ClientContext

#include <osvr/Util/ClientOpaqueTypesC.h>

Opaque handle that should be retained by your application. You need only and exactly one.

Created by osvrClientInit() at application start.

You are required to clean up this handle with osvrClientShutdown().

Definition at line 53 of file ClientOpaqueTypesC.h.

typedef struct OSVR_ClientInterfaceObject* OSVR_ClientInterface

#include <osvr/Util/ClientOpaqueTypesC.h>

Opaque handle to an interface used for registering callbacks and getting status.

You are not required to clean up this handle (it will be automatically cleaned up when the context is), but you can if you are no longer using it, using osvrClientFreeInterface() to inform the context that you no longer need this interface.

Definition at line 63 of file ClientOpaqueTypesC.h.

Function Documentation

OSVR_ClientContext osvrClientInit ( const char  applicationIdentifier[],
uint32_t  flags = 0 
)

#include <osvr/ClientKit/ContextC.h>

Initialize the library.

Parameters
applicationIdentifierA null terminated string identifying your application. Reverse DNS format strongly suggested.
flagsinitialization options (reserved) - pass 0 for now.
Returns
Client context - will be needed for subsequent calls
OSVR_ReturnCode osvrClientUpdate ( OSVR_ClientContext  ctx)

#include <osvr/ClientKit/ContextC.h>

Updates the state of the context - call regularly in your mainloop.

Parameters
ctxClient context
OSVR_ReturnCode osvrClientCheckStatus ( OSVR_ClientContext  ctx)

#include <osvr/ClientKit/ContextC.h>

Checks to see if the client context is fully started up and connected properly to a server.

If this reports that the client context is not OK, there may not be a server running, or you may just have to call osvrClientUpdate() a few times to permit startup to finish. The return value of this call will not change from failure to success without calling osvrClientUpdate().

Parameters
ctxClient context
Returns
OSVR_RETURN_FAILURE if not yet fully connected/initialized, or if some other error (null context) occurs.
OSVR_ReturnCode osvrClientShutdown ( OSVR_ClientContext  ctx)

#include <osvr/ClientKit/ContextC.h>

Shutdown the library.

Parameters
ctxClient context
OSVR_ReturnCode osvrClientGetDisplay ( OSVR_ClientContext  ctx,
OSVR_DisplayConfig disp 
)

#include <osvr/ClientKit/DisplayC.h>

Allocates a display configuration object populated with data from the OSVR system.

Before this call will succeed, your application will need to be correctly and fully connected to an OSVR server. You may consider putting this call in a loop alternating with osvrClientUpdate() until this call succeeds.

Data provided by a display configuration object:

  • The logical display topology (number and relationship of viewers, eyes, and surfaces), which remains constant throughout the life of the configuration object. (A method of notification of change here is TBD).
  • Pose data for viewers (not required for rendering) and pose/view data for eyes (used for rendering) which is based on tracker data: if used, these should be queried every frame.
  • Projection matrix data for surfaces, which while in current practice may be relatively unchanging, we are not guaranteeing them to be constant: these should be queried every frame.
  • Video-input-relative viewport size/location for a surface: would like this to be variable, but probably not feasible. If you have input, please comment on the dev mailing list.
  • Per-surface distortion strategy priorities/availabilities: constant. Note the following, though...
  • Per-surface distortion strategy parameters: variable, request each frame. (Could make constant with a notification if needed?)

Important note: While most of this data is immediately available if you are successful in getting a display config object, the pose-based data (viewer pose, eye pose, eye view matrix) needs tracker state, so at least one (and in practice, typically more) osvrClientUpdate() must be performed before a new tracker report is available to populate that state. See osvrClientCheckDisplayStartup() to query if all startup data is available.

Returns
OSVR_RETURN_FAILURE if invalid parameters were passed or some other error occurred, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientFreeDisplay ( OSVR_DisplayConfig  disp)

#include <osvr/ClientKit/DisplayC.h>

Frees a display configuration object. The corresponding context must still be open.

If you fail to call this, it will be automatically called as part of clean-up when the corresponding context is closed.

Returns
OSVR_RETURN_FAILURE if a null config was passed, or if the given display object was already freed.
OSVR_ReturnCode osvrClientCheckDisplayStartup ( OSVR_DisplayConfig  disp)

#include <osvr/ClientKit/DisplayC.h>

Checks to see if a display is fully configured and ready, including having received its first pose update.

Once this first succeeds, it will continue to succeed for the lifetime of the display config object, so it is not necessary to keep calling once you get a successful result.

Returns
OSVR_RETURN_FAILURE if a null config was passed, or if the given display config object was otherwise not ready for full use.
OSVR_ReturnCode osvrClientGetNumDisplayInputs ( OSVR_DisplayConfig  disp,
OSVR_DisplayInputCount numDisplayInputs 
)

#include <osvr/ClientKit/DisplayC.h>

A display config can have one or more display inputs to pass pixels over (HDMI/DVI connections, etc): retrieve the number of display inputs in the current configuration.

Parameters
dispDisplay config object.
[out]numDisplayInputsNumber of display inputs in the logical display topology, constant throughout the active, valid lifetime of a display config object.
See also
OSVR_DisplayInputCount
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetDisplayDimensions ( OSVR_DisplayConfig  disp,
OSVR_DisplayInputCount  displayInputIndex,
OSVR_DisplayDimension width,
OSVR_DisplayDimension height 
)

#include <osvr/ClientKit/DisplayC.h>

Retrieve the pixel dimensions of a given display input for a display config.

Parameters
dispDisplay config object.
displayInputIndexThe zero-based index of the display input.
[out]widthWidth (in pixels) of the display input.
[out]heightHeight (in pixels) of the display input.

The out parameters are constant throughout the active, valid lifetime of a display config object.

See also
OSVR_DisplayDimension
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output arguments are unmodified.
OSVR_ReturnCode osvrClientGetNumViewers ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount viewers 
)

#include <osvr/ClientKit/DisplayC.h>

A display config can have one (or theoretically more) viewers: retrieve the viewer count.

Parameters
dispDisplay config object.
[out]viewersNumber of viewers in the logical display topology, constant** throughout the active, valid lifetime of a display config object.
See also
OSVR_ViewerCount
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerPose ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_Pose3 pose 
)

#include <osvr/ClientKit/DisplayC.h>

Get the pose of a viewer in a display config.

Note that there may not necessarily be any surfaces rendered from this pose (it's the unused "center" eye in a stereo configuration, for instance) so only use this if it makes integration into your engine or existing applications (not originally designed for stereo) easier.

Will only succeed if osvrClientCheckDisplayStartup() succeeds.

Returns
OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was yet available, in which case the pose argument is unmodified.
OSVR_ReturnCode osvrClientGetNumEyesForViewer ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount eyes 
)

#include <osvr/ClientKit/DisplayC.h>

Each viewer in a display config can have one or more "eyes" which have a substantially similar pose: get the count.

Parameters
dispDisplay config object.
viewerViewer ID
[out]eyesNumber of eyes for this viewer in the logical display topology, constant throughout the active, valid lifetime of a display config object
See also
OSVR_EyeCount
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyePose ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_Pose3 pose 
)

#include <osvr/ClientKit/DisplayC.h>

Get the "viewpoint" for the given eye of a viewer in a display config.

Will only succeed if osvrClientCheckDisplayStartup() succeeds.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
[out]poseRoom-space pose (not relative to pose of the viewer)
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was yet available, in which case the pose argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeViewMatrixd ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_MatrixConventions  flags,
double *  mat 
)

#include <osvr/ClientKit/DisplayC.h>

Get the view matrix (inverse of pose) for the given eye of a viewer in a display config - matrix of doubles.

Will only succeed if osvrClientCheckDisplayStartup() succeeds.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
flagsBitwise OR of matrix convention flags (see Matrix flags)
[out]matPass a double[OSVR_MATRIX_SIZE] to get the transformation matrix from room space to eye space (not relative to pose of the viewer)
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was yet available, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeViewMatrixf ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_MatrixConventions  flags,
float *  mat 
)

#include <osvr/ClientKit/DisplayC.h>

Get the view matrix (inverse of pose) for the given eye of a viewer in a display config - matrix of floats.

Will only succeed if osvrClientCheckDisplayStartup() succeeds.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
flagsBitwise OR of matrix convention flags (see Matrix flags)
[out]matPass a float[OSVR_MATRIX_SIZE] to get the transformation matrix from room space to eye space (not relative to pose of the viewer)
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was yet available, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetNumSurfacesForViewerEye ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount surfaces 
)

#include <osvr/ClientKit/DisplayC.h>

Each eye of each viewer in a display config has one or more surfaces (aka "screens") on which content should be rendered.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
[out]surfacesNumber of surfaces (numbered [0, surfaces - 1]) for the given viewer and eye. Constant throughout the active, valid lifetime of a display config object.
See also
OSVR_SurfaceCount
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetRelativeViewportForViewerEyeSurface ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
OSVR_ViewportDimension left,
OSVR_ViewportDimension bottom,
OSVR_ViewportDimension width,
OSVR_ViewportDimension height 
)

#include <osvr/ClientKit/DisplayC.h>

Get the dimensions/location of the viewport within the display input for a surface seen by an eye of a viewer in a display config. (This does not include other video inputs that may be on a single virtual desktop, etc. or explicitly account for display configurations that use multiple video inputs. It does not necessarily indicate that a viewport in the sense of glViewport must be created with these parameters, though the parameter order matches for convenience.)

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
[out]leftOutput: Distance in pixels from the left of the video input to the left of the viewport.
[out]bottomOutput: Distance in pixels from the bottom of the video input to the bottom of the viewport.
[out]widthOutput: Width of viewport in pixels.
[out]heightOutput: Height of viewport in pixels.
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output arguments are unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceDisplayInputIndex ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
OSVR_DisplayInputCount displayInput 
)

#include <osvr/ClientKit/DisplayC.h>

Get the index of the display input for a surface seen by an eye of a viewer in a display config.

This is the OSVR-assigned display input: it may not (and in practice, usually will not) match any platform-specific display indices. This function exists to associate surfaces with video inputs as enumerated by osvrClientGetNumDisplayInputs().

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
[out]displayInputZero-based index of the display input pixels for this surface are tranmitted over.

This association is constant throughout the active, valid lifetime of a display config object.

See also
osvrClientGetNumDisplayInputs(), osvrClientGetRelativeViewportForViewerEyeSurface()
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceProjectionMatrixd ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
double  near,
double  far,
OSVR_MatrixConventions  flags,
double *  matrix 
)

#include <osvr/ClientKit/DisplayC.h>

Get the projection matrix for a surface seen by an eye of a viewer in a display config. (double version)

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
nearDistance from viewpoint to near clipping plane - must be positive.
farDistance from viewpoint to far clipping plane - must be positive and not equal to near, typically greater than near.
flagsBitwise OR of matrix convention flags (see Matrix flags)
[out]matrixOutput projection matrix: supply an array of 16 (OSVR_MATRIX_SIZE) doubles.
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceProjectionMatrixf ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
float  near,
float  far,
OSVR_MatrixConventions  flags,
float *  matrix 
)

#include <osvr/ClientKit/DisplayC.h>

Get the projection matrix for a surface seen by an eye of a viewer in a display config. (float version)

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
nearDistance to near clipping plane - must be nonzero, typically positive.
farDistance to far clipping plane - must be nonzero, typically positive and greater than near.
flagsBitwise OR of matrix convention flags (see Matrix flags)
[out]matrixOutput projection matrix: supply an array of 16 (OSVR_MATRIX_SIZE) floats.
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceProjectionClippingPlanes ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
double *  left,
double *  right,
double *  bottom,
double *  top 
)

#include <osvr/ClientKit/DisplayC.h>

Get the clipping planes (positions at unit distance) for a surface seen by an eye of a viewer in a display config.

This is only for use in integrations that cannot accept a fully-formulated projection matrix as returned by osvrClientGetViewerEyeSurfaceProjectionMatrixf() or osvrClientGetViewerEyeSurfaceProjectionMatrixd(), and may not necessarily provide the same optimizations.

As all the planes are given at unit (1) distance, before passing these planes to a consuming function in your application/engine, you will typically divide them by your near clipping plane distance.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
[out]leftDistance to left clipping plane
[out]rightDistance to right clipping plane
[out]bottomDistance to bottom clipping plane
[out]topDistance to top clipping plane
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output arguments are unmodified.
OSVR_ReturnCode osvrClientDoesViewerEyeSurfaceWantDistortion ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
OSVR_CBool distortionRequested 
)

#include <osvr/ClientKit/DisplayC.h>

Determines if a surface seen by an eye of a viewer in a display config requests some distortion to be performed.

This simply reports true or false, and does not specify which kind of distortion implementations have been parameterized for this display. For each distortion implementation your application supports, you'll want to call the corresponding priority function to find out if it is available.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
[out]distortionRequestedOutput parameter: whether distortion is requested. Constant throughout the active, valid lifetime of a display config object.
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceRadialDistortionPriority ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
OSVR_DistortionPriority priority 
)

#include <osvr/ClientKit/DisplayC.h>

Returns the priority/availability of radial distortion parameters for a surface seen by an eye of a viewer in a display config.

If osvrClientDoesViewerEyeSurfaceWantDistortion() reports false, then the display does not request distortion of any sort, and thus neither this nor any other distortion strategy priority function will report an "available" priority.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
[out]priorityOutput: the priority level. Negative values (canonically OSVR_DISTORTION_PRIORITY_UNAVAILABLE) indicate this technique not available, higher values indicate higher preference for the given technique based on the device's description. Constant throughout the active, valid lifetime of a display config object.
Returns
OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetViewerEyeSurfaceRadialDistortion ( OSVR_DisplayConfig  disp,
OSVR_ViewerCount  viewer,
OSVR_EyeCount  eye,
OSVR_SurfaceCount  surface,
OSVR_RadialDistortionParameters params 
)

#include <osvr/ClientKit/DisplayC.h>

Returns the radial distortion parameters, if known/requested, for a surface seen by an eye of a viewer in a display config.

Will only succeed if osvrClientGetViewerEyeSurfaceRadialDistortionPriority() reports a non-negative priority.

Parameters
dispDisplay config object
viewerViewer ID
eyeEye ID
surfaceSurface ID
[out]paramsOutput: the parameters for radial distortion
Returns
OSVR_RETURN_FAILURE if this surface does not have these parameters described, or if invalid parameters were passed, in which case the output argument is unmodified.
OSVR_ReturnCode osvrClientGetInterface ( OSVR_ClientContext  ctx,
const char  path[],
OSVR_ClientInterface iface 
)

#include <osvr/ClientKit/InterfaceC.h>

Get the interface associated with the given path.

Parameters
ctxClient context
pathA resource path (null-terminated string)
[out]ifaceThe interface object. May be freed when no longer needed, otherwise it will be freed when the context is closed.
OSVR_ReturnCode osvrClientFreeInterface ( OSVR_ClientContext  ctx,
OSVR_ClientInterface  iface 
)

#include <osvr/ClientKit/InterfaceC.h>

Free an interface object before context closure.

Parameters
ctxClient context
ifaceThe interface object
Returns
OSVR_RETURN_SUCCESS unless a null context or interface was passed or the given interface was not found in the context (i.e. had already been freed)
OSVR_ReturnCode osvrClientGetStringParameterLength ( OSVR_ClientContext  ctx,
const char  path[],
size_t *  len 
)

#include <osvr/ClientKit/ParametersC.h>

Get the length of a string parameter associated with the given path.

Parameters
ctxClient context
pathA resource path (null-terminated string)
[out]lenThe length of the string value, including null terminator. 0 if the parameter does not exist or is not a string.
OSVR_ReturnCode osvrClientGetStringParameter ( OSVR_ClientContext  ctx,
const char  path[],
char *  buf,
size_t  len 
)

#include <osvr/ClientKit/ParametersC.h>

Get a string parameter associated with the given path.

Parameters
ctxClient context
pathA resource path (null-terminated string)
[in,out]bufA buffer you allocate of the appropriate size. Must be at least the length returned by osvrClientGetStringParameterLength. Will contain the null-terminated string parameter value.
lenThe length of the buffer you're providing. If the buffer is too short, an error is returned and the buffer is unchanged.
OSVR_ReturnCode osvrClientSetRoomRotationUsingHead ( OSVR_ClientContext  ctx)

#include <osvr/ClientKit/TransformsC.h>

Updates the internal "room to world" transformation (applied to all tracker data for this client context instance) based on the user's head orientation, so that the direction the user is facing becomes -Z to your application. Only rotates about the Y axis (yaw).

Note that this method internally calls osvrClientUpdate() to get a head pose so your callbacks may be called during its execution!

Parameters
ctxClient context
OSVR_ReturnCode osvrClientClearRoomToWorldTransform ( OSVR_ClientContext  ctx)

#include <osvr/ClientKit/TransformsC.h>

Clears/resets the internal "room to world" transformation back to an identity transformation - that is, clears the effect of any other manipulation of the room to world transform.

Parameters
ctxClient context