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...
struct	OSVR_ImagingMetadata
struct	OSVR_ImagingState
struct	OSVR_ImagingReport

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 uint32_t	OSVR_ImageDimension
typedef uint8_t	OSVR_ImageChannels
typedef uint8_t	OSVR_ImageDepth
typedef unsigned char	OSVR_ImageBufferElement
	Type for raw buffer access to image data.
typedef enum OSVR_ImagingValueType	OSVR_ImagingValueType
typedef struct OSVR_ImagingMetadata	OSVR_ImagingMetadata
typedef struct OSVR_ImagingState	OSVR_ImagingState
typedef struct OSVR_ImagingReport	OSVR_ImagingReport

Enumerations
enum	OSVR_ImagingValueType { OSVR_IVT_UNSIGNED_INT = 0, OSVR_IVT_SIGNED_INT = 1, OSVR_IVT_FLOATING_POINT = 2 }

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.

Report callback types
typedef void(*	OSVR_PoseCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_PoseReport *report)
	C function type for a Pose callback.
typedef void(*	OSVR_PositionCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_PositionReport *report)
	C function type for a Position callback.
typedef void(*	OSVR_OrientationCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_OrientationReport *report)
	C function type for a Orientation callback.
typedef void(*	OSVR_VelocityCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_VelocityReport *report)
	C function type for a Velocity callback.
typedef void(*	OSVR_LinearVelocityCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_LinearVelocityReport *report)
	C function type for a LinearVelocity callback.
typedef void(*	OSVR_AngularVelocityCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_AngularVelocityReport *report)
	C function type for a AngularVelocity callback.
typedef void(*	OSVR_AccelerationCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_AccelerationReport *report)
	C function type for a Acceleration callback.
typedef void(*	OSVR_LinearAccelerationCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_LinearAccelerationReport *report)
	C function type for a LinearAcceleration callback.
typedef void(*	OSVR_AngularAccelerationCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_AngularAccelerationReport *report)
	C function type for a AngularAcceleration callback.
typedef void(*	OSVR_ButtonCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_ButtonReport *report)
	C function type for a Button callback.
typedef void(*	OSVR_AnalogCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_AnalogReport *report)
	C function type for a Analog callback.
typedef void(*	OSVR_ImagingCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_ImagingReport *report)
	C function type for a Imaging callback.
typedef void(*	OSVR_Location2DCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_Location2DReport *report)
	C function type for a Location2D callback.
typedef void(*	OSVR_DirectionCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_DirectionReport *report)
	C function type for a Direction callback.
typedef void(*	OSVR_EyeTracker2DCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_EyeTracker2DReport *report)
	C function type for a EyeTracker2D callback.
typedef void(*	OSVR_EyeTracker3DCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_EyeTracker3DReport *report)
	C function type for a EyeTracker3D callback.
typedef void(*	OSVR_EyeTrackerBlinkCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_EyeTrackerBlinkReport *report)
	C function type for a EyeTrackerBlink callback.
typedef void(*	OSVR_NaviVelocityCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_NaviVelocityReport *report)
	C function type for a NaviVelocity callback.
typedef void(*	OSVR_NaviPositionCallback )(void *userdata, const struct OSVR_TimeValue *timestamp, const struct OSVR_NaviPositionReport *report)
	C function type for a NaviPosition callback.

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:

• C++ wrapper-using:
  • MinimalInit.cpp
  • TrackerCallback.cpp
  • TrackerState.cpp
  • AnalogCallback.cpp
  • ButtonCallback.cpp
  • DisplayParameter.cpp
  • EyeTracker.cpp
  • Imaging.cpp
  • Location2D.cpp
  • ViewerEyeSurfaces.cpp
  • OpenGLSample.cpp
• C-only:
  • MinimalInit.c
  • TrackerCallback.c
  • TrackerState.c
  • AnalogCallback.c
  • ButtonCallback.c
  • DisplayParameter.c
  • ViewerEyeSurfaces.c
  • OpenGLSampleCAPI.cpp - in C++ but uses the display C API.

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

applicationIdentifier	A null terminated string identifying your application. Reverse DNS format strongly suggested.
flags	initialization options (reserved) - pass 0 for now.

Returns

Client context - will be needed for subsequent calls

Definition at line 48 of file ContextC.cpp.

OSVR_ReturnCode osvrClientUpdate

(

OSVR_ClientContext

ctx

)

#include <osvr/ClientKit/ContextC.h>

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

Parameters

ctx	Client context

Definition at line 72 of file ContextC.cpp.

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

ctx	Client context

Returns

OSVR_RETURN_FAILURE if not yet fully connected/initialized, or if some other error (null context) occurs.

Definition at line 63 of file ContextC.cpp.

OSVR_ReturnCode osvrClientShutdown

(

OSVR_ClientContext

ctx

)

#include <osvr/ClientKit/ContextC.h>

Shutdown the library.

Parameters

ctx	Client context

Definition at line 78 of file ContextC.cpp.

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.

Todo:

Decide if relative viewport should be constant in a display config, and update docs accordingly.

Todo:

Decide if distortion params should be constant in a display config, and update docs accordingly.

Returns

OSVR_RETURN_FAILURE if invalid parameters were passed or some other error occurred, in which case the output argument is unmodified.

Definition at line 65 of file DisplayC.cpp.

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.

Definition at line 124 of file DisplayC.cpp.

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.

Definition at line 137 of file DisplayC.cpp.

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

	disp	Display config object.
[out]	numDisplayInputs	Number 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.

Definition at line 144 of file DisplayC.cpp.

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

	disp	Display config object.
	displayInputIndex	The zero-based index of the display input.
[out]	width	Width (in pixels) of the display input.
[out]	height	Height (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.

Definition at line 153 of file DisplayC.cpp.

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

	disp	Display config object.
[out]	viewers	Number 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.

Definition at line 166 of file DisplayC.cpp.

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.

Definition at line 174 of file DisplayC.cpp.

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

	disp	Display config object.
	viewer	Viewer ID
[out]	eyes	Number 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.

Definition at line 194 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
[out]	pose	Room-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.

Definition at line 204 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	flags	Bitwise OR of matrix convention flags (see Matrix flags)
[out]	mat	Pass 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.

Definition at line 256 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	flags	Bitwise OR of matrix convention flags (see Matrix flags)
[out]	mat	Pass 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.

Definition at line 262 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
[out]	surfaces	Number 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.

Definition at line 269 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
[out]	left	Output: Distance in pixels from the left of the video input to the left of the viewport.
[out]	bottom	Output: Distance in pixels from the bottom of the video input to the bottom of the viewport.
[out]	width	Output: Width of viewport in pixels.
[out]	height	Output: Height of viewport in pixels.

Returns

OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output arguments are unmodified.

Definition at line 280 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
[out]	displayInput	Zero-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.

Definition at line 303 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
	near	Distance from viewpoint to near clipping plane - must be positive.
	far	Distance from viewpoint to far clipping plane - must be positive and not equal to near, typically greater than near.
	flags	Bitwise OR of matrix convention flags (see Matrix flags)
[out]	matrix	Output 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.

Definition at line 350 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
	near	Distance to near clipping plane - must be nonzero, typically positive.
	far	Distance to far clipping plane - must be nonzero, typically positive and greater than near.
	flags	Bitwise OR of matrix convention flags (see Matrix flags)
[out]	matrix	Output 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.

Definition at line 358 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
[out]	left	Distance to left clipping plane
[out]	right	Distance to right clipping plane
[out]	bottom	Distance to bottom clipping plane
[out]	top	Distance to top clipping plane

Returns

OSVR_RETURN_FAILURE if invalid parameters were passed, in which case the output arguments are unmodified.

Definition at line 366 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
[out]	distortionRequested	Output 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.

Definition at line 385 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
[out]	priority	Output: 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.

Definition at line 400 of file DisplayC.cpp.

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

	disp	Display config object
	viewer	Viewer ID
	eye	Eye ID
	surface	Surface ID
[out]	params	Output: 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.

Definition at line 413 of file DisplayC.cpp.

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

	ctx	Client context
	path	A resource path (null-terminated string)
[out]	iface	The interface object. May be freed when no longer needed, otherwise it will be freed when the context is closed.

Return failure if given a null context

Definition at line 37 of file InterfaceC.cpp.

OSVR_ReturnCode osvrClientFreeInterface	(	OSVR_ClientContext	ctx,
		OSVR_ClientInterface	iface
	)

#include <osvr/ClientKit/InterfaceC.h>

Free an interface object before context closure.

Parameters

ctx	Client context
iface	The 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)

Return failure if given a null context

Return failure if given a null interface

This call returns a smart pointer - going to let it go out of scope here to delete.

Return failure if the context didn't have a record of this interface.

Definition at line 53 of file InterfaceC.cpp.

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

	ctx	Client context
	path	A resource path (null-terminated string)
[out]	len	The length of the string value, including null terminator. 0 if the parameter does not exist or is not a string.

Definition at line 35 of file ParametersC.cpp.

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

	ctx	Client context
	path	A resource path (null-terminated string)
[in,out]	buf	A buffer you allocate of the appropriate size. Must be at least the length returned by osvrClientGetStringParameterLength. Will contain the null-terminated string parameter value.
	len	The length of the buffer you're providing. If the buffer is too short, an error is returned and the buffer is unchanged.

buffer too small.

Definition at line 49 of file ParametersC.cpp.

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

ctx	Client context

Return failure if given a null context

Give ourselves 200 milliseconds to get a head tracker report.

Definition at line 41 of file TransformsC.cpp.

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

ctx	Client context

Return failure if given a null context

Definition at line 71 of file TransformsC.cpp.