1 /*! @header QuesaTransform.h 2 Declares the Quesa transform functions. 3 */ 4 /* NAME: 5 QuesaTransform.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_TRANSFORM_HDR 47 #define QUESA_TRANSFORM_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 53 // Disable QD3D header 54 #ifdef __QD3DTRANSFORM__ 55 #error 56 #endif 57 58 #define __QD3DTRANSFORM__ 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 /*! 80 * @struct TQ3RotateTransformData 81 * @discussion 82 * State data for a rotate transform. 83 * 84 * @field axis Enumerated value specifying the x, y, or z axis. 85 * @field radians Number of radians to rotate about the axis. 86 */ 87 typedef struct TQ3RotateTransformData { 88 TQ3Axis axis; 89 TQ3Float32 radians; 90 } TQ3RotateTransformData; 91 92 93 /*! 94 * @struct TQ3RotateAboutPointTransformData 95 * @discussion 96 * State data for a rotate-about-point transform. 97 * 98 * @field axis Enumerated value specifying the x, y, or z axis. 99 * @field radians Number of radians to rotate about the axis. 100 * @field about A point on the desired axis of rotation. 101 */ 102 typedef struct TQ3RotateAboutPointTransformData { 103 TQ3Axis axis; 104 TQ3Float32 radians; 105 TQ3Point3D about; 106 } TQ3RotateAboutPointTransformData; 107 108 109 // Rotate about axis transform data 110 /*! 111 * @struct TQ3RotateAboutAxisTransformData 112 * @discussion 113 * State data for a transform object that rotates about an arbitrary axis. 114 * Note that the orientation vector must be normalized. 115 * 116 * @field origin A point on the axis of rotation. 117 * @field orientation A normal vector determining the direction of the axis. 118 * @field radians Number of radians to rotate about the axis. 119 */ 120 typedef struct TQ3RotateAboutAxisTransformData { 121 TQ3Point3D origin; 122 TQ3Vector3D orientation; 123 TQ3Float32 radians; 124 } TQ3RotateAboutAxisTransformData; 125 126 127 // Camera transform data 128 /*! 129 * @struct TQ3CameraTransformData 130 * @discussion 131 * State data for a transform object that manipulates the camera matrix state. 132 * 133 * Vertices are passed through three transforms to convert them from local 134 * coordinates to the canonical viewing frustum. 135 * 136 * The localToWorld transform converts local coordinates to the world coordinate 137 * system. 138 * 139 * The worldToCamera transform converts world coordinates to the camera's 140 * coordinate system, which places the camera at the origin and establishes 141 * the camera's view of the world. 142 * 143 * The cameraToFrustum converts the camera's coordinate system to the canonical 144 * viewing frustum. This frustum is a box centered on the origin, ranging from 145 * -1 to +1 in x and y. In z the frustum ranges from 0 at the near clipping plane 146 * to -1 at the far clipping plane. 147 * 148 * Once vertices have been transformed to the canonical frustum, a portion of 149 * the frustum is then selected using the current camera's viewPort and that 150 * portion mapped to the draw context's pane. These two steps are controlled by 151 * the current camera and draw context, and are not affected by a camera transform 152 * object. 153 * 154 * @field localToWorld The local-to-world matrix. 155 * @field worldToCamera The world-to-camera matrix. 156 * @field cameraToFrustum The camera-to-frustum matrix. 157 */ 158 typedef struct TQ3CameraTransformData { 159 TQ3Matrix4x4 localToWorld; 160 TQ3Matrix4x4 worldToCamera; 161 TQ3Matrix4x4 cameraToFrustum; 162 } TQ3CameraTransformData; 163 164 165 166 167 168 //============================================================================= 169 // Function prototypes 170 //----------------------------------------------------------------------------- 171 /*! 172 * @function 173 * Q3Transform_GetType 174 * @discussion 175 * Get the subtype of a transform object. Returns <code>kQ3TransformTypeMatrix</code>, 176 * <code>kQ3TransformTypeScale</code>, <code>kQ3TransformTypeTranslate</code>, 177 * <code>kQ3TransformTypeRotate</code>, <code>kQ3TransformTypeRotateAboutPoint</code>, 178 * <code>kQ3TransformTypeRotateAboutAxis</code>, <code>kQ3TransformTypeQuaternion</code>, 179 * <code>kQ3TransformTypeReset</code>, or <code>kQ3ObjectTypeInvalid</code>. 180 * 181 * @param transform A transform object. 182 * @result A transform object type or <code>kQ3ObjectTypeInvalid</code>. 183 */ 184 Q3_EXTERN_API_C ( TQ3ObjectType ) 185 Q3Transform_GetType ( 186 TQ3TransformObject transform 187 ); 188 189 190 191 /*! 192 * @function 193 * Q3Transform_GetMatrix 194 * @discussion 195 * Get the 4×4 matrix of a transform object. 196 * 197 * Non-geometrical transform objects (e.g., camera transforms) can not be 198 * expressed as a single 4×4 matrix. These transforms will return the 199 * identity matrix. 200 * 201 * @param transform A transform object. 202 * @param matrix Receives the matrix of the transform. 203 * @result Address of the resulting matrix, for convenience. 204 */ 205 Q3_EXTERN_API_C ( TQ3Matrix4x4 * ) 206 Q3Transform_GetMatrix ( 207 TQ3TransformObject transform, 208 TQ3Matrix4x4 *matrix 209 ); 210 211 212 213 /*! 214 * @function 215 * Q3Transform_Submit 216 * @discussion 217 * Submit a transform object. Should only be used within a submitting loop. 218 * 219 * 220 * @param transform A transform object. 221 * @param view A view object. 222 * @result Success or failure of the operation. 223 */ 224 Q3_EXTERN_API_C ( TQ3Status ) 225 Q3Transform_Submit ( 226 TQ3TransformObject transform, 227 TQ3ViewObject view 228 ); 229 230 231 232 /*! 233 * @function 234 * Q3MatrixTransform_New 235 * @discussion 236 * Create a new matrix transform. 237 * 238 * 239 * @param matrix Initial matrix of the transform. 240 * @result A new transform object, or NULL on failure. 241 */ 242 Q3_EXTERN_API_C ( TQ3TransformObject ) 243 Q3MatrixTransform_New ( 244 const TQ3Matrix4x4 *matrix 245 ); 246 247 248 249 /*! 250 * @function 251 * Q3MatrixTransform_Submit 252 * @discussion 253 * Submit a matrix transform in immediate mode. 254 * Should only be used within a submitting loop. 255 * 256 * @param matrix Matrix of the desired transform. 257 * @param view A view object. 258 * @result Success or failure of the operation. 259 */ 260 Q3_EXTERN_API_C ( TQ3Status ) 261 Q3MatrixTransform_Submit ( 262 const TQ3Matrix4x4 *matrix, 263 TQ3ViewObject view 264 ); 265 266 267 268 /*! 269 * @function 270 * Q3MatrixTransform_Set 271 * @discussion 272 * Change the matrix of a matrix transform. 273 * 274 * @param transform The matrix transform object. 275 * @param matrix The new matrix. 276 * @result Success or failure of the operation. 277 */ 278 Q3_EXTERN_API_C ( TQ3Status ) 279 Q3MatrixTransform_Set ( 280 TQ3TransformObject transform, 281 const TQ3Matrix4x4 *matrix 282 ); 283 284 285 286 /*! 287 * @function 288 * Q3MatrixTransform_Get 289 * @discussion 290 * Get the matrix of a matrix transform. 291 * 292 * @param transform The matrix transform object. 293 * @param matrix Receives the matrix of the transform. 294 * @result Success or failure of the operation. 295 */ 296 Q3_EXTERN_API_C ( TQ3Status ) 297 Q3MatrixTransform_Get ( 298 TQ3TransformObject transform, 299 TQ3Matrix4x4 *matrix 300 ); 301 302 303 304 /*! 305 * @function 306 * Q3RotateTransform_New 307 * @discussion 308 * Create a transform object for rotation about the x, y, or z axis. 309 * 310 * @param data Data specifying the initial state of the transform. 311 * @result The new transform object, or NULL on failure. 312 */ 313 Q3_EXTERN_API_C ( TQ3TransformObject ) 314 Q3RotateTransform_New ( 315 const TQ3RotateTransformData *data 316 ); 317 318 319 320 /*! 321 * @function 322 * Q3RotateTransform_Submit 323 * @discussion 324 * Submit a rotate transform in immediate mode. 325 * Should only be used within a submitting loop. 326 * 327 * @param data Data specifying the transform. 328 * @param view A view object. 329 * @result Success or failure of the operation. 330 */ 331 Q3_EXTERN_API_C ( TQ3Status ) 332 Q3RotateTransform_Submit ( 333 const TQ3RotateTransformData *data, 334 TQ3ViewObject view 335 ); 336 337 338 339 /*! 340 * @function 341 * Q3RotateTransform_SetData 342 * @discussion 343 * Change the data of a rotate transform. 344 * 345 * @param transform The rotate transform object. 346 * @param data Data specifying the new state of the transform. 347 * @result Success or failure of the operation. 348 */ 349 Q3_EXTERN_API_C ( TQ3Status ) 350 Q3RotateTransform_SetData ( 351 TQ3TransformObject transform, 352 const TQ3RotateTransformData *data 353 ); 354 355 356 357 /*! 358 * @function 359 * Q3RotateTransform_GetData 360 * @discussion 361 * Get the state of a rotate transform object. 362 * 363 * @param transform The rotate transform object. 364 * @param data Receives the data specifying the state of the transform. 365 * @result Success or failure of the operation. 366 */ 367 Q3_EXTERN_API_C ( TQ3Status ) 368 Q3RotateTransform_GetData ( 369 TQ3TransformObject transform, 370 TQ3RotateTransformData *data 371 ); 372 373 374 375 /*! 376 * @function 377 * Q3RotateTransform_SetAxis 378 * @discussion 379 * Change the axis of a rotate transform. 380 * 381 * @param transform The rotate transform object. 382 * @param axis New axis of rotation. 383 * @result Success or failure of the operation. 384 */ 385 Q3_EXTERN_API_C ( TQ3Status ) 386 Q3RotateTransform_SetAxis ( 387 TQ3TransformObject transform, 388 TQ3Axis axis 389 ); 390 391 392 393 /*! 394 * @function 395 * Q3RotateTransform_SetAngle 396 * @discussion 397 * Change the angle of a rotate transform. 398 * 399 * @param transform The rotate transform object. 400 * @param radians New angle of rotation in radians. 401 * @result Success or failure of the operation. 402 */ 403 Q3_EXTERN_API_C ( TQ3Status ) 404 Q3RotateTransform_SetAngle ( 405 TQ3TransformObject transform, 406 float radians 407 ); 408 409 410 411 /*! 412 * @function 413 * Q3RotateTransform_GetAxis 414 * @discussion 415 * Get the axis of a rotate transform. 416 * 417 * @param renderable The rotate transform object. 418 * @param axis Receives the enumerated value specifying the axis. 419 * @result Success or failure of the operation. 420 */ 421 Q3_EXTERN_API_C ( TQ3Status ) 422 Q3RotateTransform_GetAxis ( 423 TQ3TransformObject renderable, 424 TQ3Axis *axis 425 ); 426 427 428 429 /*! 430 * @function 431 * Q3RotateTransform_GetAngle 432 * @discussion 433 * Get the angle of rotation of a rotate transform. 434 * 435 * @param transform The rotate transform object. 436 * @param radians Receives the angle in radians. 437 * @result Success or failure of the operation. 438 */ 439 Q3_EXTERN_API_C ( TQ3Status ) 440 Q3RotateTransform_GetAngle ( 441 TQ3TransformObject transform, 442 float *radians 443 ); 444 445 446 447 /*! 448 * @function 449 * Q3RotateAboutPointTransform_New 450 * @discussion 451 * Create a new transform for rotation about an axis that is parallel to 452 * the x, y, or z axis. 453 * 454 * @param data Structure containing the initial state of the transform. 455 * @result A new rotate-about-point transform, or NULL on failure. 456 */ 457 Q3_EXTERN_API_C ( TQ3TransformObject ) 458 Q3RotateAboutPointTransform_New ( 459 const TQ3RotateAboutPointTransformData *data 460 ); 461 462 463 464 /*! 465 * @function 466 * Q3RotateAboutPointTransform_Submit 467 * @discussion 468 * Submit a rotate-about-point transform in immediate mode. 469 * Should only be used within a submitting loop. 470 * 471 * @param data Structure containing the state of the transform. 472 * @param view A view object. 473 * @result Success or failure of the operation. 474 */ 475 Q3_EXTERN_API_C ( TQ3Status ) 476 Q3RotateAboutPointTransform_Submit ( 477 const TQ3RotateAboutPointTransformData *data, 478 TQ3ViewObject view 479 ); 480 481 482 483 /*! 484 * @function 485 * Q3RotateAboutPointTransform_SetData 486 * @discussion 487 * Change the state of a rotate-about-point transform. 488 * 489 * @param transform A rotate-about-point transform object. 490 * @param data Structure containing the new state of the transform. 491 * @result Success or failure of the operation. 492 */ 493 Q3_EXTERN_API_C ( TQ3Status ) 494 Q3RotateAboutPointTransform_SetData ( 495 TQ3TransformObject transform, 496 const TQ3RotateAboutPointTransformData *data 497 ); 498 499 500 501 /*! 502 * @function 503 * Q3RotateAboutPointTransform_GetData 504 * @discussion 505 * Get the state of a rotate-about-point transform. 506 * 507 * @param transform A rotate-about-point transform object. 508 * @param data Receives the state of the transform. 509 * @result Success or failure of the operation. 510 */ 511 Q3_EXTERN_API_C ( TQ3Status ) 512 Q3RotateAboutPointTransform_GetData ( 513 TQ3TransformObject transform, 514 TQ3RotateAboutPointTransformData *data 515 ); 516 517 518 519 /*! 520 * @function 521 * Q3RotateAboutPointTransform_SetAxis 522 * @discussion 523 * Change the axis of a rotate-about-point transform. 524 * 525 * @param transform A rotate-about-point transform object. 526 * @param axis The new axis. 527 * @result Success or failure of the operation. 528 */ 529 Q3_EXTERN_API_C ( TQ3Status ) 530 Q3RotateAboutPointTransform_SetAxis ( 531 TQ3TransformObject transform, 532 TQ3Axis axis 533 ); 534 535 536 537 /*! 538 * @function 539 * Q3RotateAboutPointTransform_GetAxis 540 * @discussion 541 * Get the axis of a rotate-about-point transform. 542 * 543 * @param transform A rotate-about-point transform object. 544 * @param axis Receives the enumerated value specifying the axis. 545 * @result Success or failure of the operation. 546 */ 547 Q3_EXTERN_API_C ( TQ3Status ) 548 Q3RotateAboutPointTransform_GetAxis ( 549 TQ3TransformObject transform, 550 TQ3Axis *axis 551 ); 552 553 554 555 /*! 556 * @function 557 * Q3RotateAboutPointTransform_SetAngle 558 * @discussion 559 * Change the angle of a rotate-about-point transform. 560 * 561 * @param transform A rotate-about-point transform object. 562 * @param radians The new angle in radians. 563 * @result Success or failure of the operation. 564 */ 565 Q3_EXTERN_API_C ( TQ3Status ) 566 Q3RotateAboutPointTransform_SetAngle ( 567 TQ3TransformObject transform, 568 float radians 569 ); 570 571 572 573 /*! 574 * @function 575 * Q3RotateAboutPointTransform_GetAngle 576 * @discussion 577 * Get the angle of a rotate-about-point transform. 578 * 579 * @param transform A rotate-about-point transform object. 580 * @param radians Receives the angle in radians. 581 * @result Success or failure of the operation. 582 */ 583 Q3_EXTERN_API_C ( TQ3Status ) 584 Q3RotateAboutPointTransform_GetAngle ( 585 TQ3TransformObject transform, 586 float *radians 587 ); 588 589 590 591 /*! 592 * @function 593 * Q3RotateAboutPointTransform_SetAboutPoint 594 * @discussion 595 * Change the point on the axis of rotation of a rotate-about-point transform. 596 * 597 * @param transform A rotate-about-point transform object. 598 * @param about A point on the desired axis. 599 * @result Success or failure of the operation. 600 */ 601 Q3_EXTERN_API_C ( TQ3Status ) 602 Q3RotateAboutPointTransform_SetAboutPoint ( 603 TQ3TransformObject transform, 604 const TQ3Point3D *about 605 ); 606 607 608 609 /*! 610 * @function 611 * Q3RotateAboutPointTransform_GetAboutPoint 612 * @discussion 613 * Get a point on the axis of rotation of a rotate-about-point transform. 614 * 615 * @param transform A rotate-about-point transform object. 616 * @param about Receives a point on the axis of rotation. 617 * @result Success or failure of the operation. 618 */ 619 Q3_EXTERN_API_C ( TQ3Status ) 620 Q3RotateAboutPointTransform_GetAboutPoint ( 621 TQ3TransformObject transform, 622 TQ3Point3D *about 623 ); 624 625 626 627 /*! 628 * @function 629 * Q3RotateAboutAxisTransform_New 630 * @discussion 631 * Create a new transform object for rotation about an arbitrary axis. 632 * Note that the orientation vector must be normalized. 633 * 634 * @param data Structure specifying the initial state of the transform. 635 * @result A new rotate-about-axis transform object, or NULL on failure. 636 */ 637 Q3_EXTERN_API_C ( TQ3TransformObject ) 638 Q3RotateAboutAxisTransform_New ( 639 const TQ3RotateAboutAxisTransformData *data 640 ); 641 642 643 644 /*! 645 * @function 646 * Q3RotateAboutAxisTransform_Submit 647 * @discussion 648 * Submit a rotate-about-axis transform in immediate mode. 649 * Should only be called within a submitting loop. 650 * 651 * @param data Structure specifying the state of the transform. 652 * @param view A view object. 653 * @result Success or failure of the operation. 654 */ 655 Q3_EXTERN_API_C ( TQ3Status ) 656 Q3RotateAboutAxisTransform_Submit ( 657 const TQ3RotateAboutAxisTransformData *data, 658 TQ3ViewObject view 659 ); 660 661 662 663 /*! 664 * @function 665 * Q3RotateAboutAxisTransform_SetData 666 * @discussion 667 * Set the state of a rotate-about-axis transform object. 668 * 669 * @param transform A rotate-about-axis transform object. 670 * @param data Structure specifying the new state of the transform. 671 * @result Success or failure of the operation. 672 */ 673 Q3_EXTERN_API_C ( TQ3Status ) 674 Q3RotateAboutAxisTransform_SetData ( 675 TQ3TransformObject transform, 676 const TQ3RotateAboutAxisTransformData *data 677 ); 678 679 680 681 /*! 682 * @function 683 * Q3RotateAboutAxisTransform_GetData 684 * @discussion 685 * Get the state of a rotate-about-axis transform object. 686 * 687 * @param transform A rotate-about-axis transform object. 688 * @param data Receives the state of the transform. 689 * @result Success or failure of the operation. 690 */ 691 Q3_EXTERN_API_C ( TQ3Status ) 692 Q3RotateAboutAxisTransform_GetData ( 693 TQ3TransformObject transform, 694 TQ3RotateAboutAxisTransformData *data 695 ); 696 697 698 699 /*! 700 * @function 701 * Q3RotateAboutAxisTransform_SetOrientation 702 * @discussion 703 * Set the axis direction of a rotate-about-axis transform object. 704 * You must provide a normalized vector. 705 * 706 * @param transform A rotate-about-axis transform object. 707 * @param axis New axis direction vector (normalized). 708 * @result Success or failure of the operation. 709 */ 710 Q3_EXTERN_API_C ( TQ3Status ) 711 Q3RotateAboutAxisTransform_SetOrientation ( 712 TQ3TransformObject transform, 713 const TQ3Vector3D *axis 714 ); 715 716 717 718 /*! 719 * @function 720 * Q3RotateAboutAxisTransform_GetOrientation 721 * @discussion 722 * Get the axis direction of a rotate-about-axis transform object. 723 * 724 * @param transform A rotate-about-axis transform object. 725 * @param axis Receives the axis direction vector. 726 * @result Success or failure of the operation. 727 */ 728 Q3_EXTERN_API_C ( TQ3Status ) 729 Q3RotateAboutAxisTransform_GetOrientation ( 730 TQ3TransformObject transform, 731 TQ3Vector3D *axis 732 ); 733 734 735 736 /*! 737 * @function 738 * Q3RotateAboutAxisTransform_SetAngle 739 * @discussion 740 * Change the angle of rotation of a rotate-about-axis transform object. 741 * 742 * @param transform A rotate-about-axis transform object. 743 * @param radians New angle of rotation, in radians. 744 * @result Success or failure of the operation. 745 */ 746 Q3_EXTERN_API_C ( TQ3Status ) 747 Q3RotateAboutAxisTransform_SetAngle ( 748 TQ3TransformObject transform, 749 float radians 750 ); 751 752 753 754 /*! 755 * @function 756 * Q3RotateAboutAxisTransform_GetAngle 757 * @discussion 758 * Get the angle of rotation of a rotate-about-axis transform object. 759 * 760 * @param transform A rotate-about-axis transform object. 761 * @param radians Receives the angle of rotation, in radians. 762 * @result Success or failure of the operation. 763 */ 764 Q3_EXTERN_API_C ( TQ3Status ) 765 Q3RotateAboutAxisTransform_GetAngle ( 766 TQ3TransformObject transform, 767 float *radians 768 ); 769 770 771 772 /*! 773 * @function 774 * Q3RotateAboutAxisTransform_SetOrigin 775 * @discussion 776 * Specify a new point lying on the axis of a rotate-about-axis transform object. 777 * 778 * @param transform A rotate-about-axis transform object. 779 * @param origin A point on the desired axis of rotation. 780 * @result Success or failure of the operation. 781 */ 782 Q3_EXTERN_API_C ( TQ3Status ) 783 Q3RotateAboutAxisTransform_SetOrigin ( 784 TQ3TransformObject transform, 785 const TQ3Point3D *origin 786 ); 787 788 789 790 /*! 791 * @function 792 * Q3RotateAboutAxisTransform_GetOrigin 793 * @discussion 794 * Get a point lying on the axis of a rotate-about-axis transform object. 795 * 796 * @param transform A rotate-about-axis transform object. 797 * @param origin Receives a point on the desired axis of rotation. 798 * @result Success or failure of the operation. 799 */ 800 Q3_EXTERN_API_C ( TQ3Status ) 801 Q3RotateAboutAxisTransform_GetOrigin ( 802 TQ3TransformObject transform, 803 TQ3Point3D *origin 804 ); 805 806 807 808 /*! 809 * @function 810 * Q3ScaleTransform_New 811 * @discussion 812 * Create a new scale transform. It multiplies the x, y, and z coordinates by 813 * the components of a given vector. Most commonly, the 3 scale factors are 814 * identical positive numbers. 815 * 816 * @param scale Vector specifying scale factors for each coordinate. 817 * @result A new scale transform object, or NULL on failure. 818 */ 819 Q3_EXTERN_API_C ( TQ3TransformObject ) 820 Q3ScaleTransform_New ( 821 const TQ3Vector3D *scale 822 ); 823 824 825 826 /*! 827 * @function 828 * Q3ScaleTransform_Submit 829 * @discussion 830 * Submit a scale transform in immediate mode. This should only be called 831 * within a submitting loop. 832 * 833 * @param scale Vector containing the 3 scale factors. 834 * @param view A view object. 835 * @result Success or failure of the operation. 836 */ 837 Q3_EXTERN_API_C ( TQ3Status ) 838 Q3ScaleTransform_Submit ( 839 const TQ3Vector3D *scale, 840 TQ3ViewObject view 841 ); 842 843 844 845 /*! 846 * @function 847 * Q3ScaleTransform_Set 848 * @discussion 849 * Change the scale factors of a scale transform. 850 * 851 * @param transform A scale transform object. 852 * @param scale Vector containing the 3 scale factors. 853 * @result Success or failure of the operation. 854 */ 855 Q3_EXTERN_API_C ( TQ3Status ) 856 Q3ScaleTransform_Set ( 857 TQ3TransformObject transform, 858 const TQ3Vector3D *scale 859 ); 860 861 862 863 /*! 864 * @function 865 * Q3ScaleTransform_Get 866 * @discussion 867 * Get the scale factors of a scale transform. 868 * 869 * @param transform A scale transform object. 870 * @param scale Receives the vector containing the 3 scale factors. 871 * @result Success or failure of the operation. 872 */ 873 Q3_EXTERN_API_C ( TQ3Status ) 874 Q3ScaleTransform_Get ( 875 TQ3TransformObject transform, 876 TQ3Vector3D *scale 877 ); 878 879 880 881 /*! 882 * @function 883 * Q3TranslateTransform_New 884 * @discussion 885 * Create a new translation transform. 886 * 887 * @param translate Vector by which to translate. 888 * @result A new transform object, or NULL on failure. 889 */ 890 Q3_EXTERN_API_C ( TQ3TransformObject ) 891 Q3TranslateTransform_New ( 892 const TQ3Vector3D *translate 893 ); 894 895 896 897 /*! 898 * @function 899 * Q3TranslateTransform_Submit 900 * @discussion 901 * Submit a translate transform in immediate mode. Should only be 902 * called within a submitting loop. 903 * 904 * @param translate Vector by which to translate. 905 * @param view A view object. 906 * @result Success or failure of the operation. 907 */ 908 Q3_EXTERN_API_C ( TQ3Status ) 909 Q3TranslateTransform_Submit ( 910 const TQ3Vector3D *translate, 911 TQ3ViewObject view 912 ); 913 914 915 916 /*! 917 * @function 918 * Q3TranslateTransform_Set 919 * @discussion 920 * Change the translation vector of a translate transform. 921 * 922 * @param transform A translate transform object. 923 * @param translate New vector by which to translate. 924 * @result Success or failure of the operation. 925 */ 926 Q3_EXTERN_API_C ( TQ3Status ) 927 Q3TranslateTransform_Set ( 928 TQ3TransformObject transform, 929 const TQ3Vector3D *translate 930 ); 931 932 933 934 /*! 935 * @function 936 * Q3TranslateTransform_Get 937 * @discussion 938 * Get the translation vector of a translate transform. 939 * 940 * @param transform A translate transform object. 941 * @param translate Receives the vector by which the transform translates. 942 * @result Success or failure of the operation. 943 */ 944 Q3_EXTERN_API_C ( TQ3Status ) 945 Q3TranslateTransform_Get ( 946 TQ3TransformObject transform, 947 TQ3Vector3D *translate 948 ); 949 950 951 952 /*! 953 * @function 954 * Q3QuaternionTransform_New 955 * @discussion 956 * Create a new quaternion transform object. 957 * 958 * @param quaternion Quaternion data specifying the transform. 959 * @result A new quaternion transform object, or NULL on failure. 960 */ 961 Q3_EXTERN_API_C ( TQ3TransformObject ) 962 Q3QuaternionTransform_New ( 963 const TQ3Quaternion *quaternion 964 ); 965 966 967 968 /*! 969 * @function 970 * Q3QuaternionTransform_Submit 971 * @discussion 972 * Submit a quaternion transform in immediate mode. Should only be called 973 * within a submitting loop. 974 * 975 * @param quaternion Quaternion data specifying the transform. 976 * @param view A view object. 977 * @result Success or failure of the operation. 978 */ 979 Q3_EXTERN_API_C ( TQ3Status ) 980 Q3QuaternionTransform_Submit ( 981 const TQ3Quaternion *quaternion, 982 TQ3ViewObject view 983 ); 984 985 986 987 /*! 988 * @function 989 * Q3QuaternionTransform_Set 990 * @discussion 991 * Change the quaternion data of a quaternion transform object. 992 * 993 * @param transform A quaternion transform object. 994 * @param quaternion Quaternion data specifying the transform. 995 * @result Success or failure of the operation. 996 */ 997 Q3_EXTERN_API_C ( TQ3Status ) 998 Q3QuaternionTransform_Set ( 999 TQ3TransformObject transform, 1000 const TQ3Quaternion *quaternion 1001 ); 1002 1003 1004 1005 /*! 1006 * @function 1007 * Q3QuaternionTransform_Get 1008 * @discussion 1009 * Get the quaternion data of a quaternion transform object. 1010 * 1011 * @param transform A quaternion transform object. 1012 * @param quaternion Receives the quaternion data specifying the transform. 1013 * @result Success or failure of the operation. 1014 */ 1015 Q3_EXTERN_API_C ( TQ3Status ) 1016 Q3QuaternionTransform_Get ( 1017 TQ3TransformObject transform, 1018 TQ3Quaternion *quaternion 1019 ); 1020 1021 1022 1023 /*! 1024 * @function 1025 * Q3ResetTransform_New 1026 * @discussion 1027 * Create a new reset transform. 1028 * 1029 * When transforms are submitted, they normally concatenate together, as 1030 * modified by groups or push and pop operations. Submitting a reset 1031 * transform is a shortcut which sets the current transform to the identity. 1032 * 1033 * @result A new reset transform, or NULL on failure. 1034 */ 1035 Q3_EXTERN_API_C ( TQ3TransformObject ) 1036 Q3ResetTransform_New ( 1037 void 1038 ); 1039 1040 1041 1042 /*! 1043 * @function 1044 * Q3ResetTransform_Submit 1045 * @discussion 1046 * Submit a reset transform in immediate mode. This should only be called 1047 * within a submitting loop. 1048 * 1049 * @param view A view object. 1050 * @result Success or failure of the operation. 1051 */ 1052 Q3_EXTERN_API_C ( TQ3Status ) 1053 Q3ResetTransform_Submit ( 1054 TQ3ViewObject view 1055 ); 1056 1057 1058 1059 /*! 1060 * @function 1061 * Q3CameraTransform_New 1062 * @discussion 1063 * Create a new camera transform object. 1064 * 1065 * <em>This function is not available in QD3D.</em> 1066 * 1067 * @param theData The data for the camera transform object. 1068 * @result A new camera transform object, or NULL on failure. 1069 */ 1070 #if QUESA_ALLOW_QD3D_EXTENSIONS 1071 1072 Q3_EXTERN_API_C ( TQ3TransformObject ) 1073 Q3CameraTransform_New ( 1074 const TQ3CameraTransformData *theData 1075 ); 1076 1077 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 1078 1079 1080 1081 /*! 1082 * @function 1083 * Q3CameraTransform_Submit 1084 * @discussion 1085 * Submit a camera transform in immediate mode. Should only be called 1086 * within a submitting loop. 1087 * 1088 * <em>This function is not available in QD3D.</em> 1089 * 1090 * @param theData The data for the camera transform. 1091 * @param theView The view currently being submitted to. 1092 * @result Success or failure of the operation. 1093 */ 1094 #if QUESA_ALLOW_QD3D_EXTENSIONS 1095 1096 Q3_EXTERN_API_C ( TQ3Status ) 1097 Q3CameraTransform_Submit ( 1098 const TQ3CameraTransformData *theData, 1099 TQ3ViewObject theView 1100 ); 1101 1102 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 1103 1104 1105 1106 /*! 1107 * @function 1108 * Q3CameraTransform_Set 1109 * @discussion 1110 * Set the data of a camera transform object. 1111 * 1112 * <em>This function is not available in QD3D.</em> 1113 * 1114 * @param theTransform The camera transform object to update. 1115 * @param theData The new data for the transform object. 1116 * @result Success or failure of the operation. 1117 */ 1118 #if QUESA_ALLOW_QD3D_EXTENSIONS 1119 1120 Q3_EXTERN_API_C ( TQ3Status ) 1121 Q3CameraTransform_Set ( 1122 TQ3TransformObject theTransform, 1123 const TQ3CameraTransformData *theData 1124 ); 1125 1126 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 1127 1128 1129 1130 /*! 1131 * @function 1132 * Q3CameraTransform_Get 1133 * @discussion 1134 * Get the data of a camera transform object. 1135 * 1136 * <em>This function is not available in QD3D.</em> 1137 * 1138 * @param theTransform The camera transform object to query. 1139 * @param theData Receives thedata for the transform object. 1140 * @result Success or failure of the operation. 1141 */ 1142 #if QUESA_ALLOW_QD3D_EXTENSIONS 1143 1144 Q3_EXTERN_API_C ( TQ3Status ) 1145 Q3CameraTransform_Get ( 1146 TQ3TransformObject theTransform, 1147 TQ3CameraTransformData *theData 1148 ); 1149 1150 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 1151 1152 1153 1154 /*! 1155 * @function 1156 * Q3RasterizeCameraTransform_New 1157 * @discussion 1158 * Create a new rasterize camera transform object. 1159 * 1160 * A rasterize camera object is a camera transform object which 1161 * adjusts the camera to allow rasterizing to a draw context. 1162 * 1163 * When this type of transform is active, x and y vertex coordinates 1164 * reflect pixel (or sub-pixel) coordinates. The z coordinate ranges 1165 * from 0.0 to 1.0 (where 0.0 is the front of the scene, and 1.0 is 1166 * the back). 1167 * 1168 * The x/y coordinate system matches that of the draw context being 1169 * rendered to when the transform is submitted. The origin is placed 1170 * at the top left of the draw context, while the dimensions of the 1171 * draw context provide the coordinates of the bottom right "pixel". 1172 * 1173 * Any geometry type or rendering state may be submitted while this 1174 * transform is active, however some renderers may require transparent 1175 * objects to be sorted manually to their correct position within 1176 * the scene. 1177 * 1178 * <em>This function is not available in QD3D.</em> 1179 * 1180 * @result A new camera transform object, or NULL on failure. 1181 */ 1182 #if QUESA_ALLOW_QD3D_EXTENSIONS 1183 1184 Q3_EXTERN_API_C ( TQ3TransformObject ) 1185 Q3RasterizeCameraTransform_New ( 1186 void 1187 ); 1188 1189 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 1190 1191 1192 1193 /*! 1194 * @function 1195 * Q3RasterizeCameraTransform_Submit 1196 * @discussion 1197 * Submit a rasterize camera transform in immediate mode. Should only 1198 * be called within a submitting loop. 1199 * 1200 * <em>This function is not available in QD3D.</em> 1201 * 1202 * @param theView The view currently being submitted to. 1203 * @result Success or failure of the operation. 1204 */ 1205 #if QUESA_ALLOW_QD3D_EXTENSIONS 1206 1207 Q3_EXTERN_API_C ( TQ3Status ) 1208 Q3RasterizeCameraTransform_Submit ( 1209 TQ3ViewObject theView 1210 ); 1211 1212 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 1213 1214 1215 1216 1217 1218 //============================================================================= 1219 // C++ postamble 1220 //----------------------------------------------------------------------------- 1221 #ifdef __cplusplus 1222 } 1223 #endif 1224 1225 #endif 1226 1227 1228