1 /*! @header QuesaGroup.h 2 Declares the Quesa group objects. 3 */ 4 /* NAME: 5 QuesaGroup.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_GROUP_HDR 47 #define QUESA_GROUP_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 53 // Disable QD3D header 54 #if defined(__QD3DGROUP__) 55 #error 56 #endif 57 58 #define __QD3DGROUP__ 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 // Constants 77 //----------------------------------------------------------------------------- 78 /*! 79 * @enum 80 * TQ3DisplayGroupStateMasks 81 * @discussion 82 * Group traversal state. 83 * 84 * A group's traversal state is set with Q3DisplayGroup_SetState, and 85 * controls how the group is processed when submitted for rendering, 86 * picking, bounding, or writing. 87 * 88 * @constant kQ3DisplayGroupStateNone No value. 89 * @constant kQ3DisplayGroupStateMaskIsDrawn The group will be submitted during rendering or picking. 90 * @constant kQ3DisplayGroupStateMaskIsInline The group will be submited without pushing/popping the 91 * view state stack around the group contents. 92 * @constant kQ3DisplayGroupStateMaskUseBoundingBox The bounding box is used for culling when rendering. 93 * @constant kQ3DisplayGroupStateMaskUseBoundingSphere The bounding sphere is used for culling when rendering. 94 * @constant kQ3DisplayGroupStateMaskIsPicked The group will be eligible for returning during picking. 95 * @constant kQ3DisplayGroupStateMaskIsWritten The group will be submitted during writing. 96 * @constant kQ3DisplayGroupStateMaskIsNotForBounding The group will not be submitted during bounding. 97 * (Not in QD3D.) 98 */ 99 typedef enum { 100 kQ3DisplayGroupStateNone = 0, 101 kQ3DisplayGroupStateMaskIsDrawn = (1 << 0), 102 kQ3DisplayGroupStateMaskIsInline = (1 << 1), 103 kQ3DisplayGroupStateMaskUseBoundingBox = (1 << 2), 104 kQ3DisplayGroupStateMaskUseBoundingSphere = (1 << 3), 105 kQ3DisplayGroupStateMaskIsPicked = (1 << 4), 106 kQ3DisplayGroupStateMaskIsWritten = (1 << 5), 107 108 #if QUESA_ALLOW_QD3D_EXTENSIONS 109 kQ3DisplayGroupStateMaskIsNotForBounding = (1 << 6), 110 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 111 112 kQ3DisplayGroupStateMaskSize32 = 0xFFFFFFFF 113 } TQ3DisplayGroupStateMasks; 114 115 116 // Group method types 117 enum { 118 kQ3XMethodType_GroupAcceptObject = Q3_METHOD_TYPE('g', 'a', 'c', 'o'), 119 kQ3XMethodType_GroupAddObject = Q3_METHOD_TYPE('g', 'a', 'd', 'o'), 120 kQ3XMethodType_GroupAddObjectBefore = Q3_METHOD_TYPE('g', 'a', 'o', 'b'), 121 kQ3XMethodType_GroupAddObjectAfter = Q3_METHOD_TYPE('g', 'a', 'o', 'a'), 122 kQ3XMethodType_GroupSetPositionObject = Q3_METHOD_TYPE('g', 's', 'p', 'o'), 123 kQ3XMethodType_GroupRemovePosition = Q3_METHOD_TYPE('g', 'r', 'm', 'p'), 124 kQ3XMethodType_GroupGetFirstPositionOfType = Q3_METHOD_TYPE('g', 'f', 'r', 't'), 125 kQ3XMethodType_GroupGetLastPositionOfType = Q3_METHOD_TYPE('g', 'l', 's', 't'), 126 kQ3XMethodType_GroupGetNextPositionOfType = Q3_METHOD_TYPE('g', 'n', 'x', 't'), 127 kQ3XMethodType_GroupGetPrevPositionOfType = Q3_METHOD_TYPE('g', 'p', 'v', 't'), 128 kQ3XMethodType_GroupCountObjectsOfType = Q3_METHOD_TYPE('g', 'c', 'n', 't'), 129 kQ3XMethodType_GroupEmptyObjectsOfType = Q3_METHOD_TYPE('g', 'e', 'o', 't'), 130 kQ3XMethodType_GroupGetFirstObjectPosition = Q3_METHOD_TYPE('g', 'f', 'o', 'p'), 131 kQ3XMethodType_GroupGetLastObjectPosition = Q3_METHOD_TYPE('g', 'l', 'o', 'p'), 132 kQ3XMethodType_GroupGetNextObjectPosition = Q3_METHOD_TYPE('g', 'n', 'o', 'p'), 133 kQ3XMethodType_GroupGetPrevObjectPosition = Q3_METHOD_TYPE('g', 'p', 'o', 'p'), 134 kQ3XMethodType_GroupPositionSize = Q3_METHOD_TYPE('g', 'g', 'p', 'z'), 135 kQ3XMethodType_GroupPositionNew = Q3_METHOD_TYPE('g', 'g', 'p', 'n'), 136 kQ3XMethodType_GroupPositionCopy = Q3_METHOD_TYPE('g', 'g', 'p', 'c'), 137 kQ3XMethodType_GroupPositionDelete = Q3_METHOD_TYPE('g', 'g', 'p', 'd'), 138 kQ3XMethodType_GroupStartIterate = Q3_METHOD_TYPE('g', 's', 't', 'd'), 139 kQ3XMethodType_GroupEndIterate = Q3_METHOD_TYPE('g', 'i', 't', 'd'), 140 kQ3XMethodType_GroupEndRead = Q3_METHOD_TYPE('g', 'e', 'r', 'd') 141 }; 142 143 144 145 146 147 //============================================================================= 148 // Types 149 //----------------------------------------------------------------------------- 150 // Display group state 151 typedef TQ3Uns32 TQ3DisplayGroupState; 152 153 154 // Group methods 155 typedef Q3_CALLBACK_API_C(TQ3Boolean, TQ3XGroupAcceptObjectMethod)( 156 TQ3GroupObject theGroup, 157 TQ3Object theObject); 158 159 typedef Q3_CALLBACK_API_C(TQ3GroupPosition, TQ3XGroupAddObjectMethod)( 160 TQ3GroupObject theGroup, 161 TQ3Object theObject); 162 163 typedef Q3_CALLBACK_API_C(TQ3GroupPosition, TQ3XGroupAddObjectBeforeMethod)( 164 TQ3GroupObject theGroup, 165 TQ3GroupPosition thePosition, 166 TQ3Object theObject); 167 168 typedef Q3_CALLBACK_API_C(TQ3GroupPosition, TQ3XGroupAddObjectAfterMethod)( 169 TQ3GroupObject theGroup, 170 TQ3GroupPosition thePosition, 171 TQ3Object theObject); 172 173 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupSetPositionObjectMethod)( 174 TQ3GroupObject theGroup, 175 TQ3GroupPosition thePosition, 176 TQ3Object theObject); 177 178 typedef Q3_CALLBACK_API_C(TQ3Object, TQ3XGroupRemovePositionMethod)( 179 TQ3GroupObject theGroup, 180 TQ3GroupPosition thePosition); 181 182 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetFirstPositionOfTypeMethod)( 183 TQ3GroupObject theGroup, 184 TQ3ObjectType theType, 185 TQ3GroupPosition *thePosition); 186 187 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetLastPositionOfTypeMethod)( 188 TQ3GroupObject theGroup, 189 TQ3ObjectType theType, 190 TQ3GroupPosition *thePosition); 191 192 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetNextPositionOfTypeMethod)( 193 TQ3GroupObject theGroup, 194 TQ3ObjectType theType, 195 TQ3GroupPosition *thePosition); 196 197 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetPrevPositionOfTypeMethod)( 198 TQ3GroupObject theGroup, 199 TQ3ObjectType theType, 200 TQ3GroupPosition *thePosition); 201 202 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupCountObjectsOfTypeMethod)( 203 TQ3GroupObject theGroup, 204 TQ3ObjectType theType, 205 TQ3Uns32 *numObjects); 206 207 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupEmptyObjectsOfTypeMethod)( 208 TQ3GroupObject theGroup, 209 TQ3ObjectType theType); 210 211 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetFirstObjectPositionMethod)( 212 TQ3GroupObject theGroup, 213 TQ3Object theObject, 214 TQ3GroupPosition *thePosition); 215 216 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetLastObjectPositionMethod)( 217 TQ3GroupObject theGroup, 218 TQ3Object theObject, 219 TQ3GroupPosition *thePosition); 220 221 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetNextObjectPositionMethod)( 222 TQ3GroupObject theGroup, 223 TQ3Object theObject, 224 TQ3GroupPosition *thePosition); 225 226 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupGetPrevObjectPositionMethod)( 227 TQ3GroupObject theGroup, 228 TQ3Object theObject, 229 TQ3GroupPosition *thePosition); 230 231 typedef TQ3Uns32 TQ3XMethodTypeGroupPositionSize; 232 233 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupPositionNewMethod)( 234 void *thePosition, 235 TQ3Object theObject, 236 const void *initData); 237 238 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupPositionCopyMethod)( 239 void *srcPosition, 240 void *dstPosition); 241 242 typedef Q3_CALLBACK_API_C(void, TQ3XGroupPositionDeleteMethod)( 243 void *thePosition); 244 245 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupStartIterateMethod)( 246 TQ3GroupObject theGroup, 247 TQ3GroupPosition *thePosition, 248 TQ3Object *theObject, 249 TQ3ViewObject theView); 250 251 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupEndIterateMethod)( 252 TQ3GroupObject theGroup, 253 TQ3GroupPosition *thePosition, 254 TQ3Object *theObject, 255 TQ3ViewObject theView); 256 257 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XGroupEndReadMethod)( 258 TQ3GroupObject theGroup); 259 260 261 262 263 264 //============================================================================= 265 // Function prototypes 266 //----------------------------------------------------------------------------- 267 /*! 268 * @function 269 * Q3Group_New 270 * @discussion 271 * Create a new generic group. 272 * 273 * This function returns a newly created, empty Group object. If 274 * some error occurs during creation, this returns NULL. 275 * 276 * @result Newly created group, or NULL. 277 */ 278 Q3_EXTERN_API_C ( TQ3GroupObject ) 279 Q3Group_New ( 280 void 281 ); 282 283 284 285 /*! 286 * @function 287 * Q3Group_GetType 288 * @discussion 289 * Return the type of a group. 290 * 291 * This function returns the group type, as an enum such as 292 * kQ3GroupTypeDisplay, kQ3GroupTypeInfo, or kQ3GroupTypeLight. 293 * (Returns kQ3ObjectTypeInvalid if the type cannot be determined.) 294 * 295 * @param group Group to inspect. 296 * @result Type of that group. 297 */ 298 Q3_EXTERN_API_C ( TQ3ObjectType ) 299 Q3Group_GetType ( 300 TQ3GroupObject group 301 ); 302 303 304 305 /*! 306 * @function 307 * Q3Group_AddObject 308 * @discussion 309 * Append an object to a group. 310 * 311 * If the group is unordered (which really means unsorted), the 312 * object is appended to the end of the group. If it is ordered 313 * (i.e. sorted), it is appended to the end of the subset of 314 * objects in the group of the same type as the given <code>object</code>. 315 * 316 * The group increments the object's reference count, so you can safely 317 * dispose of your own reference if you no longer need it. 318 * 319 * If for some reason the object cannot be appended, this function 320 * returns NULL. 321 * 322 * @param group Group to add an object to. 323 * @param object Object to be added. 324 * @result Resulting position of <code>object</code> in <code>group</code>. 325 */ 326 Q3_EXTERN_API_C ( TQ3GroupPosition ) 327 Q3Group_AddObject ( 328 TQ3GroupObject group, 329 TQ3Object object 330 ); 331 332 333 334 /*! 335 * @function 336 * Q3Group_AddObjectAndDispose 337 * @discussion 338 * Add an object to a group, and then dispose of it. 339 * 340 * If theObject is not NULL, invokes Q3Group_AddObject to add the object to 341 * the group, disposes of the object, then clears the supplied pointer to 342 * prevent stale references. 343 * 344 * Equivalent to: 345 * 346 * if (theObject != NULL) 347 * { 348 * Q3Group_AddObject(theGroup, theObject); 349 * Q3Object_Dispose(theObject); 350 * theObject = NULL; 351 * } 352 * 353 * <em>This function is not available in QD3D.</em> 354 * 355 * @param theGroup The group to add the object to. 356 * @param theObject The object to add (may be NULL). 357 * @result Success or failure of the operation. 358 */ 359 #if QUESA_ALLOW_QD3D_EXTENSIONS 360 361 Q3_EXTERN_API_C ( TQ3GroupPosition ) 362 Q3Group_AddObjectAndDispose ( 363 TQ3GroupObject theGroup, 364 TQ3Object *theObject 365 ); 366 367 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 368 369 370 371 /*! 372 * @function 373 * Q3Group_AddObjectBefore 374 * @discussion 375 * Insert an object into a group before a specified position. 376 * 377 * This function adds an object to a group, before the object at the 378 * specified position. 379 * 380 * The group increments the object's reference count, so you can safely 381 * dispose of your own reference if you no longer need it. 382 * 383 * If for some reason the object cannot be appended, this function 384 * returns NULL. 385 * 386 * @param group Group to add an object to. 387 * @param position Position before which to add the object. 388 * @param object Object to be added. 389 * @result Resulting position of <code>object</code> in <code>group</code>. 390 */ 391 Q3_EXTERN_API_C ( TQ3GroupPosition ) 392 Q3Group_AddObjectBefore ( 393 TQ3GroupObject group, 394 TQ3GroupPosition position, 395 TQ3Object object 396 ); 397 398 399 400 /*! 401 * @function 402 * Q3Group_AddObjectAfter 403 * @discussion 404 * Insert an object into a group after a specified position. 405 * 406 * This function adds an object to a group, just after the object at the 407 * specified position. 408 * 409 * The group increments the object's reference count, so you can safely 410 * dispose of your own reference if you no longer need it. 411 * 412 * If for some reason the object cannot be appended, this function 413 * returns NULL. 414 * 415 * @param group Group to add an object to. 416 * @param position Position after which to add the object. 417 * @param object Object to be added. 418 * @result Resulting position of <code>object</code> in <code>group</code>. 419 */ 420 Q3_EXTERN_API_C ( TQ3GroupPosition ) 421 Q3Group_AddObjectAfter ( 422 TQ3GroupObject group, 423 TQ3GroupPosition position, 424 TQ3Object object 425 ); 426 427 428 429 /*! 430 * @function 431 * Q3Group_GetPositionObject 432 * @discussion 433 * Get the object located at a certain position in a group. 434 * 435 * This function obtains a reference to the group member at a 436 * specified position. Note that the reference count of the 437 * object is incremented, so you must dispose of this reference 438 * when you no longer need it. 439 * 440 * Sets *object to NULL if there is no object at the given position. 441 * 442 * @param group Group to inspect. 443 * @param position Position of desired object. 444 * @param object Receives a reference to the indicated object. 445 * @result Success or failure of the operation. 446 */ 447 Q3_EXTERN_API_C ( TQ3Status ) 448 Q3Group_GetPositionObject ( 449 TQ3GroupObject group, 450 TQ3GroupPosition position, 451 TQ3Object *object 452 ); 453 454 455 456 /*! 457 * @function 458 * Q3Group_SetPositionObject 459 * @discussion 460 * Sets the object at a specified position in a group. 461 * 462 * This function replaces a member of a group. The reference to 463 * the object previously at the specified position is disposed of, 464 * and a reference to the given object is stored in its place. 465 * 466 * The group increments the object's reference count, so you can safely 467 * dispose of your own reference if you no longer need it. 468 * 469 * If for some reason the object cannot be appended, this function 470 * returns NULL. 471 * 472 * @param group Group to replace an object in. 473 * @param position Position of object to replace. 474 * @param object Object to be stored. 475 * @result Success or failure of the operation. 476 */ 477 Q3_EXTERN_API_C ( TQ3Status ) 478 Q3Group_SetPositionObject ( 479 TQ3GroupObject group, 480 TQ3GroupPosition position, 481 TQ3Object object 482 ); 483 484 485 486 /*! 487 * @function 488 * Q3Group_RemovePosition 489 * @discussion 490 * Remove an object from a group. 491 * 492 * This function deletes an object reference from a group, returning it to 493 * the caller. Note that if you don't need the object, you must dispose 494 * of the returned reference; otherwise it will leak. 495 * 496 * After this function successfully completes, <code>position</code> 497 * is invalid. 498 * 499 * @param group Group to remove an object from. 500 * @param position Position of object to remove. 501 * @result Object that was removed. 502 */ 503 Q3_EXTERN_API_C ( TQ3Object ) 504 Q3Group_RemovePosition ( 505 TQ3GroupObject group, 506 TQ3GroupPosition position 507 ); 508 509 510 511 /*! 512 * @function 513 * Q3Group_GetFirstPosition 514 * @discussion 515 * Get the first position in a group. 516 * 517 * This can be used in conjunction with <code>Q3Group_GetNextPosition</code> 518 * to iterate over all members of a group. 519 * 520 * @param group Group of interest. 521 * @param position Receives the position of the first object in <code>group</code>. 522 * @result Success or failure of the operation. 523 */ 524 Q3_EXTERN_API_C ( TQ3Status ) 525 Q3Group_GetFirstPosition ( 526 TQ3GroupObject group, 527 TQ3GroupPosition *position 528 ); 529 530 531 532 /*! 533 * @function 534 * Q3Group_GetLastPosition 535 * @discussion 536 * Get the last position in a group. 537 * 538 * This can be used in conjunction with <code>Q3Group_GetPreviousPosition</code> 539 * to iterate backwards over all members of a group. 540 * 541 * @param group Group of interest. 542 * @param position Receives the position of the last object in <code>group</code>. 543 * @result Success or failure of the operation. 544 */ 545 Q3_EXTERN_API_C ( TQ3Status ) 546 Q3Group_GetLastPosition ( 547 TQ3GroupObject group, 548 TQ3GroupPosition *position 549 ); 550 551 552 553 /*! 554 * @function 555 * Q3Group_GetNextPosition 556 * @discussion 557 * Advance to the next position in a group. 558 * 559 * This function updates <code>position</code> to refer to the 560 * next position in the group. If there are no further objects 561 * in the group, <code>*position</code> is set to NULL. 562 * 563 * @param group Group of interest. 564 * @param position Address of position to advance. 565 * @result Success or failure of the operation. 566 */ 567 Q3_EXTERN_API_C ( TQ3Status ) 568 Q3Group_GetNextPosition ( 569 TQ3GroupObject group, 570 TQ3GroupPosition *position 571 ); 572 573 574 575 /*! 576 * @function 577 * Q3Group_GetPreviousPosition 578 * @discussion 579 * Step back to the previous position in a group. 580 * 581 * This function updates <code>position</code> to refer to the 582 * previous position in the group. If the given position was 583 * already on the first object in the group, <code>*position</code> 584 * is set to NULL. 585 * 586 * @param group Group of interest. 587 * @param position Address of position to step back. 588 * @result Success or failure of the operation. 589 */ 590 Q3_EXTERN_API_C ( TQ3Status ) 591 Q3Group_GetPreviousPosition ( 592 TQ3GroupObject group, 593 TQ3GroupPosition *position 594 ); 595 596 597 598 /*! 599 * @function 600 * Q3Group_CountObjects 601 * @discussion 602 * Determine how many objects are in a group. 603 * 604 * Note that subgroups (groups within the given group) count as 605 * only one object each; this function does not recurse into them 606 * to get the total number of objects in the hierarchy. 607 * 608 * @param group Group to inspect. 609 * @param nObjects Address of integer to receive the object count. 610 * @result Success or failure of the operation. 611 */ 612 Q3_EXTERN_API_C ( TQ3Status ) 613 Q3Group_CountObjects ( 614 TQ3GroupObject group, 615 TQ3Uns32 *nObjects 616 ); 617 618 619 620 /*! 621 * @function 622 * Q3Group_EmptyObjects 623 * @discussion 624 * Remove all object references from the group. 625 * 626 * Call this function to dispose of all object references in the given 627 * group. (The group itself is not disposed of.) 628 * 629 * @param group Group to empty. 630 * @result Success or failure of the operation. 631 */ 632 Q3_EXTERN_API_C ( TQ3Status ) 633 Q3Group_EmptyObjects ( 634 TQ3GroupObject group 635 ); 636 637 638 639 /*! 640 * @function 641 * Q3Group_GetFirstPositionOfType 642 * @discussion 643 * Get the position of the first object of a given type. 644 * 645 * This can be used in conjunction with <code>Q3Group_GetNextPositionOfType</code> 646 * to iterate over all group members of a certain type. 647 * 648 * @param group Group of interest. 649 * @param isType Desired object type. 650 * @param position Receives the position of the first object of that type. 651 * @result Success or failure of the operation. 652 */ 653 Q3_EXTERN_API_C ( TQ3Status ) 654 Q3Group_GetFirstPositionOfType ( 655 TQ3GroupObject group, 656 TQ3ObjectType isType, 657 TQ3GroupPosition *position 658 ); 659 660 661 662 /*! 663 * @function 664 * Q3Group_GetLastPositionOfType 665 * @discussion 666 * Get the position of the last object of a given type. 667 * 668 * This can be used in conjunction with <code>Q3Group_GetPreviousPositionOfType</code> 669 * to iterate backwards over all group members of a certain type. 670 * 671 * @param group Group of interest. 672 * @param isType Desired object type. 673 * @param position Receives the position of the last object of that type. 674 * @result Success or failure of the operation. 675 */ 676 Q3_EXTERN_API_C ( TQ3Status ) 677 Q3Group_GetLastPositionOfType ( 678 TQ3GroupObject group, 679 TQ3ObjectType isType, 680 TQ3GroupPosition *position 681 ); 682 683 684 685 /*! 686 * @function 687 * Q3Group_GetNextPositionOfType 688 * @discussion 689 * Advance to the position of the next object of a certain type. 690 * 691 * This function updates <code>position</code> to refer to the 692 * next position in the group of an object of the given type. 693 * If there are no further objects of that type 694 * in the group, <code>*position</code> is set to NULL. 695 * 696 * @param group Group of interest. 697 * @param isType Desired object type. 698 * @param position Address of position to advance. 699 * @result Success or failure of the operation. 700 */ 701 Q3_EXTERN_API_C ( TQ3Status ) 702 Q3Group_GetNextPositionOfType ( 703 TQ3GroupObject group, 704 TQ3ObjectType isType, 705 TQ3GroupPosition *position 706 ); 707 708 709 710 /*! 711 * @function 712 * Q3Group_GetPreviousPositionOfType 713 * @discussion 714 * Step back to the position of the previous object of a certain type. 715 * 716 * This function updates <code>position</code> to refer to the 717 * previous position in the group of an object of the given type. 718 * If there are no previous objects of that type 719 * in the group, <code>*position</code> is set to NULL. 720 * 721 * @param group Group of interest. 722 * @param isType Desired object type. 723 * @param position Address of position to step back. 724 * @result Success or failure of the operation. 725 */ 726 Q3_EXTERN_API_C ( TQ3Status ) 727 Q3Group_GetPreviousPositionOfType ( 728 TQ3GroupObject group, 729 TQ3ObjectType isType, 730 TQ3GroupPosition *position 731 ); 732 733 734 735 /*! 736 * @function 737 * Q3Group_CountObjectsOfType 738 * @discussion 739 * Determine how many objects of a certain type are in a group. 740 * 741 * Note that subgroups (groups within the given group) count as 742 * only one object each; this function does not recurse into them 743 * to consider the entire hierarchy. 744 * 745 * @param group Group to inspect. 746 * @param isType Object type. 747 * @param nObjects Address of integer to receive the object count. 748 * @result Success or failure of the operation. 749 */ 750 Q3_EXTERN_API_C ( TQ3Status ) 751 Q3Group_CountObjectsOfType ( 752 TQ3GroupObject group, 753 TQ3ObjectType isType, 754 TQ3Uns32 *nObjects 755 ); 756 757 758 759 /*! 760 * @function 761 * Q3Group_EmptyObjectsOfType 762 * @discussion 763 * Remove all objects of a particular type from a group. 764 * 765 * Call this function to dispose of all object references of a certain 766 * type in the given group. (The group itself is not disposed of, 767 * even if this call leaves it empty.) 768 * 769 * @param group Group to operate on. 770 * @param isType Type of objects to dispose. 771 * @result Success or failure of the operation. 772 */ 773 Q3_EXTERN_API_C ( TQ3Status ) 774 Q3Group_EmptyObjectsOfType ( 775 TQ3GroupObject group, 776 TQ3ObjectType isType 777 ); 778 779 780 781 /*! 782 * @function 783 * Q3Group_GetFirstObjectPosition 784 * @discussion 785 * Get the first position of an object within a group. 786 * 787 * An object may be referenced a group multiple times. Use this function 788 * to find the first position of the first reference to the given object. 789 * You could then use <code>Q3Group_GetNextObjectPosition</code> to 790 * iterate over all other references to the same object. 791 * 792 * @param group Group to inspect. 793 * @param object Desired object. 794 * @param position Receives first position of <code>object</code> in <code>group</code>. 795 * @result Success or failure of the operation. 796 */ 797 Q3_EXTERN_API_C ( TQ3Status ) 798 Q3Group_GetFirstObjectPosition ( 799 TQ3GroupObject group, 800 TQ3Object object, 801 TQ3GroupPosition *position 802 ); 803 804 805 806 /*! 807 * @function 808 * Q3Group_GetLastObjectPosition 809 * @discussion 810 * Get the last position of an object within a group. 811 * 812 * An object may be referenced a group multiple times. Use this function 813 * to find the last position of the first reference to the given object. 814 * You could then use <code>Q3Group_GetPreviousObjectPosition</code> to 815 * iterate backwards over all other references to the same object. 816 * 817 * @param group Group to inspect. 818 * @param object Desired object. 819 * @param position Receives last position of <code>object</code> in <code>group</code>. 820 * @result Success or failure of the operation. 821 */ 822 Q3_EXTERN_API_C ( TQ3Status ) 823 Q3Group_GetLastObjectPosition ( 824 TQ3GroupObject group, 825 TQ3Object object, 826 TQ3GroupPosition *position 827 ); 828 829 830 831 /*! 832 * @function 833 * Q3Group_GetNextObjectPosition 834 * @discussion 835 * Advance to the position of the next reference to a given object 836 * within a group. If the given object does not occur again within 837 * the group, <code>*position</code> is set to NULL. 838 * 839 * Use this in conjunction with <code>Q3Group_GetFirstObjectPosition</code> 840 * to iterate over all occurrences of an object within a group. 841 * 842 * @param group Group to inspect. 843 * @param object Desired object. 844 * @param position Position to advance to the next occurrence of <code>object</code>. 845 * @result Success or failure of the operation. 846 */ 847 Q3_EXTERN_API_C ( TQ3Status ) 848 Q3Group_GetNextObjectPosition ( 849 TQ3GroupObject group, 850 TQ3Object object, 851 TQ3GroupPosition *position 852 ); 853 854 855 856 /*! 857 * @function 858 * Q3Group_GetPreviousObjectPosition 859 * @discussion 860 * Step back to the position of the previous reference to a given object 861 * within a group. If there is no previous reference to that object within 862 * the group, <code>*position</code> is set to NULL. 863 * 864 * Use this in conjunction with <code>Q3Group_GetLastObjectPosition</code> 865 * to iterate in reverse over all occurrences of an object within a group. 866 * 867 * @param group Group to inspect. 868 * @param object Desired object. 869 * @param position Position to step back to the previous occurrence of <code>object</code>. 870 * @result Success or failure of the operation. 871 */ 872 Q3_EXTERN_API_C ( TQ3Status ) 873 Q3Group_GetPreviousObjectPosition ( 874 TQ3GroupObject group, 875 TQ3Object object, 876 TQ3GroupPosition *position 877 ); 878 879 880 881 /*! 882 * @function 883 * Q3LightGroup_New 884 * @discussion 885 * Create a new light group. 886 * 887 * A light group is a group that contains only lights. These can then 888 * be attached to a view by <code>Q3View_SetLightGroup</code>. 889 * 890 * This function returns a newly created, empty light group object. If 891 * some error occurs during creation, this returns NULL. 892 * 893 * @result Newly created light group, or NULL. 894 */ 895 Q3_EXTERN_API_C ( TQ3GroupObject ) 896 Q3LightGroup_New ( 897 void 898 ); 899 900 901 902 /*! 903 * @function 904 * Q3InfoGroup_New 905 * @discussion 906 * Create a new information group. 907 * 908 * This function returns a newly created, empty information group 909 * object. If some error occurs during creation, this returns NULL. 910 * 911 * @result Newly created information group, or NULL. 912 */ 913 Q3_EXTERN_API_C ( TQ3GroupObject ) 914 Q3InfoGroup_New ( 915 void 916 ); 917 918 919 920 /*! 921 * @function 922 * Q3DisplayGroup_New 923 * @discussion 924 * Create a new display group. 925 * 926 * A display group contains objects that are drawable: geometry, styles, 927 * transforms, attributes and attribute sets, and other display groups. 928 * A display group can be rendered by calling <code>Q3DisplayGroup_Submit</code> 929 * within the rendering loop. 930 * 931 * This function returns a newly created, empty display group object. 932 * If some error occurs during creation, this returns NULL. 933 * 934 * See also <code>Q3OrderedDisplayGroup_New</code> and <code>Q3IOProxyDisplayGroup_New</code>. 935 * 936 * @result Newly created group, or NULL. 937 */ 938 Q3_EXTERN_API_C ( TQ3GroupObject ) 939 Q3DisplayGroup_New ( 940 void 941 ); 942 943 944 945 /*! 946 * @function 947 * Q3DisplayGroup_GetType 948 * @discussion 949 * Get the specific type of a display group. 950 * 951 * The result will be <code>kQ3DisplayGroupTypeOrdered</code> for an ordered display 952 * group, <code>kQ3DisplayGroupTypeIOProxy</code> for an I/O Proxy group, and 953 * <code>kQ3GroupTypeDisplay</code> for a generic display group. 954 * <code>kQ3ObjectTypeInvalid</code> is returned if there is some error. 955 * 956 * @param group The group to query. 957 * @result The type of the group. 958 */ 959 Q3_EXTERN_API_C ( TQ3ObjectType ) 960 Q3DisplayGroup_GetType ( 961 TQ3GroupObject group 962 ); 963 964 965 966 /*! 967 * @function 968 * Q3DisplayGroup_GetState 969 * @discussion 970 * Get the state flags of a display group. 971 * 972 * The display group state flags affect its behavior with regard to 973 * rendering, picking, and computation of a bounding box or sphere. 974 * 975 * <code>kQ3DisplayGroupStateNone</code>: no flags are set. 976 * <code>kQ3DisplayGroupStateMaskIsDrawn</code>: if set, the group 977 * is processed for rendering or picking; if clear, it is skipped. 978 * <code>kQ3DisplayGroupStateMaskIsInline</code>: if set, the group is processed 979 * without pushing and popping the graphics state. 980 * <code>kQ3DisplayGroupStateMaskUseBoundingBox</code>: if set, the bounding box 981 * of the group is used during rendering. 982 * <code>kQ3DisplayGroupStateMaskUseBoundingSphere</code>: if set, the bounding 983 * sphere of the group is used during rendering. 984 * <code>kQ3DisplayGroupStateMaskIsPicked</code>: if set, the group is eligible 985 * for picking. 986 * <code>kQ3DisplayGroupStateMaskIsWritten</code>: if set, the group is eligible 987 * for writing to a file. 988 * 989 * The default state has the IsDrawn, IsPicked, and IsWritten flags set; 990 * other flags are clear. 991 * 992 * @param group Group to inspect. 993 * @param state Receives the group's state flags. 994 * @result Success or failure of the operation. 995 */ 996 Q3_EXTERN_API_C ( TQ3Status ) 997 Q3DisplayGroup_GetState ( 998 TQ3GroupObject group, 999 TQ3DisplayGroupState *state 1000 ); 1001 1002 1003 1004 /*! 1005 * @function 1006 * Q3DisplayGroup_SetState 1007 * @discussion 1008 * Set the state flags of a display group. 1009 * 1010 * The display group state flags affect its behavior with regard to 1011 * rendering, picking, and computation of a bounding box or sphere. 1012 * 1013 * <code>kQ3DisplayGroupStateNone</code>: no flags are set. 1014 * <code>kQ3DisplayGroupStateMaskIsDrawn</code>: if set, the group 1015 * is processed for rendering or picking; if clear, it is skipped. 1016 * <code>kQ3DisplayGroupStateMaskIsInline</code>: if set, the group is processed 1017 * without pushing and popping the graphics state. 1018 * <code>kQ3DisplayGroupStateMaskUseBoundingBox</code>: if set, the bounding box 1019 * of the group is used during rendering. 1020 * <code>kQ3DisplayGroupStateMaskUseBoundingSphere</code>: if set, the bounding 1021 * sphere of the group is used during rendering. 1022 * <code>kQ3DisplayGroupStateMaskIsPicked</code>: if set, the group is eligible 1023 * for picking. 1024 * <code>kQ3DisplayGroupStateMaskIsWritten</code>: if set, the group is eligible 1025 * for writing to a file. 1026 * 1027 * The default state has the IsDrawn, IsPicked, and IsWritten flags set; 1028 * other flags are clear. 1029 * 1030 * @param group Group on which to adjust state flags. 1031 * @param state Desired state flags. 1032 * @result Success or failure of the operation. 1033 */ 1034 Q3_EXTERN_API_C ( TQ3Status ) 1035 Q3DisplayGroup_SetState ( 1036 TQ3GroupObject group, 1037 TQ3DisplayGroupState state 1038 ); 1039 1040 1041 1042 /*! 1043 * @function 1044 * Q3DisplayGroup_Submit 1045 * @discussion 1046 * Submit a display group. 1047 * 1048 * This group is used within an appropriate submitting loop on a view 1049 * to render, pick, bound, or write the contents of the group. 1050 * 1051 * Note: QD3D would also let you get away with submitting a group for 1052 * rendering by calling Q3Geometry_Submit. But this is not valid; 1053 * a group (even a display group) is not a type of geometry. Quesa 1054 * is less lenient in this regard, so you should collect your drawable 1055 * objects in a display group, and submit them with this function. 1056 * 1057 * @param group Display group to submit. 1058 * @param view View (which must be in a submitting loop). 1059 * @result Success or failure of the operation. 1060 */ 1061 Q3_EXTERN_API_C ( TQ3Status ) 1062 Q3DisplayGroup_Submit ( 1063 TQ3GroupObject group, 1064 TQ3ViewObject view 1065 ); 1066 1067 1068 1069 /*! 1070 * @function 1071 * Q3DisplayGroup_SetAndUseBoundingBox 1072 * @discussion 1073 * Sets a bounding box for a display group. 1074 * 1075 * This function assigns the given bounding box to the display group. It 1076 * also sets the <code>kQ3DisplayGroupStateMaskUseBoundingBox</code> flag 1077 * on the group state, telling Quesa that the bounding box should be used 1078 * for culling. 1079 * 1080 * @param group Group on which to set a bounding box. 1081 * @param bBox Bounding box to use (must be non-empty). 1082 * @result Success or failure of the operation. 1083 */ 1084 Q3_EXTERN_API_C ( TQ3Status ) 1085 Q3DisplayGroup_SetAndUseBoundingBox ( 1086 TQ3GroupObject group, 1087 TQ3BoundingBox *bBox 1088 ); 1089 1090 1091 1092 /*! 1093 * @function 1094 * Q3DisplayGroup_GetBoundingBox 1095 * @discussion 1096 * Get the bounding box of a group. 1097 * 1098 * This function retrieves the bounding box of a group, if one has 1099 * been set or calculated. If not, kQ3Failure is returned. 1100 * 1101 * @param group Group to inspect. 1102 * @param bBox Address of bounding box to set with group's bounding box. 1103 * @result Success or failure of the operation. 1104 */ 1105 Q3_EXTERN_API_C ( TQ3Status ) 1106 Q3DisplayGroup_GetBoundingBox ( 1107 TQ3GroupObject group, 1108 TQ3BoundingBox *bBox 1109 ); 1110 1111 1112 1113 /*! 1114 * @function 1115 * Q3DisplayGroup_RemoveBoundingBox 1116 * @discussion 1117 * Remove the bounding box from a group. 1118 * 1119 * If the given group had an assigned or calculated bounding box, 1120 * this function removes it and clears the <code>kQ3DisplayGroupStateMaskUseBoundingBox</code> 1121 * flag. If not, it does nothing (and returns <code>kQ3Success</code> anyway). 1122 * 1123 * @param group Group to remove the bounding box of. 1124 * @result Success or failure of the operation. 1125 */ 1126 Q3_EXTERN_API_C ( TQ3Status ) 1127 Q3DisplayGroup_RemoveBoundingBox ( 1128 TQ3GroupObject group 1129 ); 1130 1131 1132 1133 /*! 1134 * @function 1135 * Q3DisplayGroup_CalcAndUseBoundingBox 1136 * @discussion 1137 * Calculate and use a bounding box on the given group. 1138 * 1139 * This function computes a bounding box that contains all the geometry 1140 * in the group. It then stores this box on the group, and sets the 1141 * <code>kQ3DisplayGroupStateMaskUseBoundingBox</code> flag 1142 * on the group state, telling Quesa that the bounding box should be used 1143 * for culling. 1144 * 1145 * The computed bounding box will be correct at the time of this call, 1146 * but if the group contents change, the bounding box is not automatically 1147 * updated. It is up to the application programmer to call this function 1148 * again or otherwise update the bounding box when the group changes. 1149 * 1150 * This function must not be called within a submitting loop. 1151 * 1152 * @param group Group for which a bounding box is to be calculated. 1153 * @param computeBounds Either <code>kQ3ComputeBoundsExact</code> (precise) or 1154 * <code>kQ3ComputeBoundsApproximate</code> (faster). 1155 * @param view View in which the group will ultimately be rendered. 1156 * @result Success or failure of the operation. 1157 */ 1158 Q3_EXTERN_API_C ( TQ3Status ) 1159 Q3DisplayGroup_CalcAndUseBoundingBox ( 1160 TQ3GroupObject group, 1161 TQ3ComputeBounds computeBounds, 1162 TQ3ViewObject view 1163 ); 1164 1165 1166 1167 /*! 1168 * @function 1169 * Q3OrderedDisplayGroup_New 1170 * @discussion 1171 * Create a new ordered display group. 1172 * 1173 * An ordered display group contains drawable objects (geometry, 1174 * transforms, attributes, etc.), and keeps them always sorted by 1175 * type. They are kept (and rendered) in this order: 1176 * 1177 * 1. transforms 1178 * 2. styles 1179 * 3. attribute sets 1180 * 4. shaders 1181 * 5. geometric objects 1182 * 6. groups 1183 * 7. unknown objects 1184 * 1185 * This ordering ensures that transforms, styles, attributes, and 1186 * shaders are applied to all of the geometric objects, groups, 1187 * and unknown objects in the group. 1188 * 1189 * This function returns a newly created, empty ordered display group. 1190 * If some error occurs during creation, this returns NULL. 1191 * 1192 * @result Newly created ordered display group, or NULL. 1193 */ 1194 Q3_EXTERN_API_C ( TQ3GroupObject ) 1195 Q3OrderedDisplayGroup_New ( 1196 void 1197 ); 1198 1199 1200 1201 /*! 1202 * @function 1203 * Q3IOProxyDisplayGroup_New 1204 * @discussion 1205 * Create a new generic group. 1206 * 1207 * An I/O proxy display group is a group that contains several alternate 1208 * representations of the same object, used for file input and output. 1209 * For example, if your object contains some advanced type of geometry 1210 * which some clients may not be able to support, you could use a 1211 * proxy display group to also provide simpler representations of the 1212 * model. You should put the alternate representations into the group 1213 * in order of preference; client applications will use the first entry 1214 * in the group which they can understand. 1215 * 1216 * This function returns a newly created, empty Group object. If 1217 * some error occurs during creation, this returns NULL. 1218 * 1219 * @result Newly created proxy display group, or NULL. 1220 */ 1221 Q3_EXTERN_API_C ( TQ3GroupObject ) 1222 Q3IOProxyDisplayGroup_New ( 1223 void 1224 ); 1225 1226 1227 1228 /*! 1229 * @function 1230 * Q3XGroup_GetPositionPrivate 1231 * @discussion 1232 * Get the private data stored in a group at the given position. 1233 * 1234 * This function returns private data, in the form of an untyped 1235 * pointer, which is stored in a group at the given position. 1236 * 1237 * @param group Group to inspect. 1238 * @param position Position of desired data. 1239 * @result Pointer to private data, or NULL. 1240 */ 1241 Q3_EXTERN_API_C ( void * ) 1242 Q3XGroup_GetPositionPrivate ( 1243 TQ3GroupObject group, 1244 TQ3GroupPosition position 1245 ); 1246 1247 1248 1249 1250 1251 //============================================================================= 1252 // C++ postamble 1253 //----------------------------------------------------------------------------- 1254 #ifdef __cplusplus 1255 } 1256 #endif 1257 1258 #endif 1259 1260 1261