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.

Classes
struct	OSVR_IncrementalQuaternion
	The quaternion represents the incremental rotation taking place over a period of dt seconds. 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_SkeletonJointState
	A state of a single skeleton joint. More...

struct	OSVR_SkeletonBonetState
	A state of a single skeleton bone. More...

struct	OSVR_SkeletonState
	Type of Skeleton state. More...

struct	OSVR_SkeletonReport
	Report type for a skeleton callback. 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. 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_CLIENTKIT_EXPORT OSVR_ClientContext	osvrClientInit (const char applicationIdentifier[], uint32_t flags OSVR_CPP_ONLY(=0))
	Initialize the library. More...

OSVR_CLIENTKIT_EXPORT OSVR_ClientContext	osvrClientInitHost (const char applicationIdentifier[], const char host[], uint32_t flags OSVR_CPP_ONLY(=0))
	Initialize the library. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientUpdate (OSVR_ClientContext ctx)
	Updates the state of the context - call regularly in your mainloop. More...

OSVR_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientShutdown (OSVR_ClientContext ctx)
	Shutdown the library. More...

OSVR_CLIENTKIT_EXPORT void	osvrClientLog (OSVR_ClientContext ctx, OSVR_LogLevel severity, const char *message)
	Log a message from the client.

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetInterface (OSVR_ClientContext ctx, const char path[], OSVR_ClientInterface *iface)
	Get the interface associated with the given path. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientFreeInterface (OSVR_ClientContext ctx, OSVR_ClientInterface iface)
	Free an interface object before context closure. More...

OSVR_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetStringParameter (OSVR_ClientContext ctx, const char path[], char *buf, size_t len)
	Get a string parameter associated with the given path. More...

OSVR_CLIENTKIT_EXPORT void	osvrClientAttemptServerAutoStart ()
	Ensures the OSVR server process/thread is running. More...

OSVR_CLIENTKIT_EXPORT void	osvrClientReleaseAutoStartedServer ()
	Ensures any OSVR server-related resources in the client are released. More...

OSVR_CLIENTKIT_EXPORT 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. More...

OSVR_CLIENTKIT_EXPORT 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. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetDisplay (OSVR_ClientContext ctx, OSVR_DisplayConfig *disp)
	Allocates a display configuration object populated with data from the OSVR system. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientFreeDisplay (OSVR_DisplayConfig disp)
	Frees a display configuration object. More...

OSVR_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetViewerPose (OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_Pose3 *pose)
	Get the pose of a viewer in a display config. More...

OSVR_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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. More...

OSVR_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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. More...

OSVR_CLIENTKIT_EXPORT 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. More...

OSVR_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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_CLIENTKIT_EXPORT 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...

Skeleton API
OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonBoneId (OSVR_Skeleton skel, const char boneName, OSVR_SkeletonBoneCount boneId)
	OSVR_Skeleton provides an API to iterate over articulation tree and get skeleton related information such as joint, bone states, get number of joints, etc. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonStringBoneNameLength (OSVR_Skeleton skel, OSVR_SkeletonBoneCount boneId, uint32_t *len)
	Get the length of a string parameter associated with the given boneId. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonBoneName (OSVR_Skeleton skel, OSVR_SkeletonBoneCount boneId, char *boneName, uint32_t len)
	Convert the boneId to the bone name. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonBoneState (OSVR_Skeleton skel, OSVR_SkeletonBoneCount boneId, OSVR_SkeletonBoneState *state)
	Get skeleton bone state for given boneId. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonAvailableJointId (OSVR_Skeleton skel, OSVR_SkeletonJointCount jointIndex, OSVR_SkeletonJointCount *jointId)
	Get the jointId for a given available joint. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonAvailableBoneId (OSVR_Skeleton skel, OSVR_SkeletonBoneCount boneIndex, OSVR_SkeletonBoneCount *boneId)
	Get the boneId for a given available bone. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonJointId (OSVR_Skeleton skel, const char jointName, OSVR_SkeletonJointCount jointId)
	Convert a given jointName to the jointId. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonStringJointNameLength (OSVR_Skeleton skel, OSVR_SkeletonJointCount jointId, uint32_t *len)
	Get the length of a string parameter associated with the given jointId. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonJointName (OSVR_Skeleton skel, OSVR_SkeletonJointCount boneId, char *jointName, uint32_t len)
	Convert the jointId to the joint name. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonJointState (OSVR_Skeleton skel, OSVR_SkeletonJointCount jointId, OSVR_SkeletonJointState *state)
	Get skeleton joint state for given joint Id. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonNumBones (OSVR_Skeleton skel, OSVR_SkeletonBoneCount *numBones)
	Get the number of bones available for a given skeleton. More...

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode	osvrClientGetSkeletonNumJoints (OSVR_Skeleton skel, OSVR_SkeletonJointCount *numJoints)
	Get the number of joints available for a given skeleton. 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. More...

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.

typedef uint32_t	OSVR_SkeletonJointCount
	integer type specifying joint count/index(Id)

typedef uint32_t	OSVR_SkeletonBoneCount
	integer type specifying bone count/index(Id)

typedef struct OSVR_SkeletonJointState	OSVR_SkeletonJointState
	A state of a single skeleton joint.

typedef struct OSVR_SkeletonBonetState	OSVR_SkeletonBoneState
	A state of a single skeleton bone.

typedef struct OSVR_SkeletonState	OSVR_SkeletonState
	Type of Skeleton state.

typedef struct OSVR_SkeletonReport	OSVR_SkeletonReport
	Report type for a skeleton callback. More...

#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:

C++ wrapper-using:
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

§ OSVR_ClientContext

typedef struct OSVR_ClientContextObject* OSVR_ClientContext

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().

§ OSVR_ClientInterface

typedef struct OSVR_ClientInterfaceObject* OSVR_ClientInterface

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.

§ OSVR_DisplayConfig

typedef struct OSVR_DisplayConfigObject* OSVR_DisplayConfig

Opaque type of a display configuration.

§ OSVR_IncrementalQuaternion

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

§ OSVR_SkeletonReport

typedef struct OSVR_SkeletonReport OSVR_SkeletonReport

Report type for a skeleton callback.

Provided whenever skeleton data for given sensor becomes available (When tracker sensors for each joint/site have finished reporting

Function Documentation

§ osvrClientAttemptServerAutoStart()

OSVR_CLIENTKIT_EXPORT 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.

§ osvrClientCheckDisplayStartup()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientCheckDisplayStartup ( OSVR_DisplayConfig disp )

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.

§ osvrClientCheckStatus()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientCheckStatus ( OSVR_ClientContext ctx )

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.

§ osvrClientClearRoomToWorldTransform()

OSVR_CLIENTKIT_EXPORT 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.

Parameters

ctx	Client context

Return failure if given a null context

§ osvrClientDoesViewerEyeSurfaceWantDistortion()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientFreeDisplay()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientFreeDisplay ( OSVR_DisplayConfig disp )

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.

§ osvrClientFreeInterface()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientFreeInterface	(	OSVR_ClientContext	ctx,
		OSVR_ClientInterface	iface
	)

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.

§ osvrClientGetDisplay()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetDisplay	(	OSVR_ClientContext	ctx,
		OSVR_DisplayConfig *	disp
	)

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.

§ osvrClientGetDisplayDimensions()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetInterface()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetInterface	(	OSVR_ClientContext	ctx,
		const char	path[],
		OSVR_ClientInterface *	iface
	)

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

§ osvrClientGetNumDisplayInputs()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetNumEyesForViewer()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetNumSurfacesForViewerEye()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetNumViewers()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetNumViewers	(	OSVR_DisplayConfig	disp,
		OSVR_ViewerCount *	viewers
	)

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.

§ osvrClientGetRelativeViewportForViewerEyeSurface()

OSVR_CLIENTKIT_EXPORT 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.)

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.

§ osvrClientGetSkeletonAvailableBoneId()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonAvailableBoneId	(	OSVR_Skeleton	skel,
		OSVR_SkeletonBoneCount	boneIndex,
		OSVR_SkeletonBoneCount *	boneId
	)

Get the boneId for a given available bone.

Parameters

skel	skeleton object
boneIndex	an index between 0 and numBones as reported by osvrClientGetSkeletonNumBones
boneId	the boneId of the given bone.

§ osvrClientGetSkeletonAvailableJointId()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonAvailableJointId	(	OSVR_Skeleton	skel,
		OSVR_SkeletonJointCount	jointIndex,
		OSVR_SkeletonJointCount *	jointId
	)

Get the jointId for a given available joint.

Parameters

skel	skeleton object
jointIndex	an index between 0 and numJoints as reported by osvrClientGetSkeletonNumJoints
jointId	the jointId of the given joint.

§ osvrClientGetSkeletonBoneId()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonBoneId	(	OSVR_Skeleton	skel,
		const char *	boneName,
		OSVR_SkeletonBoneCount *	boneId
	)

OSVR_Skeleton provides an API to iterate over articulation tree and get skeleton related information such as joint, bone states, get number of joints, etc.

The lifetime of OSVR_SkeletonObject is maintained internally since it requires access to articulation spec, so client app will not be responsible for initialization and/or cleanup after. OSVR_Skeleton is part of the OSVR_SkeletonState and is included in OSVR_SkeletonReport.Convert a given boneName to the boneId

Parameters

skel	skeleton object
boneName	string containing boneName
boneId	The bone id for provided boneName. If provided bone name does not exist, the boneId will be unchanged. Refer to OSVR_ReturnCode return value to make sure it exists.

§ osvrClientGetSkeletonBoneName()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonBoneName	(	OSVR_Skeleton	skel,
		OSVR_SkeletonBoneCount	boneId,
		char *	boneName,
		uint32_t	len
	)

Convert the boneId to the bone name.

Parameters

	skel	skeleton object
	boneId	An id that corresponds to this bone
[in,out]	boneName	A buffer that you allocate of appropriate size. Must be at least the length returned by osvrClientGetSkeletonStringBoneNameLength. Will contain the null-terminated string name of the boneId.
	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

§ osvrClientGetSkeletonBoneState()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonBoneState	(	OSVR_Skeleton	skel,
		OSVR_SkeletonBoneCount	boneId,
		OSVR_SkeletonBoneState *	state
	)

Get skeleton bone state for given boneId.

Parameters

skeletonIface	skeleton interface
boneId	The bone id for provided boneName.
state	bone state containing boneId and tracker report

§ osvrClientGetSkeletonJointId()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonJointId	(	OSVR_Skeleton	skel,
		const char *	jointName,
		OSVR_SkeletonJointCount *	jointId
	)

Convert a given jointName to the jointId.

Parameters

skel	skeleton object
jointName	string containing boneName
jointId	The joint id for provided boneName. If provided bone name does not exist, the boneId will be unchanged. Refer to OSVR_ReturnCode return value to make sure it exists.

§ osvrClientGetSkeletonJointName()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonJointName	(	OSVR_Skeleton	skel,
		OSVR_SkeletonJointCount	boneId,
		char *	jointName,
		uint32_t	len
	)

Convert the jointId to the joint name.

Parameters

	skel	skeleton object
	jointId	An id that corresponds to this joint
[in,out]	jointName	A buffer that you allocate of appropriate size. Must be at least the length returned by osvrClientGetSkeletonStringJointNameLength. Will contain the null-terminated string name of the boneId.
	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

§ osvrClientGetSkeletonJointState()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonJointState	(	OSVR_Skeleton	skel,
		OSVR_SkeletonJointCount	jointId,
		OSVR_SkeletonJointState *	state
	)

Get skeleton joint state for given joint Id.

Parameters

skel	skeleton object
boneId	The joint Id corresponding to a joint in current skeleton
state	joint state containing jointId and tracker report

§ osvrClientGetSkeletonNumBones()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonNumBones	(	OSVR_Skeleton	skel,
		OSVR_SkeletonBoneCount *	numBones
	)

Get the number of bones available for a given skeleton.

Parameters

skel	skeleton object
numBones	on return contains a number of bones in current skeleton

§ osvrClientGetSkeletonNumJoints()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonNumJoints	(	OSVR_Skeleton	skel,
		OSVR_SkeletonJointCount *	numJoints
	)

Get the number of joints available for a given skeleton.

Parameters

skel	skeleton object
numJoints	on return contains a number of joints in current skeleton

§ osvrClientGetSkeletonStringBoneNameLength()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonStringBoneNameLength	(	OSVR_Skeleton	skel,
		OSVR_SkeletonBoneCount	boneId,
		uint32_t *	len
	)

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

Parameters

	skel	skeleton object
	boneId	associated id of the bone
[out]	len	The length of the string value, including null terminator. 0 if the parameter does not exist or is not a string.

§ osvrClientGetSkeletonStringJointNameLength()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetSkeletonStringJointNameLength	(	OSVR_Skeleton	skel,
		OSVR_SkeletonJointCount	jointId,
		uint32_t *	len
	)

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

Parameters

	skel	skeleton object
	jointId	associated id of the joint
[out]	len	The length of the string value, including null terminator. 0 if the parameter does not exist or is not a string.

§ osvrClientGetStringParameter()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetStringParameter	(	OSVR_ClientContext	ctx,
		const char	path[],
		char *	buf,
		size_t	len
	)

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.

§ osvrClientGetStringParameterLength()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetStringParameterLength	(	OSVR_ClientContext	ctx,
		const char	path[],
		size_t *	len
	)

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.

§ osvrClientGetViewerEyePose()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerEyeSurfaceDisplayInputIndex()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerEyeSurfaceProjectionClippingPlanes()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerEyeSurfaceProjectionMatrixd()

OSVR_CLIENTKIT_EXPORT 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)

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.

§ osvrClientGetViewerEyeSurfaceProjectionMatrixf()

OSVR_CLIENTKIT_EXPORT 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)

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.

§ osvrClientGetViewerEyeSurfaceRadialDistortion()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerEyeSurfaceRadialDistortionPriority()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerEyeViewMatrixd()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerEyeViewMatrixf()

OSVR_CLIENTKIT_EXPORT 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.

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.

§ osvrClientGetViewerPose()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetViewerPose	(	OSVR_DisplayConfig	disp,
		OSVR_ViewerCount	viewer,
		OSVR_Pose3 *	pose
	)

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.

§ osvrClientInit()

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

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

§ osvrClientInitHost()

OSVR_CLIENTKIT_EXPORT OSVR_ClientContext osvrClientInitHost	(	const char	applicationIdentifier[],
		const char	host[],
		uint32_t flags	OSVR_CPP_ONLY=0
	)

Initialize the library.

Parameters

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

Returns: Client context - will be needed for subsequent calls

§ osvrClientReleaseAutoStartedServer()

OSVR_CLIENTKIT_EXPORT void osvrClientReleaseAutoStartedServer ( )

Ensures any OSVR server-related resources in the client are released.

Call once per process.

§ osvrClientSetRoomRotationUsingHead()

OSVR_CLIENTKIT_EXPORT 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).

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.

§ osvrClientShutdown()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientShutdown ( OSVR_ClientContext ctx )

Shutdown the library.

Parameters

ctx	Client context

§ osvrClientUpdate()

OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientUpdate ( OSVR_ClientContext ctx )

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

Parameters

ctx	Client context

Modules

Namespaces

Classes

Typedefs

Enumerations

Functions

Display API

Skeleton API

State types

Report types

Detailed Description

Typedef Documentation

§ OSVR_ClientContext

§ OSVR_ClientInterface

§ OSVR_DisplayConfig

§ OSVR_IncrementalQuaternion

§ OSVR_SkeletonReport

Function Documentation

§ osvrClientAttemptServerAutoStart()

§ osvrClientCheckDisplayStartup()

§ osvrClientCheckStatus()

§ osvrClientClearRoomToWorldTransform()

§ osvrClientDoesViewerEyeSurfaceWantDistortion()

§ osvrClientFreeDisplay()

§ osvrClientFreeInterface()

§ osvrClientGetDisplay()

§ osvrClientGetDisplayDimensions()

§ osvrClientGetInterface()

§ osvrClientGetNumDisplayInputs()

§ osvrClientGetNumEyesForViewer()

§ osvrClientGetNumSurfacesForViewerEye()

§ osvrClientGetNumViewers()

§ osvrClientGetRelativeViewportForViewerEyeSurface()

§ osvrClientGetSkeletonAvailableBoneId()

§ osvrClientGetSkeletonAvailableJointId()

§ osvrClientGetSkeletonBoneId()

§ osvrClientGetSkeletonBoneName()

§ osvrClientGetSkeletonBoneState()

§ osvrClientGetSkeletonJointId()

§ osvrClientGetSkeletonJointName()

§ osvrClientGetSkeletonJointState()

§ osvrClientGetSkeletonNumBones()

§ osvrClientGetSkeletonNumJoints()

§ osvrClientGetSkeletonStringBoneNameLength()

§ osvrClientGetSkeletonStringJointNameLength()

§ osvrClientGetStringParameter()

§ osvrClientGetStringParameterLength()

§ osvrClientGetViewerEyePose()

§ osvrClientGetViewerEyeSurfaceDisplayInputIndex()

§ osvrClientGetViewerEyeSurfaceProjectionClippingPlanes()

§ osvrClientGetViewerEyeSurfaceProjectionMatrixd()

§ osvrClientGetViewerEyeSurfaceProjectionMatrixf()

§ osvrClientGetViewerEyeSurfaceRadialDistortion()

§ osvrClientGetViewerEyeSurfaceRadialDistortionPriority()

§ osvrClientGetViewerEyeViewMatrixd()

§ osvrClientGetViewerEyeViewMatrixf()

§ osvrClientGetViewerPose()

§ osvrClientInit()

§ osvrClientInitHost()

§ osvrClientReleaseAutoStartedServer()

§ osvrClientSetRoomRotationUsingHead()

§ osvrClientShutdown()

§ osvrClientUpdate()