1 /*! @header QuesaCamera.h 2 Declares the Quesa camera objects. 3 */ 4 /* NAME: 5 QuesaCamera.h 6 7 DESCRIPTION: 8 Quesa public header. 9 10 COPYRIGHT: 11 Copyright (c) 1999-2004, Quesa Developers. All rights reserved. 12 13 For the current release of Quesa, please see: 14 15 <http://www.quesa.org/> 16 17 Redistribution and use in source and binary forms, with or without 18 modification, are permitted provided that the following conditions 19 are met: 20 21 o Redistributions of source code must retain the above copyright 22 notice, this list of conditions and the following disclaimer. 23 24 o Redistributions in binary form must reproduce the above 25 copyright notice, this list of conditions and the following 26 disclaimer in the documentation and/or other materials provided 27 with the distribution. 28 29 o Neither the name of Quesa nor the names of its contributors 30 may be used to endorse or promote products derived from this 31 software without specific prior written permission. 32 33 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 34 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 35 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 36 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 37 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 38 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 39 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 40 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 41 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 42 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 43 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 44 ___________________________________________________________________________ 45 */ 46 #ifndef QUESA_CAMERA_HDR 47 #define QUESA_CAMERA_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 53 // Disable QD3D header 54 #if defined(__QD3DCAMERA__) 55 #error 56 #endif 57 58 #define __QD3DCAMERA__ 59 60 61 62 63 64 //============================================================================= 65 // C++ preamble 66 //----------------------------------------------------------------------------- 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 72 73 74 75 //============================================================================= 76 // Types 77 //----------------------------------------------------------------------------- 78 /*! 79 * @struct 80 * TQ3CameraPlacement 81 * @discussion 82 * Describes the location and orientation of a camera. All points are 83 * in world-space coordinates. 84 85 * @field cameraLocation The location of the camera. 86 * @field pointOfInterest The point at which the camera is aimed. 87 * @field upVector The up vector for the camera. This vector must be 88 * normalised and perpendicular to the viewing direction 89 * of the camera. This vector is transformed to the y 90 * axis of the viewing plane. 91 */ 92 typedef struct TQ3CameraPlacement { 93 TQ3Point3D cameraLocation; 94 TQ3Point3D pointOfInterest; 95 TQ3Vector3D upVector; 96 } TQ3CameraPlacement; 97 98 99 /*! 100 * @struct 101 * TQ3CameraRange 102 * @discussion 103 * Describes the hither and yon clipping planes of a camera. 104 105 * @field hither The distance from the camera to the near clipping plane. 106 * This value must always be more than 0. 107 * @field yon The distance from the camera to the far clipping plane. 108 * This value must always be more than the hither field, 109 * although if it is too large then artifacts may be visible 110 * during rendering. 111 */ 112 typedef struct TQ3CameraRange { 113 float hither; 114 float yon; 115 } TQ3CameraRange; 116 117 118 /*! 119 * @struct 120 * TQ3CameraViewPort 121 * @discussion 122 * Describes the viewport for a camera. 123 * 124 * The camera viewport is the rectangular area of the view plane which is 125 * mapped to the rendered area of the current draw context. The default 126 * mapping is a square of size 2.0x2.0, with the top left corner anchored 127 * at {-1.0, 1.0}. 128 * 129 * By adjusting the viewport, it is possible to control which area of the 130 * camera's view is rendered (e.g., to divide an image into a series of 131 * horizontal strips for printing). 132 * 133 * @field origin The origin for the viewport. 134 * @field width The width of the viewport. 135 * @field height The width of the viewport. 136 */ 137 typedef struct TQ3CameraViewPort { 138 TQ3Point2D origin; 139 float width; 140 float height; 141 } TQ3CameraViewPort; 142 143 144 /*! 145 * @struct 146 * TQ3CameraData 147 * @discussion 148 * Describes the common state for a camera. 149 * 150 * The common camera state includes its position and orientation within 151 * the world (placement), the near and far clipping planes (range), and 152 * the current viewport. 153 * 154 * @field placement The position and orientation of the camera. 155 * @field range The near and far clipping planes of the camera. 156 * @field viewPort The viewport for the camera. 157 */ 158 typedef struct TQ3CameraData { 159 TQ3CameraPlacement placement; 160 TQ3CameraRange range; 161 TQ3CameraViewPort viewPort; 162 } TQ3CameraData; 163 164 165 /*! 166 * @struct 167 * TQ3OrthographicCameraData 168 * @discussion 169 * Describes the state for an orthographic camera. 170 * 171 * An orthographic camera is defined by four view planes, which form a 172 * box aligned with the camera view direction. These planes are defined 173 * by distances relative to the coordinate system formed by the camera 174 * location and its view direction. 175 * 176 * @field cameraData The common state for the camera. 177 * @field left The left side of the view volume. 178 * @field top The top side of the view volume. 179 * @field right The right side of the view volume. 180 * @field bottom The bottom side of the view volume. 181 */ 182 typedef struct TQ3OrthographicCameraData { 183 TQ3CameraData cameraData; 184 float left; 185 float top; 186 float right; 187 float bottom; 188 } TQ3OrthographicCameraData; 189 190 191 /*! 192 * @struct 193 * TQ3ViewPlaneCameraData 194 * @discussion 195 * Describes the state for a view plane camera. 196 * 197 * A view plane camera is a perspective camera which allows the specification 198 * of an off-center viewing frustum. 199 * 200 * The frustum is formed by following the camera view direction for a given 201 * distance, then taking the specified rectangle on that plane. The frustum 202 * extends from the camera position through the four edges of this rectangle. 203 * 204 * @field cameraData The common state for the camera. 205 * @field viewPlane The distance from the camera to the view plane. 206 * @field halfWidthAtViewPlane The half-width of the rectangle on the view plane. 207 * @field halfHeightAtViewPlane The half-height of the rectangle on the view plane. 208 * @field centerXOnViewPlane The x-center of the rectangle on the view plane. 209 * @field centerYOnViewPlane The y-center of the rectangle on the view plane. 210 */ 211 typedef struct TQ3ViewPlaneCameraData { 212 TQ3CameraData cameraData; 213 float viewPlane; 214 float halfWidthAtViewPlane; 215 float halfHeightAtViewPlane; 216 float centerXOnViewPlane; 217 float centerYOnViewPlane; 218 } TQ3ViewPlaneCameraData; 219 220 221 /*! 222 * @struct 223 * TQ3ViewAngleAspectCameraData 224 * @discussion 225 * Describes the state for a traditional perspective camera. 226 * 227 * A view angle aspect camera is a perspective camera defined by a field of 228 * view angle and an aspect ratio. 229 * 230 * The field of view angle must be a positive angle in radians. If the 231 * aspect ratio is greater than 1.0, the field of view represents the 232 * vertical range of visibility, and if the aspect ratio is less than 1.0, 233 * the field of view is horizontal. In other words, the field of view is 234 * the smaller of the two angles. 235 * 236 * @field cameraData The common state for the camera. 237 * @field fov The field of view of the camera, in radians. 238 * @field aspectRatioXToY The horizontal-to-vertical aspect ratio of the camera. 239 */ 240 typedef struct TQ3ViewAngleAspectCameraData { 241 TQ3CameraData cameraData; 242 float fov; 243 float aspectRatioXToY; 244 } TQ3ViewAngleAspectCameraData; 245 246 247 248 249 250 //============================================================================= 251 // Function prototypes 252 //----------------------------------------------------------------------------- 253 /*! 254 * @function 255 * Q3Camera_GetType 256 * @discussion 257 * Get the type of a camera. 258 * 259 * Returns kQ3CameraTypeOrthographic, kQ3CameraTypeViewAngleAspect, or 260 * kQ3CameraTypeViewPlane. Returns kQ3ObjectTypeInvalid if the camera type 261 * is unknown. 262 * 263 * @param camera The camera to query. 264 * @result The type of the camera object. 265 */ 266 Q3_EXTERN_API_C ( TQ3ObjectType ) 267 Q3Camera_GetType ( 268 TQ3CameraObject camera 269 ); 270 271 272 273 /*! 274 * @function 275 * Q3Camera_SetData 276 * @discussion 277 * Set the common state for a camera. 278 * 279 * @param camera The camera to update. 280 * @param cameraData The new common state for the camera. 281 * @result Success or failure of the operation. 282 */ 283 Q3_EXTERN_API_C ( TQ3Status ) 284 Q3Camera_SetData ( 285 TQ3CameraObject camera, 286 const TQ3CameraData *cameraData 287 ); 288 289 290 291 /*! 292 * @function 293 * Q3Camera_GetData 294 * @discussion 295 * Get the common state of a camera. 296 * 297 * @param camera The camera to query. 298 * @param cameraData Receives the common state of the camera. 299 * @result Success or failure of the operation. 300 */ 301 Q3_EXTERN_API_C ( TQ3Status ) 302 Q3Camera_GetData ( 303 TQ3CameraObject camera, 304 TQ3CameraData *cameraData 305 ); 306 307 308 309 /*! 310 * @function 311 * Q3Camera_SetPlacement 312 * @discussion 313 * Set the placement for a camera. 314 * 315 * @param camera The camera to update. 316 * @param placement The new placement for the camera. 317 * @result Success or failure of the operation. 318 */ 319 Q3_EXTERN_API_C ( TQ3Status ) 320 Q3Camera_SetPlacement ( 321 TQ3CameraObject camera, 322 const TQ3CameraPlacement *placement 323 ); 324 325 326 327 /*! 328 * @function 329 * Q3Camera_GetPlacement 330 * @discussion 331 * Get the placement of a camera. 332 * 333 * @param camera The camera to query. 334 * @param placement Receives the placement of the camera. 335 * @result Success or failure of the operation. 336 */ 337 Q3_EXTERN_API_C ( TQ3Status ) 338 Q3Camera_GetPlacement ( 339 TQ3CameraObject camera, 340 TQ3CameraPlacement *placement 341 ); 342 343 344 345 /*! 346 * @function 347 * Q3Camera_SetRange 348 * @discussion 349 * Set the range for a camera. 350 * 351 * @param camera The camera to update. 352 * @param range The new range for the camera. 353 * @result Success or failure of the operation. 354 */ 355 Q3_EXTERN_API_C ( TQ3Status ) 356 Q3Camera_SetRange ( 357 TQ3CameraObject camera, 358 const TQ3CameraRange *range 359 ); 360 361 362 363 /*! 364 * @function 365 * Q3Camera_GetRange 366 * @discussion 367 * Get the range of a camera. 368 * 369 * @param camera The camera to query. 370 * @param range Receives the range of the camera. 371 * @result Success or failure of the operation. 372 */ 373 Q3_EXTERN_API_C ( TQ3Status ) 374 Q3Camera_GetRange ( 375 TQ3CameraObject camera, 376 TQ3CameraRange *range 377 ); 378 379 380 381 /*! 382 * @function 383 * Q3Camera_SetViewPort 384 * @discussion 385 * Set the view port for a camera. 386 * 387 * @param camera The camera to update. 388 * @param viewPort The new view port for the camera. 389 * @result Success or failure of the operation. 390 */ 391 Q3_EXTERN_API_C ( TQ3Status ) 392 Q3Camera_SetViewPort ( 393 TQ3CameraObject camera, 394 const TQ3CameraViewPort *viewPort 395 ); 396 397 398 399 /*! 400 * @function 401 * Q3Camera_GetViewPort 402 * @discussion 403 * Get the view port of a camera. 404 * 405 * @param camera The camera to query. 406 * @param viewPort Receives the view port of the camera. 407 * @result Success or failure of the operation. 408 */ 409 Q3_EXTERN_API_C ( TQ3Status ) 410 Q3Camera_GetViewPort ( 411 TQ3CameraObject camera, 412 TQ3CameraViewPort *viewPort 413 ); 414 415 416 417 /*! 418 * @function 419 * Q3Camera_GetWorldToView 420 * @discussion 421 * Get the world-to-view matrix of a camera. 422 * 423 * The world-to-view matrix transforms world coordinates to a coordinate 424 * system relative to the camera. The origin of this coordinate system is 425 * the camera location, with the camera view pointing down the -z axis 426 * and the camera up vector placed along the +y axis. 427 * 428 * @param camera The camera to query. 429 * @param worldToView Receives the world-to-view matrix of the camera. 430 * @result Success or failure of the operation. 431 */ 432 Q3_EXTERN_API_C ( TQ3Status ) 433 Q3Camera_GetWorldToView ( 434 TQ3CameraObject camera, 435 TQ3Matrix4x4 *worldToView 436 ); 437 438 439 440 /*! 441 * @function 442 * Q3Camera_GetWorldToFrustum 443 * @discussion 444 * Get the world-to-frustum matrix of a camera. 445 * 446 * The world-to-frustum matrix transforms world coordinates to the viewing 447 * frustum coordinate system. It is equivalent to multiplying the matrices 448 * returned by Q3Camera_GetWorldToView and Q3Camera_GetViewToFrustum. 449 * See the documentation of Q3View_GetWorldToFrustumMatrixState for more 450 * information. 451 * 452 * @param camera The camera to query. 453 * @param worldToFrustum Receives the world-to-frustum matrix of the camera. 454 * @result Success or failure of the operation. 455 */ 456 Q3_EXTERN_API_C ( TQ3Status ) 457 Q3Camera_GetWorldToFrustum ( 458 TQ3CameraObject camera, 459 TQ3Matrix4x4 *worldToFrustum 460 ); 461 462 463 464 /*! 465 * @function 466 * Q3Camera_GetViewToFrustum 467 * @discussion 468 * Get the view-to-frustum matrix of a camera. 469 * 470 * The view-to-frustum matrix transforms the camera coordinate system 471 * (as returned by Q3Camera_GetWorldToView) to the viewing frustum 472 * coordinate system. 473 * 474 * The frustum coordinate system ranges from 0.0 to -1.0 in z, and from 475 * -1.0 to +1.0 in both x and y. 476 * 477 * @param camera The camera to query. 478 * @param viewToFrustum Receives the view-to-frustum matrix of the camera. 479 * @result Success or failure of the operation. 480 */ 481 Q3_EXTERN_API_C ( TQ3Status ) 482 Q3Camera_GetViewToFrustum ( 483 TQ3CameraObject camera, 484 TQ3Matrix4x4 *viewToFrustum 485 ); 486 487 488 489 /*! 490 * @function 491 * Q3OrthographicCamera_New 492 * @discussion 493 * Create a new orthographic camera object. 494 * 495 * @param orthographicData The data for the camera object. 496 * @result The new camera object. 497 */ 498 Q3_EXTERN_API_C ( TQ3CameraObject ) 499 Q3OrthographicCamera_New ( 500 const TQ3OrthographicCameraData *orthographicData 501 ); 502 503 504 505 /*! 506 * @function 507 * Q3OrthographicCamera_GetData 508 * @discussion 509 * Get the data for an orthographic camera. 510 * 511 * @param camera The camera to query. 512 * @param cameraData Receives the data of the camera. 513 * @result Success or failure of the operation. 514 */ 515 Q3_EXTERN_API_C ( TQ3Status ) 516 Q3OrthographicCamera_GetData ( 517 TQ3CameraObject camera, 518 TQ3OrthographicCameraData *cameraData 519 ); 520 521 522 523 /*! 524 * @function 525 * Q3OrthographicCamera_SetData 526 * @discussion 527 * Set the data for an orthographic camera. 528 * 529 * @param camera The camera to update. 530 * @param cameraData The new data for the camera. 531 * @result Success or failure of the operation. 532 */ 533 Q3_EXTERN_API_C ( TQ3Status ) 534 Q3OrthographicCamera_SetData ( 535 TQ3CameraObject camera, 536 const TQ3OrthographicCameraData *cameraData 537 ); 538 539 540 541 /*! 542 * @function 543 * Q3OrthographicCamera_SetLeft 544 * @discussion 545 * Set the left side of the viewing frustum of an orthographic camera. 546 * 547 * @param camera The camera to update. 548 * @param left The new left side for the camera. 549 * @result Success or failure of the operation. 550 */ 551 Q3_EXTERN_API_C ( TQ3Status ) 552 Q3OrthographicCamera_SetLeft ( 553 TQ3CameraObject camera, 554 float left 555 ); 556 557 558 559 /*! 560 * @function 561 * Q3OrthographicCamera_GetLeft 562 * @discussion 563 * Get the left side of the viewing frustum of an orthographic camera. 564 * 565 * @param camera The camera to query. 566 * @param left Receives the left side of the camera. 567 * @result Success or failure of the operation. 568 */ 569 Q3_EXTERN_API_C ( TQ3Status ) 570 Q3OrthographicCamera_GetLeft ( 571 TQ3CameraObject camera, 572 float *left 573 ); 574 575 576 577 /*! 578 * @function 579 * Q3OrthographicCamera_SetTop 580 * @discussion 581 * Set the top side of the viewing frustum of an orthographic camera. 582 * 583 * @param camera The camera to update. 584 * @param top The new top side for the camera. 585 * @result Success or failure of the operation. 586 */ 587 Q3_EXTERN_API_C ( TQ3Status ) 588 Q3OrthographicCamera_SetTop ( 589 TQ3CameraObject camera, 590 float top 591 ); 592 593 594 595 /*! 596 * @function 597 * Q3OrthographicCamera_GetTop 598 * @discussion 599 * Get the top side of the viewing frustum of an orthographic camera. 600 * 601 * @param camera The camera to query. 602 * @param top Receives the top side of the camera. 603 * @result Success or failure of the operation. 604 */ 605 Q3_EXTERN_API_C ( TQ3Status ) 606 Q3OrthographicCamera_GetTop ( 607 TQ3CameraObject camera, 608 float *top 609 ); 610 611 612 613 /*! 614 * @function 615 * Q3OrthographicCamera_SetRight 616 * @discussion 617 * Set the right side of the viewing frustum of an orthographic camera. 618 * 619 * @param camera The camera to update. 620 * @param right The new right side for the camera. 621 * @result Success or failure of the operation. 622 */ 623 Q3_EXTERN_API_C ( TQ3Status ) 624 Q3OrthographicCamera_SetRight ( 625 TQ3CameraObject camera, 626 float right 627 ); 628 629 630 631 /*! 632 * @function 633 * Q3OrthographicCamera_GetRight 634 * @discussion 635 * Get the right side of the viewing frustum of an orthographic camera. 636 * 637 * @param camera The camera to query. 638 * @param right Receives the right side of the camera. 639 * @result Success or failure of the operation. 640 */ 641 Q3_EXTERN_API_C ( TQ3Status ) 642 Q3OrthographicCamera_GetRight ( 643 TQ3CameraObject camera, 644 float *right 645 ); 646 647 648 649 /*! 650 * @function 651 * Q3OrthographicCamera_SetBottom 652 * @discussion 653 * Set the bottom side of the viewing frustum of an orthographic camera. 654 * 655 * @param camera The camera to update. 656 * @param bottom The new bottom side for the camera. 657 * @result Success or failure of the operation. 658 */ 659 Q3_EXTERN_API_C ( TQ3Status ) 660 Q3OrthographicCamera_SetBottom ( 661 TQ3CameraObject camera, 662 float bottom 663 ); 664 665 666 667 /*! 668 * @function 669 * Q3OrthographicCamera_GetBottom 670 * @discussion 671 * Get the bottom side of the viewing frustum of an orthographic camera. 672 * 673 * @param camera The camera to query. 674 * @param bottom Receives the bottom side of the camera. 675 * @result Success or failure of the operation. 676 */ 677 Q3_EXTERN_API_C ( TQ3Status ) 678 Q3OrthographicCamera_GetBottom ( 679 TQ3CameraObject camera, 680 float *bottom 681 ); 682 683 684 685 /*! 686 * @function 687 * Q3ViewPlaneCamera_New 688 * @discussion 689 * Create a new view plane camera object. 690 * 691 * @param cameraData The data for the camera object. 692 * @result The new camera object. 693 */ 694 Q3_EXTERN_API_C ( TQ3CameraObject ) 695 Q3ViewPlaneCamera_New ( 696 const TQ3ViewPlaneCameraData *cameraData 697 ); 698 699 700 701 /*! 702 * @function 703 * Q3ViewPlaneCamera_GetData 704 * @discussion 705 * Get the data for a view plane camera. 706 * 707 * @param camera The camera to query. 708 * @param cameraData Receives the data of the camera. 709 * @result Success or failure of the operation. 710 */ 711 Q3_EXTERN_API_C ( TQ3Status ) 712 Q3ViewPlaneCamera_GetData ( 713 TQ3CameraObject camera, 714 TQ3ViewPlaneCameraData *cameraData 715 ); 716 717 718 719 /*! 720 * @function 721 * Q3ViewPlaneCamera_SetData 722 * @discussion 723 * Set the data for a view plane camera. 724 * 725 * @param camera The camera to update. 726 * @param cameraData The new data for the camera. 727 * @result Success or failure of the operation. 728 */ 729 Q3_EXTERN_API_C ( TQ3Status ) 730 Q3ViewPlaneCamera_SetData ( 731 TQ3CameraObject camera, 732 const TQ3ViewPlaneCameraData *cameraData 733 ); 734 735 736 737 /*! 738 * @function 739 * Q3ViewPlaneCamera_SetViewPlane 740 * @discussion 741 * Set the view plane distance for a view plane camera. 742 * 743 * The view plane distance is the distance along the camera view vector 744 * from the camera location. 745 * 746 * @param camera The camera to update. 747 * @param viewPlane The new view plane distance for the camera. 748 * @result Success or failure of the operation. 749 */ 750 Q3_EXTERN_API_C ( TQ3Status ) 751 Q3ViewPlaneCamera_SetViewPlane ( 752 TQ3CameraObject camera, 753 float viewPlane 754 ); 755 756 757 758 /*! 759 * @function 760 * Q3ViewPlaneCamera_GetViewPlane 761 * @discussion 762 * Get the view plane distance of a view plane camera. 763 * 764 * The view plane distance is the distance along the camera view vector 765 * from the camera location. 766 * 767 * @param camera The camera to query. 768 * @param viewPlane Receives the view plane distance of the camera. 769 * @result Success or failure of the operation. 770 */ 771 Q3_EXTERN_API_C ( TQ3Status ) 772 Q3ViewPlaneCamera_GetViewPlane ( 773 TQ3CameraObject camera, 774 float *viewPlane 775 ); 776 777 778 779 /*! 780 * @function 781 * Q3ViewPlaneCamera_SetHalfWidth 782 * @discussion 783 * Set the half-width of the view rectangle of a view plane camera. 784 * 785 * The area of the view plane which will be rendered is a rectangle, 786 * whose width is twice the specified half-width. 787 * 788 * @param camera The camera to update. 789 * @param halfWidthAtViewPlane The new half-width of the view rectangle. 790 * @result Success or failure of the operation. 791 */ 792 Q3_EXTERN_API_C ( TQ3Status ) 793 Q3ViewPlaneCamera_SetHalfWidth ( 794 TQ3CameraObject camera, 795 float halfWidthAtViewPlane 796 ); 797 798 799 800 /*! 801 * @function 802 * Q3ViewPlaneCamera_GetHalfWidth 803 * @discussion 804 * Get the half-width of the view rectangle of a view plane camera. 805 * 806 * The area of the view plane which will be rendered is a rectangle, 807 * whose width is twice the returned half-width. 808 * 809 * @param camera The camera to query. 810 * @param halfWidthAtViewPlane Receives the half-width of the view rectangle. 811 * @result Success or failure of the operation. 812 */ 813 Q3_EXTERN_API_C ( TQ3Status ) 814 Q3ViewPlaneCamera_GetHalfWidth ( 815 TQ3CameraObject camera, 816 float *halfWidthAtViewPlane 817 ); 818 819 820 821 /*! 822 * @function 823 * Q3ViewPlaneCamera_SetHalfHeight 824 * @discussion 825 * Set the half-height of the view rectangle of a view plane camera. 826 * 827 * The area of the view plane which will be rendered is a rectangle, 828 * whose height is twice the specified half-height. 829 * 830 * @param camera The camera to update. 831 * @param halfHeightAtViewPlane The new half-height of the view rectangle. 832 * @result Success or failure of the operation. 833 */ 834 Q3_EXTERN_API_C ( TQ3Status ) 835 Q3ViewPlaneCamera_SetHalfHeight ( 836 TQ3CameraObject camera, 837 float halfHeightAtViewPlane 838 ); 839 840 841 842 /*! 843 * @function 844 * Q3ViewPlaneCamera_GetHalfHeight 845 * @discussion 846 * Get the half-height of the view rectangle of a view plane camera. 847 * 848 * The area of the view plane which will be rendered is a rectangle, 849 * whose height is twice the returned half-height. 850 * 851 * @param camera The camera to query. 852 * @param halfHeightAtViewPlane Receives the half-height of the view rectangle. 853 * @result Success or failure of the operation. 854 */ 855 Q3_EXTERN_API_C ( TQ3Status ) 856 Q3ViewPlaneCamera_GetHalfHeight ( 857 TQ3CameraObject camera, 858 float *halfHeightAtViewPlane 859 ); 860 861 862 863 /*! 864 * @function 865 * Q3ViewPlaneCamera_SetCenterX 866 * @discussion 867 * Set the x coordinate of the view rectangle center of a view plane camera. 868 * 869 * The area of the view plane which will be rendered is a rectangle, whose 870 * origin in x is at the specified coordinate. 871 * 872 * @param camera The camera to update. 873 * @param centerXOnViewPlane The new x coordinate for the center of the view rectangle. 874 * @result Success or failure of the operation. 875 */ 876 Q3_EXTERN_API_C ( TQ3Status ) 877 Q3ViewPlaneCamera_SetCenterX ( 878 TQ3CameraObject camera, 879 float centerXOnViewPlane 880 ); 881 882 883 884 /*! 885 * @function 886 * Q3ViewPlaneCamera_GetCenterX 887 * @discussion 888 * Get the x coordinate of the view rectangle center of a view plane camera. 889 * 890 * The area of the view plane which will be rendered is a rectangle, whose 891 * origin in x is at the returned coordinate. 892 * 893 * @param camera The camera to query. 894 * @param centerXOnViewPlane Receives the x coordinate of the center of the view rectangle. 895 * @result Success or failure of the operation. 896 */ 897 Q3_EXTERN_API_C ( TQ3Status ) 898 Q3ViewPlaneCamera_GetCenterX ( 899 TQ3CameraObject camera, 900 float *centerXOnViewPlane 901 ); 902 903 904 905 /*! 906 * @function 907 * Q3ViewPlaneCamera_SetCenterY 908 * @discussion 909 * Set the y coordinate of the view rectangle center of a view plane camera. 910 * 911 * The area of the view plane which will be rendered is a rectangle, whose 912 * origin in y is at the specified coordinate. 913 * 914 * @param camera The camera to update. 915 * @param centerYOnViewPlane The new y coordinate for the center of the view rectangle. 916 * @result Success or failure of the operation. 917 */ 918 Q3_EXTERN_API_C ( TQ3Status ) 919 Q3ViewPlaneCamera_SetCenterY ( 920 TQ3CameraObject camera, 921 float centerYOnViewPlane 922 ); 923 924 925 926 /*! 927 * @function 928 * Q3ViewPlaneCamera_GetCenterY 929 * @discussion 930 * Get the y coordinate of the view rectangle center of a view plane camera. 931 * 932 * The area of the view plane which will be rendered is a rectangle, whose 933 * origin in y is at the returned coordinate. 934 * 935 * @param camera The camera to query. 936 * @param centerYOnViewPlane Receives the y coordinate of the center of the view rectangle. 937 * @result Success or failure of the operation. 938 */ 939 Q3_EXTERN_API_C ( TQ3Status ) 940 Q3ViewPlaneCamera_GetCenterY ( 941 TQ3CameraObject camera, 942 float *centerYOnViewPlane 943 ); 944 945 946 947 /*! 948 * @function 949 * Q3ViewAngleAspectCamera_New 950 * @discussion 951 * Create a new view angle aspect camera object. 952 * 953 * @param cameraData The data for the camera object. 954 * @result The new camera object. 955 */ 956 Q3_EXTERN_API_C ( TQ3CameraObject ) 957 Q3ViewAngleAspectCamera_New ( 958 const TQ3ViewAngleAspectCameraData *cameraData 959 ); 960 961 962 963 /*! 964 * @function 965 * Q3ViewAngleAspectCamera_SetData 966 * @discussion 967 * Set the data for a view angle aspect camera. 968 * 969 * @param camera The camera to update. 970 * @param cameraData The new data for the camera. 971 * @result Success or failure of the operation. 972 */ 973 Q3_EXTERN_API_C ( TQ3Status ) 974 Q3ViewAngleAspectCamera_SetData ( 975 TQ3CameraObject camera, 976 const TQ3ViewAngleAspectCameraData *cameraData 977 ); 978 979 980 981 /*! 982 * @function 983 * Q3ViewAngleAspectCamera_GetData 984 * @discussion 985 * Get the data for a view angle aspect camera. 986 * 987 * @param camera The camera to query. 988 * @param cameraData Receives the data of the camera. 989 * @result Success or failure of the operation. 990 */ 991 Q3_EXTERN_API_C ( TQ3Status ) 992 Q3ViewAngleAspectCamera_GetData ( 993 TQ3CameraObject camera, 994 TQ3ViewAngleAspectCameraData *cameraData 995 ); 996 997 998 999 /*! 1000 * @function 1001 * Q3ViewAngleAspectCamera_SetFOV 1002 * @discussion 1003 * Set the field of view for a view angle aspect camera. 1004 * 1005 * The field of view is specified in radians. 1006 * 1007 * @param camera The camera to update. 1008 * @param fov The new field of view for the camera. 1009 * @result Success or failure of the operation. 1010 */ 1011 Q3_EXTERN_API_C ( TQ3Status ) 1012 Q3ViewAngleAspectCamera_SetFOV ( 1013 TQ3CameraObject camera, 1014 float fov 1015 ); 1016 1017 1018 1019 /*! 1020 * @function 1021 * Q3ViewAngleAspectCamera_GetFOV 1022 * @discussion 1023 * Get the field of view of a view angle aspect camera. 1024 * 1025 * The field of view is specified in radians. 1026 * 1027 * @param camera The camera to query. 1028 * @param fov Receives the field of view of the camera. 1029 * @result Success or failure of the operation. 1030 */ 1031 Q3_EXTERN_API_C ( TQ3Status ) 1032 Q3ViewAngleAspectCamera_GetFOV ( 1033 TQ3CameraObject camera, 1034 float *fov 1035 ); 1036 1037 1038 1039 /*! 1040 * @function 1041 * Q3ViewAngleAspectCamera_SetAspectRatio 1042 * @discussion 1043 * Set the aspect ratio for a view angle aspect camera. 1044 * 1045 * If the aspect ratio is greater than 1.0, the field of view of the 1046 * camera is vertical. If it is less than 1.0, the field of view is 1047 * horizontal. 1048 * 1049 * @param camera The camera to update. 1050 * @param aspectRatioXToY The new horizontal-to-vertical aspect ratio of the camera. 1051 * @result Success or failure of the operation. 1052 */ 1053 Q3_EXTERN_API_C ( TQ3Status ) 1054 Q3ViewAngleAspectCamera_SetAspectRatio ( 1055 TQ3CameraObject camera, 1056 float aspectRatioXToY 1057 ); 1058 1059 1060 1061 /*! 1062 * @function 1063 * Q3ViewAngleAspectCamera_GetAspectRatio 1064 * @discussion 1065 * Get the aspect ratio of a view angle aspect camera. 1066 * 1067 * If the aspect ratio is greater than 1.0, the field of view of the 1068 * camera is vertical. If it is less than 1.0, the field of view is 1069 * horizontal. 1070 * 1071 * @param camera The camera to query. 1072 * @param aspectRatioXToY Receives the horizontal-to-vertical aspect ratio of the camera. 1073 * @result Success or failure of the operation. 1074 */ 1075 Q3_EXTERN_API_C ( TQ3Status ) 1076 Q3ViewAngleAspectCamera_GetAspectRatio ( 1077 TQ3CameraObject camera, 1078 float *aspectRatioXToY 1079 ); 1080 1081 1082 1083 1084 1085 //============================================================================= 1086 // C++ postamble 1087 //----------------------------------------------------------------------------- 1088 #ifdef __cplusplus 1089 } 1090 #endif 1091 1092 #endif 1093 1094 1095