TNL::GhostConnection class Reference

TNL::GhostConnection Class Reference

#include <tnlGhostConnection.h>

Inheritance diagram for TNL::GhostConnection:

Detailed Description

GhostConnection is a subclass of EventConnection that manages the transmission (ghosting) and updating of NetObjects over a connection.

The GhostConnection is responsible for doing scoping calculations (on the server side) and transmitting most-recent ghost information to the client.

Ghosting is the most complex, and most powerful, part of TNL's capabilities. It allows the information sent to clients to be very precisely matched to what they need, so that no excess bandwidth is wasted. Each GhostConnection has a scope object that is responsible for determining what other NetObject instances are relevant to that connection's client. Each time GhostConnection sends a packet, NetObject::performScopeQuery() is called on the scope object, which calls GhostConnection::objectInScope() for each relevant object.

Each object that is in scope, and in need of update (based on its maskbits) is given a priority ranking by calling that object's getUpdatePriority() method. The packet is then filled with updates, ordered by priority. This way the most important updates get through first, with less important updates being sent as space is available.

There is a cap on the maximum number of ghosts that can be active through a GhostConnection at once. The enum GhostIdBitSize (defaults to 10) determines how many bits will be used to transmit the ID for each ghost, so the maximum number is 2^GhostIdBitSize or 1024. This can be easily raised; see the GhostConstants enum.

Each object ghosted is assigned a ghost ID; the client is only aware of the ghost ID. This acts to enhance simulation security, as it becomes difficult to map objects from one connection to another, or to reliably identify objects from ID alone. IDs are also reassigned based on need, making it hard to track objects that have fallen out of scope (as any object which the player shouldn't see would).

resolveGhost() is used on the client side, and resolveObjectFromGhostIndex() on the server side, to convert ghost IDs to object references.

See also:: NetObject for more information on network object functionality.

Public Types

enum GhostConstants {
  GhostIdBitSize = 10,
  GhostLookupTableSizeShift = 10,
  MaxGhostCount = (1 << GhostIdBitSize),
  GhostCountBitSize = GhostIdBitSize + 1,
  GhostLookupTableSize = (1 << GhostLookupTableSizeShift),
  GhostLookupTableMask = (GhostLookupTableSize - 1)
}

Public Member Functions

GhostConnection ()

~GhostConnection ()

void setGhostFrom (bool ghostFrom)

Sets whether ghosts transmit from this side of the connection.

void setGhostTo (bool ghostTo)

Sets whether ghosts are allowed from the other side of the connection.

bool doesGhostFrom ()

Does this GhostConnection ghost NetObjects to the remote host?

bool doesGhostTo ()

Does this GhostConnection receive ghosts from the remote host?

U32 getGhostingSequence ()

Returns the sequence number of this ghosting session.

void setScopeObject (NetObject *object)

Sets the object that is queried at each packet to determine what NetObjects should be ghosted on this connection.

NetObject * getScopeObject ()

void objectInScope (NetObject *object)

Indicate that the specified object is currently in scope.

void objectLocalScopeAlways (NetObject *object)

The specified object should be always in scope for this connection.

void objectLocalClearAlways (NetObject *object)

The specified object should not be always in scope for this connection.

NetObject * resolveGhost (S32 id)

Given an object's ghost id, returns the ghost of the object (on the client side).

NetObject * resolveGhostParent (S32 id)

Given an object's ghost id, returns the source object (on the server side).

void ghostPushNonZero (GhostInfo *gi)

Moves the specified GhostInfo into the range of the ghost array for non-zero updateMasks.

void ghostPushToZero (GhostInfo *gi)

Moves the specified GhostInfo into the range of the ghost array for zero updateMasks.

void ghostPushZeroToFree (GhostInfo *gi)

Moves the specified GhostInfo into the range of the ghost array for free (unused) GhostInfos.

void ghostPushFreeToZero (GhostInfo *info)

Moves the specified GhostInfo from the free area into the range of the ghost array for zero updateMasks.

S32 getGhostIndex (NetObject *object)

Returns the client-side ghostIndex of the specified server object, or -1 if the object is not available on the client.

bool isGhostAvailable (NetObject *object)

Returns true if the object is available on the client.

void resetGhosting ()

Stops ghosting objects from this GhostConnection to the remote host, which causes all ghosts to be destroyed on the client.

void activateGhosting ()

Begins ghosting objects from this GhostConnection to the remote host, starting with the GhostAlways objects.

bool isGhosting ()

Returns true if this connection is currently ghosting objects to the remote host.

void detachObject (GhostInfo *info)

Notifies the GhostConnection that the specified GhostInfo should no longer be scoped to the client.

TNL_DECLARE_RPC (rpcStartGhosting,(U32 sequence))

RPC from server to client before the GhostAlwaysObjects are transmitted.

TNL_DECLARE_RPC (rpcReadyForNormalGhosts,(U32 sequence))

RPC from client to server sent when the client receives the rpcGhostAlwaysActivated.

TNL_DECLARE_RPC (rpcEndGhosting,())

RPC from server to client sent to notify that ghosting should stop.

Protected Member Functions

PacketNotify * allocNotify ()

Override of EventConnection's allocNotify, to use the GhostPacketNotify structure.

void packetDropped (PacketNotify *notify)

Override to properly update the GhostInfo's for all ghosts that had upates in the dropped packet.

void packetReceived (PacketNotify *notify)

Override to update flags associated with the ghosts updated in this packet.

void prepareWritePacket ()

Performs the scoping query in order to determine if there is data to send from this GhostConnection.

void writePacket (BitStream *bstream, PacketNotify *notify)

Override to write ghost updates into each packet.

void readPacket (BitStream *bstream)

Override to read updated ghost information from the packet stream.

bool isDataToTransmit ()

Override to check if there is data pending on this GhostConnection.

void clearGhostInfo ()

void deleteLocalGhosts ()

bool validateGhostArray ()

void freeGhostInfo (GhostInfo *)

virtual void onStartGhosting ()

Notifies subclasses that the remote host is about to start ghosting objects.

virtual void onEndGhosting ()

Notifies subclasses that the server has stopped ghosting objects on this connection.

Protected Attributes

GhostInfo ** mGhostArray

Array of GhostInfo structures used to track all the objects ghosted by this side of the connection.

S32 mGhostZeroUpdateIndex

Index in mGhostArray of first ghost with 0 update mask (ie, with no updates).

S32 mGhostFreeIndex

index in mGhostArray of first free ghost.

bool mGhosting

Am I currently ghosting objects over?

bool mScoping

Am I currently allowing objects to be scoped?

U32 mGhostingSequence

Sequence number describing this ghosting session.

NetObject ** mLocalGhosts

Local ghost array for remote objects, or NULL if mGhostTo is false.

GhostInfo * mGhostRefs

Allocated array of ghostInfos, or NULL if mGhostFrom is false.

GhostInfo ** mGhostLookupTable

Table indexed by object id->GhostInfo, or NULL if mGhostFrom is false.

SafePtr< NetObject > mScopeObject

The local NetObject that performs scoping queries to determine what objects to ghost to the client.

Private Types

typedef EventConnection Parent

Friends

class ConnectionMessageEvent

Member Typedef Documentation

typedef EventConnection TNL::GhostConnection::Parent [private]

Reimplemented from TNL::EventConnection.
Reimplemented in TNLTest::TestConnection, Zap::ControlObjectConnection, and Zap::GameConnection.

Member Enumeration Documentation

enum TNL::GhostConnection::GhostConstants

Enumeration values:

GhostIdBitSize Size, in bits, of the integer used to transmit ghost IDs.

GhostLookupTableSizeShift The size of the hash table used to lookup source NetObjects by remote ghost ID is 1 << GhostLookupTableSizeShift.

MaxGhostCount Maximum number of ghosts that can be active at any one time.

GhostCountBitSize Size of the field needed to transmit the total number of ghosts.

GhostLookupTableSize Size of the hash table used to lookup source NetObjects by remote ghost ID.

GhostLookupTableMask Hashing mask for table lookups.

Constructor & Destructor Documentation

TNL::GhostConnection::GhostConnection ( )

TNL::GhostConnection::~GhostConnection ( )

Member Function Documentation

PacketNotify* TNL::GhostConnection::allocNotify ( ) [inline, protected, virtual]

Override of EventConnection's allocNotify, to use the GhostPacketNotify structure.

Reimplemented from TNL::EventConnection.
Reimplemented in Zap::ControlObjectConnection.

void TNL::GhostConnection::packetDropped ( PacketNotify * notify ) [protected, virtual]

Override to properly update the GhostInfo's for all ghosts that had upates in the dropped packet.

Reimplemented from TNL::EventConnection.

void TNL::GhostConnection::packetReceived ( PacketNotify * notify ) [protected, virtual]

Override to update flags associated with the ghosts updated in this packet.

Reimplemented from TNL::EventConnection.
Reimplemented in Zap::ControlObjectConnection.

void TNL::GhostConnection::prepareWritePacket ( ) [protected, virtual]

Performs the scoping query in order to determine if there is data to send from this GhostConnection.

Reimplemented from TNL::NetConnection.

void TNL::GhostConnection::writePacket ( BitStream * bstream,

PacketNotify * notify

) [protected, virtual]

Override to write ghost updates into each packet.

Reimplemented from TNL::EventConnection.
Reimplemented in Zap::ControlObjectConnection.

void TNL::GhostConnection::readPacket ( BitStream * bstream ) [protected, virtual]

Override to read updated ghost information from the packet stream.

Reimplemented from TNL::EventConnection.
Reimplemented in Zap::ControlObjectConnection.

bool TNL::GhostConnection::isDataToTransmit ( ) [protected, virtual]

Override to check if there is data pending on this GhostConnection.

Reimplemented from TNL::EventConnection.
Reimplemented in TNLTest::TestConnection, and Zap::ControlObjectConnection.

void TNL::GhostConnection::clearGhostInfo ( ) [protected]

void TNL::GhostConnection::deleteLocalGhosts ( ) [protected]

bool TNL::GhostConnection::validateGhostArray ( ) [protected]

void TNL::GhostConnection::freeGhostInfo ( GhostInfo * ) [protected]

virtual void TNL::GhostConnection::onStartGhosting ( ) [protected, virtual]

Notifies subclasses that the remote host is about to start ghosting objects.

virtual void TNL::GhostConnection::onEndGhosting ( ) [protected, virtual]

Notifies subclasses that the server has stopped ghosting objects on this connection.

void TNL::GhostConnection::setGhostFrom ( bool ghostFrom )

Sets whether ghosts transmit from this side of the connection.

void TNL::GhostConnection::setGhostTo ( bool ghostTo )

Sets whether ghosts are allowed from the other side of the connection.

bool TNL::GhostConnection::doesGhostFrom ( ) [inline]

Does this GhostConnection ghost NetObjects to the remote host?

bool TNL::GhostConnection::doesGhostTo ( ) [inline]

Does this GhostConnection receive ghosts from the remote host?

U32 TNL::GhostConnection::getGhostingSequence ( ) [inline]

Returns the sequence number of this ghosting session.

void TNL::GhostConnection::setScopeObject ( NetObject * object )

Sets the object that is queried at each packet to determine what NetObjects should be ghosted on this connection.

NetObject* TNL::GhostConnection::getScopeObject ( ) [inline]

void TNL::GhostConnection::objectInScope ( NetObject * object )

Indicate that the specified object is currently in scope.
Method called by the scope object to indicate that the specified object is in scope.

void TNL::GhostConnection::objectLocalScopeAlways ( NetObject * object )

The specified object should be always in scope for this connection.

void TNL::GhostConnection::objectLocalClearAlways ( NetObject * object )

The specified object should not be always in scope for this connection.

NetObject* TNL::GhostConnection::resolveGhost ( S32 id )

Given an object's ghost id, returns the ghost of the object (on the client side).

NetObject* TNL::GhostConnection::resolveGhostParent ( S32 id )

Given an object's ghost id, returns the source object (on the server side).

void TNL::GhostConnection::ghostPushNonZero ( GhostInfo * gi ) [inline]

Moves the specified GhostInfo into the range of the ghost array for non-zero updateMasks.

void TNL::GhostConnection::ghostPushToZero ( GhostInfo * gi ) [inline]

Moves the specified GhostInfo into the range of the ghost array for zero updateMasks.

void TNL::GhostConnection::ghostPushZeroToFree ( GhostInfo * gi ) [inline]

Moves the specified GhostInfo into the range of the ghost array for free (unused) GhostInfos.

void TNL::GhostConnection::ghostPushFreeToZero ( GhostInfo * info ) [inline]

Moves the specified GhostInfo from the free area into the range of the ghost array for zero updateMasks.

S32 TNL::GhostConnection::getGhostIndex ( NetObject * object )

Returns the client-side ghostIndex of the specified server object, or -1 if the object is not available on the client.

bool TNL::GhostConnection::isGhostAvailable ( NetObject * object ) [inline]

Returns true if the object is available on the client.

void TNL::GhostConnection::resetGhosting ( )

Stops ghosting objects from this GhostConnection to the remote host, which causes all ghosts to be destroyed on the client.

void TNL::GhostConnection::activateGhosting ( )

Begins ghosting objects from this GhostConnection to the remote host, starting with the GhostAlways objects.

bool TNL::GhostConnection::isGhosting ( ) [inline]

Returns true if this connection is currently ghosting objects to the remote host.

void TNL::GhostConnection::detachObject ( GhostInfo * info )

Notifies the GhostConnection that the specified GhostInfo should no longer be scoped to the client.

TNL::GhostConnection::TNL_DECLARE_RPC ( rpcStartGhosting ,

(U32 sequence)

)

RPC from server to client before the GhostAlwaysObjects are transmitted.

TNL::GhostConnection::TNL_DECLARE_RPC ( rpcReadyForNormalGhosts ,

(U32 sequence)

)

RPC from client to server sent when the client receives the rpcGhostAlwaysActivated.

TNL::GhostConnection::TNL_DECLARE_RPC ( rpcEndGhosting ,

()

)

RPC from server to client sent to notify that ghosting should stop.

Friends And Related Function Documentation

friend class ConnectionMessageEvent [friend]

Field Documentation

GhostInfo** TNL::GhostConnection::mGhostArray [protected]

Array of GhostInfo structures used to track all the objects ghosted by this side of the connection.
For efficiency, ghosts are stored in three segments - the first segment contains GhostInfos that have pending updates, the second ghostrefs that need no updating, and last, free GhostInfos that may be reused.

S32 TNL::GhostConnection::mGhostZeroUpdateIndex [protected]

Index in mGhostArray of first ghost with 0 update mask (ie, with no updates).

S32 TNL::GhostConnection::mGhostFreeIndex [protected]

index in mGhostArray of first free ghost.

bool TNL::GhostConnection::mGhosting [protected]

Am I currently ghosting objects over?

bool TNL::GhostConnection::mScoping [protected]

Am I currently allowing objects to be scoped?

U32 TNL::GhostConnection::mGhostingSequence [protected]

Sequence number describing this ghosting session.

NetObject** TNL::GhostConnection::mLocalGhosts [protected]

Local ghost array for remote objects, or NULL if mGhostTo is false.

GhostInfo* TNL::GhostConnection::mGhostRefs [protected]

Allocated array of ghostInfos, or NULL if mGhostFrom is false.

GhostInfo** TNL::GhostConnection::mGhostLookupTable [protected]

Table indexed by object id->GhostInfo, or NULL if mGhostFrom is false.

SafePtr<NetObject> TNL::GhostConnection::mScopeObject [protected]

The local NetObject that performs scoping queries to determine what objects to ghost to the client.