Torque Game Engine Documentation
CVS Revision Label 1.3.x

AbstractClassRep Class Reference

#include <consoleObject.h>

Inheritance diagram for AbstractClassRep:

Detailed Description

Core functionality for class manipulation.

Introduction (or, Why AbstractClassRep?)

Many of Torque's subsystems, especially network, console, and sim, require the ability to programatically instantiate classes. For instance, when objects are ghosted, the networking layer needs to be able to create an instance of the object on the client. When the console scripting language runtime encounters the "new" keyword, it has to be able to fill that request.

Since standard C++ doesn't provide a function to create a new instance of an arbitrary class at runtime, one must be created. This is what AbstractClassRep and ConcreteClassRep are all about. They allow the registration and instantiation of arbitrary classes at runtime.

In addition, ACR keeps track of the fields (registered via addField() and co.) of a class, allowing programmatic access of class fields.

See also:: ConsoleObject

Note:: In general, you will only access the functionality implemented in this class via ConsoleObject::create(). Most of the time, you will only ever need to use this part part of the engine indirectly - ie, you will use the networking system or the console, or ConsoleObject, and they will indirectly use this code. The following discussion is really only relevant for advanced engine users.

NetClasses and Class IDs

Torque supports a notion of group, type, and direction for objects passed over the network. Class IDs are assigned sequentially per-group, per-type, so that, for instance, the IDs assigned to Datablocks are seperate from the IDs assigned to NetObjects or NetEvents. This can translate into significant bandwidth savings (especially since the size of the fields for transmitting these bits are determined at run-time based on the number of IDs given out.

AbstractClassRep Internals

Much like ConsoleConstructor, ACR does some preparatory work at runtime before execution is passed to main(). In actual fact, this preparatory work is done by the ConcreteClassRep template. Let's examine this more closely.

If we examine ConsoleObject, we see that two macros must be used in the definition of a properly integrated objects. From the ConsoleObject example:

         // This is from inside the class definition...
         DECLARE_CONOBJECT(TorqueObject);
   
    // And this is from outside the class definition...
    IMPLEMENT_CONOBJECT(TorqueObject);

What do these things actually do?

Not all that much, in fact. They expand to code something like this:

         // This is from inside the class definition...
         static ConcreteClassRep<TorqueObject> dynClassRep;
         static AbstractClassRep* getParentStaticClassRep();
         static AbstractClassRep* getStaticClassRep();
         virtual AbstractClassRep* getClassRep() const;

    // And this is from outside the class definition...
    AbstractClassRep* TorqueObject::getClassRep() const { return &TorqueObject::dynClassRep; }
    AbstractClassRep* TorqueObject::getStaticClassRep() { return &dynClassRep; }
    AbstractClassRep* TorqueObject::getParentStaticClassRep() { return Parent::getStaticClassRep(); }
    ConcreteClassRep<TorqueObject> TorqueObject::dynClassRep("TorqueObject", 0, -1, 0);

As you can see, getClassRep(), getStaticClassRep(), and getParentStaticClassRep() are just accessors to allow access to various ConcreteClassRep instances. This is where the Parent typedef comes into play as well - it lets getParentStaticClassRep() get the right class rep.

In addition, dynClassRep is declared as a member of TorqueObject, and defined later on. Much like ConsoleConstructor, ConcreteClassReps add themselves to a global linked list in their constructor.

Then, when AbstractClassRep::initialize() is called, from Con::init(), we iterate through the list and perform the following tasks:

Sets up a Namespace for each class.
Call the init() method on each ConcreteClassRep. This method:
- Links namespaces between parent and child classes, using Con::classLinkNamespaces.
- Calls initPersistFields() and consoleInit().
As a result of calling initPersistFields, the field list for the class is populated.
Assigns network IDs for classes based on their NetGroup membership. Determines bit allocations for network ID fields.

Fields

typedef Vector< Field > FieldList

enum ACRFieldTypes {
  StartGroupFieldType = 0xFFFFFFFD,
  EndGroupFieldType = 0xFFFFFFFE,
  DepricatedFieldType = 0xFFFFFFFF
}

const Field * findField (StringTableEntry fieldName) const

FieldList mFieldList

bool mDynamicGroupExpand

'Tructors

AbstractClassRep ()

virtual ~AbstractClassRep ()

Representation Interface

S32 getClassId (U32 netClassGroup) const

const char * getClassName () const

Namespace * getNameSpace ()

AbstractClassRep * getNextClass ()

virtual ConsoleObject * create () const =0

S32 mClassGroupMask

Mask indicating in which NetGroups this object belongs.

S32 mClassType

Stores the NetClass of this class.

S32 mNetEventDir

Stores the NetDirection of this class.

S32 mClassId [NetClassGroupsCount]

Stores the IDs assigned to this class for each group.

static U32 getClassCRC (U32 netClassGroup)

static AbstractClassRep * getClassList ()

virtual void init () const =0

const char * mClassName

AbstractClassRep * nextClass

Namespace * mNamespace

Abstract Class Database

static void registerClassRep (AbstractClassRep *)

static void initialize ()

static U32 NetClassCount [NetClassGroupsCount][NetClassTypesCount]

static U32 NetClassBitSize [NetClassGroupsCount][NetClassTypesCount]

static ConsoleObject * create (const char *in_pClassName)

static ConsoleObject * create (const U32 groupId, const U32 typeId, const U32 in_classId)

static AbstractClassRep ** classTable [NetClassGroupsCount][NetClassTypesCount]

static AbstractClassRep * classLinkList

static U32 classCRC [NetClassGroupsCount]

static bool initialized

Friends

class ConsoleObject

Data Structures

struct Field

Member Typedef Documentation

typedef Vector<Field> AbstractClassRep::FieldList

Member Enumeration Documentation

enum AbstractClassRep::ACRFieldTypes

Enumeration values:

StartGroupFieldType

EndGroupFieldType

DepricatedFieldType

Constructor & Destructor Documentation

AbstractClassRep::AbstractClassRep ( ) [inline]

virtual AbstractClassRep::~AbstractClassRep ( ) [inline, virtual]

Member Function Documentation

S32 AbstractClassRep::getClassId ( U32 netClassGroup ) const [inline]

U32 AbstractClassRep::getClassCRC ( U32 netClassGroup ) [inline, static]

const char * AbstractClassRep::getClassName ( ) const [inline]

AbstractClassRep * AbstractClassRep::getClassList ( ) [inline, static]

Namespace * AbstractClassRep::getNameSpace ( ) [inline]

AbstractClassRep * AbstractClassRep::getNextClass ( ) [inline]

virtual ConsoleObject* AbstractClassRep::create ( ) const [pure virtual]

Implemented in ConcreteClassRep< T >.

virtual void AbstractClassRep::init ( ) const [protected, pure virtual]

Implemented in ConcreteClassRep< T >.

const Field* AbstractClassRep::findField ( StringTableEntry fieldName ) const

static ConsoleObject* AbstractClassRep::create ( const char * in_pClassName ) [static, protected]

static ConsoleObject* AbstractClassRep::create ( const U32 groupId,

const U32 typeId,

const U32 in_classId

) [static, protected]

static void AbstractClassRep::registerClassRep ( AbstractClassRep * ) [static]

static void AbstractClassRep::initialize ( ) [static]

Friends And Related Function Documentation

friend class ConsoleObject [friend]

Field Documentation

S32 AbstractClassRep::mClassGroupMask

Mask indicating in which NetGroups this object belongs.

S32 AbstractClassRep::mClassType

Stores the NetClass of this class.

S32 AbstractClassRep::mNetEventDir

Stores the NetDirection of this class.

S32 AbstractClassRep::mClassId[NetClassGroupsCount]

Stores the IDs assigned to this class for each group.

const char* AbstractClassRep::mClassName [protected]

AbstractClassRep* AbstractClassRep::nextClass [protected]

Namespace* AbstractClassRep::mNamespace [protected]

FieldList AbstractClassRep::mFieldList

bool AbstractClassRep::mDynamicGroupExpand

AbstractClassRep** AbstractClassRep::classTable[NetClassGroupsCount][NetClassTypesCount] [static, protected]

AbstractClassRep* AbstractClassRep::classLinkList [static, protected]

U32 AbstractClassRep::classCRC[NetClassGroupsCount] [static, protected]

bool AbstractClassRep::initialized [static, protected]

U32 AbstractClassRep::NetClassCount[NetClassGroupsCount][NetClassTypesCount] [static]

U32 AbstractClassRep::NetClassBitSize[NetClassGroupsCount][NetClassTypesCount] [static]