1 /*! @header QuesaExtension.h 2 Declares the Quesa extension interface. 3 */ 4 /* NAME: 5 QuesaExtension.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_EXTENSION_HDR 47 #define QUESA_EXTENSION_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 #include "QuesaErrors.h" 53 54 // Disable QD3D header 55 #if defined(__QD3DEXTENSION__) 56 #error 57 #endif 58 59 #define __QD3DEXTENSION__ 60 61 62 63 64 65 //============================================================================= 66 // C++ preamble 67 //----------------------------------------------------------------------------- 68 #ifdef __cplusplus 69 extern "C" { 70 #endif 71 72 73 74 75 76 //============================================================================= 77 // Constants 78 //----------------------------------------------------------------------------- 79 // Mac file types 80 enum { 81 kQ3XExtensionMacCreatorType = Q3_OBJECT_TYPE('Q', '3', 'X', 'T'), 82 kQ3XExtensionMacFileType = Q3_OBJECT_TYPE('s', 'h', 'l', 'b') 83 }; 84 85 86 /*! 87 * @enum Class method types 88 * @abstract Codes identifying methods of Quesa objects. 89 * @discussion These values should be considered to be of type TQ3XMethodType. 90 * 91 * @constant kQ3XMethodTypeObjectClassVersion 92 * This is the type of a pseudo-method, really just a value of 93 * type TQ3XObjectClassVersion rather than a function pointer. 94 * @constant kQ3XMethodTypeObjectClassRegister 95 * Currently unused by Quesa. 96 * @constant kQ3XMethodTypeObjectClassReplace 97 * Currently unused by Quesa. 98 * @constant kQ3XMethodTypeObjectClassUnregister 99 * Currently unused by Quesa. 100 * @constant kQ3XMethodTypeObjectNew 101 * Method of type TQ3XObjectNewMethod that is called when 102 * an object is created. 103 * @constant kQ3XMethodTypeObjectDelete 104 * Method of type TQ3XObjectDeleteMethod that is called 105 * when an object is deleted. 106 * @constant kQ3XMethodTypeObjectDuplicate 107 * Method of type TQ3XObjectDuplicateMethod that is called 108 * when an object is duplicated. 109 * @constant kQ3XMethodTypeViewSubmitRetainedRender 110 * Method of type TQ3XViewSubmitRetainedMethod belonging to a 111 * View object that is called when a retained object is 112 * submitted to the View for rendering. 113 * @constant kQ3XMethodTypeViewSubmitRetainedPick 114 * Method of type TQ3XViewSubmitRetainedMethod belonging to a 115 * View object that is called when a retained object is 116 * submitted to the View for picking. 117 * @constant kQ3XMethodTypeViewSubmitRetainedBound 118 * Method of type TQ3XViewSubmitRetainedMethod belonging to a 119 * View object that is called when a retained object is 120 * submitted to the View for bounding. 121 * @constant kQ3XMethodTypeViewSubmitRetainedWrite 122 * Method of type TQ3XViewSubmitRetainedMethod belonging to a 123 * View object that is called when a retained object is 124 * submitted to the View for writing. 125 * @constant kQ3XMethodTypeViewSubmitImmediateRender 126 * Method of type TQ3XViewSubmitImmediateMethod belonging to a 127 * View object that is called when an immediate object is 128 * submitted to the View for rendering. 129 * @constant kQ3XMethodTypeViewSubmitImmediatePick 130 * Method of type TQ3XViewSubmitImmediateMethod belonging to a 131 * View object that is called when an immediate object is 132 * submitted to the View for picking. 133 * @constant kQ3XMethodTypeViewSubmitImmediateBound 134 * Method of type TQ3XViewSubmitImmediateMethod belonging to a 135 * View object that is called when an immediate object is 136 * submitted to the View for bounding. 137 * @constant kQ3XMethodTypeViewSubmitImmediateWrite 138 * Method of type TQ3XViewSubmitImmediateMethod belonging to a 139 * View object that is called when an immediate object is 140 * submitted to the View for writing. 141 */ 142 enum { 143 kQ3XMethodTypeObjectClassVersion = Q3_METHOD_TYPE('v', 'r', 's', 'n'), 144 kQ3XMethodTypeObjectClassRegister = Q3_METHOD_TYPE('r', 'g', 's', 't'), 145 kQ3XMethodTypeObjectClassReplace = Q3_METHOD_TYPE('r', 'g', 'r', 'p'), 146 kQ3XMethodTypeObjectClassUnregister = Q3_METHOD_TYPE('u', 'n', 'r', 'g'), 147 kQ3XMethodTypeObjectNew = Q3_METHOD_TYPE('n', 'e', 'w', 'o'), 148 kQ3XMethodTypeObjectDelete = Q3_METHOD_TYPE('d', 'l', 't', 'e'), 149 kQ3XMethodTypeObjectDuplicate = Q3_METHOD_TYPE('d', 'u', 'p', 'l'), 150 kQ3XMethodTypeViewSubmitRetainedRender = Q3_METHOD_TYPE('s', 'v', 'r', 'r'), 151 kQ3XMethodTypeViewSubmitRetainedPick = Q3_METHOD_TYPE('s', 'v', 'r', 'p'), 152 kQ3XMethodTypeViewSubmitRetainedBound = Q3_METHOD_TYPE('s', 'v', 'r', 'b'), 153 kQ3XMethodTypeViewSubmitRetainedWrite = Q3_METHOD_TYPE('s', 'v', 'r', 'w'), 154 kQ3XMethodTypeViewSubmitImmediateRender = Q3_METHOD_TYPE('s', 'v', 'i', 'r'), 155 kQ3XMethodTypeViewSubmitImmediatePick = Q3_METHOD_TYPE('s', 'v', 'i', 'p'), 156 kQ3XMethodTypeViewSubmitImmediateBound = Q3_METHOD_TYPE('s', 'v', 'i', 'b'), 157 kQ3XMethodTypeViewSubmitImmediateWrite = Q3_METHOD_TYPE('s', 'v', 'i', 'w') 158 }; 159 160 161 162 163 164 //============================================================================= 165 // Types 166 //----------------------------------------------------------------------------- 167 // Version type 168 /*! 169 * @typedef 170 * TQ3XObjectClassVersion 171 * @abstract 172 * Pseudo-method that returns the version of a class. 173 */ 174 typedef TQ3Uns32 TQ3XObjectClassVersion; 175 176 177 // Class methods 178 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XObjectClassRegisterMethod)( 179 TQ3XObjectClass objectClass, 180 void *classPrivate); 181 182 typedef Q3_CALLBACK_API_C(void, TQ3XObjectClassReplaceMethod)( 183 TQ3XObjectClass oldObjectClass, 184 void *oldClassPrivate, 185 TQ3XObjectClass newObjectClass, 186 void *newClassPrivate); 187 188 typedef Q3_CALLBACK_API_C(void, TQ3XObjectClassUnregisterMethod)( 189 TQ3XObjectClass objectClass, 190 void *classPrivate); 191 192 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XObjectNewMethod)( 193 TQ3Object object, 194 void *privateData, 195 void *parameters); 196 197 typedef Q3_CALLBACK_API_C(void, TQ3XObjectDeleteMethod)( 198 TQ3Object object, 199 void *privateData); 200 201 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XObjectDuplicateMethod)( 202 TQ3Object fromObject, 203 const void *fromPrivateData, 204 TQ3Object toObject, 205 const void *toPrivateData); 206 207 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XSharedLibraryRegister)( 208 void); 209 210 211 /*! 212 * @typedef 213 * TQ3XViewSubmitRetainedMethod 214 * @abstract 215 * Method type that a view object uses when a retained object is submitted. 216 * @param theView A view object. 217 * @param theObject An object. 218 * @result Success or failure of the operation. 219 */ 220 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XViewSubmitRetainedMethod)( 221 TQ3ViewObject theView, 222 TQ3Object theObject); 223 224 /*! 225 * @typedef 226 * TQ3XViewSubmitImmediateMethod 227 * @abstract 228 * Method type that a view object uses when an immediate object is submitted. 229 * @param theView A view object. 230 * @param objectType An object type. 231 * @param objectData The data of the object. 232 * @result Success or failure of the operation. 233 */ 234 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3XViewSubmitImmediateMethod)( 235 TQ3ViewObject theView, 236 TQ3ObjectType objectType, 237 const void *objectData); 238 239 240 /*! 241 * @typedef 242 * TQ3XSharedLibraryInfo 243 * @discussion 244 * Parameter data for Q3XSharedLibrary_Register. 245 * 246 * The sharedLibrary field is often used to hold a platform-specific 247 * shared library reference. It has no meaning for Quesa, and is used 248 * as an identifier to match up calls to Q3XSharedLibrary_Unregister 249 * with the appropriate call to Q3XSharedLibrary_Register. 250 * 251 * @field registerFunction Shared library registration method. 252 * @field sharedLibrary Platform-specific shared library reference. 253 */ 254 typedef struct TQ3XSharedLibraryInfo { 255 TQ3XSharedLibraryRegister registerFunction; 256 TQ3Uns32 sharedLibrary; 257 } TQ3XSharedLibraryInfo; 258 259 260 261 262 263 //============================================================================= 264 // Macros 265 //----------------------------------------------------------------------------- 266 // Version packing/unpacking 267 #define Q3_OBJECT_CLASS_VERSION(_major, _minor) \ 268 (TQ3Uns32) (((_major) << 16) | (_minor)) 269 270 #define Q3_OBJECT_GET_MAJOR_VERSION(_version) \ 271 (TQ3Uns32) ((_version) >> 16) 272 273 #define Q3_OBJECT_GET_MINOR_VERSION(_version) \ 274 (TQ3Uns32) ((_version) & 0x0000FFFF) 275 276 277 278 279 280 //============================================================================= 281 // Function prototypes 282 //----------------------------------------------------------------------------- 283 /*! 284 * @function 285 * Q3XObjectHierarchy_RegisterClass 286 * @discussion 287 * Register a new object class in the class tree. 288 * 289 * Quesa does not support the virtualMetaHandler or methodsSize parameters, 290 * and these should be set to NULL and 0 respectively. 291 * 292 * Virtual methods are inherited from the parent class metahandler in the 293 * Quesa class tree, and the QD3D docs are unclear on the purpose of 294 * methodsSize. 295 * 296 * @param parentType The object type of the parent the new class should 297 * be derived from. To derive new classes from the 298 * root TQ3Object class, pass in kQ3ObjectTypeInvalid. 299 * @param objectType Receives the new object type for the new class. 300 * This value is used as the class identifier in binary 301 * 3DMF files, and is returned by the _GetType and 302 * Q3Object_GetLeafType class. It may also be passed to 303 * Q3Object_IsType to identify objects of this class. 304 * @param objectName A C string which acts as a unique textual identifier 305 * for the new class. This value is used as the class 306 * identifier in text 3DMF files. 307 * @param metaHandler The metahandler for the class. 308 * @param virtualMetaHandler The virtual metahandler for the class (should be NULL). 309 * @param methodsSize The size of the private class data (shoudld be 0). 310 * @param instanceSize The size of the instance data for the class, if any. 311 * @result The new class reference. 312 */ 313 Q3_EXTERN_API_C ( TQ3XObjectClass ) 314 Q3XObjectHierarchy_RegisterClass ( 315 TQ3ObjectType parentType, 316 TQ3ObjectType *objectType, 317 const char *objectName, 318 TQ3XMetaHandler metaHandler, 319 TQ3XMetaHandler virtualMetaHandler, 320 TQ3Uns32 methodsSize, 321 TQ3Uns32 instanceSize 322 ); 323 324 325 326 /*! 327 * @function 328 * Q3XObjectHierarchy_UnregisterClass 329 * @discussion 330 * Unregister a object class from the class tree. 331 * 332 * Only classes registered by Q3XObjectHierarchy_RegisterClass should 333 * be unregistered by this routine. 334 * 335 * @param objectClass The class to unregister. 336 * @result Success or failure of the operation. 337 */ 338 Q3_EXTERN_API_C ( TQ3Status ) 339 Q3XObjectHierarchy_UnregisterClass ( 340 TQ3XObjectClass objectClass 341 ); 342 343 344 345 /*! 346 * @function 347 * Q3XObjectClass_GetMethod 348 * @discussion 349 * Get a method of a class. 350 * 351 * @param objectClass The class to query. 352 * @param methodType The method type to retrieve. 353 * @result The function pointer for the method. 354 */ 355 Q3_EXTERN_API_C ( TQ3XFunctionPointer ) 356 Q3XObjectClass_GetMethod ( 357 TQ3XObjectClass objectClass, 358 TQ3XMethodType methodType 359 ); 360 361 362 363 /*! 364 * @function 365 * Q3XObjectHierarchy_NewObject 366 * @discussion 367 * Instantiate a class. 368 * 369 * @param objectClass The class to instantiate. 370 * @param parameters The parameter data for the NewMethod method. 371 * @result A new instance of the class. 372 */ 373 Q3_EXTERN_API_C ( TQ3Object ) 374 Q3XObjectHierarchy_NewObject ( 375 TQ3XObjectClass objectClass, 376 void *parameters 377 ); 378 379 380 381 /*! 382 * @function 383 * Q3XObjectClass_GetLeafType 384 * @discussion 385 * Get the leaf type of a class. 386 * 387 * The leaf type is the type returned by Q3XObjectHierarchy_RegisterClass 388 * when the class was registered. 389 * 390 * @param objectClass The class to query. 391 * @result The leaf type of the class. 392 */ 393 Q3_EXTERN_API_C ( TQ3ObjectType ) 394 Q3XObjectClass_GetLeafType ( 395 TQ3XObjectClass objectClass 396 ); 397 398 399 400 /*! 401 * @function 402 * Q3XObjectHierarchy_GetClassVersion 403 * @discussion 404 * Get the version of a class. 405 * 406 * The class version is returned by the class ClassVersion method. 407 * 408 * @param objectClassType The class to query. 409 * @param version Receives the version of the class. 410 * @result Success or failure of the operation. 411 */ 412 Q3_EXTERN_API_C ( TQ3Status ) 413 Q3XObjectHierarchy_GetClassVersion ( 414 TQ3ObjectType objectClassType, 415 TQ3XObjectClassVersion *version 416 ); 417 418 419 420 /*! 421 * @function 422 * Q3XObjectClass_GetType 423 * @discussion 424 * Get the type of a class. 425 * 426 * @param objectClass The class to query. 427 * @param theType Receives the type of the class. 428 * @result Success or failure of the operation. 429 */ 430 Q3_EXTERN_API_C ( TQ3Status ) 431 Q3XObjectClass_GetType ( 432 TQ3XObjectClass objectClass, 433 TQ3ObjectType *theType 434 ); 435 436 437 438 /*! 439 * @function 440 * Q3XObjectHierarchy_FindClassByType 441 * @discussion 442 * Locate a class within the class tree. 443 * 444 * @param theType The class type. 445 * @result The class registered under theType, or NULL. 446 */ 447 Q3_EXTERN_API_C ( TQ3XObjectClass ) 448 Q3XObjectHierarchy_FindClassByType ( 449 TQ3ObjectType theType 450 ); 451 452 453 454 /*! 455 * @function 456 * Q3XObjectClass_GetPrivate 457 * @discussion 458 * Get the private instance data of an object. 459 * 460 * If no instance data space was reserved for the object, a NULL 461 * pointer will be returned. 462 * 463 * @param objectClass The class of the object. 464 * @param targetObject The object to query. 465 * @result A pointer to the private instance data. 466 */ 467 Q3_EXTERN_API_C ( void * ) 468 Q3XObjectClass_GetPrivate ( 469 TQ3XObjectClass objectClass, 470 TQ3Object targetObject 471 ); 472 473 474 475 /*! 476 * @function 477 * Q3XObject_GetClass 478 * @discussion 479 * Get the class of an object. 480 * 481 * @param object The object to query. 482 * @result The class of the object. 483 */ 484 Q3_EXTERN_API_C ( TQ3XObjectClass ) 485 Q3XObject_GetClass ( 486 TQ3Object object 487 ); 488 489 490 491 /*! 492 * @function 493 * Q3XSharedLibrary_Register 494 * @discussion 495 * Register a shared library with Quesa. 496 * 497 * Can be called from within a shared library entry point to register 498 * a callback with Quesa. The callback will be invoked by Q3Initialize 499 * during initialisation, to allow it to register custom classes with 500 * the Quesa class tree. 501 * 502 * @param sharedLibraryInfo The shared library registration state. 503 * @result Success or failure of the operation. 504 */ 505 Q3_EXTERN_API_C ( TQ3Status ) 506 Q3XSharedLibrary_Register ( 507 TQ3XSharedLibraryInfo *sharedLibraryInfo 508 ); 509 510 511 512 /*! 513 * @function 514 * Q3XSharedLibrary_Unregister 515 * @discussion 516 * Unregister a shared library with Quesa. 517 * 518 * The sharedLibrary parameter should match the sharedLibrary field 519 * within the TQ3XSharedLibraryInfo that was passed to 520 * Q3XSharedLibrary_Register. 521 * 522 * @param sharedLibrary The shared library reference. 523 * @result Success or failure of the operation. 524 */ 525 Q3_EXTERN_API_C ( TQ3Status ) 526 Q3XSharedLibrary_Unregister ( 527 TQ3Uns32 sharedLibrary 528 ); 529 530 531 532 /*! 533 * @function 534 * Q3XError_Post 535 * @discussion 536 * Post an error to the error manager. 537 * 538 * Although intended only for use by extensions in QD3D, this call 539 * is also available to general application clients in Quesa. 540 * 541 * @param error The error to post. 542 */ 543 Q3_EXTERN_API_C ( void ) 544 Q3XError_Post ( 545 TQ3Error error 546 ); 547 548 549 550 /*! 551 * @function 552 * Q3XWarning_Post 553 * @discussion 554 * Post a warning to the error manager. 555 * 556 * Although intended only for use by extensions in QD3D, this call 557 * is also available to general application clients in Quesa. 558 * 559 * @param warning The warning to post. 560 */ 561 Q3_EXTERN_API_C ( void ) 562 Q3XWarning_Post ( 563 TQ3Warning warning 564 ); 565 566 567 568 /*! 569 * @function 570 * Q3XNotice_Post 571 * @discussion 572 * Post a notice to the error manager. 573 * 574 * Although intended only for use by extensions in QD3D, this call 575 * is also available to general application clients in Quesa. 576 * 577 * @param notice The notice to post. 578 */ 579 Q3_EXTERN_API_C ( void ) 580 Q3XNotice_Post ( 581 TQ3Notice notice 582 ); 583 584 585 586 587 588 //============================================================================= 589 // Mac OS function prototypes 590 //----------------------------------------------------------------------------- 591 #if QUESA_OS_MACINTOSH 592 593 /*! 594 * @function 595 * Q3XMacintoshError_Post 596 * @discussion 597 * Post a Mac OS-specific error to the error manager. 598 * 599 * Although intended only for use by extensions in QD3D, this call 600 * is also available to general application clients in Quesa. 601 * 602 * Note that this call is equivalent to a call to Q3Error_PlatformPost, 603 * which is the preferred method for posting platform-specific errors. 604 * 605 * @param macOSErr The Mac OS error to post. 606 */ 607 Q3_EXTERN_API_C ( void ) 608 Q3XMacintoshError_Post ( 609 OSErr macOSErr 610 ); 611 612 #endif // QUESA_OS_MACINTOSH 613 614 615 616 617 618 //============================================================================= 619 // C++ postamble 620 //----------------------------------------------------------------------------- 621 #ifdef __cplusplus 622 } 623 #endif 624 625 #endif 626 627 628