1 /* 2 * OpenHMD - Free and Open Source API and drivers for immersive technology. 3 * Copyright (C) 2013 Fredrik Hultin. 4 * Copyright (C) 2013 Jakob Bornecrantz. 5 * Distributed under the Boost 1.0 licence, see LICENSE for full text. 6 */ 7 8 /** 9 * \file openhmd.h 10 * Main header for OpenHMD public API. 11 **/ 12 13 #ifndef OPENHMD_H 14 #define OPENHMD_H 15 16 #ifdef __cplusplus 17 extern "C" { 18 #endif 19 20 #ifdef _WIN32 21 #ifdef DLL_EXPORT 22 #define OHMD_APIENTRY __cdecl 23 #define OHMD_APIENTRYDLL __declspec( dllexport ) 24 #else 25 #ifdef OHMD_STATIC 26 #define OHMD_APIENTRY __cdecl 27 #define OHMD_APIENTRYDLL 28 #else 29 #define OHMD_APIENTRY __cdecl 30 #define OHMD_APIENTRYDLL __declspec( dllimport ) 31 #endif 32 #endif 33 #else 34 #define OHMD_APIENTRY 35 #define OHMD_APIENTRYDLL __attribute__((visibility("default"))) 36 #endif 37 38 /** Maximum length of a string, including termination, in OpenHMD. */ 39 #define OHMD_STR_SIZE 256 40 41 /** Return status codes, used for all functions that can return an error. */ 42 typedef enum { 43 OHMD_S_OK = 0, 44 OHMD_S_UNKNOWN_ERROR = -1, 45 OHMD_S_INVALID_PARAMETER = -2, 46 OHMD_S_UNSUPPORTED = -3, 47 OHMD_S_INVALID_OPERATION = -4, 48 49 /** OHMD_S_USER_RESERVED and below can be used for user purposes, such as errors within ohmd wrappers, etc. */ 50 OHMD_S_USER_RESERVED = -16384, 51 } ohmd_status; 52 53 /** A collection of string value information types, used for getting information with ohmd_list_gets(). */ 54 typedef enum { 55 OHMD_VENDOR = 0, 56 OHMD_PRODUCT = 1, 57 OHMD_PATH = 2, 58 } ohmd_string_value; 59 60 /** A collection of string descriptions, used for getting strings with ohmd_gets(). */ 61 typedef enum { 62 OHMD_GLSL_DISTORTION_VERT_SRC = 0, 63 OHMD_GLSL_DISTORTION_FRAG_SRC = 1, 64 OHMD_GLSL_330_DISTORTION_VERT_SRC = 2, 65 OHMD_GLSL_330_DISTORTION_FRAG_SRC = 3, 66 OHMD_GLSL_ES_DISTORTION_VERT_SRC = 4, 67 OHMD_GLSL_ES_DISTORTION_FRAG_SRC = 5, 68 } ohmd_string_description; 69 70 /** Standard controls. Note that this is not an index into the control state. 71 Use OHMD_CONTROL_TYPES to determine what function a control serves at a given index. */ 72 typedef enum { 73 OHMD_GENERIC = 0, 74 OHMD_TRIGGER = 1, 75 OHMD_TRIGGER_CLICK = 2, 76 OHMD_SQUEEZE = 3, 77 OHMD_MENU = 4, 78 OHMD_HOME = 5, 79 OHMD_ANALOG_X = 6, 80 OHMD_ANALOG_Y = 7, 81 OHMD_ANALOG_PRESS = 8, 82 OHMD_BUTTON_A = 9, 83 OHMD_BUTTON_B = 10, 84 OHMD_BUTTON_X = 11, 85 OHMD_BUTTON_Y = 12, 86 OHMD_VOLUME_PLUS = 13, 87 OHMD_VOLUME_MINUS = 14, 88 OHMD_MIC_MUTE = 15, 89 } ohmd_control_hint; 90 91 /** Control type. Indicates whether controls are digital or analog. */ 92 typedef enum { 93 OHMD_DIGITAL = 0, 94 OHMD_ANALOG = 1 95 } ohmd_control_type; 96 97 /** A collection of float value information types, used for getting and setting information with 98 ohmd_device_getf() and ohmd_device_setf(). */ 99 typedef enum { 100 /** float[4] (get): Absolute rotation of the device, in space, as a quaternion (x, y, z, w). */ 101 OHMD_ROTATION_QUAT = 1, 102 103 /** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the 104 left eye of the HMD. */ 105 OHMD_LEFT_EYE_GL_MODELVIEW_MATRIX = 2, 106 /** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a modelview matrix for the 107 right eye of the HMD. */ 108 OHMD_RIGHT_EYE_GL_MODELVIEW_MATRIX = 3, 109 110 /** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the 111 left eye of the HMD. */ 112 OHMD_LEFT_EYE_GL_PROJECTION_MATRIX = 4, 113 /** float[16] (get): A "ready to use" OpenGL style 4x4 matrix with a projection matrix for the 114 right eye of the HMD. */ 115 OHMD_RIGHT_EYE_GL_PROJECTION_MATRIX = 5, 116 117 /** float[3] (get): A 3-D vector representing the absolute position of the device, in space. */ 118 OHMD_POSITION_VECTOR = 6, 119 120 /** float[1] (get): Physical width of the device screen in metres. */ 121 OHMD_SCREEN_HORIZONTAL_SIZE = 7, 122 /** float[1] (get): Physical height of the device screen in metres. */ 123 OHMD_SCREEN_VERTICAL_SIZE = 8, 124 125 /** float[1] (get): Physical separation of the device lenses in metres. */ 126 OHMD_LENS_HORIZONTAL_SEPARATION = 9, 127 /** float[1] (get): Physical vertical position of the lenses in metres. */ 128 OHMD_LENS_VERTICAL_POSITION = 10, 129 130 /** float[1] (get): Physical field of view for the left eye in degrees. */ 131 OHMD_LEFT_EYE_FOV = 11, 132 /** float[1] (get): Physical display aspect ratio for the left eye screen. */ 133 OHMD_LEFT_EYE_ASPECT_RATIO = 12, 134 /** float[1] (get): Physical field of view for the left right in degrees. */ 135 OHMD_RIGHT_EYE_FOV = 13, 136 /** float[1] (get): Physical display aspect ratio for the right eye screen. */ 137 OHMD_RIGHT_EYE_ASPECT_RATIO = 14, 138 139 /** float[1] (get, set): Physical interpupillary distance of the user in metres. */ 140 OHMD_EYE_IPD = 15, 141 142 /** float[1] (get, set): Z-far value for the projection matrix calculations (i.e. drawing distance). */ 143 OHMD_PROJECTION_ZFAR = 16, 144 /** float[1] (get, set): Z-near value for the projection matrix calculations (i.e. close clipping distance). */ 145 OHMD_PROJECTION_ZNEAR = 17, 146 147 /** float[6] (get): Device specific distortion value. */ 148 OHMD_DISTORTION_K = 18, 149 150 /** 151 * float[10] (set): Perform sensor fusion on values from external sensors. 152 * 153 * Values are: dt (time since last update in seconds) X, Y, Z gyro, X, Y, Z accelerometer and X, Y, Z magnetometer. 154 **/ 155 OHMD_EXTERNAL_SENSOR_FUSION = 19, 156 157 /** float[4] (get): Universal shader distortion coefficients (PanoTools model <a,b,c,d>. */ 158 OHMD_UNIVERSAL_DISTORTION_K = 20, 159 160 /** float[3] (get): Universal shader aberration coefficients (post warp scaling <r,g,b>. */ 161 OHMD_UNIVERSAL_ABERRATION_K = 21, 162 163 /** float[OHMD_CONTROL_COUNT] (get): Get the state of the device's controls. */ 164 OHMD_CONTROLS_STATE = 22, 165 166 } ohmd_float_value; 167 168 /** A collection of int value information types used for getting information with ohmd_device_geti(). */ 169 typedef enum { 170 /** int[1] (get, ohmd_geti()): Physical horizontal resolution of the device screen. */ 171 OHMD_SCREEN_HORIZONTAL_RESOLUTION = 0, 172 /** int[1] (get, ohmd_geti()): Physical vertical resolution of the device screen. */ 173 OHMD_SCREEN_VERTICAL_RESOLUTION = 1, 174 175 /** int[1] (get, ohmd_geti()/ohmd_list_geti()): Gets the class of the device. See: ohmd_device_class. */ 176 OHMD_DEVICE_CLASS = 2, 177 /** int[1] (get, ohmd_geti()/ohmd_list_geti()): Gets the flags of the device. See: ohmd_device_flags. */ 178 OHMD_DEVICE_FLAGS = 3, 179 180 /** int[1] (get, ohmd_geti()): Get the number of analog and digital controls of the device. */ 181 OHMD_CONTROL_COUNT = 4, 182 183 /** int[OHMD_CONTROL_COUNT] (get, ohmd_geti()): Get what function controls serve. */ 184 OHMD_CONTROLS_HINTS = 5, 185 186 /** int[OHMD_CONTROL_COUNT] (get, ohmd_geti()): Get whether controls are digital or analog. */ 187 OHMD_CONTROLS_TYPES = 6, 188 } ohmd_int_value; 189 190 /** A collection of data information types used for setting information with ohmd_set_data(). */ 191 typedef enum { 192 /** void* (set): Set void* data for use in the internal drivers. */ 193 OHMD_DRIVER_DATA = 0, 194 /** 195 * ohmd_device_properties* (set): 196 * Set the device properties based on the ohmd_device_properties struct for use in the internal drivers. 197 * 198 * This can be used to fill in information about the device internally, such as Android, or for setting profiles. 199 **/ 200 OHMD_DRIVER_PROPERTIES = 1, 201 } ohmd_data_value; 202 203 typedef enum { 204 /** int[1] (set, default: 1): Set this to 0 to prevent OpenHMD from creating background threads to do automatic device ticking. 205 Call ohmd_update(); must be called frequently, at least 10 times per second, if the background threads are disabled. */ 206 OHMD_IDS_AUTOMATIC_UPDATE = 0, 207 } ohmd_int_settings; 208 209 /** Device classes. */ 210 typedef enum 211 { 212 /** HMD device. */ 213 OHMD_DEVICE_CLASS_HMD = 0, 214 /** Controller device. */ 215 OHMD_DEVICE_CLASS_CONTROLLER = 1, 216 /** Generic tracker device. */ 217 OHMD_DEVICE_CLASS_GENERIC_TRACKER = 2, 218 } ohmd_device_class; 219 220 /** Device flags. */ 221 typedef enum 222 { 223 /** Device is a null (dummy) device. */ 224 OHMD_DEVICE_FLAGS_NULL_DEVICE = 1, 225 OHMD_DEVICE_FLAGS_POSITIONAL_TRACKING = 2, 226 OHMD_DEVICE_FLAGS_ROTATIONAL_TRACKING = 4, 227 OHMD_DEVICE_FLAGS_LEFT_CONTROLLER = 8, 228 OHMD_DEVICE_FLAGS_RIGHT_CONTROLLER = 16, 229 } ohmd_device_flags; 230 231 /** An opaque pointer to a context structure. */ 232 typedef struct ohmd_context ohmd_context; 233 234 /** An opaque pointer to a structure representing a device, such as an HMD. */ 235 typedef struct ohmd_device ohmd_device; 236 237 /** An opaque pointer to a structure representing arguments for a device. */ 238 typedef struct ohmd_device_settings ohmd_device_settings; 239 240 /** 241 * Create an OpenHMD context. 242 * 243 * @return a pointer to an allocated ohmd_context on success or NULL if it fails. 244 **/ 245 OHMD_APIENTRYDLL ohmd_context* OHMD_APIENTRY ohmd_ctx_create(void); 246 247 /** 248 * Destroy an OpenHMD context. 249 * 250 * ohmd_ctx_destroy de-initializes and de-allocates an OpenHMD context allocated with ohmd_ctx_create. 251 * All devices associated with the context are automatically closed. 252 * 253 * @param ctx The context to destroy. 254 **/ 255 OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_ctx_destroy(ohmd_context* ctx); 256 257 /** 258 * Get the last error as a human readable string. 259 * 260 * If a function taking a context as an argument (ohmd_context "methods") returns non-successfully, 261 * a human readable error message describing what went wrong can be retrieved with this function. 262 * 263 * @param ctx The context to retrieve the error message from. 264 * @return a pointer to the error message. 265 **/ 266 OHMD_APIENTRYDLL const char* OHMD_APIENTRY ohmd_ctx_get_error(ohmd_context* ctx); 267 268 /** 269 * Update a context. 270 * 271 * Update the values for the devices handled by a context. 272 * 273 * If background threads are disabled, this performs tasks like pumping events from the device. The exact details 274 * are up to the driver but try to call it quite frequently. 275 * Once per frame in a "game loop" should be sufficient. 276 * If OpenHMD is handled in a background thread in your program, calling ohmd_ctx_update and then sleeping for 10-20 ms 277 * is recommended. 278 * 279 * @param ctx The context that needs updating. 280 **/ 281 OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_ctx_update(ohmd_context* ctx); 282 283 /** 284 * Probe for devices. 285 * 286 * Probes for and enumerates supported devices attached to the system. 287 * 288 * @param ctx A context with no currently open devices. 289 * @return the number of devices found on the system. 290 **/ 291 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_ctx_probe(ohmd_context* ctx); 292 293 /** 294 * Get string from openhmd. 295 * 296 * Gets a string from OpenHMD. This is where non-device specific strings reside. 297 * This is where the distortion shader sources can be retrieved. 298 * 299 * @param type The name of the string to fetch. One of OHMD_GLSL_DISTORTION_FRAG_SRC, and OHMD_GLSL_DISTORTION_FRAG_SRC. 300 * @param out The location to return a const char* 301 * @return 0 on success, <0 on failure. 302 **/ 303 OHMD_APIENTRYDLL int ohmd_gets(ohmd_string_description type, const char** out); 304 305 /** 306 * Get device description from enumeration list index. 307 * 308 * Gets a human readable device description string from a zero indexed enumeration index 309 * between 0 and (max - 1), where max is the number ohmd_ctx_probe returned 310 * (i.e. if ohmd_ctx_probe returns 3, valid indices are 0, 1 and 2). 311 * The function can return three types of data. The vendor name, the product name and 312 * a driver specific path where the device is attached. 313 * 314 * ohmd_ctx_probe must be called before calling ohmd_list_gets. 315 * 316 * @param ctx A (probed) context. 317 * @param index An index, between 0 and the value returned from ohmd_ctx_probe. 318 * @param type The type of data to fetch. One of OHMD_VENDOR, OHMD_PRODUCT and OHMD_PATH. 319 * @return a string with a human readable device name. 320 **/ 321 OHMD_APIENTRYDLL const char* OHMD_APIENTRY ohmd_list_gets(ohmd_context* ctx, int index, ohmd_string_value type); 322 323 324 /** 325 * Get integer value from enumeration list index. 326 * 327 * 328 * 329 * ohmd_ctx_probe must be called before calling ohmd_list_gets. 330 * 331 * @param ctx A (probed) context. 332 * @param index An index, between 0 and the value returned from ohmd_ctx_probe. 333 * @param type What type of value to retrieve, ohmd_int_value section for more information. 334 * @return 0 on success, <0 on failure. 335 **/ 336 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_list_geti(ohmd_context* ctx, int index, ohmd_int_value type, int* out); 337 338 /** 339 * Open a device. 340 * 341 * Opens a device from a zero indexed enumeration index between 0 and (max - 1) 342 * where max is the number ohmd_ctx_probe returned (i.e. if ohmd_ctx_probe returns 3, 343 * valid indices are 0, 1 and 2). 344 * 345 * ohmd_ctx_probe must be called before calling ohmd_list_open_device. 346 * 347 * @param ctx A (probed) context. 348 * @param index An index, between 0 and the value returned from ohmd_ctx_probe. 349 * @return a pointer to an ohmd_device, which represents a hardware device, such as an HMD. 350 **/ 351 OHMD_APIENTRYDLL ohmd_device* OHMD_APIENTRY ohmd_list_open_device(ohmd_context* ctx, int index); 352 353 /** 354 * Open a device with additional settings provided. 355 * 356 * Opens a device from a zero indexed enumeration index between 0 and (max - 1) 357 * where max is the number ohmd_ctx_probe returned (i.e. if ohmd_ctx_probe returns 3, 358 * valid indices are 0, 1 and 2). 359 * 360 * ohmd_ctx_probe must be called before calling ohmd_list_open_device. 361 * 362 * @param ctx A (probed) context. 363 * @param index An index, between 0 and the value returned from ohmd_ctx_probe. 364 * @param settings A pointer to a device settings struct. 365 * @return a pointer to an ohmd_device, which represents a hardware device, such as an HMD. 366 **/ 367 OHMD_APIENTRYDLL ohmd_device* OHMD_APIENTRY ohmd_list_open_device_s(ohmd_context* ctx, int index, ohmd_device_settings* settings); 368 369 /** 370 * Specify int settings in a device settings struct. 371 * 372 * @param settings The device settings struct to set values to. 373 * @param key The specefic setting you wish to set. 374 * @param value A pointer to an int or int array (containing the expected number of elements) with the value(s) you wish to set. 375 **/ 376 OHMD_APIENTRYDLL ohmd_status OHMD_APIENTRY ohmd_device_settings_seti(ohmd_device_settings* settings, ohmd_int_settings key, const int* val); 377 378 /** 379 * Create a device settings instance. 380 * 381 * @param ctx A pointer to a valid ohmd_context. 382 * @return a pointer to an allocated ohmd_context on success or NULL if it fails. 383 **/ 384 OHMD_APIENTRYDLL ohmd_device_settings* OHMD_APIENTRY ohmd_device_settings_create(ohmd_context* ctx); 385 386 /** 387 * Destroy a device settings instance. 388 * 389 * @param ctx The device settings instance to destroy. 390 **/ 391 OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_device_settings_destroy(ohmd_device_settings* settings); 392 393 /** 394 * Close a device. 395 * 396 * Closes a device opened by ohmd_list_open_device. Note that ohmd_ctx_destroy automatically closes any open devices 397 * associated with the context being destroyed. 398 * 399 * @param device The open device. 400 * @return 0 on success, <0 on failure. 401 **/ 402 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_close_device(ohmd_device* device); 403 404 /** 405 * Get a floating point value from a device. 406 * 407 * 408 * @param device An open device to retrieve the value from. 409 * @param type What type of value to retrieve, see ohmd_float_value section for more information. 410 * @param[out] out A pointer to a float, or float array where the retrieved value should be written. 411 * @return 0 on success, <0 on failure. 412 **/ 413 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_getf(ohmd_device* device, ohmd_float_value type, float* out); 414 415 /** 416 * Set a floating point value for a device. 417 * 418 * @param device An open device to set the value in. 419 * @param type What type of value to set, see ohmd_float_value section for more information. 420 * @param in A pointer to a float, or float array where the new value is stored. 421 * @return 0 on success, <0 on failure. 422 **/ 423 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_setf(ohmd_device* device, ohmd_float_value type, const float* in); 424 425 /** 426 * Get an integer value from a device. 427 * 428 * @param device An open device to retrieve the value from. 429 * @param type What type of value to retrieve, ohmd_int_value section for more information. 430 * @param[out] out A pointer to an integer, or integer array where the retrieved value should be written. 431 * @return 0 on success, <0 on failure. 432 **/ 433 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_geti(ohmd_device* device, ohmd_int_value type, int* out); 434 435 /** 436 * Set an integer value for a device. 437 * 438 * @param device An open device to set the value in. 439 * @param type What type of value to set, see ohmd_float_value section for more information. 440 * @param in A pointer to a int, or int array where the new value is stored. 441 * @return 0 on success, <0 on failure. 442 **/ 443 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_seti(ohmd_device* device, ohmd_int_value type, const int* in); 444 445 /** 446 * Set an void* data value for a device. 447 * 448 * @param device An open device to set the value in. 449 * @param type What type of value to set, see ohmd_float_value section for more information. 450 * @param in A pointer to the void* casted object. 451 * @return 0 on success, <0 on failure. 452 **/ 453 OHMD_APIENTRYDLL int OHMD_APIENTRY ohmd_device_set_data(ohmd_device* device, ohmd_data_value type, const void* in); 454 455 /** 456 * Get the library version. 457 * 458 * @param major Major version. 459 * @param minor Minor version. 460 * @param patch Patch version. 461 **/ 462 OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_get_version(int* out_major, int* out_minor, int* out_patch); 463 464 /** 465 * Check that the library is compatible with the required version. 466 * 467 * @param major Required major version. 468 * @param minor Required minor version. 469 * @param patch Required patch version. 470 * @return OMHD_S_OK if the version is compatible or OHMD_S_UNSUPPORTED if it's not. 471 **/ 472 OHMD_APIENTRYDLL ohmd_status OHMD_APIENTRY ohmd_require_version(int major, int minor, int patch); 473 474 /** 475 * Sleep for the given amount of seconds. 476 * 477 * @param time Time to sleep in seconds. 478 **/ 479 OHMD_APIENTRYDLL void OHMD_APIENTRY ohmd_sleep(double time); 480 481 #ifdef __cplusplus 482 } 483 #endif 484 485 #endif 486