1 /*! @header QuesaSet.h 2 Declarations for Quesa sets, elements, and attributes. 3 */ 4 /* NAME: 5 QuesaSet.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_SET_HDR 47 #define QUESA_SET_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 53 // Disable QD3D header 54 #if defined(__QD3DSET__) 55 #error 56 #endif 57 58 #define __QD3DSET__ 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 * TQ3AttributeTypes 81 * @discussion 82 * Type numbers for standard attributes. See QuesaView.h for default values of some 83 * of these attributes. For instance you will find that if you do not specify 84 * any attributes, an object will be white, opaque, and somewhat shiny. 85 * 86 * @constant kQ3AttributeTypeNone No type. See 87 * <code>Q3AttributeSet_GetNextAttributeType</code>. 88 * @constant kQ3AttributeTypeSurfaceUV Surface UV coordinates (<code>TQ3Param2D</code>) 89 * for texture mapping. 90 * @constant kQ3AttributeTypeShadingUV Shading UV coordinates (<code>TQ3Param2D</code>) 91 * (originally intended for procedural shaders, but 92 * effectively interchangable with surface UV). 93 * @constant kQ3AttributeTypeNormal Normal vector (<code>TQ3Vector3D</code>) 94 * @constant kQ3AttributeTypeAmbientCoefficient Ambient coefficient (<code>float</code>) 95 * @constant kQ3AttributeTypeDiffuseColor Diffuse color (<code>TQ3ColorRGB</code>) 96 * @constant kQ3AttributeTypeSpecularColor Specular color (<code>TQ3ColorRGB</code>) 97 * @constant kQ3AttributeTypeSpecularControl Specular control (<code>float</code>). 98 * Larger values make smaller specular highlights. 99 * @constant kQ3AttributeTypeTransparencyColor Transparency color (<code>TQ3ColorRGB</code>). 100 * { 0, 0, 0 } is completely transparent, and 101 * { 1, 1, 1 } is completely opaque. 102 * @constant kQ3AttributeTypeSurfaceTangent Surface tangent (<code>TQ3Tangent2D</code>) 103 * @constant kQ3AttributeTypeHighlightState Highlight state (<code>TQ3Switch</code>) 104 * @constant kQ3AttributeTypeSurfaceShader Surface shader (<code>TQ3SurfaceShaderObject</code>) 105 * @constant kQ3AttributeTypeNumTypes Number of standard attribute types. 106 */ 107 typedef enum TQ3AttributeTypes { 108 kQ3AttributeTypeNone = 0, // N/A 109 kQ3AttributeTypeSurfaceUV = 1, // TQ3Param2D 110 kQ3AttributeTypeShadingUV = 2, // TQ3Param2D 111 kQ3AttributeTypeNormal = 3, // TQ3Vector3D 112 kQ3AttributeTypeAmbientCoefficient = 4, // float 113 kQ3AttributeTypeDiffuseColor = 5, // TQ3ColorRGB 114 kQ3AttributeTypeSpecularColor = 6, // TQ3ColorRGB 115 kQ3AttributeTypeSpecularControl = 7, // float 116 kQ3AttributeTypeTransparencyColor = 8, // TQ3ColorRGB 117 kQ3AttributeTypeSurfaceTangent = 9, // TQ3Tangent2D 118 kQ3AttributeTypeHighlightState = 10, // TQ3Switch 119 kQ3AttributeTypeSurfaceShader = 11, // TQ3SurfaceShaderObject 120 kQ3AttributeTypeNumTypes = 12, // N/A 121 kQ3AttributeTypeSize32 = 0xFFFFFFFF 122 } TQ3AttributeTypes; 123 124 125 /*! 126 * @enum 127 * TQ3XAttributeMask 128 * @discussion 129 * Attribute mask flags. 130 * 131 * @constant kQ3XAttributeMaskNone No attributes. 132 * @constant kQ3XAttributeMaskSurfaceUV Surface UV attribute mask. 133 * @constant kQ3XAttributeMaskShadingUV Shading UV attribute mask. 134 * @constant kQ3XAttributeMaskNormal Normal attribute mask. 135 * @constant kQ3XAttributeMaskAmbientCoefficient Ambient coefficent attribute mask. 136 * @constant kQ3XAttributeMaskDiffuseColor Diffuse color attribute mask. 137 * @constant kQ3XAttributeMaskSpecularColor Specular color attribute mask. 138 * @constant kQ3XAttributeMaskSpecularControl Specular control attribute mask. 139 * @constant kQ3XAttributeMaskTransparencyColor Transparency color attribute mask. 140 * @constant kQ3XAttributeMaskSurfaceTangent Surface tangent attribute mask. 141 * @constant kQ3XAttributeMaskHighlightState Highlight state attribute mask. 142 * @constant kQ3XAttributeMaskSurfaceShader Surface shader attribute mask. 143 * @constant kQ3XAttributeMaskCustomAttribute Custom attribute mask. 144 * @constant kQ3XAttributeMaskAll All attributes. 145 * @constant kQ3XAttributeMaskInherited Inherited attributes mask. 146 * @constant kQ3XAttributeMaskInterpolated Interpolated attributes mask. 147 */ 148 enum { 149 kQ3XAttributeMaskNone = 0, 150 kQ3XAttributeMaskSurfaceUV = (1 << (kQ3AttributeTypeSurfaceUV - 1)), 151 kQ3XAttributeMaskShadingUV = (1 << (kQ3AttributeTypeShadingUV - 1)), 152 kQ3XAttributeMaskNormal = (1 << (kQ3AttributeTypeNormal - 1)), 153 kQ3XAttributeMaskAmbientCoefficient = (1 << (kQ3AttributeTypeAmbientCoefficient - 1)), 154 kQ3XAttributeMaskDiffuseColor = (1 << (kQ3AttributeTypeDiffuseColor - 1)), 155 kQ3XAttributeMaskSpecularColor = (1 << (kQ3AttributeTypeSpecularColor - 1)), 156 kQ3XAttributeMaskSpecularControl = (1 << (kQ3AttributeTypeSpecularControl - 1)), 157 kQ3XAttributeMaskTransparencyColor = (1 << (kQ3AttributeTypeTransparencyColor - 1)), 158 kQ3XAttributeMaskSurfaceTangent = (1 << (kQ3AttributeTypeSurfaceTangent - 1)), 159 kQ3XAttributeMaskHighlightState = (1 << (kQ3AttributeTypeHighlightState - 1)), 160 kQ3XAttributeMaskSurfaceShader = (1 << (kQ3AttributeTypeSurfaceShader - 1)), 161 kQ3XAttributeMaskCustomAttribute = 0x80000000, 162 kQ3XAttributeMaskAll = 0x800007FF, 163 kQ3XAttributeMaskInherited = 0x000003FF, 164 kQ3XAttributeMaskInterpolated = kQ3XAttributeMaskSurfaceUV | 165 kQ3XAttributeMaskShadingUV | 166 kQ3XAttributeMaskNormal | 167 kQ3XAttributeMaskAmbientCoefficient | 168 kQ3XAttributeMaskDiffuseColor | 169 kQ3XAttributeMaskSpecularControl | 170 kQ3XAttributeMaskTransparencyColor | 171 kQ3XAttributeMaskSurfaceTangent, 172 kQ3XAttributeMaskSize32 = 0xFFFFFFFF 173 }; 174 175 typedef TQ3Uns32 TQ3XAttributeMask; 176 177 /*! 178 * @enum 179 * Element method types 180 * @discussion 181 * These are method types that apply particularly to custom elements. Note that 182 * a custom element may also need to provide more general custom class methods, 183 * such as <code>kQ3XMethodTypeObjectTraverse</code>. 184 * 185 * @constant kQ3XMethodTypeElementCopyAdd See <code>TQ3XElementCopyAddMethod</code>. 186 * @constant kQ3XMethodTypeElementCopyReplace See <code>TQ3XElementCopyReplaceMethod</code>. 187 * @constant kQ3XMethodTypeElementCopyGet See <code>TQ3XElementCopyGetMethod</code>. 188 * @constant kQ3XMethodTypeElementCopyDuplicate See <code>TQ3XElementCopyDuplicateMethod</code>. 189 * @constant kQ3XMethodTypeElementDelete See <code>TQ3XElementDeleteMethod</code>. 190 */ 191 enum { 192 kQ3XMethodTypeElementCopyAdd = Q3_METHOD_TYPE('e', 'c', 'p', 'a'), 193 kQ3XMethodTypeElementCopyReplace = Q3_METHOD_TYPE('e', 'c', 'p', 'r'), 194 kQ3XMethodTypeElementCopyGet = Q3_METHOD_TYPE('e', 'c', 'p', 'g'), 195 kQ3XMethodTypeElementCopyDuplicate = Q3_METHOD_TYPE('e', 'c', 'p', 'd'), 196 kQ3XMethodTypeElementDelete = Q3_METHOD_TYPE('e', 'd', 'e', 'l') 197 }; 198 199 200 /*! 201 * @enum 202 * Attribute method types 203 * @discussion 204 * These are method types that apply particularly to custom attributes. Note that 205 * a custom element may also need to provide more general custom element or custom class methods, 206 * such as <code>kQ3XMethodTypeObjectTraverse</code>. 207 * 208 * @constant kQ3XMethodTypeAttributeInherit See <code>TQ3XAttributeInheritMethod</code>. 209 * @constant kQ3XMethodTypeAttributeCopyInherit See <code>TQ3XAttributeCopyInheritMethod</code>. 210 * @constant kQ3XMethodTypeAttributeDefault See <code>TQ3XAttributeDefaultMethod</code>. 211 * @constant kQ3XMethodTypeAttributeIsDefault See <code>TQ3XAttributeIsDefaultMethod</code>. 212 */ 213 enum { 214 kQ3XMethodTypeAttributeInherit = Q3_METHOD_TYPE('i', 'n', 'h', 't'), 215 kQ3XMethodTypeAttributeCopyInherit = Q3_METHOD_TYPE('a', 'c', 'p', 'i'), 216 kQ3XMethodTypeAttributeDefault = Q3_METHOD_TYPE('a', 's', 'd', 'f'), 217 kQ3XMethodTypeAttributeIsDefault = Q3_METHOD_TYPE('a', 'i', 'd', 'f') 218 }; 219 220 221 222 223 224 //============================================================================= 225 // Types 226 //----------------------------------------------------------------------------- 227 /*! 228 * @typedef TQ3AttributeType 229 * @discussion This is a 32-bit value identifying a particular attribute. 230 */ 231 typedef TQ3ElementType TQ3AttributeType; 232 233 234 /*! 235 * @typedef TQ3XElementCopyAddMethod 236 * @discussion 237 * This method is called to add a new element to a set, as by <code>Q3Set_Add</code> or 238 * <code>Q3Shape_AddElement</code>. On entry, <code>toInternalElement</code> points to an uninitialized 239 * block of <code>sizeOfElement</code> bytes, where <code>sizeOfElement</code> 240 * is the size you provided when registering the class. 241 * 242 * @param fromAPIElement Data to be copied, in its external form. 243 * @param toInternalElement Destination of the copy, in internal form. 244 * @result Success or failure of the method. 245 */ 246 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XElementCopyAddMethod)( 247 const void *fromAPIElement, 248 void *toInternalElement); 249 250 251 /*! 252 * @typedef TQ3XElementCopyReplaceMethod 253 * @discussion 254 * This method is called to replace an existing element in a set, as by <code>Q3Set_Add</code> or 255 * <code>Q3Shape_AddElement</code>. On entry, <code>toInternalElement</code> points to existing element data, 256 * which you may need to dispose before replacing by new data. 257 * 258 * @param fromAPIElement Data to be copied, in its external form. 259 * @param toInternalElement Destination of the copy, in internal form. 260 * @result Success or failure of the method. 261 */ 262 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XElementCopyReplaceMethod)( 263 const void *fromAPIElement, 264 void *toInternalElement); 265 266 267 /*! 268 * @typedef TQ3XElementCopyGetMethod 269 * @discussion 270 * This method is called to copy element data out of a set, as by <code>Q3Set_Get</code> or 271 * <code>Q3Shape_GetElement</code>. If you do not provide this method, the default action is 272 * a memory copy of <code>sizeOfElement</code> bytes. 273 * 274 * @param fromInternalElement Data to be copied, in its internal form. 275 * @param toAPIElement Destination of the copy, in external form. 276 * @result Success or failure of the method. 277 */ 278 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XElementCopyGetMethod)( 279 const void *fromInternalElement, 280 void *toAPIElement); 281 282 283 /*! 284 * @typedef TQ3XElementCopyDuplicateMethod 285 * @discussion 286 * This method is called when <code>Q3Object_Duplicate</code> is used on a set or attribute set. 287 * 288 * @param fromInternalElement Data to be copied, in its internal form. 289 * @param toInternalElement Destination of the copy, in internal form. 290 * @result Success or failure of the method. 291 */ 292 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XElementCopyDuplicateMethod)( 293 const void *fromInternalElement, 294 void *toInternalElement); 295 296 297 /*! 298 * @typedef TQ3XElementDeleteMethod 299 * @discussion 300 * This method is called to delete element data from a set or attribute set. 301 * 302 * @param internalElement Data to be deleted, in its internal form. 303 * @result Success or failure of the method. 304 */ 305 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XElementDeleteMethod)( 306 void *internalElement); 307 308 309 /*! 310 * @typedef TQ3XAttributeInheritMethod 311 * @discussion 312 * This is not literally a method. Your metahandler returns kQ3True or kQ3False to 313 * report whether a custom attribute supports inheritance. 314 */ 315 typedef TQ3Boolean TQ3XAttributeInheritMethod; 316 317 318 /*! 319 * @typedef TQ3XAttributeCopyInheritMethod 320 * @discussion If your custom attribute supports inheritance, this method is called to 321 * copy attribute data from a parent set to a child set. 322 * 323 * @param fromInternalAttribute Attribute data to copy, in internal form. 324 * @param toInternalAttribute Destination of the copy, in internal form. 325 * @result Success or failure of the method. 326 */ 327 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XAttributeCopyInheritMethod)( 328 const void *fromInternalAttribute, 329 void *toInternalAttribute); 330 331 /*! 332 * @typedef TQ3XAttributeDefaultMethod 333 * @discussion This method does not appear to be mentioned in the QuickDraw 3D documentation, 334 * and is not currently used in Quesa. 335 */ 336 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XAttributeDefaultMethod)( 337 void *internalAttribute); 338 339 340 /*! 341 * @typedef TQ3XAttributeIsDefaultMethod 342 * @discussion This method does not appear to be mentioned in the QuickDraw 3D documentation, 343 * and is not currently used in Quesa. 344 */ 345 typedef Q3_CALLBACK_API_C(TQ3Boolean, TQ3XAttributeIsDefaultMethod)( 346 void *internalAttribute); 347 348 349 350 351 352 //============================================================================= 353 // Function prototypes 354 //----------------------------------------------------------------------------- 355 /*! 356 * @function 357 * Q3Set_New 358 * @discussion 359 * Create a new set, initially empty. 360 * 361 * Plain sets are less commonly used than attribute sets. 362 * 363 * @result The new set object, or NULL on failure. 364 */ 365 Q3_EXTERN_API_C ( TQ3SetObject ) 366 Q3Set_New ( 367 void 368 ); 369 370 371 372 /*! 373 * @function 374 * Q3Set_GetType 375 * @discussion 376 * Get the type of a set object. 377 * 378 * Returns kQ3SetTypeAttribute or kQ3ObjectTypeInvalid. 379 * 380 * @param theSet The set object. 381 * @result The subtype of the set. 382 */ 383 Q3_EXTERN_API_C ( TQ3ObjectType ) 384 Q3Set_GetType ( 385 TQ3SetObject theSet 386 ); 387 388 389 390 /*! 391 * @function 392 * Q3Set_Add 393 * @discussion 394 * Add an element to a set. 395 * 396 * This function copies an element into an existing set. If the set 397 * already contains an element of the given type, it is replaced. 398 * In the case of a custom element, the type is the type that was 399 * returned by <code>Q3XElementClass_Register</code>. 400 * 401 * @param theSet The set object. 402 * @param theType Type of the element. 403 * @param data Pointer to the element data. 404 * @result Success or failure of the operation. 405 */ 406 Q3_EXTERN_API_C ( TQ3Status ) 407 Q3Set_Add ( 408 TQ3SetObject theSet, 409 TQ3ElementType theType, 410 const void *data 411 ); 412 413 414 415 /*! 416 * @function 417 * Q3Set_Get 418 * @discussion 419 * Copy the data of an element into a buffer you provide. 420 * 421 * @param theSet The set object. 422 * @param theType The element type. 423 * @param data Pointer to a buffer large enough to receive the element data. 424 * @result Success or failure of the operation. 425 */ 426 Q3_EXTERN_API_C ( TQ3Status ) 427 Q3Set_Get ( 428 TQ3SetObject theSet, 429 TQ3ElementType theType, 430 void *data 431 ); 432 433 434 435 /*! 436 * @function 437 * Q3Set_Contains 438 * @discussion 439 * Determine whether a set contains an element of a given type. 440 * 441 * @param theSet The set object. 442 * @param theType The element type. 443 * @result kQ3True if the element exists in the set. 444 */ 445 Q3_EXTERN_API_C ( TQ3Boolean ) 446 Q3Set_Contains ( 447 TQ3SetObject theSet, 448 TQ3ElementType theType 449 ); 450 451 452 453 /*! 454 * @function 455 * Q3Set_Clear 456 * @discussion 457 * Remove an element of a given type from a set. 458 * 459 * If the set did not contain an element of the specified type, 460 * the function returns kQ3Failure. 461 * 462 * @param theSet The set object. 463 * @param theType The element type. 464 * @result Success or failure of the operation. 465 */ 466 Q3_EXTERN_API_C ( TQ3Status ) 467 Q3Set_Clear ( 468 TQ3SetObject theSet, 469 TQ3ElementType theType 470 ); 471 472 473 474 /*! 475 * @function 476 * Q3Set_Empty 477 * @discussion 478 * Remove all elements from a set. 479 * 480 * @param target The set object. 481 * @result Success or failure of the operation. 482 */ 483 Q3_EXTERN_API_C ( TQ3Status ) 484 Q3Set_Empty ( 485 TQ3SetObject target 486 ); 487 488 489 490 /*! 491 * @function 492 * Q3Set_GetNextElementType 493 * @discussion 494 * Find the next element type in a set. 495 * 496 * If you pass <code>kQ3ElementTypeNone</code>, it will return the first element type. 497 * After reaching the last element type, it returns <code>kQ3ElementTypeNone</code>. 498 * Hence, you could iterate through all the element types as follows: 499 * 500 * <blockquote><pre><code> 501 * TQ3ElementType theType = kQ3ElementTypeNone; 502 * while ( Q3Set_GetNextElementType( set, &theType ) && 503 * (theType != kQ3ElementTypeNone) ) 504 * { 505 * DoSomething( theType ); 506 * } 507 * </code></pre></blockquote> 508 * 509 * Search results are undefined if the set is edited while a search is in progress. 510 * Q3Set_GetNextElementType will always return a valid element type or kQ3ElementTypeNone, 511 * however some elements may be skipped if the set is modified before the final 512 * kQ3ElementTypeNone is returned. 513 * 514 * @param theSet The set object. 515 * @param theType Given an element type, receives the next element type. 516 * @result Success or failure of the operation. 517 */ 518 Q3_EXTERN_API_C ( TQ3Status ) 519 Q3Set_GetNextElementType ( 520 TQ3SetObject theSet, 521 TQ3ElementType *theType 522 ); 523 524 525 526 /*! 527 * @function 528 * Q3Set_CopyElement 529 * @discussion 530 * Copies an element from one set to another. 531 * 532 * If the destination set already contains an element of the specified 533 * type, the element will be replaced. 534 * 535 * <em>This function is not available in QD3D.</em> 536 * 537 * @param sourceSet The set containing the element to be copied. 538 * @param theType Type of the element. 539 * @param destSet Set to receive the copied element. 540 * @result Success or failure of the operation. 541 */ 542 #if QUESA_ALLOW_QD3D_EXTENSIONS 543 Q3_EXTERN_API_C ( TQ3Status ) 544 Q3Set_CopyElement( 545 TQ3SetObject sourceSet, 546 TQ3ElementType theType, 547 TQ3SetObject destSet 548 ); 549 #endif 550 551 552 553 /*! 554 * @function 555 * Q3Attribute_Submit 556 * @discussion 557 * Submit an attribute in immediate mode. 558 * 559 * This should only be used within a submitting loop. 560 * 561 * @param attributeType The attribute type. 562 * @param data Pointer to attribute data. 563 * @param view The view object. 564 * @result Success or failure of the operation. 565 */ 566 Q3_EXTERN_API_C ( TQ3Status ) 567 Q3Attribute_Submit ( 568 TQ3AttributeType attributeType, 569 const void *data, 570 TQ3ViewObject view 571 ); 572 573 574 575 /*! 576 * @function 577 * Q3AttributeSet_New 578 * @discussion 579 * Create an attribute set object. 580 * 581 * @result A new empty attribute set, or NULL on failure. 582 */ 583 Q3_EXTERN_API_C ( TQ3AttributeSet ) 584 Q3AttributeSet_New ( 585 void 586 ); 587 588 589 590 /*! 591 * @function 592 * Q3AttributeSet_Add 593 * @discussion 594 * Add an attribute to an attribute set. 595 * 596 * Copy attribute data into an attribute set. If the set already contains 597 * the specified type of attribute, it is replaced. 598 * 599 * @param attributeSet The attribute set. 600 * @param theType The attribute type. 601 * @param data Pointer to the attribute data. 602 * @result Success or failure of the operation. 603 */ 604 Q3_EXTERN_API_C ( TQ3Status ) 605 Q3AttributeSet_Add ( 606 TQ3AttributeSet attributeSet, 607 TQ3AttributeType theType, 608 const void *data 609 ); 610 611 612 613 /*! 614 * @function 615 * Q3AttributeSet_Contains 616 * @discussion 617 * Determine whether an attribute set contains a specified attribute. 618 * 619 * @param attributeSet The attribute set. 620 * @param attributeType The attribute type. 621 * @result kQ3True if the attribute type exists in the set. 622 */ 623 Q3_EXTERN_API_C ( TQ3Boolean ) 624 Q3AttributeSet_Contains ( 625 TQ3AttributeSet attributeSet, 626 TQ3AttributeType attributeType 627 ); 628 629 630 631 /*! 632 * @function 633 * Q3AttributeSet_Get 634 * @discussion 635 * Get attribute data from an attribute set. 636 * 637 * Copies attribute data into a user-provided buffer which should be 638 * large enough for the given kind of attribute. 639 * 640 * @param attributeSet The attribute set. 641 * @param theType The attribute type. 642 * @param data Pointer to a buffer to receive the attribute data. 643 * @result Success or failure of the operation. 644 */ 645 Q3_EXTERN_API_C ( TQ3Status ) 646 Q3AttributeSet_Get ( 647 TQ3AttributeSet attributeSet, 648 TQ3AttributeType theType, 649 void *data 650 ); 651 652 653 654 /*! 655 * @function 656 * Q3AttributeSet_Clear 657 * @discussion 658 * Remove an attribute from an attribute set. 659 * 660 * @param attributeSet The attribute set. 661 * @param theType The attribute type. 662 * @result Success or failure of the operation. 663 */ 664 Q3_EXTERN_API_C ( TQ3Status ) 665 Q3AttributeSet_Clear ( 666 TQ3AttributeSet attributeSet, 667 TQ3AttributeType theType 668 ); 669 670 671 672 /*! 673 * @function 674 * Q3AttributeSet_Empty 675 * @discussion 676 * Remove all attributes from an attribute set. 677 * 678 * @param target The attribute set. 679 * @result Success or failure of the operation. 680 */ 681 Q3_EXTERN_API_C ( TQ3Status ) 682 Q3AttributeSet_Empty ( 683 TQ3AttributeSet target 684 ); 685 686 687 688 /*! 689 * @function 690 * Q3AttributeSet_GetNextAttributeType 691 * @discussion 692 * Find the next attribute type in an attribute set. 693 * 694 * If you pass <code>kQ3AttributeTypeNone</code>, it will return the first attribute type. 695 * After reaching the last element type, it returns <code>kQ3AttributeTypeNone</code>. 696 * Hence, you could iterate through all the attribute types as follows: 697 * 698 * <blockquote><pre><code> 699 * TQ3AttributeType theType = kQ3AttributeTypeNone; 700 * while ( Q3AttributeSet_GetNextAttributeType( set, &theType ) && 701 * (theType != kQ3AttributeTypeNone) ) 702 * { 703 * DoSomething( theType ); 704 * } 705 * </code></pre></blockquote> 706 * 707 * @param source The attribute set object. 708 * @param theType Given an attribute type, receives the next attribute type. 709 * @result Success or failure of the operation. 710 */ 711 Q3_EXTERN_API_C ( TQ3Status ) 712 Q3AttributeSet_GetNextAttributeType ( 713 TQ3AttributeSet source, 714 TQ3AttributeType *theType 715 ); 716 717 718 719 /*! 720 * @function 721 * Q3AttributeSet_Submit 722 * @discussion 723 * Submit an attribute set. 724 * 725 * This should only be used within a submitting loop. 726 * 727 * @param attributeSet The attribute set object. 728 * @param view A view object. 729 * @result Success or failure of the operation. 730 */ 731 Q3_EXTERN_API_C ( TQ3Status ) 732 Q3AttributeSet_Submit ( 733 TQ3AttributeSet attributeSet, 734 TQ3ViewObject view 735 ); 736 737 738 739 /*! 740 * @function 741 * Q3AttributeSet_Inherit 742 * @discussion 743 * Configures an attribute set by copying all attributes from one set 744 * (the child) and then copying any attributes that were not in the 745 * child from another attribute set (the parent). 746 * 747 * The set you pass to receive the result must be an existing attribute set, 748 * but any existing attributes in it will be removed. 749 * 750 * @param parent An attribute set. 751 * @param child An attribute set. 752 * @param result An attribute set to be redefined. 753 * @result Success or failure of the operation. 754 */ 755 Q3_EXTERN_API_C ( TQ3Status ) 756 Q3AttributeSet_Inherit ( 757 TQ3AttributeSet parent, 758 TQ3AttributeSet child, 759 TQ3AttributeSet result 760 ); 761 762 763 764 /*! 765 * @function 766 * Q3XElementClass_Register 767 * @discussion 768 * Register a custom element class. 769 * 770 * The custom class naming convention is to begin with your company name, 771 * then a colon, then a specific class name. 772 * 773 * If your element's data contains indirect data, such as pointers to other 774 * data or references to Quesa objects, your metahandler should provide methods 775 * of the types <code>kQ3XMethodTypeElementCopyAdd</code>, <code>kQ3XMethodTypeElementCopyGet</code>, 776 * <code>kQ3XMethodTypeElementCopyDuplicate</code>, <code>kQ3XMethodTypeElementCopyReplace</code>, and 777 * <code>kQ3XMethodTypeElementDelete</code>. If you want to be able to write your element 778 * to a file and read it back, your metahandler should define methods of the 779 * types <code>kQ3XMethodTypeObjectTraverse</code>, <code>kQ3XMethodTypeObjectWrite</code>, and 780 * <code>kQ3XMethodTypeObjectReadData</code>. 781 * 782 * See QuesaExtension.h for other operations on a custom class, such 783 * as <code>Q3XObjectHierarchy_UnregisterClass</code>. 784 * 785 * @param elementType Receives the element type assigned by Quesa. 786 * @param name The unique name of the new class. 787 * @param sizeOfElement Size of the data for the element. 788 * @param metaHandler Your metahandler function that returns element methods. 789 * You may return NULL for some methods. 790 * @result Opaque pointer to the new object class. 791 */ 792 Q3_EXTERN_API_C ( TQ3XObjectClass ) 793 Q3XElementClass_Register ( 794 TQ3ElementType *elementType, 795 const char *name, 796 TQ3Uns32 sizeOfElement, 797 TQ3XMetaHandler metaHandler 798 ); 799 800 801 802 /*! 803 * @function 804 * Q3XElementType_GetElementSize 805 * @discussion 806 * Return the size in bytes of an element type. 807 * 808 * In the case of a custom element, this would be the same as the size 809 * you provided when you called <code>Q3XElementClass_Register</code>. 810 * 811 * @param elementType An element type. 812 * @param sizeOfElement Receives the size in bytes of the element. 813 * @result Success or failure of the operation. 814 */ 815 Q3_EXTERN_API_C ( TQ3Status ) 816 Q3XElementType_GetElementSize ( 817 TQ3ElementType elementType, 818 TQ3Uns32 *sizeOfElement 819 ); 820 821 822 823 /*! 824 * @function 825 * Q3XAttributeClass_Register 826 * @discussion 827 * Register a custom attribute class. 828 * 829 * @param attributeType Receives the new attribute type. 830 * @param className Unique name for the new attribute. 831 * @param sizeOfElement Size in bytes of the attribute data. 832 * @param metaHandler Your metahandler, providing appropriate methods. 833 * It may return NULL in some cases. 834 * @result Pointer to the new class. 835 */ 836 Q3_EXTERN_API_C ( TQ3XObjectClass ) 837 Q3XAttributeClass_Register ( 838 TQ3AttributeType *attributeType, 839 const char *className, 840 TQ3Uns32 sizeOfElement, 841 TQ3XMetaHandler metaHandler 842 ); 843 844 845 846 /*! 847 * @function 848 * Q3XAttributeSet_GetPointer 849 * @discussion 850 * Get a pointer to the internal data structure for an attribute. 851 * 852 * For attributes of type kQ3AttributeTypeXXX, the internal attribute data 853 * is currently identical to the data structured passed to Q3AttributeSet_Add. 854 * 855 * This function should only be called from renderer plug-ins. 856 * 857 * @param attributeSet The attribute set to query. 858 * @param attributeType The attribute type to locate. 859 * @result A pointer to the internal attribute data if present, or NULL. 860 */ 861 Q3_EXTERN_API_C ( void * ) 862 Q3XAttributeSet_GetPointer ( 863 TQ3AttributeSet attributeSet, 864 TQ3AttributeType attributeType 865 ); 866 867 868 869 /*! 870 * @function 871 * Q3XAttributeSet_GetMask 872 * @discussion 873 * Get a mask of the attributes contained in an attribute set. 874 * 875 * This function should only be called from renderer plug-ins. 876 * 877 * @param attributeSet The attribute set to query. 878 * @result A mask indicating the attributes present in attributeSet. 879 */ 880 Q3_EXTERN_API_C ( TQ3XAttributeMask ) 881 Q3XAttributeSet_GetMask ( 882 TQ3AttributeSet attributeSet 883 ); 884 885 886 887 888 889 //============================================================================= 890 // C++ postamble 891 //----------------------------------------------------------------------------- 892 #ifdef __cplusplus 893 } 894 #endif 895 896 #endif 897 898 899