Message Groups

The MessageGroup is the mechanism for grouping parameterized messages to be sent all at once when a block of data is received. The messages may be completely specified, or may have some of their parameters (only floating point numbers please) replaced by the * symbol, followed by an integer. The integer is an index into a data array. When the MessageGroup receives a data array, indices in the stored messages are replaced by data from the array (at the specified index point), and the messages are sent. If an index exceeds the length of the data array, the message containing that index is not sent. Indices are 'C' style (start at 0). Messages are only sent when a data array is received by the MessageGroup. The data in the array may be used more than once, or not at all.

When a message sent by MessageGroup causes a new handle to be generated (e.g., Create, BeginSound) that would have been passed back to the client had the client sent the message, that handle is stored temporarily with the MessageGroup. Subsequent messages in that MessageGroup can refer to this handle with the *? symbol. This handle is remembered only while processing the current data array; it's replaced each time a new handle is generated. So to create a handler and send it message Foo with arguments from a data array, one could use the following messages:

	AddMessage hMG BeginSound hGenerator;
	AddMessage hMG Foo *? *1 *3;
Every time an array is sent to this MessageGroup, a new handler is created for hGenerator, and the message Foo is sent to the new handler with the second and fourth array elements as arguments.

To use MessageGroups, load and create an actor of type MessageGroup. MessageGroups are also used in the AUDupdate mechanism.

Special note for AUDupdate: other actors can also use the *1 *3 kind of notation to access the values of the data array passed to a message group via AUDupdate, even if those actors are not themselves MessageGroup actors. In this case, *3 for example refers to the fourth argument of the last AUDupdate sent to any message group at all. Use this with care: you might not realize that another AUDupdate happened in the meantime which clobbered the datum you needed. Or there might have been fewer than four elements in the AUDupdate array to begin with.

New abbreviation: anywhere you can write *2 *3 *4 *5 *6, you can replace that with *2 to *6. Also, *$ in this context (*0 to *$, *1 to *$, etc.) means the last parameter passed in from AUDupdate. You can use this to work with messages with an unknown or variable number of parameters.

MessageGroup messages

In addition to the messages understood by all actors, the MessageGroup understands the following messages:
AddMessage hActor message
Add message to the list of paramterized messages to be sent when a data array is received.
SendData hActor [ x1, x2, x3... ]
[ x1, x2, x3... ] is an array of floating point data to be used to construct complete messages from the parameterized versions the MessageGroup has stored. The MessageGroup will construct and send as many of its messages as possible. Messages indexing data beyond the length of the data array [ x1, x2, x3... ] are not sent.
ScheduleData hActor [t1, t2, t3...] [x1, y1...] [x2, y2...] [...] ...
Receive data arrays as above with time offsets [t1, t2, t3...]. Receive [x1, y1...] at t1, [x2, y2...] at t2, etc. Time offsets are relative to the time of receipt of the ScheduleData message.