OpenHMD
Macros | Typedefs | Enumerations | Functions
openhmd.h File Reference

Go to the source code of this file.

Macros

#define OHMD_APIENTRY
 
#define OHMD_STR_SIZE   256
 

Typedefs

typedef struct ohmd_context ohmd_context
 
typedef struct ohmd_device ohmd_device
 

Enumerations

enum  ohmd_string_value {
  OHMD_VENDOR = 0,
  OHMD_PRODUCT = 1,
  OHMD_PATH = 2
}
 
enum  ohmd_float_value {
  OHMD_ROTATION_QUAT = 1,
  OHMD_LEFT_EYE_GL_MODELVIEW_MATRIX = 2,
  OHMD_RIGHT_EYE_GL_MODELVIEW_MATRIX = 3,
  OHMD_LEFT_EYE_GL_PROJECTION_MATRIX = 4,
  OHMD_RIGHT_EYE_GL_PROJECTION_MATRIX = 5,
  OHMD_POSITION_VECTOR = 6,
  OHMD_SCREEN_HORIZONTAL_SIZE = 7,
  OHMD_SCREEN_VERTICAL_SIZE = 8,
  OHMD_LENS_HORIZONTAL_SEPARATION = 9,
  OHMD_LENS_VERTICAL_POSITION = 10,
  OHMD_LEFT_EYE_FOV = 11,
  OHMD_LEFT_EYE_ASPECT_RATIO = 12,
  OHMD_RIGHT_EYE_FOV = 13,
  OHMD_RIGHT_EYE_ASPECT_RATIO = 14,
  OHMD_EYE_IPD = 15,
  OHMD_PROJECTION_ZFAR = 16,
  OHMD_PROJECTION_ZNEAR = 17,
  OHMD_DISTORTION_K = 18
}
 
enum  ohmd_int_value {
  OHMD_SCREEN_HORIZONTAL_RESOLUTION = 0,
  OHMD_SCREEN_VERTICAL_RESOLUTION = 1
}
 

Functions

OHMD_APIENTRY ohmd_contextohmd_ctx_create ()
 
OHMD_APIENTRY void ohmd_ctx_destroy (ohmd_context *ctx)
 
OHMD_APIENTRY const char * ohmd_ctx_get_error (ohmd_context *ctx)
 
OHMD_APIENTRY void ohmd_ctx_update (ohmd_context *ctx)
 
OHMD_APIENTRY int ohmd_ctx_probe (ohmd_context *ctx)
 
OHMD_APIENTRY const char * ohmd_list_gets (ohmd_context *ctx, int index, ohmd_string_value type)
 
OHMD_APIENTRY ohmd_deviceohmd_list_open_device (ohmd_context *ctx, int index)
 
OHMD_APIENTRY int ohmd_device_getf (ohmd_device *device, ohmd_float_value type, float *out)
 
OHMD_APIENTRY int ohmd_device_setf (ohmd_device *device, ohmd_float_value type, float *in)
 
OHMD_APIENTRY int ohmd_device_geti (ohmd_device *device, ohmd_int_value type, int *out)
 

Detailed Description

Main header for OpenHMD public API.

Macro Definition Documentation

#define OHMD_STR_SIZE   256

Maximum length of a string, including termination, in OpenHMD.

Typedef Documentation

typedef struct ohmd_context ohmd_context

An opaque pointer to a context structure.

typedef struct ohmd_device ohmd_device

An opaque pointer to a structure representing a device, such as an HMD.

Enumeration Type Documentation

A collection of float value information types, used for getting and setting information with ohmd_device_getf() and ohmd_device_setf().

Enumerator
OHMD_ROTATION_QUAT 

float[4] (get): Absolute rotation of the device, in space, as a quaternion (x, y, z, w).

OHMD_LEFT_EYE_GL_MODELVIEW_MATRIX 

float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the left eye of the HMD.

OHMD_RIGHT_EYE_GL_MODELVIEW_MATRIX 

float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the right eye of the HMD.

OHMD_LEFT_EYE_GL_PROJECTION_MATRIX 

float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the left eye of the HMD.

OHMD_RIGHT_EYE_GL_PROJECTION_MATRIX 

float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the right eye of the HMD.

OHMD_POSITION_VECTOR 

float[3] (get): A 3-D vector representing the absolute position of the device, in space.

OHMD_SCREEN_HORIZONTAL_SIZE 

float[1] (get): Physical width of the device screen in metres.

OHMD_SCREEN_VERTICAL_SIZE 

float[1] (get): Physical height of the device screen in metres.

OHMD_LENS_HORIZONTAL_SEPARATION 

float[1] (get): Physical separation of the device lenses in metres.

OHMD_LENS_VERTICAL_POSITION 

float[1] (get): Physical vertical position of the lenses in metres.

OHMD_LEFT_EYE_FOV 

float[1] (get): Physical field of view for the left eye in degrees.

OHMD_LEFT_EYE_ASPECT_RATIO 

float[1] (get): Physical display aspect ratio for the left eye screen.

OHMD_RIGHT_EYE_FOV 

float[1] (get): Physical field of view for the left right in degrees.

OHMD_RIGHT_EYE_ASPECT_RATIO 

float[1] (get): Physical display aspect ratio for the right eye screen.

OHMD_EYE_IPD 

float[1] (get, set): Physical interpupillary distance of the user in metres.

OHMD_PROJECTION_ZFAR 

float[1] (get, set): Z-far value for the projection matrix calculations (i.e. drawing distance).

OHMD_PROJECTION_ZNEAR 

float[1] (get, set): Z-near value for the projection matrix calculations (i.e. close clipping distance).

OHMD_DISTORTION_K 

float[6] (get): Device specific distortion value.

A collection of int value information types used for getting information with ohmd_device_geti().

Enumerator
OHMD_SCREEN_HORIZONTAL_RESOLUTION 

int[1] (get): Physical horizontal resolution of the device screen.

OHMD_SCREEN_VERTICAL_RESOLUTION 

int[1] (get): Physical vertical resolution of the device screen.

A collection of string value information types, used for getting information with ohmd_list_gets().

Function Documentation

OHMD_APIENTRY ohmd_context* ohmd_ctx_create ( )

Create an OpenHMD context.

Returns
a pointer to an allocated ohmd_context on success or NULL if it fails.
OHMD_APIENTRY void ohmd_ctx_destroy ( ohmd_context ctx)

Destroy an OpenHMD context.

ohmd_ctx_destroy de-initializes and de-allocates an OpenHMD context allocated with ohmd_ctx_create.

Parameters
ctxThe context to destroy.
OHMD_APIENTRY const char* ohmd_ctx_get_error ( ohmd_context ctx)

Get the last error as a human readable string.

If a function taking a context as an argument (ohmd_context "methods") returns non-successfully, a human readable error message describing what went wrong can be retrieved with this function.

Parameters
ctxThe context to retrieve the error message from.
Returns
a pointer to the error message.
OHMD_APIENTRY int ohmd_ctx_probe ( ohmd_context ctx)

Probe for devices.

Probes for and enumerates supported devices attached to the system.

Parameters
ctxA context with no currently open devices.
Returns
the number of devices found on the system.
OHMD_APIENTRY void ohmd_ctx_update ( ohmd_context ctx)

Update a context.

Performs tasks like pumping events from the device. The exact details are up to the driver but try to call it quite frequently. Once per frame in a "game loop" should be sufficient. If OpenHMD is handled in a background thread, calling ohmd_ctx_update and then sleeping for 10-20 ms is recommended.

Parameters
ctxThe context that needs updating.
OHMD_APIENTRY int ohmd_device_getf ( ohmd_device device,
ohmd_float_value  type,
float *  out 
)

Get a floating point value from a device.

Parameters
deviceAn open device to retrieve the value from.
typeWhat type of value to retrieve, see ohmd_float_value section for more information.
[out]outA pointer to a float, or float array where the retrieved value should be written.
Returns
0 on success, <0 on failure.
OHMD_APIENTRY int ohmd_device_geti ( ohmd_device device,
ohmd_int_value  type,
int *  out 
)

Get an integer value from a device.

Parameters
deviceAn open device to retrieve the value from.
typeWhat type of value to retrieve, ohmd_int_value section for more information.
[out]outA pointer to an integer, or integer array where the retrieved value should be written.
Returns
0 on success, <0 on failure.
OHMD_APIENTRY int ohmd_device_setf ( ohmd_device device,
ohmd_float_value  type,
float *  in 
)

Set a floating point value for a device.

Parameters
deviceAn open device to set the value in.
typeWhat type of value to set, see ohmd_float_value section for more information.
inA pointer to a float, or float array where the new value is stored.
Returns
0 on success, <0 on failure.
OHMD_APIENTRY const char* ohmd_list_gets ( ohmd_context ctx,
int  index,
ohmd_string_value  type 
)

Get device description from enumeration list index.

Gets a human readable device description string from a zero indexed enumeration index between 0 and (max - 1), where max is the number ohmd_ctx_probe returned (i.e. if ohmd_ctx_probe returns 3, valid indices are 0, 1 and 2). The function can return three types of data. The vendor name, the product name and a driver specific path where the device is attached.

ohmd_ctx_probe must be called before calling ohmd_list_gets.

Parameters
ctxA (probed) context.
indexAn index, between 0 and the value returned from ohmd_ctx_probe.
typeThe type of data to fetch. One of OHMD_VENDOR, OHMD_PRODUCT and OHMD_PATH.
Returns
a string with a human readable device name.
OHMD_APIENTRY ohmd_device* ohmd_list_open_device ( ohmd_context ctx,
int  index 
)

Open a device.

Opens a device from a zero indexed enumeration index between 0 and (max - 1) where max is the number ohmd_ctx_probe returned (i.e. if ohmd_ctx_probe returns 3, valid indices are 0, 1 and 2).

ohmd_ctx_probe must be called before calling ohmd_list_open_device.

Parameters
ctxA (probed) context.
indexAn index, between 0 and the value returned from ohmd_ctx_probe.
Returns
a pointer to an ohmd_device, which represents a hardware device, such as an HMD.