//----------------------------------------------------------------------------- // Copyright (c) 2012 GarageGames, LLC // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to // deal in the Software without restriction, including without limitation the // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or // sell copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS // IN THE SOFTWARE. //----------------------------------------------------------------------------- #ifndef _ENGINEAPI_H_ #define _ENGINEAPI_H_ #include #include #ifndef _FIXEDTUPLE_H_ #include "fixedTuple.h" #endif #ifndef _CONSOLETYPES_H_ #include "console/consoleTypes.h" #endif #ifndef _CONSOLE_H_ #include "console/console.h" #endif #ifndef _STRINGFUNCTIONS_H_ #include "core/strings/stringFunctions.h" #endif #ifndef _SIMOBJECT_H_ #include "console/simObject.h" #endif #ifndef _ENGINEFUNCTIONS_H_ #include "console/engineFunctions.h" #endif // Whatever types are used in API definitions, their DECLAREs must be visible to the // macros. We include the basic primitive and struct types here. #ifndef _ENGINEPRIMITIVES_H_ #include "console/enginePrimitives.h" #endif #ifndef _ENGINESTRUCTS_H_ #include "console/engineStructs.h" #endif // Needed for the executef macros. Blame GCC. #ifndef _SIMEVENTS_H_ #include "console/simEvents.h" #endif /// @file /// Definitions for exposing engine functionality to the control layer. /// /// This file provides a convenience layer around the underlying engine interop system (which at /// the moment still includes the legacy TorqueScript interop a.k.a. "console system"). The /// macros exposed here will automatically take care of all marshalling, value type constraints, /// reflection info instancing, etc. involved in defining engine API call-ins and call-outs. /// /// @note At the moment, this file supplies both the legacy TorqueScript console system as well /// as the new engine export system with the structures and information they need. In the /// near future, the console-based parts will get purged. This will not result in visible /// changes to users of the functionality here except for the string-based marshalling /// functions currently exposed (which will also disappear). //TODO: Disable warning for extern "C" functions returning UDTs for now; need to take a closer look at this #pragma warning( disable : 4190 ) // Disable some VC warnings that are irrelevant to us. #pragma warning( push ) #pragma warning( disable : 4510 ) // default constructor could not be generated; all the Args structures are never constructed by us #pragma warning( disable : 4610 ) // can never be instantiated; again Args is never constructed by us namespace engineAPI { /// Flag for enabling legacy console behavior in the interop system while /// we still have it around. Will disappear along with console. extern bool gUseConsoleInterop; /// Flag to allow engine functions to detect whether the engine had been /// initialized or shut down. extern bool gIsInitialized; } /// @name Marshalling /// /// Functions for converting to/from string-based data representations. /// /// @note This functionality is specific to the console interop. /// @{ /// Marshal a single piece of data from native into client form. template< typename T > inline const char* EngineMarshallData( const T& value ) { return castConsoleTypeToString( value ); } inline const char* EngineMarshallData( bool value ) { if( value ) return "1"; else return "0"; } inline const char* EngineMarshallData( const char* str ) { // The API assumes that if you pass a plain "const char*" through it, then you are referring // to string storage with non-local lifetime that can be safely passed to the control layer. return str; } template< typename T > inline const char* EngineMarshallData( T* object ) { return ( object ? object->getIdString() : "0" ); } template< typename T > inline const char* EngineMarshallData( const T* object ) { return ( object ? object->getIdString() : "0" ); } inline const char* EngineMarshallData( U32 value ) { return EngineMarshallData( S32( value ) ); } /// Marshal data from native into client form stored directly in /// client function invocation vector. template< typename T > inline void EngineMarshallData( const T& arg, S32& argc, ConsoleValue *argv ) { const char* str = castConsoleTypeToString(arg);; argv[ argc++ ].setString(str); } inline void EngineMarshallData( bool arg, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setBool(arg); } inline void EngineMarshallData( S32 arg, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setInt(arg); } inline void EngineMarshallData( U32 arg, S32& argc, ConsoleValue *argv ) { EngineMarshallData( S32( arg ), argc, argv ); } inline void EngineMarshallData( F32 arg, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setFloat(arg); } inline void EngineMarshallData( const char* arg, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setString(arg); } inline void EngineMarshallData( char* arg, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setString(arg); } template< typename T > inline void EngineMarshallData( T* object, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setInt(object ? object->getId() : 0); } template< typename T > inline void EngineMarshallData( const T* object, S32& argc, ConsoleValue *argv ) { argv[ argc++ ].setInt(object ? object->getId() : 0); } /// Unmarshal data from client form to engine form. /// /// This is wrapped in an a struct as partial specializations on function /// templates are not allowed in C++. template< typename T > struct EngineUnmarshallData { T operator()( const char* str ) const { T value; castConsoleTypeFromString( value, str ); return value; } }; template<> struct EngineUnmarshallData< S32 > { S32 operator()( ConsoleValue &ref ) const { return (S32)ref.getInt(); } S32 operator()( const char* str ) const { return dAtoi( str ); } }; template<> struct EngineUnmarshallData< U32 > { U32 operator()( ConsoleValue &ref ) const { return (U32)ref.getInt(); } U32 operator()( const char* str ) const { return dAtoui( str ); } }; template<> struct EngineUnmarshallData< F32 > { F32 operator()( ConsoleValue &ref ) const { return (F32)ref.getFloat(); } F32 operator()( const char* str ) const { return dAtof( str ); } }; template<> struct EngineUnmarshallData< U8 > { U8 operator()( ConsoleValue &ref ) const { return (U8)((S32)ref.getInt()); } U8 operator()( const char* str ) const { return dAtoui( str ); } }; template<> struct EngineUnmarshallData< const char* > { const char* operator()( ConsoleValue &ref ) const { return ref.getString(); } const char* operator()( const char* str ) const { return str; } }; template< typename T > struct EngineUnmarshallData< T* > { T* operator()( ConsoleValue &ref ) const { return dynamic_cast< T* >( Sim::findObject( ref ) ); } T* operator()( const char* str ) const { return dynamic_cast< T* >( Sim::findObject( str ) ); } }; template<> struct EngineUnmarshallData< void > { void operator()( ConsoleValue& ) const {} void operator()( const char* ) const {} }; template<> struct EngineUnmarshallData< ConsoleValue > { ConsoleValue operator()( ConsoleValue ref ) const { return std::move(ref); } }; /// @} /// @name C to C++ Trampolines /// /// The trampolines serve two purposes: /// /// For one, they ensure that no matter what argument types are specified by users of the engine API macros, the correct /// argument value types are enforced on the functions exported by the engine. Let's say, for example, the user writes /// a function that takes a "Point3F direction" argument, then the template machinery here will automatically expose an /// API function that takes a "Point3F& direction" argument. /// /// Secondly, the templates jump the incoming calls from extern "C" space into C++ space. This is mostly relevant for /// methods only as they will need an implicit object type argument. /// /// @{ // Helper type to factor out commonalities between function and method trampolines. template struct _EngineTrampoline { struct Args {}; }; template< typename R, typename ...ArgTs > struct _EngineTrampoline< R( ArgTs ... ) > { template using AVT = typename EngineTypeTraits::ArgumentValueType; typedef fixed_tuple ...> Args; Args argT; }; template< typename T > struct _EngineFunctionTrampolineBase : public _EngineTrampoline< T > { typedef T FunctionType; }; // Trampolines for any call-ins that aren't methods. template< typename T > struct _EngineFunctionTrampoline {}; template< typename R, typename ...ArgTs > struct _EngineFunctionTrampoline< R(ArgTs...) > : public _EngineFunctionTrampolineBase< R(ArgTs...) > { private: using Super = _EngineFunctionTrampolineBase< R(ArgTs...) >; using SelfType = _EngineFunctionTrampoline< R(ArgTs...) >; using ArgsType = typename _EngineFunctionTrampolineBase< R(ArgTs ...) >::Args; template struct Seq {}; template struct Gens : Gens {}; template struct Gens<0, I...>{ typedef Seq type; }; template static typename fixed_tuple_element>::type getAndToType(const ArgsType& args) { return EngineTypeTraits>::type>::ArgumentToValue(fixed_tuple_accessor::get(args)); } template static R dispatchHelper(typename Super::FunctionType fn, const ArgsType& args, Seq) { return R( fn(SelfType::template getAndToType(args) ...) ); } using SeqType = typename Gens::type; public: static R jmp(typename Super::FunctionType fn, const ArgsType& args ) { return dispatchHelper(fn, args, SeqType()); } }; // Trampolines for engine methods template< typename T > struct _EngineMethodTrampolineBase : public _EngineTrampoline< T > {}; template< typename Frame, typename T > struct _EngineMethodTrampoline {}; template< typename Frame, typename R, typename ...ArgTs > struct _EngineMethodTrampoline< Frame, R(ArgTs ...) > : public _EngineMethodTrampolineBase< R(ArgTs ...) > { using FunctionType = R( typename Frame::ObjectType*, ArgTs ...); private: using Super = _EngineMethodTrampolineBase< R(ArgTs ...) >; using SelfType = _EngineMethodTrampoline< Frame, R(ArgTs ...) >; using ArgsType = typename _EngineMethodTrampolineBase< R(ArgTs ...) >::Args; template struct Seq {}; template struct Gens : Gens {}; template struct Gens<0, I...>{ typedef Seq type; }; template static typename fixed_tuple_element>::type getAndToType(const ArgsType& args) { return EngineTypeTraits>::type>::ArgumentToValue(fixed_tuple_accessor::get(args)); } template static R dispatchHelper(Frame f, const ArgsType& args, Seq) { return R(f._exec(SelfType::template getAndToType(args) ...)); } using SeqType = typename Gens::type; public: static R jmp( typename Frame::ObjectType* object, const ArgsType& args ) { Frame f; f.object = object; return dispatchHelper(f, args, SeqType()); } }; /// @} /// @name Thunking /// /// Internal functionality for thunks placed between TorqueScript calls of engine functions and their native /// implementations. /// /// @note The functionality in this group is specific to the console interop system. /// @{ // Helper function to return data from a thunk. template< typename T > inline const char* _EngineConsoleThunkReturnValue( const T& value ) { return EngineMarshallData( value ); } inline bool _EngineConsoleThunkReturnValue( bool value ) { return value; } inline S32 _EngineConsoleThunkReturnValue( S32 value ) { return value; } inline F32 _EngineConsoleThunkReturnValue( F32 value ) { return value; } inline const char* _EngineConsoleThunkReturnValue( const String& str ) { return Con::getReturnBuffer( str ); } inline const char* _EngineConsoleThunkReturnValue( const char* value ) { return EngineMarshallData( value ); } template< typename T > inline const char* _EngineConsoleThunkReturnValue( T* value ) { return ( value ? value->getIdString() : "" ); } template< typename T > inline const char* _EngineConsoleThunkReturnValue( const T* value ) { return ( value ? value->getIdString() : "" ); } // Helper class to determine the type of callback registered with the console system. template< typename R > struct _EngineConsoleThunkType { typedef const char* ReturnType; typedef StringCallback CallbackType; }; template<> struct _EngineConsoleThunkType< S32 > { typedef S32 ReturnType; typedef IntCallback CallbackType; }; template<> struct _EngineConsoleThunkType< U32 > { typedef U32 ReturnType; typedef IntCallback CallbackType; }; template<> struct _EngineConsoleThunkType< F32 > { typedef F32 ReturnType; typedef FloatCallback CallbackType; }; template<> struct _EngineConsoleThunkType< bool > { typedef bool ReturnType; typedef BoolCallback CallbackType; }; template<> struct _EngineConsoleThunkType< void > { typedef void ReturnType; typedef VoidCallback CallbackType; }; // Helper struct to count the number of parameters in a function list. // The setup through operator () allows omitting the the argument list entirely. struct _EngineConsoleThunkCountArgs { template U32 operator()(ArgTs... args){ return sizeof...(ArgTs); } operator U32() const{ // FIXME: WHAT IS THIS?? I'm pretty sure it's incorrect, and it's the version that is invoked by all the macros return 0; } }; // Encapsulation of a legacy console function invocation. namespace engineAPI{ namespace detail{ template struct ThunkHelpers { using SelfType = ThunkHelpers; using FunctionType = R(*)(ArgTs...); template using MethodType = R(Frame::*)(ArgTs ...) const; template using IthArgType = typename std::tuple_element >::type; template struct Seq {}; template struct Gens : Gens {}; template struct Gens<0, I...>{ typedef Seq type; }; typedef typename _EngineConsoleThunkType< R >::ReturnType ReturnType; static const S32 NUM_ARGS = sizeof...(ArgTs) + startArgc; template static IthArgType getRealArgValue(S32 argc, ConsoleValue *argv, const _EngineFunctionDefaultArguments< void(RealArgTs...) >& defaultArgs) { if((startArgc + index) < argc) { return EngineUnmarshallData< IthArgType >()( argv[ startArgc + index ] ); } else { return fixed_tuple_accessor::get(defaultArgs.mArgs); } } template static R dispatchHelper(S32 argc, ConsoleValue *argv, FunctionType fn, const _EngineFunctionDefaultArguments< void(ArgTs...) >& defaultArgs, Seq){ return fn(SelfType::getRealArgValue(argc, argv, defaultArgs) ...); } template static R dispatchHelper(S32 argc, ConsoleValue *argv, MethodType fn, Frame* frame, const _EngineFunctionDefaultArguments< void( typename Frame::ObjectType*, ArgTs...) >& defaultArgs, Seq){ return (frame->*fn)(SelfType::getRealArgValue(argc, argv, defaultArgs) ...); } using SeqType = typename Gens::type; }; template struct MarshallHelpers { template static void marshallEach(S32 &argc, ArgVT *argv, const ArgTs& ...args){} template static void marshallEach(S32 &argc, ArgVT *argv, const H& head, const Tail& ...tail){ argv[argc++] = EngineMarshallData(head); marshallEach(argc, argv, tail...); } }; template<> struct MarshallHelpers { template static void marshallEach(S32 &argc, ConsoleValue *argv, const ArgTs& ...args){} template static void marshallEach(S32 &argc, ConsoleValue *argv, const H& head, const Tail& ...tail){ EngineMarshallData(head, argc, argv); marshallEach(argc, argv, tail...); } }; } } template< S32 startArgc, typename T > struct _EngineConsoleThunk {}; template< S32 startArgc, typename R, typename ...ArgTs > struct _EngineConsoleThunk< startArgc, R(ArgTs...) > { private: using Helper = engineAPI::detail::ThunkHelpers; using SeqType = typename Helper::SeqType; public: typedef typename Helper::FunctionType FunctionType; typedef typename Helper::ReturnType ReturnType; template using MethodType = typename Helper::template MethodType; static const S32 NUM_ARGS = Helper::NUM_ARGS; static ReturnType thunk( S32 argc, ConsoleValue *argv, FunctionType fn, const _EngineFunctionDefaultArguments< void(ArgTs...) >& defaultArgs) { return _EngineConsoleThunkReturnValue( Helper::dispatchHelper(argc, argv, fn, defaultArgs, SeqType())); } template< typename Frame > static ReturnType thunk( S32 argc, ConsoleValue *argv, MethodType fn, Frame* frame, const _EngineFunctionDefaultArguments< void( typename Frame::ObjectType*, ArgTs...) >& defaultArgs) { return _EngineConsoleThunkReturnValue( Helper::dispatchHelper(argc, argv, fn, frame, defaultArgs, SeqType())); } }; // Have to do a partial specialization for void-returning functions :( template struct _EngineConsoleThunk { private: using Helper = engineAPI::detail::ThunkHelpers; using SeqType = typename Helper::SeqType; public: typedef typename Helper::FunctionType FunctionType; typedef typename Helper::ReturnType ReturnType; template using MethodType = typename Helper::template MethodType; static const S32 NUM_ARGS = Helper::NUM_ARGS; static void thunk( S32 argc, ConsoleValue *argv, FunctionType fn, const _EngineFunctionDefaultArguments< void(ArgTs...) >& defaultArgs) { Helper::dispatchHelper(argc, argv, fn, defaultArgs, SeqType()); } template< typename Frame > static void thunk( S32 argc, ConsoleValue *argv, MethodType fn, Frame* frame, const _EngineFunctionDefaultArguments< void( typename Frame::ObjectType*, ArgTs...) >& defaultArgs) { Helper::dispatchHelper(argc, argv, fn, frame, defaultArgs, SeqType()); } }; /// @} /// @name API Definition Macros /// /// The macros in this group allow to create engine API functions that work both with the /// legacy console system as well as with the new engine export system. As such, they only /// support those function features that are available in both systems. This means that for /// console-style variadic functions, the ConsoleXXX must be used and that for overloaded /// and/or C-style variadic functions as well as for placing functions in export scopes, /// DEFINE_CALLIN must be used directly. /// /// When the console system is removed, the console thunking functionality will be removed /// from these macros but otherwise they will remain unchanged and in place. /// /// @{ // Helpers to implement initialization checks. Pulled out into separate macros so this can be deactivated easily. // Especially important for the initialize() function itself. #define _CHECK_ENGINE_INITIALIZED_IMPL( fnName, returnType ) \ if( !engineAPI::gIsInitialized ) \ { \ Con::errorf( "EngineAPI: Engine not initialized when calling " #fnName ); \ return EngineTypeTraits< returnType >::ReturnValue( EngineTypeTraits< returnType >::ReturnValueType() ); \ } #define _CHECK_ENGINE_INITIALIZED( fnName, returnType ) _CHECK_ENGINE_INITIALIZED_IMPL( fnName, returnType ) /// Define a call-in point for calling into the engine. /// /// @param name The name of the function as it should be seen by the control layer. /// @param returnType The value type returned to the control layer. /// @param args The argument list as it would appear on the function definition /// @param defaultArgs The list of default argument values. /// @param usage The usage doc string for the engine API reference. /// /// @code /// DefineEngineFunction( myFunction, int, ( float f, const String& s ), ( "value for s" ), "This is my function." ) /// { /// return int( f ) + dAtoi( s ); /// } /// @endcode #define DefineEngineFunction( name, returnType, args, defaultArgs, usage ) \ static inline returnType _fn ## name ## impl args; \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType fn ## name \ ( _EngineFunctionTrampoline< returnType args >::Args a ) \ { \ _CHECK_ENGINE_INITIALIZED( name, returnType ); \ return EngineTypeTraits< returnType >::ReturnValue( \ _EngineFunctionTrampoline< returnType args >::jmp( _fn ## name ## impl, a ) \ ); \ } \ static _EngineFunctionDefaultArguments< void args > _fn ## name ## DefaultArgs defaultArgs; \ static EngineFunctionInfo _fn ## name ## FunctionInfo( \ #name, \ &_SCOPE<>()(), \ usage, \ #returnType " " #name #args, \ "fn" #name, \ TYPE< returnType args >(), \ &_fn ## name ## DefaultArgs, \ ( void* ) &fn ## name, \ 0 \ ); \ static _EngineConsoleThunkType< returnType >::ReturnType _ ## name ## caster( SimObject*, S32 argc, ConsoleValue *argv ) \ { \ return _EngineConsoleThunkType< returnType >::ReturnType( _EngineConsoleThunk< 1, returnType args >::thunk( \ argc, argv, &_fn ## name ## impl, _fn ## name ## DefaultArgs \ ) ); \ } \ static ConsoleFunctionHeader _ ## name ## header \ ( #returnType, #args, #defaultArgs ); \ static ConsoleConstructor \ _ ## name ## obj( NULL, #name, _EngineConsoleThunkType< returnType >::CallbackType( _ ## name ## caster ), usage, \ _EngineConsoleThunk< 1, returnType args >::NUM_ARGS - _EngineConsoleThunkCountArgs() defaultArgs, \ _EngineConsoleThunk< 1, returnType args >::NUM_ARGS, \ false, &_ ## name ## header \ ); \ static inline returnType _fn ## name ## impl args // The next thing is a bit tricky. DefineEngineMethod allows to make the 'object' (=this) argument to the function // implicit which presents quite an obstacle for the macro internals as the engine export system requires the // name of a DLL symbol that represents an extern "C" function with an explicit first object pointer argument. // // Even if we ignored the fact that we don't have a guarantee how the various C++ compilers implement implicit 'this' arguments, // we could still not just use a C++ method for this as then we would have to get past the C++ compiler's mangling to // get to the function symbol name (let alone the fact that typing this method correctly would be tricky). // // So, the trick employed here is to package all but the implicit 'this' argument in a structure and then define an // extern "C" function that takes the object pointer as a first argument and the struct type as the second argument. // This will result in a function with an identical stack call frame layout to the function we want. // // Unfortunately, that still requires that function to chain on to the real user-defined function. To do this // cleanly and portably, _EngineMethodTrampoline is used to unpack and jump the call from extern "C" into C++ space. // In optimized builds, the compiler should be smart enough to pretty much optimize all our trickery here away. #define _DefineMethodTrampoline( className, name, returnType, args ) \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType \ fn ## className ## _ ## name ( className* object, _EngineMethodTrampoline< _ ## className ## name ## frame, returnType args >::Args a )\ { \ _CHECK_ENGINE_INITIALIZED( className::name, returnType ); \ return EngineTypeTraits< returnType >::ReturnValue( \ _EngineMethodTrampoline< _ ## className ## name ## frame, returnType args >::jmp( object, a ) \ ); \ } /// Define a call-in point for calling a method on an engine object. /// /// @param name The name of the C++ class. /// @param name The name of the method as it should be seen by the control layer. /// @param returnType The value type returned to the control layer. /// @param args The argument list as it would appear on the function definition /// @param defaultArgs The list of default argument values. /// @param usage The usage doc string for the engine API reference. /// /// @code /// DefineEngineMethod( MyClass, myMethod, int, ( float f, const String& s ), ( "value for s" ), "This is my method." ) /// { /// return object->someMethod( f, s ); /// } /// @endcode #define DefineEngineMethod( className, name, returnType, args, defaultArgs, usage ) \ struct _ ## className ## name ## frame \ { \ typedef className ObjectType; \ className* object; \ inline returnType _exec args const; \ }; \ _DefineMethodTrampoline( className, name, returnType, args ); \ static _EngineFunctionDefaultArguments< _EngineMethodTrampoline< _ ## className ## name ## frame, void args >::FunctionType > \ _fn ## className ## name ## DefaultArgs defaultArgs; \ static EngineFunctionInfo _fn ## className ## name ## FunctionInfo( \ #name, \ &_SCOPE< className >()(), \ usage, \ "virtual " #returnType " " #name #args, \ "fn" #className "_" #name, \ TYPE< _EngineMethodTrampoline< _ ## className ## name ## frame, returnType args >::FunctionType >(), \ &_fn ## className ## name ## DefaultArgs, \ ( void* ) &fn ## className ## _ ## name, \ 0 \ ); \ static _EngineConsoleThunkType< returnType >::ReturnType _ ## className ## name ## caster( SimObject* object, S32 argc, ConsoleValue *argv ) \ { \ _ ## className ## name ## frame frame; \ frame.object = static_cast< className* >( object ); \ return _EngineConsoleThunkType< returnType >::ReturnType( _EngineConsoleThunk< 2, returnType args >::thunk( \ argc, argv, &_ ## className ## name ## frame::_exec, &frame, _fn ## className ## name ## DefaultArgs \ ) ); \ } \ static ConsoleFunctionHeader _ ## className ## name ## header \ ( #returnType, #args, #defaultArgs ); \ static ConsoleConstructor \ className ## name ## obj( #className, #name, \ _EngineConsoleThunkType< returnType >::CallbackType( _ ## className ## name ## caster ), usage, \ _EngineConsoleThunk< 2, returnType args >::NUM_ARGS - _EngineConsoleThunkCountArgs() defaultArgs, \ _EngineConsoleThunk< 2, returnType args >::NUM_ARGS, \ false, &_ ## className ## name ## header \ ); \ returnType _ ## className ## name ## frame::_exec args const /// Define a call-in point for calling into the engine. Unlike with DefineEngineFunction, the statically /// callable function will be confined to the namespace of the given class. /// /// @param classname The name of the C++ class (or a registered export scope). /// @param name The name of the method as it should be seen by the control layer. /// @param returnType The value type returned to the control layer. /// @param args The argument list as it would appear on the function definition /// @param defaultArgs The list of default argument values. /// @param usage The usage doc string for the engine API reference. /// /// @code /// DefineEngineStaticMethod( MyClass, myMethod, int, ( float f, string s ), ( "value for s" ), "This is my method." ) /// { /// } /// @endcode #define DefineEngineStaticMethod( className, name, returnType, args, defaultArgs, usage ) \ static inline returnType _fn ## className ## name ## impl args; \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType fn ## className ## _ ## name \ ( _EngineFunctionTrampoline< returnType args >::Args a ) \ { \ _CHECK_ENGINE_INITIALIZED( className::name, returnType ); \ return EngineTypeTraits< returnType >::ReturnValue( \ _EngineFunctionTrampoline< returnType args >::jmp( _fn ## className ## name ## impl, a ) \ ); \ } \ static _EngineFunctionDefaultArguments< void args > _fn ## className ## name ## DefaultArgs defaultArgs; \ static EngineFunctionInfo _fn ## name ## FunctionInfo( \ #name, \ &_SCOPE< className >()(), \ usage, \ #returnType " " #name #args, \ "fn" #className "_" #name, \ TYPE< returnType args >(), \ &_fn ## className ## name ## DefaultArgs, \ ( void* ) &fn ## className ## _ ## name, \ 0 \ ); \ static _EngineConsoleThunkType< returnType >::ReturnType _ ## className ## name ## caster( SimObject*, S32 argc, ConsoleValue *argv )\ { \ return _EngineConsoleThunkType< returnType >::ReturnType( _EngineConsoleThunk< 1, returnType args >::thunk( \ argc, argv, &_fn ## className ## name ## impl, _fn ## className ## name ## DefaultArgs \ ) ); \ } \ static ConsoleFunctionHeader _ ## className ## name ## header \ ( #returnType, #args, #defaultArgs, true ); \ static ConsoleConstructor \ _ ## className ## name ## obj( #className, #name, _EngineConsoleThunkType< returnType >::CallbackType( _ ## className ## name ## caster ), usage, \ _EngineConsoleThunk< 1, returnType args >::NUM_ARGS - _EngineConsoleThunkCountArgs() defaultArgs, \ _EngineConsoleThunk< 1, returnType args >::NUM_ARGS, \ false, &_ ## className ## name ## header \ ); \ static inline returnType _fn ## className ## name ## impl args # define DefineEngineStringlyVariadicFunction(name,returnType,minArgs,maxArgs,usage) \ static inline returnType _fn ## name ## impl (SimObject *, S32 argc, ConsoleValue *argv); \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType fn ## name \ (Vector* vec) \ { \ _CHECK_ENGINE_INITIALIZED( name, returnType ); \ StringArrayToConsoleValueWrapper args(vec->size(), vec->address()); \ return EngineTypeTraits< returnType >::ReturnValue( \ _fn ## name ## impl(NULL, args.count(), args) \ ); \ } \ static _EngineFunctionDefaultArguments< void (Vector* vec) > _fn ## name ## DefaultArgs; \ static EngineFunctionInfo _fn ## name ## FunctionInfo( \ #name, \ &_SCOPE<>()(), \ usage, \ #returnType " " #name "(Vector args)", \ "fn" #name, \ TYPE< returnType (Vector* vec) >(), \ &_fn ## name ## DefaultArgs, \ ( void* ) &fn ## name, \ 0 \ ); \ ConsoleConstructor cc_##name##_obj(NULL,#name,_fn ## name ## impl,usage,minArgs,maxArgs); \ returnType _fn ## name ## impl(SimObject *, S32 argc, ConsoleValue *argv) # define DefineEngineStringlyVariadicMethod(className, name,returnType,minArgs,maxArgs,usage) \ struct _ ## className ## name ## frame \ { \ typedef className ObjectType; \ className* object; \ inline returnType _exec (S32 argc, ConsoleValue* argv) const; \ }; \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType fn ## className ## _ ## name \ (className* object, Vector* vec) \ { \ _CHECK_ENGINE_INITIALIZED( name, returnType ); \ StringArrayToConsoleValueWrapper args(vec->size(), vec->address()); \ _ ## className ## name ## frame frame {}; \ frame.object = static_cast< className* >( object ); \ return EngineTypeTraits< returnType >::ReturnValue( \ frame._exec(args.count(), args) \ ); \ } \ static _EngineFunctionDefaultArguments< void (className* object, S32 argc, const char** argv) > \ _fn ## className ## name ## DefaultArgs; \ static EngineFunctionInfo _fn ## className ## name ## FunctionInfo( \ #name, \ &_SCOPE< className >()(), \ usage, \ "virtual " #returnType " " #name "(Vector args)", \ "fn" #className "_" #name, \ TYPE< _EngineMethodTrampoline< _ ## className ## name ## frame, returnType (Vector vec) >::FunctionType >(), \ &_fn ## className ## name ## DefaultArgs, \ ( void* ) &fn ## className ## _ ## name, \ 0 \ ); \ returnType cm_##className##_##name##_caster(SimObject* object, S32 argc, ConsoleValue* argv) { \ AssertFatal( dynamic_cast( object ), "Object passed to " #name " is not a " #className "!" ); \ _ ## className ## name ## frame frame {}; \ frame.object = static_cast< className* >( object ); \ conmethod_return_##returnType ) frame._exec(argc,argv); \ }; \ ConsoleConstructor cc_##className##_##name##_obj(#className,#name,cm_##className##_##name##_caster,usage,minArgs,maxArgs); \ inline returnType _ ## className ## name ## frame::_exec(S32 argc, ConsoleValue *argv) const // The following three macros are only temporary. They allow to define engineAPI functions using the framework // here in this file while being visible only in the new API. When the console interop is removed, these macros // can be removed and all their uses be replaced with their corresponding versions that now still include support // for the console (e.g. DefineNewEngineFunction should become DefineEngineFunction). #define DefineNewEngineFunction( name, returnType, args, defaultArgs, usage ) \ static inline returnType _fn ## name ## impl args; \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType fn ## name \ ( _EngineFunctionTrampoline< returnType args >::Args a ) \ { \ _CHECK_ENGINE_INITIALIZED( name, returnType ); \ return EngineTypeTraits< returnType >::ReturnValue( \ _EngineFunctionTrampoline< returnType args >::jmp( _fn ## name ## impl, a ) \ ); \ } \ static _EngineFunctionDefaultArguments< void args > _fn ## name ## DefaultArgs defaultArgs; \ static EngineFunctionInfo _fn ## name ## FunctionInfo( \ #name, \ &_SCOPE<>()(), \ usage, \ #returnType " " #name #args, \ "fn" #name, \ TYPE< returnType args >(), \ &_fn ## name ## DefaultArgs, \ ( void* ) &fn ## name, \ 0 \ ); \ static inline returnType _fn ## name ## impl args #define DefineNewEngineMethod( className, name, returnType, args, defaultArgs, usage ) \ struct _ ## className ## name ## frame \ { \ typedef className ObjectType; \ className* object; \ inline returnType _exec args const; \ }; \ _DefineMethodTrampoline( className, name, returnType, args ); \ static _EngineFunctionDefaultArguments< _EngineMethodTrampoline< _ ## className ## name ## frame, void args >::FunctionType > \ _fn ## className ## name ## DefaultArgs defaultArgs; \ static EngineFunctionInfo _fn ## className ## name ## FunctionInfo( \ #name, \ &_SCOPE< className >()(), \ usage, \ "virtual " #returnType " " #name #args, \ "fn" #className "_" #name, \ TYPE< _EngineMethodTrampoline< _ ## className ## name ## frame, returnType args >::FunctionType >(), \ &_fn ## className ## name ## DefaultArgs, \ ( void* ) &fn ## className ## _ ## name, \ 0 \ ); \ returnType _ ## className ## name ## frame::_exec args const #define DefineNewEngineStaticMethod( className, name, returnType, args, defaultArgs, usage ) \ static inline returnType _fn ## className ## name ## impl args; \ TORQUE_API EngineTypeTraits< returnType >::ReturnValueType fn ## className ## _ ## name \ ( _EngineFunctionTrampoline< returnType args >::Args a ) \ { \ _CHECK_ENGINE_INITIALIZED( className::name, returnType ); \ return EngineTypeTraits< returnType >::ReturnValue( \ _EngineFunctionTrampoline< returnType args >::jmp( _fn ## className ## name ## impl, a ) \ ); \ } \ static _EngineFunctionDefaultArguments< void args > _fn ## className ## name ## DefaultArgs defaultArgs; \ static EngineFunctionInfo _fn ## name ## FunctionInfo( \ #name, \ &_SCOPE< className >()(), \ usage, \ #returnType " " #name #args, \ "fn" #className "_" #name, \ TYPE< returnType args >(), \ &_fn ## className ## name ## DefaultArgs, \ ( void* ) &fn ## className ## _ ## name, \ 0 \ ); \ static inline returnType _fn ## className ## name ## impl args /// @} //============================================================================= // Callbacks. //============================================================================= /// Matching implement for DECLARE_CALLBACK. /// /// /// @warn With the new interop system, method-style callbacks must not be triggered on object /// that are being created! This is because the control layer will likely not yet have a fully valid wrapper /// object in place for the EngineObject under construction. #define IMPLEMENT_CALLBACK( class, name, returnType, args, argNames, usageString ) \ struct _ ## class ## name ## frame { typedef class ObjectType; }; \ TORQUE_API _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType* cb ## class ## _ ## name; \ TORQUE_API void set_cb ## class ## _ ## name( \ _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType fn ) \ { cb ## class ## _ ## name = fn; } \ _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType* cb ## class ## _ ## name; \ namespace { \ ::EngineFunctionInfo _cb ## class ## name( \ #name, \ &::_SCOPE< class >()(), \ usageString, \ "virtual " #returnType " " #name #args, \ "cb" #class "_" #name, \ ::TYPE< _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType >(), \ NULL, \ ( void* ) &cb ## class ## _ ## name, \ EngineFunctionCallout \ ); \ } \ returnType class::name ## _callback args \ { \ if( cb ## class ## _ ## name ) { \ _EngineCallbackHelper cbh( this, reinterpret_cast< const void* >( cb ## class ## _ ## name ) ); \ return returnType( cbh.call< returnType > argNames ); \ } \ if( engineAPI::gUseConsoleInterop ) \ { \ static StringTableEntry sName = StringTable->insert( #name ); \ _EngineConsoleCallbackHelper cbh( sName, this ); \ return returnType( cbh.call< returnType > argNames ); \ } \ return returnType(); \ } \ namespace { \ ConsoleFunctionHeader _ ## class ## name ## header( \ #returnType, #args, "" ); \ ConsoleConstructor _ ## class ## name ## obj( #class, #name, usageString, &_ ## class ## name ## header ); \ } /// Used to define global callbacks not associated with /// any particular class or namespace. #define IMPLEMENT_GLOBAL_CALLBACK( name, returnType, args, argNames, usageString ) \ DEFINE_CALLOUT( cb ## name, name,, returnType, args, 0, usageString ); \ returnType name ## _callback args \ { \ if( cb ## name ) \ return returnType( cb ## name argNames ); \ if( engineAPI::gUseConsoleInterop ) \ { \ static StringTableEntry sName = StringTable->insert( #name ); \ _EngineConsoleCallbackHelper cbh( sName, NULL ); \ return returnType( cbh.call< returnType > argNames ); \ } \ return returnType(); \ } \ namespace { \ ConsoleFunctionHeader _ ## name ## header( \ #returnType, #args, "" ); \ ConsoleConstructor _ ## name ## obj( NULL, #name, usageString, &_ ## name ## header ); \ } // Again, temporary macros to allow splicing the API while we still have the console interop around. #define IMPLEMENT_CONSOLE_CALLBACK( class, name, returnType, args, argNames, usageString ) \ returnType class::name ## _callback args \ { \ if( engineAPI::gUseConsoleInterop ) \ { \ static StringTableEntry sName = StringTable->insert( #name ); \ _EngineConsoleCallbackHelper cbh( sName, this ); \ return returnType( cbh.call< returnType > argNames ); \ } \ return returnType(); \ } \ namespace { \ ConsoleFunctionHeader _ ## class ## name ## header( \ #returnType, #args, "" ); \ ConsoleConstructor _ ## class ## name ## obj( #class, #name, usageString, &_ ## class ## name ## header ); \ } #define IMPLEMENT_NEW_CALLBACK( class, name, returnType, args, argNames, usageString ) \ struct _ ## class ## name ## frame { typedef class ObjectType; }; \ TORQUE_API _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType* cb ## class ## _ ## name; \ TORQUE_API void set_cb ## class ## _ ## name( \ _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType fn ) \ { cb ## class ## _ ## name = fn; } \ _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType* cb ## class ## _ ## name; \ namespace { \ ::EngineFunctionInfo _cb ## class ## name( \ #name, \ &::_SCOPE< class >()(), \ usageString, \ "virtual " #returnType " " #name #args, \ "cb" #class "_" #name, \ ::TYPE< _EngineMethodTrampoline< _ ## class ## name ## frame, returnType args >::FunctionType >(), \ NULL, \ &cb ## class ## _ ## name, \ EngineFunctionCallout \ ); \ } \ returnType class::name ## _callback args \ { \ if( cb ## class ## _ ## name ) { \ _EngineCallbackHelper cbh( this, reinterpret_cast< const void* >( cb ## class ## _ ## name ) ); \ return returnType( cbh.call< returnType > argNames ); \ } \ return returnType(); \ } // Internal helper class for doing call-outs in the new interop. struct _EngineCallbackHelper { protected: EngineObject* mThis; const void* mFn; public: _EngineCallbackHelper( EngineObject* pThis, const void* fn ) : mThis( pThis ), mFn( fn ) {} template< typename R, typename ...ArgTs > R call(ArgTs ...args) const { typedef R( FunctionType )( EngineObject*, ArgTs... ); return R( reinterpret_cast< FunctionType* >( const_cast(mFn) )( mThis, args... ) ); } }; #include "console/stringStack.h" // Internal helper for callback support in legacy console system. struct _BaseEngineConsoleCallbackHelper { public: /// Matches up to storeArgs. static const U32 MAX_ARGUMENTS = 11; SimObject* mThis; S32 mInitialArgc; S32 mArgc; StringTableEntry mCallbackName; ConsoleValue mArgv[ MAX_ARGUMENTS + 2 ]; ConsoleValue _exec(); ConsoleValue _execLater(SimConsoleThreadExecEvent *evt); _BaseEngineConsoleCallbackHelper(): mThis(NULL), mInitialArgc(0), mArgc(0), mCallbackName(StringTable->EmptyString()){;} }; // Base helper for console callbacks struct _EngineConsoleCallbackHelper : public _BaseEngineConsoleCallbackHelper { private: using Helper = engineAPI::detail::MarshallHelpers; public: _EngineConsoleCallbackHelper( StringTableEntry callbackName, SimObject* pThis ) { mThis = pThis; mArgc = mInitialArgc = pThis ? 2 : 1 ; mCallbackName = callbackName; } template< typename R, typename ...ArgTs > R call(ArgTs ...args) { if (Con::isMainThread()) { ConsoleStackFrameSaver sav; sav.save(); mArgv[ 0 ].setStringTableEntry(mCallbackName); Helper::marshallEach(mArgc, mArgv, args...); return R( EngineUnmarshallData< R >()( _exec() ) ); } else { SimConsoleThreadExecCallback cb; SimConsoleThreadExecEvent *evt = new SimConsoleThreadExecEvent(mArgc + sizeof...(ArgTs), NULL, false, &cb); evt->populateArgs(mArgv); mArgv[ 0 ].setStringTableEntry(mCallbackName); Helper::marshallEach(mArgc, mArgv, args...); Sim::postEvent((SimObject*)Sim::getRootGroup(), evt, Sim::getCurrentTime()); return R( EngineUnmarshallData< R >()( cb.waitForResult() ) ); } } }; // Override for when first parameter is presumably a SimObject*, in which case A will be absorbed as the callback template struct _EngineConsoleExecCallbackHelper : public _BaseEngineConsoleCallbackHelper { private: using Helper = engineAPI::detail::MarshallHelpers; public: _EngineConsoleExecCallbackHelper( SimObject* pThis ) { mThis = pThis; mArgc = mInitialArgc = 2; mCallbackName = NULL; } template< typename R, typename SCB, typename ...ArgTs > R call( SCB simCB , ArgTs ...args ) { if (Con::isMainThread()) { ConsoleStackFrameSaver sav; sav.save(); mArgv[ 0 ].setString(simCB); Helper::marshallEach(mArgc, mArgv, args...); return R( EngineUnmarshallData< R >()( _exec() ) ); } else { SimConsoleThreadExecCallback cb; SimConsoleThreadExecEvent *evt = new SimConsoleThreadExecEvent(mArgc+sizeof...(ArgTs), NULL, true, &cb); evt->populateArgs(mArgv); mArgv[ 0 ].setString(simCB); Helper::marshallEach(mArgc, mArgv, args...); Sim::postEvent(mThis, evt, Sim::getCurrentTime()); return R( EngineUnmarshallData< R >()( cb.waitForResult() ) ); } } }; // Override for when first parameter is const char* template<> struct _EngineConsoleExecCallbackHelper : public _BaseEngineConsoleCallbackHelper { private: using Helper = engineAPI::detail::MarshallHelpers; public: _EngineConsoleExecCallbackHelper( const char *callbackName ) { mThis = NULL; mArgc = mInitialArgc = 1; mCallbackName = StringTable->insert(callbackName); } template< typename R, typename ...ArgTs > R call(ArgTs ...args) { if (Con::isMainThread()) { ConsoleStackFrameSaver sav; sav.save(); mArgv[ 0 ].setStringTableEntry(mCallbackName); Helper::marshallEach(mArgc, mArgv, args...); return R( EngineUnmarshallData< R >()( _exec() ) ); } else { SimConsoleThreadExecCallback cb; SimConsoleThreadExecEvent *evt = new SimConsoleThreadExecEvent(mArgc+sizeof...(ArgTs), NULL, false, &cb); evt->populateArgs(mArgv); mArgv[ 0 ].setStringTableEntry(mCallbackName); Helper::marshallEach(mArgc, mArgv, args...); Sim::postEvent((SimObject*)Sim::getRootGroup(), evt, Sim::getCurrentTime()); return R( EngineUnmarshallData< R >()( cb.waitForResult() ) ); } } }; // Re-enable some VC warnings we disabled for this file. #pragma warning( pop ) // 4510 and 4610 #endif // !_ENGINEAPI_H_