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         /// Return the name of the property.
237         const char* getName() const { return mName; }
238         
239         /// Return the number of indexed elements of the property.
240         U32 getNumElements() const { return mNumElements; }
241         
242         /// Return the documentation string for this property.
243         const char* getDocString() const { return mDocString; }
244                           
245         /// Test whether the property has a constant value.
246         bool isConstant() const { return ( mFlags & EnginePropertyConstant ); }
247         
248         /// Test whether the property value is transient, i.e. should not be serialized.
249         bool isTransient() const { return ( mFlags & EnginePropertyTransient ); }
250         
251         /// Test whether this property begins a group of properties.
252         bool isGroupBegin() const { return ( mFlags & EnginePropertyGroupBegin ); }
253         
254         /// Test whether this property ends a group of properties.
255         bool isGroupEnd() const { return ( mFlags & EnginePropertyGroupEnd ); }
256         
257         ///
258         bool hideInInspectors() const { return ( mFlags & EnginePropertyHideInInspectors ); }
259      };
260      
261   protected:
262   
263      /// Number of properties in this table.
264      U32 mNumProperties;
265      
266      /// Array of property definitions.
267      const Property* mProperties;
268      
269   public:
270   
271      ///
272      EnginePropertyTable( U32 numProperties, const Property* properties )
273         :  mNumProperties( numProperties ),
274            mProperties( properties ) {}
275      
276      ///
277      U32 getNumProperties() const { return mNumProperties; }
278      
279      ///
280      const Property& operator []( U32 index ) const
281      {
282         AssertFatal( index <= getNumProperties(), "EnginePropertyTable - index out of range" );
283         return mProperties[ index ];
284      }
285};
286
287
288/// Information about the return and argument types of a function type.
289class EngineArgumentTypeTable
290{
291   protected:
292   
293      /// Return type of the function type.
294      const EngineTypeInfo* mReturnType;
295      
296      /// Number of argument types of the function type.
297      U32 mNumArguments;
298      
299      /// Array of argument types of the function type.
300      const EngineTypeInfo* const* mArgumentTypes;
301      
302   public:
303      
304      ///
305      EngineArgumentTypeTable( const EngineTypeInfo* returnType,
306                               U32 numArguments,
307                               const EngineTypeInfo* const* argumentTypes )
308         :  mReturnType( returnType ),
309            mNumArguments( numArguments ),
310            mArgumentTypes( argumentTypes ) {}
311            
312      /// Return the return type of the function type.
313      const EngineTypeInfo* getReturnType() const { return mReturnType; }
314      
315      /// Return the number of argument types of the function type.
316      U32 getNumArguments() const { return mNumArguments; }
317      
318      /// Get the argument type at the given index.
319      const EngineTypeInfo* operator []( U32 index ) const
320      {
321         AssertFatal( index <= getNumArguments(), "EngineArgumentTypeTable - Index out of range!" );
322         return mArgumentTypes[ index ];
323      }
324};
325
326
327/// Networking related information for an engine API type.
328struct EngineTypeNetInfo
329{   
330   S32 mNetGroupMask;
331   S32 mNetType;
332   S32 mNetEventDir;
333
334   #ifdef TORQUE_NET_STATS
335   struct NetStatInstance
336   {
337   };
338   #endif
339   
340   EngineTypeNetInfo()
341      : mNetGroupMask( 0 ),
342        mNetType( 0 ),
343        mNetEventDir( 0 ) {}
344};
345
346
347/// Information about an engine type.
348///
349/// This class is used to store run-time type information about engine types.
350///
351/// Once created, type info objects must persist for the entire duration the engine
352/// is running.
353///
354/// All types are implicitly export scopes and may thus contain other exports
355/// within them.
356class EngineTypeInfo : public EngineExportScope
357{
358   public:
359   
360      DECLARE_CLASS( EngineTypeInfo, EngineExportScope );
361      
362      // While we still have the old ConsoleObject system around, allow
363      // them to retroactively install property tables.  Will be removed
364      // when the console interop is removed and all classes are migrated
365      // to the new system.
366      template< typename T > friend class ConcreteAbstractClassRep;
367      
368   protected:
369      
370      /// Kind of type.
371      EngineTypeKind mTypeKind;
372
373      /// Size of an instance of this type.
374      U32 mInstanceSize;
375      
376      /// Combination of EngineTypeFlags.
377      BitSet32 mTypeFlags;
378                              
379      /// If this is an enumeration or bitfield type, this is the pointer to the enum table.
380      const EngineEnumTable* mEnumTable;
381      
382      /// If this is a struct type, this is the pointer to the field table.
383      const EngineFieldTable* mFieldTable;
384      
385      /// If this is a class type, this is the pointer to the property table.
386      const EnginePropertyTable* mPropertyTable;
387      
388      /// If this is a function type, this is the pointer to the argument type table.
389      const EngineArgumentTypeTable* mArgumentTypeTable;
390      
391      /// Pointer to type info object for engine type that this type subtypes from.  NULL if none.
392      const EngineTypeInfo* mSuperType;
393      
394      /// Networking related information for this type.
395      mutable EngineTypeNetInfo mNetInfo;
396      
397      /// Next type in the global link chain.
398      const EngineTypeInfo* mNext;
399      
400      /// Total number of defined types.
401      static U32 smNumTypes;
402      
403      /// First type in the global link chain of type info instances.
404      static const EngineTypeInfo* smFirst;
405
406      ///
407      EngineTypeInfo( const char* typeName, EngineExportScope* scope, EngineTypeKind kind, U32 instanceSize, const char* docString );
408
409   public:
410
411      /// @name List Interface
412      /// Interface for accessing/traversing the list of types.
413      /// @{
414
415      /// Return the first type in the global link chain of types.
416      static const EngineTypeInfo* getFirstType() { return smFirst; }
417
418      /// Return the next type in the global link chain of types.
419      const EngineTypeInfo* getNextType() const
420      {
421         return mNext;
422      }
423
424      /// @}
425
426      /// Get the type info instance for the given type.
427      /// @param typeName Name of a registered engine type.
428      /// @return Type info instance for @a typeName or NULL if no such type exists.
429      static const EngineTypeInfo* getTypeInfoByName( const char* typeName );
430            
431      /// Return the name of the type.
432      /// @return The name of the type or an empty string if this is an anonymous type.
433      const char* getTypeName() const { return getExportName(); }
434
435      /// Return the kind this type.
436      EngineTypeKind getTypeKind() const { return mTypeKind; }
437      
438      /// Return the type info object of the engine type that this type subtypes from.
439      const EngineTypeInfo* getSuperType() const { return mSuperType; }
440
441      /// Return the size of a single value in bytes.
442      /// Be aware that the value size refers to the value as it is passed around.  For types using
443      /// reference or pointer value semantics, this is thus the size of a pointer or reference and
444      /// not the size of the actual instance.
445      U32 getValueSize() const;
446      
447      /// Return the
448      U32 getInstanceSize() const { return mInstanceSize; }
449      
450      /// Return true if the type is abstract.
451      /// @note Only class and function types can be abstract.
452      bool isAbstract() const { return mTypeFlags.test( EngineTypeAbstract ); }
453      
454      /// Return true if the type can be instantiated from outside the engine.
455      bool isInstantiable() const { return mTypeFlags.test( EngineTypeInstantiable ); }
456      
457      /// Return true if the objects of this type can be disposed by the engine.
458      bool isDisposable() const { return mTypeFlags.test( EngineTypeDisposable ); }
459      
460      /// Return true if the type can have only a single instance.
461      bool isSingleton() const { return mTypeFlags.test( EngineTypeSingleton ); }
462      
463      /// Return true if the type is a variadic function type.
464      bool isVariadic() const { return mTypeFlags.test( EngineTypeVariadic ); }
465                                    
466      /// Test whether this type is a primitive type.
467      bool isPrimitive() const { return ( getTypeKind() == EngineTypeKindPrimitive ); }
468      
469      /// Test whether this type is an enumeration type.
470      bool isEnum() const { return ( getTypeKind() == EngineTypeKindEnum ); }
471      
472      /// Test whether this type is a bitfield type.
473      bool isBitfield() const { return ( getTypeKind() == EngineTypeKindBitfield ); }
474      
475      /// Test whether this type is a function type.
476      bool isFunction() const { return ( getTypeKind() == EngineTypeKindFunction ); }
477      
478      /// Test whether this type is a struct type.
479      bool isStruct() const { return ( getTypeKind() == EngineTypeKindStruct ); }
480
481      /// Test whether this is a class type.
482      bool isClass() const { return ( getTypeKind() == EngineTypeKindClass ); }
483            
484      /// Return the EngineEnumTable for this type (only for enumeration and bitfield types).
485      const EngineEnumTable* getEnumTable() const { return mEnumTable; }
486      
487      /// Return the EngineFieldTable for this type (only for struct types).
488      const EngineFieldTable* getFieldTable() const { return mFieldTable; }
489      
490      /// Return the EnginePropertyTable for this type (only for class types).
491      const EnginePropertyTable* getPropertyTable() const { return mPropertyTable; }
492      
493      ///
494      const EngineArgumentTypeTable* getArgumentTypeTable() const { return mArgumentTypeTable; }
495      
496      /// Return true if this type is a subtype of the given type.
497      bool isSubtypeOf( const EngineTypeInfo* type ) const;
498      
499      ///
500      EngineTypeNetInfo& getNetInfo() const { return mNetInfo; }
501      
502      /// @name Instancing
503      /// @{
504      
505      /// Create a new instance at the given address.
506      /// @pre Must not be called for abstract types.
507      virtual bool constructInstance( void* ptr ) const;
508      
509      /// Destroy the instance at the given address.
510      /// @pre Must not be called for abstract types.
511      virtual void destructInstance( void* ptr ) const;
512      
513      /// @}
514};
515
516//--------------------------------------------------------------------------
517//    Type Info Helper Classes.
518//--------------------------------------------------------------------------
519
520
521/// Template for type infos of primitive, enum, and bitfield types.
522template< typename T >
523class EngineSimpleTypeInfo : public EngineTypeInfo
524{
525   public:
526   
527      typedef EngineTypeInfo Parent;
528      
529      EngineSimpleTypeInfo( const char* name, EngineExportScope* scope, EngineTypeKind kind, const char* docString, EngineEnumTable* enumTable = NULL )
530         : Parent( name, scope, kind, sizeof( T ), docString )
531      {
532         mEnumTable = enumTable;
533         mTypeFlags.set( EngineTypeInstantiable );
534      }
535      
536      virtual bool constructInstance( void* ptr ) const
537      {
538         T* p = reinterpret_cast< T* >( ptr );
539         *p = T();
540         return true;
541      }
542      
543      virtual void destructInstance( void* ptr ) const
544      {
545         // Nothing to do.
546      }
547};
548
549
550/// Template for struct type infos.
551template< typename T >
552class EngineStructTypeInfo : public EngineTypeInfo
553{
554   public:
555   
556      typedef EngineTypeInfo Parent;
557      
558      EngineStructTypeInfo( const char* name, EngineExportScope* scope, const char* docString, EngineFieldTable* fieldTable )
559         : Parent( name, scope, EngineTypeKindStruct, sizeof( T ), docString )
560      {
561         mFieldTable = fieldTable;
562         mTypeFlags.set( EngineTypeInstantiable );
563      }
564      
565      virtual bool constructInstance( void* ptr ) const
566      {
567         T* p = reinterpret_cast< T* >( ptr );
568         *p = T();
569         return true;
570      }
571   
572      virtual void destructInstance( void* ptr ) const
573      {
574         T* p = reinterpret_cast< T* >( ptr );
575         destructInPlace( p );
576      }
577};
578
579
580/// Template for class type infos.
581template< typename T, typename Base >
582class EngineClassTypeInfo : public EngineTypeInfo
583{
584   public:
585   
586      typedef EngineTypeInfo Parent;
587      
588      /// The documentation string set by CLASSDOC (if any).
589      static const char* smDocString;
590
591      EngineClassTypeInfo( const char* name, EngineExportScope* scope, const char* docString = NULL )
592         : Parent( name, scope, EngineTypeKindClass, sizeof( T ), docString ? docString : smDocString )
593      {
594         mPropertyTable = &T::_smPropertyTable;
595         mSuperType = TYPE< typename T::SuperType >();
596         if( IsTrueType< typename Base::IsAbstractType >() )
597            mTypeFlags.set( EngineTypeAbstract );
598         else if( IsTrueType< typename T::__IsInstantiableType >() )
599            mTypeFlags.set( EngineTypeInstantiable );
600            
601         if( IsTrueType< typename T::__IsDisposableType >() )
602            mTypeFlags.set( EngineTypeDisposable );
603         if( IsTrueType< typename T::__IsSingletonType >() )
604            mTypeFlags.set( EngineTypeSingleton );
605      }
606      
607      virtual bool constructInstance( void* ptr ) const
608      {
609         return Base::_construct( ptr );
610      }
611   
612      virtual void destructInstance( void* ptr ) const
613      {
614         return Base::_destruct( ptr );
615      }
616};
617
618template< typename T, typename Base > const char* EngineClassTypeInfo< T, Base >::smDocString;
619
620
621/// Template for function type infos.
622template< typename T >
623class EngineFunctionTypeInfo : public EngineTypeInfo
624{
625   public:
626   
627      typedef EngineTypeInfo Parent;
628      
629      static _EngineArgumentTypeTable< T> ARGTYPES;
630      
631      EngineFunctionTypeInfo()
632         : Parent( "", &_SCOPE<>()(), EngineTypeKindFunction, sizeof( T* ), "" )
633      {
634         mArgumentTypeTable = &ARGTYPES;
635         
636         if( ARGTYPES.VARIADIC )
637            mTypeFlags.set( EngineTypeVariadic );
638         
639         // Function types cannot be instantiated.
640         mTypeFlags.set( EngineTypeAbstract );
641      }      
642};
643
644template< typename T > _EngineArgumentTypeTable< T> EngineFunctionTypeInfo< T >::ARGTYPES;
645template< typename T > const EngineFunctionTypeInfo< T> _EngineFunctionTypeTraits< T >::smTYPEINFO;
646
647
648//--------------------------------------------------------------------------
649//    Function Argument Type Infos.
650//--------------------------------------------------------------------------
651
652
653#ifdef TORQUE_COMILER_GCC
654#define ARGS_SIZE_SAFE(wanted) (wanted)
655#else
656#define ARGS_SIZE_SAFE(wanted) (((wanted) < 1) ? 1 : (wanted))
657#endif
658
659template< typename R, typename ...ArgTs >
660struct _EngineArgumentTypeTable< R( ArgTs ... ) > : public EngineArgumentTypeTable
661{
662   static const U32 NUM_ARGUMENTS = sizeof...(ArgTs);
663   static const bool VARIADIC = false;
664   static const EngineTypeInfo* const RETURN;
665   static const EngineTypeInfo* const ARGS[ ARGS_SIZE_SAFE(sizeof...(ArgTs)) ];
666
667   _EngineArgumentTypeTable()
668      : EngineArgumentTypeTable( TYPE< typename EngineTypeTraits< R >::Type >(), NUM_ARGUMENTS, ARGS ) {}
669};
670template< typename R, typename ...ArgTs >
671const EngineTypeInfo* const _EngineArgumentTypeTable< R( ArgTs ... ) >::RETURN = TYPE< typename EngineTypeTraits< R >::Type >();
672template< typename R, typename ...ArgTs >
673const EngineTypeInfo* const _EngineArgumentTypeTable< R( ArgTs ... ) >::ARGS[ ARGS_SIZE_SAFE(sizeof...(ArgTs)) ] =
674{
675   TYPE< typename EngineTypeTraits< ArgTs >::Type >() ...
676};
677template< typename R, typename ... ArgTs >
678struct _EngineArgumentTypeTable< R( ArgTs ..., ... ) > : public _EngineArgumentTypeTable< R( ArgTs ... ) >
679{
680   static const bool VARIADIC = true;
681   _EngineArgumentTypeTable() {}
682};
683
684#endif // !_ENGINETYPEINFO_H_
685