engineFunctions.h
Engine/source/console/engineFunctions.h
Structures for function-type engine export information.
Classes:
class
class
Structure storing the default argument values for a function invocation frame.
class
A function exported by the engine for interfacing with the control layer.
Public Defines
define
DEFINE_CALLIN(bindingName, exportName, scope, returnType, args, defaultArgs, flags, doc) TORQUE_API returnType bindingName args; \ namespace { namespace _ ## bindingName { \ < args > sDefaultArgs defaultArgs; \ sFunctionInfo( \ #exportName, \ &< scope >()(), \ doc, \ #returnType " " #exportName #args, \ #bindingName, \ < returnType args >(), \ &sDefaultArgs, \ ( * ) &bindingName, \ ( flags ) \ ); \ } } \ TORQUE_API returnType bindingName args
Due to the given argument types and return type being directly used as is, it is not possible to use this macro with engine types that have more complex value passing semantics (like e.g.
define
DEFINE_CALLOUT(bindingName, exportName, scope, returnType, args, flags, doc) TORQUE_API returnType ( *bindingName ) args; \ TORQUE_API set_ ## bindingName( returnType ( *fn ) args ) \ { bindingName = fn; } \ returnType ( *bindingName ) args; \ namespace { \ :: _cb ## bindingName( \ #exportName, \ &::< scope >()(), \ doc, \ #returnType " " #exportName #args, \ #bindingName, \ ::< returnType args >(), \ , \ ( * ) &bindingName, \ | ( flags ) \ ); \ }
Not all control layers may be able to access data variables in a DLL so this macro exposes both the variable and a set_XXX function to set the variable programmatically.
Public Enumerations
enum
EngineFunctionFlags { EngineFunctionCallout = BIT( 0 ) }
Detailed Description
Structures for function-type engine export information.
Public Defines
DEFINE_CALLIN(bindingName, exportName, scope, returnType, args, defaultArgs, flags, doc) TORQUE_API returnType bindingName args; \ namespace { namespace _ ## bindingName { \ < args > sDefaultArgs defaultArgs; \ sFunctionInfo( \ #exportName, \ &< scope >()(), \ doc, \ #returnType " " #exportName #args, \ #bindingName, \ < returnType args >(), \ &sDefaultArgs, \ ( * ) &bindingName, \ ( flags ) \ ); \ } } \ TORQUE_API returnType bindingName args
Due to the given argument types and return type being directly used as is, it is not possible to use this macro with engine types that have more complex value passing semantics (like e.g.
String). Use engineAPI in this case.
note:The method of defining functions exposed by this macro is very low-level. To more conveniently define API functions and methods, use the facilities provided in engineAPI.h.
see:
DEFINE_CALLOUT(bindingName, exportName, scope, returnType, args, flags, doc) TORQUE_API returnType ( *bindingName ) args; \ TORQUE_API set_ ## bindingName( returnType ( *fn ) args ) \ { bindingName = fn; } \ returnType ( *bindingName ) args; \ namespace { \ :: _cb ## bindingName( \ #exportName, \ &::< scope >()(), \ doc, \ #returnType " " #exportName #args, \ #bindingName, \ ::< returnType args >(), \ , \ ( * ) &bindingName, \ | ( flags ) \ ); \ }
Not all control layers may be able to access data variables in a DLL so this macro exposes both the variable and a set_XXX function to set the variable programmatically.
Public Enumerations
EngineFunctionFlags
Enumerator
- EngineFunctionCallout = BIT( 0 )
Function is a callback into the control layer.
If this flag is not set, the function is a call-in.
1 2//----------------------------------------------------------------------------- 3// Copyright (c) 2012 GarageGames, LLC 4// 5// Permission is hereby granted, free of charge, to any person obtaining a copy 6// of this software and associated documentation files (the "Software"), to 7// deal in the Software without restriction, including without limitation the 8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 9// sell copies of the Software, and to permit persons to whom the Software is 10// furnished to do so, subject to the following conditions: 11// 12// The above copyright notice and this permission notice shall be included in 13// all copies or substantial portions of the Software. 14// 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 21// IN THE SOFTWARE. 22//----------------------------------------------------------------------------- 23 24#ifndef _ENGINEFUNCTIONS_H_ 25#define _ENGINEFUNCTIONS_H_ 26 27#ifndef _ENGINEEXPORTS_H_ 28 #include "console/engineExports.h" 29#endif 30#ifndef _ENGINETYPEINFO_H_ 31 #include "console/engineTypeInfo.h" 32#endif 33 34 35/// @file 36/// Structures for function-type engine export information. 37 38 39#ifdef TORQUE_COMPILER_VISUALC 40 #define TORQUE_API extern "C" __declspec( dllexport ) 41#elif defined( TORQUE_COMPILER_GCC ) 42 #define TORQUE_API extern "C" __attribute__( ( visibility( "default" ) ) ) 43#else 44 #error Unsupported compiler. 45#endif 46 47 48// #pragma pack is bugged in GCC in that the packing in place at the template instantiation 49// sites rather than their definition sites is used. Enable workarounds. 50#ifdef TORQUE_COMPILER_GCC 51 #define _PACK_BUG_WORKAROUNDS 52#endif 53 54 55 56/// Structure storing the default argument values for a function invocation 57/// frame. 58struct EngineFunctionDefaultArguments 59{ 60 /// Number of default arguments for the function call frame. 61 /// 62 /// @warn This is @b NOT the size of the memory block returned by getArgs() and also 63 /// not the number of elements it contains. 64 U32 mNumDefaultArgs; 65 66 /// Return a pointer to the variable-sized array of default argument values. 67 /// 68 /// @warn The arguments must be stored @b IMMEDIATELY after #mNumDefaultArgs. 69 /// @warn This is a @b FULL frame and not just the default arguments, i.e. it starts with the 70 /// first argument that the function takes and ends with the last argument it takes. 71 /// @warn If the compiler's #pragma pack is buggy, the elements in this structure are allowed 72 /// to be 4-byte aligned rather than byte-aligned as they should be. 73 const U8* getArgs() const 74 { 75 return ( const U8* ) &( mNumDefaultArgs ) + sizeof( mNumDefaultArgs ); 76 } 77}; 78 79 80// Need byte-aligned packing for the default argument structures. 81#ifdef _WIN64 82#pragma pack( push, 4 ) 83#else 84#pragma pack( push, 1 ) 85#endif 86 87 88// Structure encapsulating default arguments to an engine API function. 89template< typename T > 90struct _EngineFunctionDefaultArguments {}; 91template<> 92struct _EngineFunctionDefaultArguments< void() > : public EngineFunctionDefaultArguments 93{ 94 _EngineFunctionDefaultArguments() 95 { mNumDefaultArgs = 0; } 96}; 97template< typename A > 98struct _EngineFunctionDefaultArguments< void( A ) > : public EngineFunctionDefaultArguments 99{ 100 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 101 102 _EngineFunctionDefaultArguments() 103 { mNumDefaultArgs = 0; } 104 _EngineFunctionDefaultArguments( A a ) 105 : a( a ) 106 { mNumDefaultArgs = 1; } 107}; 108template< typename A, typename B > 109struct _EngineFunctionDefaultArguments< void( A, B ) > : public EngineFunctionDefaultArguments 110{ 111 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 112 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 113 114 _EngineFunctionDefaultArguments() 115 { mNumDefaultArgs = 0; } 116 _EngineFunctionDefaultArguments( B b ) 117 : b( b ) 118 { mNumDefaultArgs = 1; } 119 _EngineFunctionDefaultArguments( A a, B b ) 120 : a( a ), 121 b( b ) 122 { mNumDefaultArgs = 2; } 123}; 124template< typename A, typename B, typename C > 125struct _EngineFunctionDefaultArguments< void( A, B, C ) > : public EngineFunctionDefaultArguments 126{ 127 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 128 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 129 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 130 131 _EngineFunctionDefaultArguments() 132 { mNumDefaultArgs = 0; } 133 _EngineFunctionDefaultArguments( C c ) 134 : c( c ) 135 { mNumDefaultArgs = 1; } 136 _EngineFunctionDefaultArguments( B b, C c ) 137 : b( b ), 138 c( c ) 139 { mNumDefaultArgs = 2; } 140 _EngineFunctionDefaultArguments( A a, B b, C c ) 141 : a( a ), 142 b( b ), 143 c( c ) 144 { mNumDefaultArgs = 3; } 145}; 146template< typename A, typename B, typename C, typename D > 147struct _EngineFunctionDefaultArguments< void( A, B, C, D ) > : public EngineFunctionDefaultArguments 148{ 149 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 150 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 151 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 152 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 153 154 _EngineFunctionDefaultArguments() 155 { mNumDefaultArgs = 0; } 156 _EngineFunctionDefaultArguments( D d ) 157 : d( d ) 158 { mNumDefaultArgs = 1; } 159 _EngineFunctionDefaultArguments( C c, D d ) 160 : c( c ), 161 d( d ) 162 { mNumDefaultArgs = 2; } 163 _EngineFunctionDefaultArguments( B b, C c, D d ) 164 : b( b ), 165 c( c ), 166 d( d ) 167 { mNumDefaultArgs = 3; } 168 _EngineFunctionDefaultArguments( A a, B b, C c, D d ) 169 : a( a ), 170 b( b ), 171 c( c ), 172 d( d ) 173 { mNumDefaultArgs = 4; } 174}; 175template< typename A, typename B, typename C, typename D, typename E > 176struct _EngineFunctionDefaultArguments< void( A, B, C, D, E ) > : public EngineFunctionDefaultArguments 177{ 178 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 179 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 180 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 181 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 182 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 183 184 _EngineFunctionDefaultArguments() 185 { mNumDefaultArgs = 0; } 186 _EngineFunctionDefaultArguments( E e ) 187 : e( e ) 188 { mNumDefaultArgs = 1; } 189 _EngineFunctionDefaultArguments( D d, E e ) 190 : d( d ), 191 e( e ) 192 { mNumDefaultArgs = 2; } 193 _EngineFunctionDefaultArguments( C c, D d, E e ) 194 : c( c ), 195 d( d ), 196 e( e ) 197 { mNumDefaultArgs = 3; } 198 _EngineFunctionDefaultArguments( B b, C c, D d, E e ) 199 : b( b ), 200 c( c ), 201 d( d ), 202 e( e ) 203 { mNumDefaultArgs = 4; } 204 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e ) 205 : a( a ), 206 b( b ), 207 c( c ), 208 d( d ), 209 e( e ) 210 { mNumDefaultArgs = 5; } 211}; 212template< typename A, typename B, typename C, typename D, typename E, typename F > 213struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F ) > : public EngineFunctionDefaultArguments 214{ 215 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 216 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 217 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 218 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 219 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 220 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 221 222 _EngineFunctionDefaultArguments() 223 { mNumDefaultArgs = 0; } 224 _EngineFunctionDefaultArguments( F f ) 225 : f( f ) 226 { mNumDefaultArgs = 1; } 227 _EngineFunctionDefaultArguments( E e, F f ) 228 : e( e ), 229 f( f ) 230 { mNumDefaultArgs = 2; } 231 _EngineFunctionDefaultArguments( D d, E e, F f ) 232 : d( d ), 233 e( e ), 234 f( f ) 235 { mNumDefaultArgs = 3; } 236 _EngineFunctionDefaultArguments( C c, D d, E e, F f ) 237 : c( c ), 238 d( d ), 239 e( e ), 240 f( f ) 241 { mNumDefaultArgs = 4; } 242 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f ) 243 : b( b ), 244 c( c ), 245 d( d ), 246 e( e ), 247 f( f ) 248 { mNumDefaultArgs = 5; } 249 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f ) 250 : a( a ), 251 b( b ), 252 c( c ), 253 d( d ), 254 e( e ), 255 f( f ) 256 { mNumDefaultArgs = 6; } 257}; 258template< typename A, typename B, typename C, typename D, typename E, typename F, typename G > 259struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F, G ) > : public EngineFunctionDefaultArguments 260{ 261 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 262 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 263 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 264 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 265 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 266 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 267 typename EngineTypeTraits< G >::DefaultArgumentValueStoreType g; 268 269 _EngineFunctionDefaultArguments() 270 { mNumDefaultArgs = 0; } 271 _EngineFunctionDefaultArguments( G g ) 272 : g( g ) 273 { mNumDefaultArgs = 1; } 274 _EngineFunctionDefaultArguments( F f, G g ) 275 : f( f ), 276 g( g ) 277 { mNumDefaultArgs = 2; } 278 _EngineFunctionDefaultArguments( E e, F f, G g ) 279 : e( e ), 280 f( f ), 281 g( g ) 282 { mNumDefaultArgs = 3; } 283 _EngineFunctionDefaultArguments( D d, E e, F f, G g ) 284 : d( d ), 285 e( e ), 286 f( f ), 287 g( g ) 288 { mNumDefaultArgs = 4; } 289 _EngineFunctionDefaultArguments( C c, D d, E e, F f, G g ) 290 : c( c ), 291 d( d ), 292 e( e ), 293 f( f ), 294 g( g ) 295 { mNumDefaultArgs = 5; } 296 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f, G g ) 297 : b( b ), 298 c( c ), 299 d( d ), 300 e( e ), 301 f( f ), 302 g( g ) 303 { mNumDefaultArgs = 6; } 304 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f, G g ) 305 : a( a ), 306 b( b ), 307 c( c ), 308 d( d ), 309 e( e ), 310 f( f ), 311 g( g ) 312 { mNumDefaultArgs = 7; } 313}; 314template< typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H > 315struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F, G, H ) > : public EngineFunctionDefaultArguments 316{ 317 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 318 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 319 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 320 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 321 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 322 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 323 typename EngineTypeTraits< G >::DefaultArgumentValueStoreType g; 324 typename EngineTypeTraits< H >::DefaultArgumentValueStoreType h; 325 326 _EngineFunctionDefaultArguments() 327 { mNumDefaultArgs = 0; } 328 _EngineFunctionDefaultArguments( H h ) 329 : h( h ) 330 { mNumDefaultArgs = 1; } 331 _EngineFunctionDefaultArguments( G g, H h ) 332 : g( g ), 333 h( h ) 334 { mNumDefaultArgs = 2; } 335 _EngineFunctionDefaultArguments( F f, G g, H h ) 336 : f( f ), 337 g( g ), 338 h( h ) 339 { mNumDefaultArgs = 3; } 340 _EngineFunctionDefaultArguments( E e, F f, G g, H h ) 341 : e( e ), 342 f( f ), 343 g( g ), 344 h( h ) 345 { mNumDefaultArgs = 4; } 346 _EngineFunctionDefaultArguments( D d, E e, F f, G g, H h ) 347 : d( d ), 348 e( e ), 349 f( f ), 350 g( g ), 351 h( h ) 352 { mNumDefaultArgs = 5; } 353 _EngineFunctionDefaultArguments( C c, D d, E e, F f, G g, H h ) 354 : c( c ), 355 d( d ), 356 e( e ), 357 f( f ), 358 g( g ), 359 h( h ) 360 { mNumDefaultArgs = 6; } 361 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f, G g, H h ) 362 : b( b ), 363 c( c ), 364 d( d ), 365 e( e ), 366 f( f ), 367 g( g ), 368 h( h ) 369 { mNumDefaultArgs = 7; } 370 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f, G g, H h ) 371 : a( a ), 372 b( b ), 373 c( c ), 374 d( d ), 375 e( e ), 376 f( f ), 377 g( g ), 378 h( h ) 379 { mNumDefaultArgs = 8; } 380}; 381template< typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I > 382struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F, G, H, I ) > : public EngineFunctionDefaultArguments 383{ 384 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 385 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 386 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 387 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 388 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 389 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 390 typename EngineTypeTraits< G >::DefaultArgumentValueStoreType g; 391 typename EngineTypeTraits< H >::DefaultArgumentValueStoreType h; 392 typename EngineTypeTraits< I >::DefaultArgumentValueStoreType i; 393 394 _EngineFunctionDefaultArguments() 395 { mNumDefaultArgs = 0; } 396 _EngineFunctionDefaultArguments( I i ) 397 : i( i ) 398 { mNumDefaultArgs = 1; } 399 _EngineFunctionDefaultArguments( H h, I i ) 400 : h( h ), 401 i( i ) 402 { mNumDefaultArgs = 2; } 403 _EngineFunctionDefaultArguments( G g, H h, I i ) 404 : g( g ), 405 h( h ), 406 i( i ) 407 { mNumDefaultArgs = 3; } 408 _EngineFunctionDefaultArguments( F f, G g, H h, I i ) 409 : f( f ), 410 g( g ), 411 h( h ), 412 i( i ) 413 { mNumDefaultArgs = 4; } 414 _EngineFunctionDefaultArguments( E e, F f, G g, H h, I i ) 415 : e( e ), 416 f( f ), 417 g( g ), 418 h( h ), 419 i( i ) 420 { mNumDefaultArgs = 5; } 421 _EngineFunctionDefaultArguments( D d, E e, F f, G g, H h, I i ) 422 : d( d ), 423 e( e ), 424 f( f ), 425 g( g ), 426 h( h ), 427 i( i ) 428 { mNumDefaultArgs = 6; } 429 _EngineFunctionDefaultArguments( C c, D d, E e, F f, G g, H h, I i ) 430 : c( c ), 431 d( d ), 432 e( e ), 433 f( f ), 434 g( g ), 435 h( h ), 436 i( i ) 437 { mNumDefaultArgs = 7; } 438 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f, G g, H h, I i ) 439 : b( b ), 440 c( c ), 441 d( d ), 442 e( e ), 443 f( f ), 444 g( g ), 445 h( h ), 446 i( i ) 447 { mNumDefaultArgs = 8; } 448 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f, G g, H h, I i ) 449 : a( a ), 450 b( b ), 451 c( c ), 452 d( d ), 453 e( e ), 454 f( f ), 455 g( g ), 456 h( h ), 457 i( i ) 458 { mNumDefaultArgs = 9; } 459}; 460template< typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I, typename J > 461struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F, G, H, I, J ) > : public EngineFunctionDefaultArguments 462{ 463 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 464 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 465 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 466 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 467 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 468 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 469 typename EngineTypeTraits< G >::DefaultArgumentValueStoreType g; 470 typename EngineTypeTraits< H >::DefaultArgumentValueStoreType h; 471 typename EngineTypeTraits< I >::DefaultArgumentValueStoreType i; 472 typename EngineTypeTraits< J >::DefaultArgumentValueStoreType j; 473 474 _EngineFunctionDefaultArguments() 475 { mNumDefaultArgs = 0; } 476 _EngineFunctionDefaultArguments( J j ) 477 : j( j ) 478 { mNumDefaultArgs = 1; } 479 _EngineFunctionDefaultArguments( I i, J j ) 480 : i( i ), 481 j( j ) 482 { mNumDefaultArgs = 2; } 483 _EngineFunctionDefaultArguments( H h, I i, J j ) 484 : h( h ), 485 i( i ), 486 j( j ) 487 { mNumDefaultArgs = 3; } 488 _EngineFunctionDefaultArguments( G g, H h, I i, J j ) 489 : g( g ), 490 h( h ), 491 i( i ), 492 j( j ) 493 { mNumDefaultArgs = 4; } 494 _EngineFunctionDefaultArguments( F f, G g, H h, I i, J j ) 495 : f( f ), 496 g( g ), 497 h( h ), 498 i( i ), 499 j( j ) 500 { mNumDefaultArgs = 5; } 501 _EngineFunctionDefaultArguments( E e, F f, G g, H h, I i, J j ) 502 : e( e ), 503 f( f ), 504 g( g ), 505 h( h ), 506 i( i ), 507 j( j ) 508 { mNumDefaultArgs = 6; } 509 _EngineFunctionDefaultArguments( D d, E e, F f, G g, H h, I i, J j ) 510 : d( d ), 511 e( e ), 512 f( f ), 513 g( g ), 514 h( h ), 515 i( i ), 516 j( j ) 517 { mNumDefaultArgs = 7; } 518 _EngineFunctionDefaultArguments( C c, D d, E e, F f, G g, H h, I i, J j ) 519 : c( c ), 520 d( d ), 521 e( e ), 522 f( f ), 523 g( g ), 524 h( h ), 525 i( i ), 526 j( j ) 527 { mNumDefaultArgs = 8; } 528 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f, G g, H h, I i, J j ) 529 : b( b ), 530 c( c ), 531 d( d ), 532 e( e ), 533 f( f ), 534 g( g ), 535 h( h ), 536 i( i ), 537 j( j ) 538 { mNumDefaultArgs = 9; } 539 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f, G g, H h, I i, J j ) 540 : a( a ), 541 b( b ), 542 c( c ), 543 d( d ), 544 e( e ), 545 f( f ), 546 g( g ), 547 h( h ), 548 i( i ), 549 j( j ) 550 { mNumDefaultArgs = 10; } 551}; 552template< typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I, typename J, typename K > 553struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F, G, H, I, J, K ) > : public EngineFunctionDefaultArguments 554{ 555 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 556 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 557 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 558 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 559 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 560 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 561 typename EngineTypeTraits< G >::DefaultArgumentValueStoreType g; 562 typename EngineTypeTraits< H >::DefaultArgumentValueStoreType h; 563 typename EngineTypeTraits< I >::DefaultArgumentValueStoreType i; 564 typename EngineTypeTraits< J >::DefaultArgumentValueStoreType j; 565 typename EngineTypeTraits< K >::DefaultArgumentValueStoreType k; 566 567 _EngineFunctionDefaultArguments() 568 { mNumDefaultArgs = 0; } 569 _EngineFunctionDefaultArguments( K k ) 570 : k( k ) 571 { mNumDefaultArgs = 1; } 572 _EngineFunctionDefaultArguments( J j, K k ) 573 : j( j ), 574 k( k ) 575 { mNumDefaultArgs = 2; } 576 _EngineFunctionDefaultArguments( I i, J j, K k ) 577 : i( i ), 578 j( j ), 579 k( k ) 580 { mNumDefaultArgs = 3; } 581 _EngineFunctionDefaultArguments( H h, I i, J j, K k ) 582 : h( h ), 583 i( i ), 584 j( j ), 585 k( k ) 586 { mNumDefaultArgs = 4; } 587 _EngineFunctionDefaultArguments( G g, H h, I i, J j, K k ) 588 : g( g ), 589 h( h ), 590 i( i ), 591 j( j ), 592 k( k ) 593 { mNumDefaultArgs = 5; } 594 _EngineFunctionDefaultArguments( F f, G g, H h, I i, J j, K k ) 595 : f( f ), 596 g( g ), 597 h( h ), 598 i( i ), 599 j( j ), 600 k( k ) 601 { mNumDefaultArgs = 6; } 602 _EngineFunctionDefaultArguments( E e, F f, G g, H h, I i, J j, K k ) 603 : e( e ), 604 f( f ), 605 g( g ), 606 h( h ), 607 i( i ), 608 j( j ), 609 k( k ) 610 { mNumDefaultArgs = 7; } 611 _EngineFunctionDefaultArguments( D d, E e, F f, G g, H h, I i, J j, K k ) 612 : d( d ), 613 e( e ), 614 f( f ), 615 g( g ), 616 h( h ), 617 i( i ), 618 j( j ), 619 k( k ) 620 { mNumDefaultArgs = 8; } 621 _EngineFunctionDefaultArguments( C c, D d, E e, F f, G g, H h, I i, J j, K k ) 622 : c( c ), 623 d( d ), 624 e( e ), 625 f( f ), 626 g( g ), 627 h( h ), 628 i( i ), 629 j( j ), 630 k( k ) 631 { mNumDefaultArgs = 9; } 632 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f, G g, H h, I i, J j, K k ) 633 : b( b ), 634 c( c ), 635 d( d ), 636 e( e ), 637 f( f ), 638 g( g ), 639 h( h ), 640 i( i ), 641 j( j ), 642 k( k ) 643 { mNumDefaultArgs = 10; } 644 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f, G g, H h, I i, J j, K k ) 645 : a( a ), 646 b( b ), 647 c( c ), 648 d( d ), 649 e( e ), 650 f( f ), 651 g( g ), 652 h( h ), 653 i( i ), 654 j( j ), 655 k( k ) 656 { mNumDefaultArgs = 11; } 657}; 658template< typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I, typename J, typename K, typename L > 659struct _EngineFunctionDefaultArguments< void( A, B, C, D, E, F, G, H, I, J, K, L ) > : public EngineFunctionDefaultArguments 660{ 661 typename EngineTypeTraits< A >::DefaultArgumentValueStoreType a; 662 typename EngineTypeTraits< B >::DefaultArgumentValueStoreType b; 663 typename EngineTypeTraits< C >::DefaultArgumentValueStoreType c; 664 typename EngineTypeTraits< D >::DefaultArgumentValueStoreType d; 665 typename EngineTypeTraits< E >::DefaultArgumentValueStoreType e; 666 typename EngineTypeTraits< F >::DefaultArgumentValueStoreType f; 667 typename EngineTypeTraits< G >::DefaultArgumentValueStoreType g; 668 typename EngineTypeTraits< H >::DefaultArgumentValueStoreType h; 669 typename EngineTypeTraits< I >::DefaultArgumentValueStoreType i; 670 typename EngineTypeTraits< J >::DefaultArgumentValueStoreType j; 671 typename EngineTypeTraits< K >::DefaultArgumentValueStoreType k; 672 typename EngineTypeTraits< L >::DefaultArgumentValueStoreType l; 673 674 _EngineFunctionDefaultArguments() 675 { mNumDefaultArgs = 0; } 676 _EngineFunctionDefaultArguments( L l ) 677 : l( l ) 678 { mNumDefaultArgs = 1; } 679 _EngineFunctionDefaultArguments( K k, L l ) 680 : k( k ), 681 l( l ) 682 { mNumDefaultArgs = 2; } 683 _EngineFunctionDefaultArguments( J j, K k, L l ) 684 : j( j ), 685 k( k ), 686 l( l ) 687 { mNumDefaultArgs = 3; } 688 _EngineFunctionDefaultArguments( I i, J j, K k, L l ) 689 : i( i ), 690 j( j ), 691 k( k ), 692 l( l ) 693 { mNumDefaultArgs = 4; } 694 _EngineFunctionDefaultArguments( H h, I i, J j, K k, L l ) 695 : h( h ), 696 i( i ), 697 j( j ), 698 k( k ), 699 l( l ) 700 { mNumDefaultArgs = 5; } 701 _EngineFunctionDefaultArguments( G g, H h, I i, J j, K k, L l ) 702 : g( g ), 703 h( h ), 704 i( i ), 705 j( j ), 706 k( k ), 707 l( l ) 708 { mNumDefaultArgs = 6; } 709 _EngineFunctionDefaultArguments( F f, G g, H h, I i, J j, K k, L l ) 710 : f( f ), 711 g( g ), 712 h( h ), 713 i( i ), 714 j( j ), 715 k( k ), 716 l( l ) 717 { mNumDefaultArgs = 7; } 718 _EngineFunctionDefaultArguments( E e, F f, G g, H h, I i, J j, K k, L l ) 719 : e( e ), 720 f( f ), 721 g( g ), 722 h( h ), 723 i( i ), 724 j( j ), 725 k( k ), 726 l( l ) 727 { mNumDefaultArgs = 8; } 728 _EngineFunctionDefaultArguments( D d, E e, F f, G g, H h, I i, J j, K k, L l ) 729 : d( d ), 730 e( e ), 731 f( f ), 732 g( g ), 733 h( h ), 734 i( i ), 735 j( j ), 736 k( k ), 737 l( l ) 738 { mNumDefaultArgs = 9; } 739 _EngineFunctionDefaultArguments( C c, D d, E e, F f, G g, H h, I i, J j, K k, L l ) 740 : c( c ), 741 d( d ), 742 e( e ), 743 f( f ), 744 g( g ), 745 h( h ), 746 i( i ), 747 j( j ), 748 k( k ), 749 l( l ) 750 { mNumDefaultArgs = 10; } 751 _EngineFunctionDefaultArguments( B b, C c, D d, E e, F f, G g, H h, I i, J j, K k, L l ) 752 : b( b ), 753 c( c ), 754 d( d ), 755 e( e ), 756 f( f ), 757 g( g ), 758 h( h ), 759 i( i ), 760 j( j ), 761 k( k ), 762 l( l ) 763 { mNumDefaultArgs = 11; } 764 _EngineFunctionDefaultArguments( A a, B b, C c, D d, E e, F f, G g, H h, I i, J j, K k, L l ) 765 : a( a ), 766 b( b ), 767 c( c ), 768 d( d ), 769 e( e ), 770 f( f ), 771 g( g ), 772 h( h ), 773 i( i ), 774 j( j ), 775 k( k ), 776 l( l ) 777 { mNumDefaultArgs = 12; } 778}; 779 780#pragma pack( pop ) 781 782 783// Helper to allow flags argument to DEFINE_FUNCTION to be empty. 784struct _EngineFunctionFlags 785{ 786 U32 val; 787 _EngineFunctionFlags() 788 : val( 0 ) {} 789 _EngineFunctionFlags( U32 val ) 790 : val( val ) {} 791 operator U32() const { return val; } 792}; 793 794 795/// 796enum EngineFunctionFlags 797{ 798 /// Function is a callback into the control layer. If this flag is not set, 799 /// the function is a call-in. 800 EngineFunctionCallout = BIT( 0 ), 801}; 802 803 804/// A function exported by the engine for interfacing with the control layer. 805/// 806/// A function can either be a call-in, transfering control flow from the control layer to the engine, or a call-out, 807/// transfering control flow from the engine to the control layer. 808/// 809/// All engine API functions use the native C (@c cdecl) calling convention. 810/// 811/// Be aware that there a no implicit parameters to functions. This, for example, means that methods will simply 812/// list an object type parameter as their first argument but otherwise be indistinguishable from other functions. 813/// 814/// Variadic functions are supported. 815/// 816/// @section engineFunction_strings String Arguments and Return Values 817/// 818/// Strings passed through the API are assumed to be owned by the caller. They must persist for the entire duration 819/// of a call. 820/// 821/// Strings returned by a function are assumed to be in transient storage that will be overwritten by subsequent API 822/// calls. If the caller wants to preserve a string, it is responsible to copying strings to its own memory. This will 823/// happen with most higher-level control layers anyway. 824/// 825/// @section engineFunction_defaultargs Default Arguments 826/// 827/// As the engine API export system is set up to not require hand-written code in generated wrappers per se, the 828/// export system seeks to include a maximum possible amount of information in the export structures. 829/// To this end, where applicable, information about suggested default values for arguments to the engine API 830/// functions is stored in the export structures. It is up to the wrapper generator if and how it makes use of 831/// this information. 832/// 833/// Default arguments are represented by capturing raw stack frame vectors of the arguments to functions. These 834/// frames could be used as default images for passing arguments in stack frames, though wrapper generators 835/// may actually want to read out individual argument values and include them in function prototypes within 836/// the generated code. 837/// 838/// @section engineFunction_callin Call-ins 839/// 840/// Call-ins are exposed as native entry points. The control layer must be able to natively 841/// marshall arguments and call DLL function exports using C calling conventions. 842/// 843/// @section engineFunction_callout Call-outs 844/// 845/// Call-outs are exposed as pointer-sized memory locations into which the control layer needs 846/// to install addresses of functions that receive the call from the engine back into the control 847/// layer. The function has to follow C calling conventions and 848/// 849/// A call-out will initially be set to NULL and while being NULL, will simply cause the engine 850/// to skip and ignore the call-out. This allows the control layer to only install call-outs 851/// it is actually interested in. 852/// 853class EngineFunctionInfo : public EngineExport 854{ 855 public: 856 857 DECLARE_CLASS( EngineFunctionInfo, EngineExport ); 858 859 protected: 860 861 /// A combination of EngineFunctionFlags. 862 BitSet32 mFunctionFlags; 863 864 /// The type of the function. 865 const EngineTypeInfo* mFunctionType; 866 867 /// Default values for the function arguments. 868 const EngineFunctionDefaultArguments* mDefaultArgumentValues; 869 870 /// Name of the DLL symbol denoting the address of the exported entity. 871 const char* mBindingName; 872 873 /// Full function prototype string. Useful for quick printing and most importantly, 874 /// this will be the only place containing information about the argument names. 875 const char* mPrototypeString; 876 877 /// Address of either the function implementation or the variable taking the address 878 /// of a call-out. 879 void* mAddress; 880 881 /// Next function in the global link chain of engine functions. 882 EngineFunctionInfo* mNextFunction; 883 884 /// First function in the global link chain of engine functions. 885 static EngineFunctionInfo* smFirstFunction; 886 887 public: 888 889 /// 890 EngineFunctionInfo( const char* name, 891 EngineExportScope* scope, 892 const char* docString, 893 const char* protoypeString, 894 const char* bindingName, 895 const EngineTypeInfo* functionType, 896 const EngineFunctionDefaultArguments* defaultArgs, 897 void* address, 898 U32 flags ); 899 900 /// Return the name of the function. 901 const char* getFunctionName() const { return getExportName(); } 902 903 /// Return the function's full prototype string including the return type, function name, 904 /// and argument list. 905 const char* getPrototypeString() const { return mPrototypeString; } 906 907 /// Return the DLL export symbol name. 908 const char* getBindingName() const { return mBindingName; } 909 910 /// Test whether this is a callout function. 911 bool isCallout() const { return mFunctionFlags.test( EngineFunctionCallout ); } 912 913 /// Test whether the function is variadic, i.e. takes a variable number of arguments. 914 bool isVariadic() const { return mFunctionType->isVariadic(); } 915 916 /// Return the type of this function. 917 const EngineTypeInfo* getFunctionType() const { return mFunctionType; } 918 919 /// Return the return type of the function. 920 const EngineTypeInfo* getReturnType() const { return getFunctionType()->getArgumentTypeTable()->getReturnType(); } 921 922 /// Return the number of arguments that this function takes. If the function is variadic, 923 /// this is the number of fixed arguments. 924 U32 getNumArguments() const { return getFunctionType()->getArgumentTypeTable()->getNumArguments(); } 925 926 /// 927 const EngineTypeInfo* getArgumentType( U32 index ) const { return ( *( getFunctionType()->getArgumentTypeTable() ) )[ index ]; } 928 929 /// Return the vector storing the default argument values. 930 const EngineFunctionDefaultArguments* getDefaultArguments() const { return mDefaultArgumentValues; } 931 932 /// Reset all callout function pointers back to NULL. This deactivates all callbacks. 933 static void resetAllCallouts(); 934}; 935 936 937/// 938/// 939/// Due to the given argument types and return type being directly used as is, it is not possible 940/// to use this macro with engine types that have more complex value passing semantics (like e.g. 941/// String). Use engineAPI in this case. 942/// 943/// @note The method of defining functions exposed by this macro is very low-level. To more 944/// conveniently define API functions and methods, use the facilities provided in engineAPI.h. 945/// 946/// @see engineAPI.h 947#define DEFINE_CALLIN( bindingName, exportName, scope, returnType, args, defaultArgs, flags, doc ) \ 948 TORQUE_API returnType bindingName args; \ 949 namespace { namespace _ ## bindingName { \ 950 _EngineFunctionDefaultArguments< void args > sDefaultArgs defaultArgs; \ 951 EngineFunctionInfo sFunctionInfo( \ 952 #exportName, \ 953 &_SCOPE< scope >()(), \ 954 doc, \ 955 #returnType " " #exportName #args, \ 956 #bindingName, \ 957 TYPE< returnType args >(), \ 958 &sDefaultArgs, \ 959 ( void* ) &bindingName, \ 960 _EngineFunctionFlags( flags ) \ 961 ); \ 962 } } \ 963 TORQUE_API returnType bindingName args 964 965 966/// 967/// 968/// Not all control layers may be able to access data variables in a DLL so this macro exposes 969/// both the variable and a set_XXX function to set the variable programmatically. 970#define DEFINE_CALLOUT( bindingName, exportName, scope, returnType, args, flags, doc ) \ 971 TORQUE_API returnType ( *bindingName ) args; \ 972 TORQUE_API void set_ ## bindingName( returnType ( *fn ) args ) \ 973 { bindingName = fn; } \ 974 returnType ( *bindingName ) args; \ 975 namespace { \ 976 ::EngineFunctionInfo _cb ## bindingName( \ 977 #exportName, \ 978 &::_SCOPE< scope >()(), \ 979 doc, \ 980 #returnType " " #exportName #args, \ 981 #bindingName, \ 982 ::TYPE< returnType args >(), \ 983 NULL, \ 984 ( void* ) &bindingName, \ 985 EngineFunctionCallout | EngineFunctionFlags( flags ) \ 986 ); \ 987 } 988 989 990#endif // !_ENGINEFUNCTIONS_H_ 991