DisplayC.h (20868B)
1 /** @file 2 @brief Header 3 4 Must be c-safe! 5 6 @date 2015 7 8 @author 9 Sensics, Inc. 10 <http://sensics.com/osvr> 11 */ 12 13 /* 14 // Copyright 2015 Sensics, Inc. 15 // 16 // Licensed under the Apache License, Version 2.0 (the "License"); 17 // you may not use this file except in compliance with the License. 18 // You may obtain a copy of the License at 19 // 20 // http://www.apache.org/licenses/LICENSE-2.0 21 // 22 // Unless required by applicable law or agreed to in writing, software 23 // distributed under the License is distributed on an "AS IS" BASIS, 24 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 // See the License for the specific language governing permissions and 26 // limitations under the License. 27 */ 28 29 #ifndef INCLUDED_DisplayC_h_GUID_8658EDC9_32A2_49A2_5F5C_10F67852AE74 30 #define INCLUDED_DisplayC_h_GUID_8658EDC9_32A2_49A2_5F5C_10F67852AE74 31 32 /* Internal Includes */ 33 #include <osvr/ClientKit/Export.h> 34 #include <osvr/Util/APIBaseC.h> 35 #include <osvr/Util/ReturnCodesC.h> 36 #include <osvr/Util/ClientOpaqueTypesC.h> 37 #include <osvr/Util/RenderingTypesC.h> 38 #include <osvr/Util/MatrixConventionsC.h> 39 #include <osvr/Util/Pose3C.h> 40 #include <osvr/Util/BoolC.h> 41 #include <osvr/Util/RadialDistortionParametersC.h> 42 43 /* Library/third-party includes */ 44 /* none */ 45 46 /* Standard includes */ 47 /* none */ 48 49 OSVR_EXTERN_C_BEGIN 50 /** @addtogroup ClientKit 51 @{ 52 @name Display API 53 @{ 54 */ 55 56 /** @brief Opaque type of a display configuration. */ 57 typedef struct OSVR_DisplayConfigObject* OSVR_DisplayConfig; 58 59 /** @brief Allocates a display configuration object populated with data from the 60 OSVR system. 61 62 Before this call will succeed, your application will need to be correctly 63 and fully connected to an OSVR server. You may consider putting this call in 64 a loop alternating with osvrClientUpdate() until this call succeeds. 65 66 Data provided by a display configuration object: 67 68 - The logical display topology (number and relationship of viewers, eyes, 69 and surfaces), which remains constant throughout the life of the 70 configuration object. (A method of notification of change here is TBD). 71 - Pose data for viewers (not required for rendering) and pose/view data for 72 eyes (used for rendering) which is based on tracker data: if used, these 73 should be queried every frame. 74 - Projection matrix data for surfaces, which while in current practice may 75 be relatively unchanging, we are not guaranteeing them to be constant: 76 these should be queried every frame. 77 - Video-input-relative viewport size/location for a surface: would like this 78 to be variable, but probably not feasible. If you have input, please 79 comment on the dev mailing list. 80 - Per-surface distortion strategy priorities/availabilities: constant. Note 81 the following, though... 82 - Per-surface distortion strategy parameters: variable, request each frame. 83 (Could make constant with a notification if needed?) 84 85 Important note: While most of this data is immediately available if you are 86 successful in getting a display config object, the pose-based data (viewer 87 pose, eye pose, eye view matrix) needs tracker state, so at least one (and in 88 practice, typically more) osvrClientUpdate() must be performed before a new 89 tracker report is available to populate that state. See 90 osvrClientCheckDisplayStartup() to query if all startup data is available. 91 92 @todo Decide if relative viewport should be constant in a display config, 93 and update docs accordingly. 94 95 @todo Decide if distortion params should be constant in a display config, 96 and update docs accordingly. 97 98 @return OSVR_RETURN_FAILURE if invalid parameters were passed or some other 99 error occurred, in which case the output argument is unmodified. 100 */ 101 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 102 osvrClientGetDisplay(OSVR_ClientContext ctx, OSVR_DisplayConfig* disp); 103 104 /** @brief Frees a display configuration object. The corresponding context must 105 still be open. 106 107 If you fail to call this, it will be automatically called as part of 108 clean-up when the corresponding context is closed. 109 110 @return OSVR_RETURN_FAILURE if a null config was passed, or if the given 111 display object was already freed. 112 */ 113 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 114 osvrClientFreeDisplay(OSVR_DisplayConfig disp); 115 116 /** @brief Checks to see if a display is fully configured and ready, including 117 having received its first pose update. 118 119 Once this first succeeds, it will continue to succeed for the lifetime of 120 the display config object, so it is not necessary to keep calling once you 121 get a successful result. 122 123 @return OSVR_RETURN_FAILURE if a null config was passed, or if the given 124 display config object was otherwise not ready for full use. 125 */ 126 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 127 osvrClientCheckDisplayStartup(OSVR_DisplayConfig disp); 128 129 /** @brief A display config can have one or more display inputs to pass pixels 130 over (HDMI/DVI connections, etc): retrieve the number of display inputs in 131 the current configuration. 132 133 @param disp Display config object. 134 @param[out] numDisplayInputs Number of display inputs in the logical display 135 topology, **constant** throughout the active, valid lifetime of a display 136 config object. 137 138 @sa OSVR_DisplayInputCount 139 140 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in 141 which case the output argument is unmodified. 142 */ 143 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetNumDisplayInputs( 144 OSVR_DisplayConfig disp, OSVR_DisplayInputCount* numDisplayInputs); 145 146 /** @brief Retrieve the pixel dimensions of a given display input for a display 147 config 148 149 @param disp Display config object. 150 @param displayInputIndex The zero-based index of the display input. 151 @param[out] width Width (in pixels) of the display input. 152 @param[out] height Height (in pixels) of the display input. 153 154 The out parameters are **constant** throughout the active, valid lifetime of 155 a display config object. 156 157 @sa OSVR_DisplayDimension 158 159 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in 160 which case the output arguments are unmodified. 161 */ 162 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetDisplayDimensions( 163 OSVR_DisplayConfig disp, OSVR_DisplayInputCount displayInputIndex, 164 OSVR_DisplayDimension* width, OSVR_DisplayDimension* height); 165 166 /** @brief A display config can have one (or theoretically more) viewers: 167 retrieve the viewer count. 168 169 @param disp Display config object. 170 @param[out] viewers Number of viewers in the logical display topology, 171 **constant** throughout the active, valid lifetime of a display config 172 object. 173 174 @sa OSVR_ViewerCount 175 176 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 177 the output argument is unmodified. 178 */ 179 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 180 osvrClientGetNumViewers(OSVR_DisplayConfig disp, OSVR_ViewerCount* viewers); 181 182 /** @brief Get the pose of a viewer in a display config. 183 184 Note that there may not necessarily be any surfaces rendered from this pose 185 (it's the unused "center" eye in a stereo configuration, for instance) so 186 only use this if it makes integration into your engine or existing 187 applications (not originally designed for stereo) easier. 188 189 Will only succeed if osvrClientCheckDisplayStartup() succeeds. 190 191 @return OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was 192 yet available, in which case the pose argument is unmodified. 193 */ 194 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetViewerPose( 195 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_Pose3* pose); 196 197 /** @brief Each viewer in a display config can have one or more "eyes" which 198 have a substantially similar pose: get the count. 199 200 @param disp Display config object. 201 @param viewer Viewer ID 202 @param[out] eyes Number of eyes for this viewer in the logical display 203 topology, **constant** throughout the active, valid lifetime of a display 204 config object 205 206 @sa OSVR_EyeCount 207 208 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 209 the output argument is unmodified. 210 */ 211 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetNumEyesForViewer( 212 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount* eyes); 213 214 /** @brief Get the "viewpoint" for the given eye of a viewer in a display 215 config. 216 217 Will only succeed if osvrClientCheckDisplayStartup() succeeds. 218 219 @param disp Display config object 220 @param viewer Viewer ID 221 @param eye Eye ID 222 @param[out] pose Room-space pose (not relative to pose of the viewer) 223 224 @return OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was 225 yet available, in which case the pose argument is unmodified. 226 */ 227 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 228 osvrClientGetViewerEyePose(OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, 229 OSVR_EyeCount eye, OSVR_Pose3* pose); 230 231 /** @brief Get the view matrix (inverse of pose) for the given eye of a 232 viewer in a display config - matrix of **doubles**. 233 234 Will only succeed if osvrClientCheckDisplayStartup() succeeds. 235 236 @param disp Display config object 237 @param viewer Viewer ID 238 @param eye Eye ID 239 @param flags Bitwise OR of matrix convention flags (see @ref MatrixFlags) 240 @param[out] mat Pass a double[::OSVR_MATRIX_SIZE] to get the transformation 241 matrix from room space to eye space (not relative to pose of the viewer) 242 243 @return OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was 244 yet available, in which case the output argument is unmodified. 245 */ 246 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetViewerEyeViewMatrixd( 247 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 248 OSVR_MatrixConventions flags, double* mat); 249 250 /** @brief Get the view matrix (inverse of pose) for the given eye of a 251 viewer in a display config - matrix of **floats**. 252 253 Will only succeed if osvrClientCheckDisplayStartup() succeeds. 254 255 @param disp Display config object 256 @param viewer Viewer ID 257 @param eye Eye ID 258 @param flags Bitwise OR of matrix convention flags (see @ref MatrixFlags) 259 @param[out] mat Pass a float[::OSVR_MATRIX_SIZE] to get the transformation 260 matrix from room space to eye space (not relative to pose of the viewer) 261 262 @return OSVR_RETURN_FAILURE if invalid parameters were passed or no pose was 263 yet available, in which case the output argument is unmodified. 264 */ 265 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetViewerEyeViewMatrixf( 266 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 267 OSVR_MatrixConventions flags, float* mat); 268 269 /** @brief Each eye of each viewer in a display config has one or more surfaces 270 (aka "screens") on which content should be rendered. 271 272 @param disp Display config object 273 @param viewer Viewer ID 274 @param eye Eye ID 275 @param[out] surfaces Number of surfaces (numbered [0, surfaces - 1]) for the 276 given viewer and eye. **Constant** throughout the active, valid lifetime of 277 a display config object. 278 279 @sa OSVR_SurfaceCount 280 281 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 282 the output argument is unmodified. 283 */ 284 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode osvrClientGetNumSurfacesForViewerEye( 285 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 286 OSVR_SurfaceCount* surfaces); 287 288 /** @brief Get the dimensions/location of the viewport **within the display 289 input** for a surface seen by an eye of a viewer in a display config. (This 290 does not include other video inputs that may be on a single virtual desktop, 291 etc. or explicitly account for display configurations that use multiple 292 video inputs. It does not necessarily indicate that a viewport in the sense 293 of glViewport must be created with these parameters, though the parameter 294 order matches for convenience.) 295 296 @param disp Display config object 297 @param viewer Viewer ID 298 @param eye Eye ID 299 @param surface Surface ID 300 @param[out] left Output: Distance in pixels from the left of the video input 301 to the left of the viewport. 302 @param[out] bottom Output: Distance in pixels from the bottom of the video 303 input to the bottom of the viewport. 304 @param[out] width Output: Width of viewport in pixels. 305 @param[out] height Output: Height of viewport in pixels. 306 307 308 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 309 the output arguments are unmodified. 310 */ 311 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 312 osvrClientGetRelativeViewportForViewerEyeSurface( 313 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 314 OSVR_SurfaceCount surface, OSVR_ViewportDimension* left, 315 OSVR_ViewportDimension* bottom, OSVR_ViewportDimension* width, 316 OSVR_ViewportDimension* height); 317 318 /** @brief Get the index of the display input for a surface seen by an eye of a 319 viewer in a display config. 320 321 This is the OSVR-assigned display input: it may not (and in practice, 322 usually will not) match any platform-specific display indices. This function 323 exists to associate surfaces with video inputs as enumerated by 324 osvrClientGetNumDisplayInputs(). 325 326 @param disp Display config object 327 @param viewer Viewer ID 328 @param eye Eye ID 329 @param surface Surface ID 330 @param[out] displayInput Zero-based index of the display input pixels for 331 this surface are tranmitted over. 332 333 This association is **constant** throughout the active, valid lifetime of a 334 display config object. 335 336 @sa osvrClientGetNumDisplayInputs(), 337 osvrClientGetRelativeViewportForViewerEyeSurface() 338 339 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which 340 case the output argument is unmodified. 341 */ 342 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 343 osvrClientGetViewerEyeSurfaceDisplayInputIndex( 344 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 345 OSVR_SurfaceCount surface, OSVR_DisplayInputCount* displayInput); 346 347 /** @brief Get the projection matrix for a surface seen by an eye of a viewer 348 in a display config. (double version) 349 350 @param disp Display config object 351 @param viewer Viewer ID 352 @param eye Eye ID 353 @param surface Surface ID 354 @param near Distance from viewpoint to near clipping plane - must be 355 positive. 356 @param far Distance from viewpoint to far clipping plane - must be positive 357 and not equal to near, typically greater than near. 358 @param flags Bitwise OR of matrix convention flags (see @ref MatrixFlags) 359 @param[out] matrix Output projection matrix: supply an array of 16 360 (::OSVR_MATRIX_SIZE) doubles. 361 362 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 363 the output argument is unmodified. 364 */ 365 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 366 osvrClientGetViewerEyeSurfaceProjectionMatrixd( 367 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 368 OSVR_SurfaceCount surface, double near, double far, 369 OSVR_MatrixConventions flags, double* matrix); 370 371 /** @brief Get the projection matrix for a surface seen by an eye of a viewer 372 in a display config. (float version) 373 374 @param disp Display config object 375 @param viewer Viewer ID 376 @param eye Eye ID 377 @param surface Surface ID 378 @param near Distance to near clipping plane - must be nonzero, typically 379 positive. 380 @param far Distance to far clipping plane - must be nonzero, typically 381 positive and greater than near. 382 @param flags Bitwise OR of matrix convention flags (see @ref MatrixFlags) 383 @param[out] matrix Output projection matrix: supply an array of 16 384 (::OSVR_MATRIX_SIZE) floats. 385 386 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 387 the output argument is unmodified. 388 */ 389 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 390 osvrClientGetViewerEyeSurfaceProjectionMatrixf( 391 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 392 OSVR_SurfaceCount surface, float near, float far, 393 OSVR_MatrixConventions flags, float* matrix); 394 395 /** @brief Get the clipping planes (positions at unit distance) for a surface 396 seen by an eye of a viewer 397 in a display config. 398 399 This is only for use in integrations that cannot accept a fully-formulated 400 projection matrix as returned by 401 osvrClientGetViewerEyeSurfaceProjectionMatrixf() or 402 osvrClientGetViewerEyeSurfaceProjectionMatrixd(), and may not necessarily 403 provide the same optimizations. 404 405 As all the planes are given at unit (1) distance, before passing these 406 planes to a consuming function in your application/engine, you will typically 407 divide them by your near clipping plane distance. 408 409 @param disp Display config object 410 @param viewer Viewer ID 411 @param eye Eye ID 412 @param surface Surface ID 413 @param[out] left Distance to left clipping plane 414 @param[out] right Distance to right clipping plane 415 @param[out] bottom Distance to bottom clipping plane 416 @param[out] top Distance to top clipping plane 417 418 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 419 the output arguments are unmodified. 420 */ 421 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 422 osvrClientGetViewerEyeSurfaceProjectionClippingPlanes( 423 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 424 OSVR_SurfaceCount surface, double* left, double* right, double* bottom, 425 double* top); 426 427 /** @brief Determines if a surface seen by an eye of a viewer in a display 428 config requests some distortion to be performed. 429 430 This simply reports true or false, and does not specify which kind of 431 distortion implementations have been parameterized for this display. For 432 each distortion implementation your application supports, you'll want to 433 call the corresponding priority function to find out if it is available. 434 435 @param disp Display config object 436 @param viewer Viewer ID 437 @param eye Eye ID 438 @param surface Surface ID 439 @param[out] distortionRequested Output parameter: whether distortion is 440 requested. **Constant** throughout the active, valid lifetime of a display 441 config object. 442 443 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 444 the output argument is unmodified. 445 */ 446 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 447 osvrClientDoesViewerEyeSurfaceWantDistortion(OSVR_DisplayConfig disp, 448 OSVR_ViewerCount viewer, 449 OSVR_EyeCount eye, 450 OSVR_SurfaceCount surface, 451 OSVR_CBool* distortionRequested); 452 453 /** @brief Returns the priority/availability of radial distortion parameters for 454 a surface seen by an eye of a viewer in a display config. 455 456 If osvrClientDoesViewerEyeSurfaceWantDistortion() reports false, then the 457 display does not request distortion of any sort, and thus neither this nor 458 any other distortion strategy priority function will report an "available" 459 priority. 460 461 @param disp Display config object 462 @param viewer Viewer ID 463 @param eye Eye ID 464 @param surface Surface ID 465 @param[out] priority Output: the priority level. Negative values 466 (canonically OSVR_DISTORTION_PRIORITY_UNAVAILABLE) indicate this technique 467 not available, higher values indicate higher preference for the given 468 technique based on the device's description. **Constant** throughout the 469 active, valid lifetime of a display config object. 470 471 @return OSVR_RETURN_FAILURE if invalid parameters were passed, in which case 472 the output argument is unmodified. 473 */ 474 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 475 osvrClientGetViewerEyeSurfaceRadialDistortionPriority( 476 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 477 OSVR_SurfaceCount surface, OSVR_DistortionPriority* priority); 478 479 /** @brief Returns the radial distortion parameters, if known/requested, for a 480 surface seen by an eye of a viewer in a display config. 481 482 Will only succeed if osvrClientGetViewerEyeSurfaceRadialDistortionPriority() 483 reports a non-negative priority. 484 485 @param disp Display config object 486 @param viewer Viewer ID 487 @param eye Eye ID 488 @param surface Surface ID 489 @param[out] params Output: the parameters for radial distortion 490 491 @return OSVR_RETURN_FAILURE if this surface does not have these parameters 492 described, or if invalid parameters were passed, in which case the output 493 argument is unmodified. 494 */ 495 OSVR_CLIENTKIT_EXPORT OSVR_ReturnCode 496 osvrClientGetViewerEyeSurfaceRadialDistortion( 497 OSVR_DisplayConfig disp, OSVR_ViewerCount viewer, OSVR_EyeCount eye, 498 OSVR_SurfaceCount surface, OSVR_RadialDistortionParameters* params); 499 500 /** @} 501 @} 502 */ 503 504 OSVR_EXTERN_C_END 505 506 #endif