engineTypeInfo.h

Public Functions

DECLARE_ENUM_R(EngineTypeKind )

  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 _ENGINETYPEINFO_H_
 25#define _ENGINETYPEINFO_H_
 26
 27#ifndef _ENGINEEXPORTS_H_
 28   #include "console/engineExports.h"
 29#endif
 30
 31
 32class EngineTypeInfo;
 33
 34
 35/// Kinding for engine types.  Engine types are segregated into kinds which
 36/// are to types what types are to values, i.e. a value is an instance of a type
 37/// and a type is an instance of a kind.
 38enum EngineTypeKind
 39{
 40   EngineTypeKindPrimitive,      ///< Any kind of atomic data.  Passed by value.
 41   EngineTypeKindEnum,           ///< Enumeration.  Passed by value.
 42   EngineTypeKindBitfield,       ///< Bitfield.  Passed by value.
 43   EngineTypeKindFunction,       ///< Function pointer.
 44   EngineTypeKindStruct,         ///< Structured value.  Passed by reference.
 45   EngineTypeKindClass           ///< Pointer to opaque EngineObject.
 46};
 47
 48DECLARE_ENUM_R( EngineTypeKind );
 49
 50/// Flags for an EngineTypeInfo.
 51enum EngineTypeFlags
 52{
 53   EngineTypeAbstract      = BIT( 0 ),    ///< Type is abstract.
 54   EngineTypeInstantiable  = BIT( 1 ),    ///< Type can be instantiated through API.
 55   EngineTypeDisposable    = BIT( 2 ),    ///< Instances can be disposed by the engine.
 56   EngineTypeSingleton     = BIT( 3 ),    ///< Class type with only a single instance.
 57   EngineTypeVariadic      = BIT( 4 ),    ///< Variadic function type.
 58};
 59
 60
 61
 62/// Table of values for an enumeration or bitfield type.
 63class EngineEnumTable
 64{
 65   public:
 66   
 67      /// A value in an enumeration.
 68      ///
 69      /// The order of the fields in this structure is important as it is meant to be
 70      /// initialized with { ... } in code.
 71      struct Value
 72      {
 73         /// Integer value.  If the enumeration is a bit field,
 74         /// this is the bit value.
 75         S32 mInt;
 76
 77         /// Name of the value.
 78         const char* mName;
 79         
 80         /// Documentation string.
 81         const char* mDocString;
 82         
 83         /// Return the name of this enum value.
 84         const char* getName() const { return mName; }
 85         
 86         /// Return the documentation string of this enum value.
 87         const char* getDocString() const { return mDocString; }
 88         
 89         /// Return the integer value of this enum value.
 90         S32 getInt() const { return mInt; }
 91                  
 92         operator S32() const
 93         {
 94            return getInt();
 95         }
 96      };
 97      
 98   protected:
 99   
100      /// Number of values in this enumeration.
101      U32 mNumValues;
102      
103      /// Records for all the enum values.
104      const Value* mValues;
105      
106   public:
107   
108      ///
109      EngineEnumTable( U32 numValues, const Value* values )
110         :  mNumValues( numValues ),
111            mValues( values ) {}
112      
113      /// Return the number of Values in this enumeration/bitfield.
114      U32 getNumValues() const { return mNumValues; }
115      
116      /// Get the enum value at the given index.
117      const Value& operator []( U32 index ) const
118      {
119         AssertFatal( index < getNumValues(), "" );
120         return mValues[ index ];
121      }
122};
123
124
125/// Table of fields for a struct type.
126class EngineFieldTable
127{
128   public:
129   
130      /// A field descriptor in a field table.
131      struct Field
132      {
133         /// Name of the field or group.
134         const char* mName;
135
136         /// Documentation string.
137         const char* mDocString;
138
139         /// Indexed size of this field.  Must be >=1.
140         U32 mNumElements;
141
142         /// Type of the field.
143         const EngineTypeInfo* mType;
144         
145         /// Offset of the field in instances.
146         U32 mOffset;
147
148         ///
149         const char* getName() const { return mName; }
150         
151         ///
152         const char* getDocString() const { return mDocString; }
153         
154         ///
155         U32 getNumElements() const { return mNumElements; }
156         
157         ///
158         const EngineTypeInfo* getType() const { return mType; }
159         
160         ///
161         U32 getOffset() const { return mOffset; }
162      };   
163      
164   protected:
165   
166      /// Number of fields in this table.
167      U32 mNumFields;
168      
169      ///
170      const Field* mFields;
171
172   public:
173   
174      /// Construct a field table from a NULL-terminated array of Field
175      /// records.
176      EngineFieldTable( const Field* fields )
177         : mNumFields( 0 ),
178           mFields( fields )
179      {
180         while( fields[ mNumFields ].getName() )
181            mNumFields ++;
182      }
183   
184      ///
185      EngineFieldTable( U32 numFields, const Field* fields )
186         :  mNumFields( numFields ),
187            mFields( fields ) {}
188      
189      ///
190      U32 getNumFields() const { return mNumFields; }
191      
192      ///
193      const Field& operator []( U32 index ) const
194      {
195         AssertFatal( index <= getNumFields(), "EngineFieldTable - index out of range" );
196         return mFields[ index ];
197      }
198};
199
200
201/// Flags for property descriptors.
202enum EnginePropertyFlags
203{
204   EnginePropertyTransient             = BIT( 0 ),       ///< Exclude from serializations.
205   EnginePropertyConstant              = BIT( 1 ),       ///< Property value is constant once object has been constructed.
206   EnginePropertyHideInInspectors      = BIT( 2 ),       ///< Don't make the property visible in property sheets in the editor.
207   EnginePropertyGroupBegin            = BIT( 3 ),       ///< Special property to mark the beginning of a group; does not define a real property on the object.
208   EnginePropertyGroupEnd              = BIT( 4 ),       ///< Special property to mark the end of a group; does not define a real property on the object.
209};
210
211///
212///
213///
214/// - Read-only properties only have a getXXX and no setXXX method.
215/// - Static properties (value shared by all instances) don't take a 'this' parameter.
216/// - 
217class EnginePropertyTable
218{
219   public:
220   
221      struct Property
222      {
223         /// Name of the property.
224         const char* mName;
225         
226         /// Doc string using Javadoc markup.
227         const char* mDocString;
228         
229         /// Indexed size of the property.  If 0, the property array is variable-sized.  If 1, the property
230         /// is not indexed.  If >1, the property is a fixed-size array.
231         U32 mNumElements;
232
233         /// Combination of EnginePropertyFlags.
234         U32 mFlags;
235
236         /// Type-id of the property
237         U32 mType;
238         
239         /// Return the name of the property.
240         const char* getName() const { return mName; }
241         
242         /// Return the number of indexed elements of the property.
243         U32 getNumElements() const { return mNumElements; }
244         
245         /// Return the documentation string for this property.
246         const char* getDocString() const { return mDocString; }
247                           
248         /// Test whether the property has a constant value.
249         bool isConstant() const { return ( mFlags & EnginePropertyConstant ); }
250         
251         /// Test whether the property value is transient, i.e. should not be serialized.
252         bool isTransient() const { return ( mFlags & EnginePropertyTransient ); }
253         
254         /// Test whether this property begins a group of properties.
255         bool isGroupBegin() const { return ( mFlags & EnginePropertyGroupBegin ); }
256         
257         /// Test whether this property ends a group of properties.
258         bool isGroupEnd() const { return ( mFlags & EnginePropertyGroupEnd ); }
259         
260         ///
261         bool hideInInspectors() const { return ( mFlags & EnginePropertyHideInInspectors ); }
262
263         /// Return the type-id of the property.
264         U32 getType() const { return mType; }
265      };
266      
267   protected:
268   
269      /// Number of properties in this table.
270      U32 mNumProperties;
271      
272      /// Array of property definitions.
273      const Property* mProperties;
274      
275   public:
276   
277      ///
278      EnginePropertyTable( U32 numProperties, const Property* properties )
279         :  mNumProperties( numProperties ),
280            mProperties( properties ) {}
281      
282      ///
283      U32 getNumProperties() const { return mNumProperties; }
284      
285      ///
286      const Property& operator []( U32 index ) const
287      {
288         AssertFatal( index <= getNumProperties(), "EnginePropertyTable - index out of range" );
289         return mProperties[ index ];
290      }
291};
292
293
294/// Information about the return and argument types of a function type.
295class EngineArgumentTypeTable
296{
297   protected:
298   
299      /// Return type of the function type.
300      const EngineTypeInfo* mReturnType;
301      
302      /// Number of argument types of the function type.
303      U32 mNumArguments;
304      
305      /// Array of argument types of the function type.
306      const EngineTypeInfo* const* mArgumentTypes;
307      
308   public:
309      
310      ///
311      EngineArgumentTypeTable( const EngineTypeInfo* returnType,
312                               U32 numArguments,
313                               const EngineTypeInfo* const* argumentTypes )
314         :  mReturnType( returnType ),
315            mNumArguments( numArguments ),
316            mArgumentTypes( argumentTypes ) {}
317            
318      /// Return the return type of the function type.
319      const EngineTypeInfo* getReturnType() const { return mReturnType; }
320      
321      /// Return the number of argument types of the function type.
322      U32 getNumArguments() const { return mNumArguments; }
323      
324      /// Get the argument type at the given index.
325      const EngineTypeInfo* operator []( U32 index ) const
326      {
327         AssertFatal( index <= getNumArguments(), "EngineArgumentTypeTable - Index out of range!" );
328         return mArgumentTypes[ index ];
329      }
330};
331
332
333/// Networking related information for an engine API type.
334struct EngineTypeNetInfo
335{   
336   S32 mNetGroupMask;
337   S32 mNetType;
338   S32 mNetEventDir;
339
340   #ifdef TORQUE_NET_STATS
341   struct NetStatInstance
342   {
343   };
344   #endif
345   
346   EngineTypeNetInfo()
347      : mNetGroupMask( 0 ),
348        mNetType( 0 ),
349        mNetEventDir( 0 ) {}
350};
351
352
353/// Information about an engine type.
354///
355/// This class is used to store run-time type information about engine types.
356///
357/// Once created, type info objects must persist for the entire duration the engine
358/// is running.
359///
360/// All types are implicitly export scopes and may thus contain other exports
361/// within them.
362class EngineTypeInfo : public EngineExportScope
363{
364   public:
365   
366      DECLARE_CLASS( EngineTypeInfo, EngineExportScope );
367      
368      // While we still have the old ConsoleObject system around, allow
369      // them to retroactively install property tables.  Will be removed
370      // when the console interop is removed and all classes are migrated
371      // to the new system.
372      template< typename T > friend class ConcreteAbstractClassRep;
373      
374   protected:
375      
376      /// Kind of type.
377      EngineTypeKind mTypeKind;
378
379      /// Size of an instance of this type.
380      U32 mInstanceSize;
381      
382      /// Combination of EngineTypeFlags.
383      BitSet32 mTypeFlags;
384                              
385      /// If this is an enumeration or bitfield type, this is the pointer to the enum table.
386      const EngineEnumTable* mEnumTable;
387      
388      /// If this is a struct type, this is the pointer to the field table.
389      const EngineFieldTable* mFieldTable;
390      
391      /// If this is a class type, this is the pointer to the property table.
392      const EnginePropertyTable* mPropertyTable;
393      
394      /// If this is a function type, this is the pointer to the argument type table.
395      const EngineArgumentTypeTable* mArgumentTypeTable;
396      
397      /// Pointer to type info object for engine type that this type subtypes from.  NULL if none.
398      const EngineTypeInfo* mSuperType;
399      
400      /// Networking related information for this type.
401      mutable EngineTypeNetInfo mNetInfo;
402      
403      /// Next type in the global link chain.
404      const EngineTypeInfo* mNext;
405      
406      /// Total number of defined types.
407      static U32 smNumTypes;
408      
409      /// First type in the global link chain of type info instances.
410      static const EngineTypeInfo* smFirst;
411
412      ///
413      EngineTypeInfo( const char* typeName, EngineExportScope* scope, EngineTypeKind kind, U32 instanceSize, const char* docString );
414
415   public:
416
417      /// @name List Interface
418      /// Interface for accessing/traversing the list of types.
419      /// @{
420
421      /// Return the first type in the global link chain of types.
422      static const EngineTypeInfo* getFirstType() { return smFirst; }
423
424      /// Return the next type in the global link chain of types.
425      const EngineTypeInfo* getNextType() const
426      {
427         return mNext;
428      }
429
430      /// @}
431
432      /// Get the type info instance for the given type.
433      /// @param typeName Name of a registered engine type.
434      /// @return Type info instance for @a typeName or NULL if no such type exists.
435      static const EngineTypeInfo* getTypeInfoByName( const char* typeName );
436            
437      /// Return the name of the type.
438      /// @return The name of the type or an empty string if this is an anonymous type.
439      const char* getTypeName() const { return getExportName(); }
440
441      /// Return the kind this type.
442      EngineTypeKind getTypeKind() const { return mTypeKind; }
443      
444      /// Return the type info object of the engine type that this type subtypes from.
445      const EngineTypeInfo* getSuperType() const { return mSuperType; }
446
447      /// Return the size of a single value in bytes.
448      /// Be aware that the value size refers to the value as it is passed around.  For types using
449      /// reference or pointer value semantics, this is thus the size of a pointer or reference and
450      /// not the size of the actual instance.
451      U32 getValueSize() const;
452      
453      /// Return the
454      U32 getInstanceSize() const { return mInstanceSize; }
455      
456      /// Return true if the type is abstract.
457      /// @note Only class and function types can be abstract.
458      bool isAbstract() const { return mTypeFlags.test( EngineTypeAbstract ); }
459      
460      /// Return true if the type can be instantiated from outside the engine.
461      bool isInstantiable() const { return mTypeFlags.test( EngineTypeInstantiable ); }
462      
463      /// Return true if the objects of this type can be disposed by the engine.
464      bool isDisposable() const { return mTypeFlags.test( EngineTypeDisposable ); }
465      
466      /// Return true if the type can have only a single instance.
467      bool isSingleton() const { return mTypeFlags.test( EngineTypeSingleton ); }
468      
469      /// Return true if the type is a variadic function type.
470      bool isVariadic() const { return mTypeFlags.test( EngineTypeVariadic ); }
471                                    
472      /// Test whether this type is a primitive type.
473      bool isPrimitive() const { return ( getTypeKind() == EngineTypeKindPrimitive ); }
474      
475      /// Test whether this type is an enumeration type.
476      bool isEnum() const { return ( getTypeKind() == EngineTypeKindEnum ); }
477      
478      /// Test whether this type is a bitfield type.
479      bool isBitfield() const { return ( getTypeKind() == EngineTypeKindBitfield ); }
480      
481      /// Test whether this type is a function type.
482      bool isFunction() const { return ( getTypeKind() == EngineTypeKindFunction ); }
483      
484      /// Test whether this type is a struct type.
485      bool isStruct() const { return ( getTypeKind() == EngineTypeKindStruct ); }
486
487      /// Test whether this is a class type.
488      bool isClass() const { return ( getTypeKind() == EngineTypeKindClass ); }
489            
490      /// Return the EngineEnumTable for this type (only for enumeration and bitfield types).
491      const EngineEnumTable* getEnumTable() const { return mEnumTable; }
492      
493      /// Return the EngineFieldTable for this type (only for struct types).
494      const EngineFieldTable* getFieldTable() const { return mFieldTable; }
495      
496      /// Return the EnginePropertyTable for this type (only for class types).
497      const EnginePropertyTable* getPropertyTable() const { return mPropertyTable; }
498      
499      ///
500      const EngineArgumentTypeTable* getArgumentTypeTable() const { return mArgumentTypeTable; }
501      
502      /// Return true if this type is a subtype of the given type.
503      bool isSubtypeOf( const EngineTypeInfo* type ) const;
504      
505      ///
506      EngineTypeNetInfo& getNetInfo() const { return mNetInfo; }
507      
508      /// @name Instancing
509      /// @{
510      
511      /// Create a new instance at the given address.
512      /// @pre Must not be called for abstract types.
513      virtual bool constructInstance( void* ptr ) const;
514      
515      /// Destroy the instance at the given address.
516      /// @pre Must not be called for abstract types.
517      virtual void destructInstance( void* ptr ) const;
518      
519      /// @}
520};
521
522//--------------------------------------------------------------------------
523//    Type Info Helper Classes.
524//--------------------------------------------------------------------------
525
526
527/// Template for type infos of primitive, enum, and bitfield types.
528template< typename T >
529class EngineSimpleTypeInfo : public EngineTypeInfo
530{
531   public:
532   
533      typedef EngineTypeInfo Parent;
534      
535      EngineSimpleTypeInfo( const char* name, EngineExportScope* scope, EngineTypeKind kind, const char* docString, EngineEnumTable* enumTable = NULL )
536         : Parent( name, scope, kind, sizeof( T ), docString )
537      {
538         mEnumTable = enumTable;
539         mTypeFlags.set( EngineTypeInstantiable );
540      }
541      
542      virtual bool constructInstance( void* ptr ) const
543      {
544         T* p = reinterpret_cast< T* >( ptr );
545         *p = T();
546         return true;
547      }
548      
549      virtual void destructInstance( void* ptr ) const
550      {
551         // Nothing to do.
552      }
553};
554
555
556/// Template for struct type infos.
557template< typename T >
558class EngineStructTypeInfo : public EngineTypeInfo
559{
560   public:
561   
562      typedef EngineTypeInfo Parent;
563      
564      EngineStructTypeInfo( const char* name, EngineExportScope* scope, const char* docString, EngineFieldTable* fieldTable )
565         : Parent( name, scope, EngineTypeKindStruct, sizeof( T ), docString )
566      {
567         mFieldTable = fieldTable;
568         mTypeFlags.set( EngineTypeInstantiable );
569      }
570      
571      virtual bool constructInstance( void* ptr ) const
572      {
573         T* p = reinterpret_cast< T* >( ptr );
574         *p = T();
575         return true;
576      }
577   
578      virtual void destructInstance( void* ptr ) const
579      {
580         T* p = reinterpret_cast< T* >( ptr );
581         destructInPlace( p );
582      }
583};
584
585
586/// Template for class type infos.
587template< typename T, typename Base >
588class EngineClassTypeInfo : public EngineTypeInfo
589{
590   public:
591   
592      typedef EngineTypeInfo Parent;
593      
594      /// The documentation string set by CLASSDOC (if any).
595      static const char* smDocString;
596
597      EngineClassTypeInfo( const char* name, EngineExportScope* scope, const char* docString = NULL )
598         : Parent( name, scope, EngineTypeKindClass, sizeof( T ), docString ? docString : smDocString )
599      {
600         mPropertyTable = &T::_smPropertyTable;
601         mSuperType = TYPE< typename T::SuperType >();
602         if( IsTrueType< typename Base::IsAbstractType >() )
603            mTypeFlags.set( EngineTypeAbstract );
604         else if( IsTrueType< typename T::__IsInstantiableType >() )
605            mTypeFlags.set( EngineTypeInstantiable );
606            
607         if( IsTrueType< typename T::__IsDisposableType >() )
608            mTypeFlags.set( EngineTypeDisposable );
609         if( IsTrueType< typename T::__IsSingletonType >() )
610            mTypeFlags.set( EngineTypeSingleton );
611      }
612      
613      virtual bool constructInstance( void* ptr ) const
614      {
615         return Base::_construct( ptr );
616      }
617   
618      virtual void destructInstance( void* ptr ) const
619      {
620         return Base::_destruct( ptr );
621      }
622};
623
624template< typename T, typename Base > const char* EngineClassTypeInfo< T, Base >::smDocString;
625
626
627/// Template for function type infos.
628template< typename T >
629class EngineFunctionTypeInfo : public EngineTypeInfo
630{
631   public:
632   
633      typedef EngineTypeInfo Parent;
634      
635      static _EngineArgumentTypeTable< T> ARGTYPES;
636      
637      EngineFunctionTypeInfo()
638         : Parent( "", &_SCOPE<>()(), EngineTypeKindFunction, sizeof( T* ), "" )
639      {
640         mArgumentTypeTable = &ARGTYPES;
641         
642         if( ARGTYPES.VARIADIC )
643            mTypeFlags.set( EngineTypeVariadic );
644         
645         // Function types cannot be instantiated.
646         mTypeFlags.set( EngineTypeAbstract );
647      }      
648};
649
650template< typename T > _EngineArgumentTypeTable< T> EngineFunctionTypeInfo< T >::ARGTYPES;
651template< typename T > const EngineFunctionTypeInfo< T> _EngineFunctionTypeTraits< T >::smTYPEINFO;
652
653
654//--------------------------------------------------------------------------
655//    Function Argument Type Infos.
656//--------------------------------------------------------------------------
657
658
659#ifdef TORQUE_COMILER_GCC
660#define ARGS_SIZE_SAFE(wanted) (wanted)
661#else
662#define ARGS_SIZE_SAFE(wanted) (((wanted) < 1) ? 1 : (wanted))
663#endif
664
665template< typename R, typename ...ArgTs >
666struct _EngineArgumentTypeTable< R( ArgTs ... ) > : public EngineArgumentTypeTable
667{
668   static const U32 NUM_ARGUMENTS = sizeof...(ArgTs);
669   static const bool VARIADIC = false;
670   static const EngineTypeInfo* const RETURN;
671   static const EngineTypeInfo* const ARGS[ ARGS_SIZE_SAFE(sizeof...(ArgTs)) ];
672
673   _EngineArgumentTypeTable()
674      : EngineArgumentTypeTable( TYPE< typename EngineTypeTraits< R >::Type >(), NUM_ARGUMENTS, ARGS ) {}
675};
676template< typename R, typename ...ArgTs >
677const EngineTypeInfo* const _EngineArgumentTypeTable< R( ArgTs ... ) >::RETURN = TYPE< typename EngineTypeTraits< R >::Type >();
678template< typename R, typename ...ArgTs >
679const EngineTypeInfo* const _EngineArgumentTypeTable< R( ArgTs ... ) >::ARGS[ ARGS_SIZE_SAFE(sizeof...(ArgTs)) ] =
680{
681   TYPE< typename EngineTypeTraits< ArgTs >::Type >() ...
682};
683template< typename R, typename ... ArgTs >
684struct _EngineArgumentTypeTable< R( ArgTs ..., ... ) > : public _EngineArgumentTypeTable< R( ArgTs ... ) >
685{
686   static const bool VARIADIC = true;
687   _EngineArgumentTypeTable() {}
688};
689
690#endif // !_ENGINETYPEINFO_H_
691