Main Page Modules Namespaces C++ Classes Compound List File List Index
TNL: 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)
| Returns the current scope 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

## Data Structures

struct | GhostPacketNotify
| Notify structure attached to each packet with information about the ghost updates in the packet. More...
struct | GhostRef
| GhostRef tracks an update sent in one packet for the ghost of one NetObject. More...

## 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

Enumerator:

  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]`

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]`

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]`

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 | ) |

Returns the current scope 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.