template <class avatarType> class CAVERN_baseAvatarManager_c

CAVERN base avatar manager class

Public Methods

CAVERN_baseAvatarManager_c ()
Constructor.
int init (char* serverIP, int hailingPort, int trackerPort, int trackerDataSize, int helloDataSize, int auxDataSize)
Initialize Avatar Manager
~CAVERN_baseAvatarManager_c ()
Delete the avatar manager and also tell other clients that you have left
void garbageCollect ()
Performed by process() to purge avatars that disconnected abnormally.
void process ()
Do avatar management
void applyToAllAvatars (int (*userFunc)(long avatarID, CAVERN_baseAvatar_c *, void *inParam1, void *inParam2, void *inParam3, void *& retParam), void *inParam1, void *inParam2, void *inParam3, void *& inOutParam)
Apply a user function to all the avatars
void setNewAvatarCallback (void (*cb)(CAVERN_baseAvatar_c *, void* ), void* param)
When a new avatar arrives call your callback
void setAvatarHelloChangeCallback (void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
When avatar hello data has changed call your callback
void setAvatarAuxCallback (void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
When avatar auxiliary data has arrived your callback
void setAvatarExitCallback (void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
If an avatar has left call your callback
void setAvatarTrackerCallback (void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
If a new packet of tracker data arrives call your callback
void setHelloData (char *hello)
Set the hello data that you wish to send out. Use sendHello() to dispatch the data.
void setAuxData (char *aux)
Set the aux data that you wish to send out. Use sendHello() to dispatch the data.
void setTrackerData (char *tracker)
Set the tracker data that you wish to send out. Use sendTracker() to dispatch the data.
void sendHello ()
Sending the hello data.
void sendAux ()
Sending the aux data.
void setTrackerUpdateDelay (double delay)
Set how often tracker data is sent
void sendTracker ()
Sending the tracker data.
void sendBye ()
Send bye message to all clients.

Protected Methods

void initPerformanceMonitoring ()
Starts up performance monitoring
void doPerformanceMonitoring ()
Updates performance statistics based on the time
void endPerformanceMonitoring ()
Cleans up performance monitoring by closing the logfile.

Documentation

CAVERN base avatar manager class. This is a template class. You create a special manager for your special brand of avatar. Basically the manager handles the entry and exit of avatars. It leaves the specialized management of graphics to the callbacks in the API.

This manages avatars that connect and disconnect from your client. Begin by creating a single manager and then initializing it with init(). Then set the hello data you wish to send and call sendHello(). Everytime you wish to send a tracker packet, package the tracker data you want to send, call setTrackerData() and then call sendTracker(). When you want to tell everyone you are leaving call: sendBye() or simply delete your avatar manager object. Similary to send auxiliary data call setAuxData() followed by sendAux();

Note: nothing is implied in the format of the tracker, hello, or aux data. This is done intentionally so that you can bundle whatever you want in it. Then you can build higher level avatar classes on top of this or extend this avatar class by adding things that are specific to say OpenGL or Performer.

For example, tracker data could be an array of floats containing an avatar's body position, orientation etc. Hello data could consist of information about an avatar's color, size, filenames for 3D models, database path/name information, and keys to find 3D models, etc. Aux data could be intermittent chat text messages sent between avatars.

Hello and aux data are sent via reliable channels. The tracker data are sent via unreliable channels.

Network performance can be monitored automatically by the avatar manager. This is done using the internal performance monitoring capabilities of CAVERNsoft. The methods for activating and stopped performance monitoring are called automatically by the class, and specific details are available through the use of environment variables. To disable performance monitoring, simply unset the environment variables.

AVATAR_PERFMON_DAEMON IP address to send statistics

AVATAR_PERFMON_UDP seconds to wait between logging tracking data

AVATAR_PERFMON_TCP seconds to wait between loggin hailing data

AVATAR_PERFMON_LOGFILE name of a logfile to store statistics

int init(char* serverIP, int hailingPort, int trackerPort, int trackerDataSize, int helloDataSize, int auxDataSize)
Initialize Avatar Manager. Do this before doing any other avatar manager calls.
Parameters:
serverIP - IP address of avatar server.
hailingPort - port to connect to to send reliable avatar data.
trackerPort - port to connect to to send tracker data.
trackerDataSize - the expected size of the data that will carry all the positional, and orientational information about the avatar all packed into 1 array of characters.
helloDataSize - the expected size of the data that will carry all the other avatar information like the color of an avatar, or the filename for each part of the avatar (head, hand etc), or the database path and name of where to retrieve the different parts of the avatar.
auxDataSize - the expected size of the data that will carry any auxiliary data over the reliable hailing channel during the course of the operation of the avatar.

void process()
Do avatar management. Do this in a loop so that manager constantly tracks new incoming data and connections.

void applyToAllAvatars(int (*userFunc)(long avatarID, CAVERN_baseAvatar_c *, void *inParam1, void *inParam2, void *inParam3, void *& retParam), void *inParam1, void *inParam2, void *inParam3, void *& inOutParam)
Apply a user function to all the avatars. The user function will be applied to each avatar in turn if the function returns a 1. If you wish to abort this process have the function return 0.

The user function should be of the form: int userFunc(long avatarID, CAVERN_baseAvatar_c *eachAvatar, void* inParam1, void* inParam2, void* inParam3, void *& retParam)

eachAvatar is a pointer to each of the avatar class object.

The inParams are designed for you to pass your application data into the function.

The retParam can be used to pass in as well as return a value to your application. E.g. within the userFunc you could set

retParam = (void*) somePointer; return 0;

somePointer will then be returned back to the applyToAllAvatars() member function in the parameter inOutParam.

void setNewAvatarCallback(void (*cb)(CAVERN_baseAvatar_c *, void* ), void* param)
When a new avatar arrives call your callback.
Parameters:
param - pass in user data.

void setAvatarHelloChangeCallback(void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
When avatar hello data has changed call your callback
Parameters:
param - pass in user data.

void setAvatarAuxCallback(void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
When avatar auxiliary data has arrived your callback
Parameters:
param - pass in user data.

void setAvatarExitCallback(void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
If an avatar has left call your callback
Parameters:
param - pass in user data.

void setAvatarTrackerCallback(void (*cb)(CAVERN_baseAvatar_c *, void*), void* param)
If a new packet of tracker data arrives call your callback
Parameters:
param - pass in user data.

void setTrackerUpdateDelay(double delay)
Set how often tracker data is sent. Delay is in seconds with microsecond accuracy. By setting this, no matter how often you call sendTracker it will only actually send data packets as often as the delay allows it. This is useful to prevent tracker data from flooding the network. By default this delay is set at 1/15s

void initPerformanceMonitoring()
Starts up performance monitoring. The avatar manager uses performance monitoring to measure the network performance for data transmission. Control is done through the use of several environment variables:

AVATAR_PERFMON_DAEMON AVATAR_PERFMON_UDP AVATAR_PERFMON_TCP AVATAR_PERFMON_LOGFILE

This class has no child classes.

alphabetic index hierarchy of classes

this page has been generated automatically by doc++

(c)opyright by Malte Zöckler, Roland Wunderling
contact: doc++@zib.de