Communication Ring

Starting with this version of LScript (v2.7), scripts are full-fledged members of the Communication Ring system. The Communication Ring is a mechanism that has been added to LightWave 8, and it allows plug-ins to effeciently intercommunicate events, and even exchange data along with those events. LScripts can also partake in that mechanism. (Please refer to the LightWave plug-in SDK documentation for a more robust explanation of the Communciation Ring system.)

To support this system, several new commands have been added:

comringattach(topic,callback)

Opens a channel to the specified Communication Ring. Each ComRing is identified by a unique topic, which is a character string. The first subscriber to a ring creates it, and the last to detach causes its destruction.

In addition, you must define a callback UDF to be invoked whenever events are generated on that particular ComRing by other subscribers. This callback will accept two values, the event code (integer) and a data pointer (internal type) for the generated event. The internal data pointer is processed using the comringencode() and comringdecode() functions (explained later).

comringdetach(topic)

When a script is completed with its subscription to a ComRing (such as when it terminates), it should detach from each ComRing to which it is attached.

comringmsg(topic,code[,data])

Generates an event on the specified ComRing. All other subscribers on the ring will receive notification of the event, and process the event at that time. It is important to point out that events are not cached -- events are processed when they arrive. So, processing of a ring event should be completed as quickly as possible.

The event code is simply an integer value that has some meaning as an identifier for the event. This value is completely user-defined.

The data value is optional. However, if you do wish to transmit data to another plug-in, the value you provide here can only have come from the comringencode() function. Any other kind of data will generate a run-time error.

comringencode(datalist,...)
This function will take a variable list of data and encode it into an in-memory form that can be accessed by other plug-ins. The arrangement of the data will allow it to be accessed by a structure type-cast in a C plug-in. If you are sending the data to any other active LScript on the ring, that LScript should use the comringdecode() function to extract the data.

The datalist is an array of character strings that identify the target data types. Data types can be "s" for string, "i" for integer, "f" for float, and "d" for double. In the case of string values, you must specify a size for the character buffer. This size value is specified by appending a colon and an integer size value to the data type metacharacter. For example, a string value to be stored in a character buffer of 200 bytes would be specified as "s:200".

In addition, you can specify a count for the data types to be processed. A count value is specified using a pound sign. So, for example, if the data you need to process consists of an array of three strings, each contained in a 200-byte buffer, an integer value, and five floating-point values, your datalist would look like the following:

"s:200#3","i","f#5"

The above datalist sequence would encode to an internal memory value that could be accessed with the following C structure:

struct
{
    char buf[3][200];
    int ival;
    float fval[5];
};

When you specify a count for a particular data data type, you must provide an array or initblock in that position of the provided data list to be processed. A run-time error will occur if an array or initblock is not found where a count value is specified.

The data value returned by comringencode() can only be used in the call to comringmsg() as the data value.

comringdecode()

This function is used to extract data from a data value included with a ComRing event. The datalist provided should define the type and order of the data found in the data value.

Values decoded are returned as a stream of elements, so you can store them all into a single array variable, or you can use associative assignment to extract elements into individual variables.

The "ComRing" SDK sample project shows this mechanism in action. A Master LScript controls the appearance of a C-code Custom Object plug-in in real-time, and illustrates two-way data exchange.