Main Page Modules Namespaces C++ Classes Compound List File List Index
TNL: TNL::NetClassRep Class Reference

# TNL::NetClassRep Class Reference

`#include <tnlNetBase.h>`

Inheritance diagram for TNL::NetClassRep:

## Detailed Description

NetClassRep class instances represent each declared NetClass and are used to construct object instances.

Core functionality for TNL-registered class manipulation.

## Introduction (or, Why AbstractClassRep?)

TNL requires the ability to programatically instantiate classes, by name or by ID numbers. This is used for handling connections, ghosting, working with events, and in many other areas. Torque uses this functionality for its scripting language, too.

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 NetClassRep and NetClassRepInstance are all about. They allow the registration and instantiation of arbitrary classes at runtime.

See also:
  TNL::Object

Note:
  In general, you will only access the functionality implemented in this class via TNL::Object::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. The following discussion is really only relevant for advanced TNL users.

## NetClasses and Class IDs

TNL 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 TNL::NetObjects are seperate from the IDs assigned to 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.

## NetClassRep Internals

NCR does some preparatory work at runtime before execution is passed to main(), through static initialization. In actual fact, this preparatory work is done by the NetClassRepInstasnce template. Let's examine this more closely.

If we examine TNL::Object, we see that two macros must be used in the definition of a properly integrated objects. Let's look at an example:

          // This is from inside the class definition...
          DECLARE_CONOBJECT(TestObject);

     // And this is from outside the class definition...
     IMPLEMENT_CONOBJECT(TestObject);

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 NetClassRepInstance<TestObject> dynClassRep;
          static NetClassRep* getParentStaticClassRep();
          static NetClassRep* getStaticClassRep();
          virtual NetClassRep* getClassRep() const;

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

As you can see, getClassRep(), getStaticClassRep(), and getParentStaticClassRep() are just accessors to allow access to various NetClassRepInstance 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 TestObject, and defined later on. Much like Torque's ConsoleConstructor, NetClassRepInstances add themselves to a global linked list in their constructor.

Then, when NetClassRep::initialize() is called, we iterate through the list and perform the following tasks:

- Assigns network IDs for classes based on their NetGroup membership. Determines bit allocations for network ID fields.

## Object Creation

These helper functions let you create an instance of a class by name or ID.

Note:
  Call Object::create() instead of these.

static Object * | create (const char *className)
static Object * | create (const U32 groupId, const U32 typeId, const U32 classId)

## Public Member Functions

U32 | getClassId (NetClassGroup classGroup) const
| Returns the class ID, within its type, for the particular group.
NetClassType | getClassType () const
| Returns the NetClassType of this class.
S32 | getClassVersion () const
| Returns the version of this class.
const char * | getClassName () const
| Returns the string class name.
void | addInitialUpdate (U32 bitCount)
| Records bits used in the initial update of objects of this class.
void | addPartialUpdate (U32 bitCount)
| Records bits used in a partial update of an object of this class.
virtual Object * | create () const=0
| Creates an instance of the class this represents.

## Static Public Member Functions

static U32 | getNetClassCount (U32 classGroup, U32 classType)
| Returns the number of classes registered under classGroup and classType.
static U32 | getNetClassBitSize (U32 classGroup, U32 classType)
| Returns the number of bits necessary to transmit class ids of the specified classGroup and classType.
static bool | isVersionBorderCount (U32 classGroup, U32 classType, U32 count)
| Returns true if the given class count is on a version boundary.
static NetClassRep * | getClass (U32 classGroup, U32 classType, U32 index)
static U32 | getClassGroupCRC (NetClassGroup classGroup)
| Returns a CRC of class data, for checking on connection.
static void | initialize ()
| Initializes the class table and associated data - called from TNL::init().
static void | logBitUsage ()
| Logs the bit usage information of all the NetClassReps.

## Protected Member Functions

| NetClassRep ()
virtual | ~NetClassRep ()

## Protected Attributes

U32 | mClassGroupMask
| Mask for which class groups this class belongs to.
S32 | mClassVersion
| The version number for this class.
NetClassType | mClassType
| Which class type is this?
U32 | mClassId [NetClassGroupCount]
| The id for this class in each class group.
char * | mClassName
| The unmangled name of the class.
U32 | mInitialUpdateBitsUsed
| Number of bits used on initial updates of objects of this class.
U32 | mPartialUpdateBitsUsed
| Number of bits used on partial updates of objects of this class.
U32 | mInitialUpdateCount
| Number of objects of this class constructed over a connection.
U32 | mPartialUpdateCount
| Number of objects of this class updated over a connection.
NetClassRep * | mNextClass
| Next declared NetClassRep.

## Static Protected Attributes

static NetClassRep * | mClassLinkList
| Head of the linked class list.
static Vector< NetClassRep * > | mClassTable [NetClassGroupCount][NetClassTypeCount]
| Table of NetClassReps for construction by class ID.
static U32 | mClassCRC [NetClassGroupCount]
| Internally computed class group CRC.
static bool | mInitialized
| Set once the class tables are built, from initialize.
static U32 | mNetClassBitSize [NetClassGroupCount][NetClassTypeCount]
| mNetClassBitSize is the number of bits needed to transmit the class ID for a group and type.

## Friends

class | Object

## Constructor & Destructor Documentation

TNL::NetClassRep::NetClassRep | ( |  | ) | `[protected]`

virtual TNL::NetClassRep::~NetClassRep | ( |  | ) | `[inline, protected, virtual]`

## Member Function Documentation

static Object* TNL::NetClassRep::create | ( | const char * | className | ) | `[static, protected]`

static Object* TNL::NetClassRep::create | ( | const U32 | groupId,
|  | const U32 | typeId,
|  | const U32 | classId |
| ) |  |  | `[static, protected]`

U32 TNL::NetClassRep::getClassId | ( | NetClassGroup | classGroup | ) | const`[inline]`

Returns the class ID, within its type, for the particular group.

NetClassType TNL::NetClassRep::getClassType | ( |  | ) | const`[inline]`

Returns the NetClassType of this class.

S32 TNL::NetClassRep::getClassVersion | ( |  | ) | const`[inline]`

Returns the version of this class.

const char * TNL::NetClassRep::getClassName | ( |  | ) | const`[inline]`

Returns the string class name.

void TNL::NetClassRep::addInitialUpdate | ( | U32 | bitCount | ) | `[inline]`

Records bits used in the initial update of objects of this class.

void TNL::NetClassRep::addPartialUpdate | ( | U32 | bitCount | ) | `[inline]`

Records bits used in a partial update of an object of this class.

virtual Object* TNL::NetClassRep::create | ( |  | ) | const`[pure virtual]`

Creates an instance of the class this represents.

Implemented in TNL::NetClassRepInstance< T >.

static U32 TNL::NetClassRep::getNetClassCount | ( | U32 | classGroup,
|  | U32 | classType |
| ) |  |  | `[inline, static]`

Returns the number of classes registered under classGroup and classType.

static U32 TNL::NetClassRep::getNetClassBitSize | ( | U32 | classGroup,
|  | U32 | classType |
| ) |  |  | `[inline, static]`

Returns the number of bits necessary to transmit class ids of the specified classGroup and classType.

static bool TNL::NetClassRep::isVersionBorderCount | ( | U32 | classGroup,
|  | U32 | classType,
|  | U32 | count |
| ) |  |  | `[inline, static]`

Returns true if the given class count is on a version boundary.

static NetClassRep* TNL::NetClassRep::getClass | ( | U32 | classGroup,
|  | U32 | classType,
|  | U32 | index |
| ) |  |  | `[inline, static]`

U32 TNL::NetClassRep::getClassGroupCRC | ( | NetClassGroup | classGroup | ) | `[inline, static]`

Returns a CRC of class data, for checking on connection.

static void TNL::NetClassRep::initialize | ( |  | ) | `[static]`

Initializes the class table and associated data - called from TNL::init().

static void TNL::NetClassRep::logBitUsage | ( |  | ) | `[static]`

Logs the bit usage information of all the NetClassReps.

## Friends And Related Function Documentation

friend class Object`[friend]`

## Field Documentation

U32 TNL::NetClassRep::mClassGroupMask`[protected]`

Mask for which class groups this class belongs to.

S32 TNL::NetClassRep::mClassVersion`[protected]`

The version number for this class.

NetClassType TNL::NetClassRep::mClassType`[protected]`

Which class type is this?

U32 TNL::NetClassRep::mClassId[NetClassGroupCount]`[protected]`

The id for this class in each class group.

char* TNL::NetClassRep::mClassName`[protected]`

The unmangled name of the class.

U32 TNL::NetClassRep::mInitialUpdateBitsUsed`[protected]`

Number of bits used on initial updates of objects of this class.

U32 TNL::NetClassRep::mPartialUpdateBitsUsed`[protected]`

Number of bits used on partial updates of objects of this class.

U32 TNL::NetClassRep::mInitialUpdateCount`[protected]`

Number of objects of this class constructed over a connection.

U32 TNL::NetClassRep::mPartialUpdateCount`[protected]`

Number of objects of this class updated over a connection.

NetClassRep* TNL::NetClassRep::mNextClass`[protected]`

Next declared NetClassRep.

These are stored in a linked list built by the macro constructs.

NetClassRep* TNL::NetClassRep::mClassLinkList`[static, protected]`

Head of the linked class list.

Vector<NetClassRep *> TNL::NetClassRep::mClassTable[NetClassGroupCount][NetClassTypeCount]`[static, protected]`

Table of NetClassReps for construction by class ID.

U32 TNL::NetClassRep::mClassCRC[NetClassGroupCount]`[static, protected]`

Internally computed class group CRC.

bool TNL::NetClassRep::mInitialized`[static, protected]`

Set once the class tables are built, from initialize.

U32 TNL::NetClassRep::mNetClassBitSize[NetClassGroupCount][NetClassTypeCount]`[static, protected]`

mNetClassBitSize is the number of bits needed to transmit the class ID for a group and type.