1 introduction

This is a machine generated document created from a database of information. It exists in both paper and HTML form. Other documents describe the API exported to other programming language environments.

The API also includes the following ordinary data structures:

1.1 Reading This Document

The document is organized around the various classes enumerated above. At the top level, there is a section for each class. Within these sections, there are subsections corresponding to each instance variable and method.

Applications do not communicate directly with each other, but rather only with the world model. This allows applications to be written without thinking about how communication is achieved. An application does exactly the same things when it is interacting with an application running in shared memory on the same machine as it does when interacting with an application connected via the Internet.

The world model is not a scene graph, but rather an object-oriented database that does not consider one kind of content to be any more important than another. In particular, we believe that audio information and autonomous behavior are at least as important as visual information and should not be limited by constraints inherited from visual rendering.

The world model specifies what objects exist in the virtual world, where they are, what they look like, and what sounds they are making. The world model does not contain historical information, but rather just a snapshot of what the virtual world is like at the current moment. As the virtual world changes second by second, the world model changes.

The emphasis in the design of the world model is on the term database, not object oriented. The objects have methods associated with them, but by far the dominant operations consist of reading and writing data stored in the instance variables of world model objects.

A central feature of the system is that it is designed to be scalable to a large number of users (e.g., thousands) interacting in real time. Two key features support this: providing only approximate equality of local world model copies and dividing the world model into chunks each of which is communicated only to the small group of users that are actually interested in it, rather than to all the users of the world model.

Distributed databases typically require that all local copies of the database must agree exactly on the information in the database. However, this requires object locking and handshaking that is incompatible with real-time interaction if there are more than a very small number of users. In contrast, the focus here is on real-time interaction at all costs, providing only approximate equality between world model copies.

The primary way in which world model copies are only approximately equal is that different users observe things as occurring at slightly different times. We call this a relativity model of communication and is actually not unlike the real world. When you hear sounds from distant sources, you do not hear the sound that is being made now, but rather the sound that was made seconds ago. As a result, people in different locations do not hear the same things at the same time. How great the differences are depends on how far apart the sound sources and people are.

Similarly, when an application process finds out about a world model change, it is not finding out about a change that is happening now, but rather about one that happened some time ago. How long ago depends on the network distance between the two processes. In general, this distance is not more than a couple hundred milliseconds and does not lead to world model differences that are unduly large.

In the lower right of the figure is the session manager. It handles the connection of new users to an on-going session and their eventual disconnection. Its workload is proportional only to the number of users that enter or leave the session in a given minute, not the total number of connected users.

One or more servers are included in a Spline session to act as: user servers, region servers, beacon servers, and contact points. For flexibility, there is only one kind of server process, which can act in any of the above roles, or several at once.

The purpose of a user server is to support users with slow network connections (e.g., modems) that do not allow them to operate as first class peers. When acting in this role, a server intercepts all communication to and from the user. The message traffic to the user is compressed to take maximum advantage of the bandwidth available. As part of this, audio streams are combined and localized before sending them to the user. Servers are replicated as needed so that no one server has to support more users than it can handle. Two servers acting in this capacity are shown in Figure 3.

A region server maintains a record of everything in a given region. When the locus of attention of a user process enters a new region, the appropriate region server is queried in order to obtain initial information about the state of objects in the region. After this initial download, the user process obtains further incremental information by peer-to-peer communication. Responsibility for regions is parceled out among a set of servers, which is made large enough that no one server is responsible for a larger piece of the virtual world than it can easily handle.

The foundation of the system is the inter-process communication module shown at the bottom of Figure 4. It provides all the processing necessary to maintain approximate consistency between the world model copies associated with a group of communicating processes, sending messages describing changes in the world model caused by the local application and receiving messages from other processes about changes made remotely. The network interface specifies the format of these messages. Any process that obeys this interface can interoperate.

The messages sent are of three kinds, corresponding to three kinds of data in the world model: small rapidly changing objects, large slowly changing objects, and continuous streams of data. An important feature of the system is that it includes an efficient scheme for synchronizing these different kinds of data.

The most prevalent kind of object in the world model is small things that can change rapidly. For example, an object representing something in the virtual world (e.g., a chair) requires only a small description---i.e., to specify its position and orientation, whether it is contained in some other object, and which appearance should be used when displaying it. The features of small objects can be changed very rapidly.

Messages describing changes in small objects are sent using User Datagram Protocol (UDP) messages. This allows them to be communicated very rapidly. The objects must be small enough so that a message describing one will fit in one UDP message.

Graphic models, recorded sounds, and behaviors are represented using large objects. These objects are identified by Universal Resource Locators (URLs) and communicated using standard World Wide Web protocols. Standard formats are used (e.g., VRML for graphic models, WAVE for sounds, and Java for behaviors) so that standard tools can be used. There is no limitation on the size of the large objects, but several seconds can be required to communicate one. Fortunately, since these objects change infrequently, this latency can generally be masked by preloading the objects before they need to be used.

The final kind of object in the world model corresponds to continuous streams of data such as sound captured by a microphone. These streams are communicated in small chunks using UDP messages. At the moment, video streams are not supported. When they are, they will be communicated in a similar fashion, but of necessity using larger messages.

1.2.5 Rendering

Visual and audio rendering modules are provided; however rather than being tightly integrated with the system, they are separate applications interfaced to the system. They use the same API as other applications and do not have to be tightly coupled with the main application.

One advantage of the loose coupling of renderers is that the renderers interacting with a person can run in separate processes from the main application. This allows them to operate on separate machines in situations where maximum performance is required. However, the primary mode of operation is for them to run in the same process with the main application, sharing a single copy of the world model as shown in Figure 5.

The greatest advantage of the loose coupling between rendering and the system core is that the system is not tied to any one renderer. Rather, the API is designed to be easily interfaced to almost any renderer. Default renderers are supplied with the system, but it is expected that demanding applications will switch to renderers that are tuned to the task at hand.

Consider visual rendering as an example. In the world model, objects can have positions, orientations, and appearances. The visual renderer creates a scene graph by combining the appearances associated with the objects that are near enough to be seen and renders the scene graph from the vantage point specified by the application. The system itself does nothing with the graphic models that describe the appearances of objects. The only thing that matters is that the visual renderer being used can load them.

A simulation operates just like any other application using the same API to interact with the world model. However, no visual or audio rendering is needed, because there is no person to see or hear it. Complex simulations, intelligent agents, and large persistent databases can all be directly connected to a virtual world. Large powerful computers without support for graphics or sound can be used to manage shared content.

It is important to note that it is a great deal easier to say that a simulation interacts with the world model just like any other application than it is to make it possible for a simulation to effectively interact with the world model. The reason for this is that applications supporting a user have a human being in the loop and simulations do not.

The following paragraphs briefly describe each kind of atomic data used in the API. Some of these types of data are described at greater length in other sections.

Boolean values represented using the type spBoolean. These are used to indicate True and False values.

16-bit integers represented using the type short. These are used when low range integers are adequate.

32-bit integers represented using the type long. These are used for representing most integer values.

32-bit floating point numbers represented using the type float. In keeping with standard graphics practice, these are used to represent most non-integer values. They have limited precision, but are compact.

32-bit unique names represented using the type spName. The system dynamically generates names that are unique across all the processes participating in a session. These names are used both to identify shared objects and to identify the processes that own the objects.

IP addresses/port pairs represented using the type spAddress. These are used to represent network addresses. They contain two pieces of information, a 32-bit IP host address and a 16-bit port number. In C an spAddress is a struct containing the host address, followed by the port number. followed by 16 unused bits to pad the total field out to two full words.

32-bit time durations in milliseconds represented using the type spDuration. Whenever an API function takes a time duration as an argument, this argument is in terms of milliseconds. For compactness, 32-bit integers are used. This allows a range of approximately plus or minus two weeks. (This does not impose any limitation on the lifetime of a session in the virtual world, but rather only limits the maximum difference between two times that can be represented.)

A key feature of the API is that pointer data is always passed into and returned from functions by reference rather than copying. This promotes efficiency, but means you must pay close attention to the following.

1- The system never alters data that is passed to it via a pointer unless this document explicitly states otherwise. This means you can depend on the value remaining the same unless you change it yourself.

2- The system never retains a pointer passed to it beyond the time the function that was given the pointer returns. (If the system needs to keep any of the data, it copies it.)

3- When a pointer is passed to you, you must never alter the data pointed to unless it is explicitly stated that you should, because the system depends on the data not being altered. In particular, you must never free something referred to by a pointer unless you yourself allocated the storage.

1.5.1 Accessors

All interaction with instance variables in shared objects is via access functions, rather than via direct access to the instance variables or structure fields. In the external API, the number of access functions available depends on the visibility of the instance variable in the API. The following discusses the accessors in detail for an instance variable V in a shared class spK containing data of type T.

A particularly good example of the problems related to asynchronous changes is what must be done to properly handle the asynchronous removal of objects. To start with, it is important to understand what happens when an object is removed.

First, the IsRemoved bit is set on in the object R being removed and all connections between R and other objects are broken. Specifically, any instance variable in any other object that refers to R is set to Null. In addition, any instance variable of R that refers to any other shared object is set to Null. A result of this is that having an object's Parent removed is treated very much the same as if the object's Parent was simply changed to Null.

After the first stage of removal above, one can still consult all the instance variables of R, with the proviso that the variables that point to other objects have all become Null. (For variables that are shared with other processes, you can consult the old values of the instance variables to find out what they used to point to.)

Second, some time later (exactly how much time later is discussed in detail below) the storage corresponding to object R is freed. After that time, one can no longer access any of the instance variables of R, and it can be disastrous to try. A key purpose of the first step of removal is to ensure that no other shared object can retain a pointer to a freed object. Applications must be sure that they don't either. There is a separation in time between the first and second stages of removal so that applications have time to notice when objects have been removed.

To deal with asynchronous object removal, an application must check on a regular basis whether any objects it is interested in have been removed and respond appropriately before the objects are freed. The system has carefully designed rules about when objects can be removed and freed in order to reduce the number of times an application has to check for an object's continued existence.

The extended Java syntax is supported by a preprocessor called SPOT. In general, SPOT takes in a Java file containing a shared class definition and produces:

• 1 - A file of automatically generated C functions that adds the shared class to the C API, along with an appropriate .h file;
• 2 - A new Java file using standard syntax that adds the shared class to the Java API;
• 3 - A Java stub file that links the two files above; and
• 4 - A class descriptor file that is used by the system core.

In C-only mode, SPOT is used purely to extend the C API. In C-only mode, everything in the definition of a class must be native. (What this means for instance variables is discussed below.) In C-only mode outputs (2) and (3) are unnecessary.

In Java-only mode, SPOT operates purely to extend the Java API. In Java-only mode, classes can not contain any native elements. Things are arranged so that the shared class can be used from Java without having to link anything additional into the system core. In particular, outputs (1) and (3) are unnecessary.

The following example is used throughout the explanation below. It is contrived to illustrate many different features in a small space.

public class spExample extends spThing { //* [+SendToContact]
  shared public float[] Orientation;            //* [spTransform:17]
  shared public/protected spAction Agent;
  native int Timeout;                           //* [spDuration]

  native public static int New(float [] Orientation);
   //* [sp spExampleNew(spTransform:17 Orientation)]

  native public void Initialization();
   //* [void spExampleInitialization(sp Object)]

  native void SetTimeout(int Timeout);
   //* [void spExampleSetTimeout(sp Object, spDuration Timeout)]

  native public final void Setup(int Timeout, spAction Action);
   //* [void spExampleSetup(sp ExampleObj, spDuration Timeout, sp Action)]
}

A class is a shared class if and only if it is the root shared class sp or extends another shared class. (In the case above, spExample extends the shared class spThing.) The key feature of a shared class is that the objects that are created as instances of the class are shared between the processes participating in a session.

The definition of a shared class must use the keyword `extends' and can use the keywords `public' and/or `abstract'. However, it cannot use any other keywords. In particular, it cannot use the keyword `implements'.

The keyword `shared' specifies that an instance variable is shared between processes. When a shared variable is set in one process, the change is automatically reflected in all other processes. In contrast, variables that are not marked as shared exist in each process, but the values of non-shared variables are set separately by each process, with no effect on their values in any other processes.

The keyword `native' specifies that an instance variable is represented in C so that efficient methods exist for accessing it directly from C. (Shared implies native.)

The keyword native by itself is used often when defining the standard classes in the system, and would be used by someone extending the C API. It would never be used by someone who was solely extending the Java API.

If the keyword shared or native is used, then the data stored in the variable must be one of only a few permitted types. These types fall into two groups: scalar types and pointer types.

A shared or native instance variable can have as its type any of Java's eight primitive scalar data types (byte, short, int, long, float, double, char, and boolean).

Since each shared and native instance variable is represented in C, it must have a C type as well as a Java type. The following table shows the default C type associated with each of the scalar Java types.

• Scalar Java type - Default C type
• boolean - spBoolean
• byte - char
• short - short
• char - unsigned short
• int - long
• long - double
• float - float
• double - double

The semicolon ending a shared or native instance variable declaration can be followed by a comment beginning with `//*' that specifies a non-default type to use for the variable in the C API. This specification has the form [type] where the type is a C type (defined separately in a C file). The only restriction on the C type is that it occupy the same amount of storage as the Java type. For instance, an int in Java is represented using 32 bits. Any 32-bit C type can be used in conjunction with it. Whenever they are passed as arguments to functions or passed between C and Java, scalar values are copied.

In general, SPOT does nothing special with individual types. It merely needs to know what types to use in Java and in C and what their sizes are. However, one scalar type gets special treatment.

In addition too the eight Java scalar types, a shared or native instance variable can have one of the following pointer types.

• A - The variable can have as its type a shared class. These classes include the basic object hierarchy (i.e., spThing and everything else descended from the base shared object class sp) as well as any new shared classes that are defined.
• B - The variable can have as its type the special class spFn.
• C - The variable can have as its type String.
• D - The variable can be an array whose elements are a scalar Java type.

As with scalar types, each of the pointer types above must be mapped to a C type. The correspondence is shown in the table below.

• Permitted Java type - C type
• shared object - sp
• spFn - spFn
• String -
• arrays -

In C, all shared objects are referred to by pointers of type sp and no other C type can be specified. All functional arguments are referred to by pointers of type spFn and no other C type can be specified. Note that it is not possible to have a shared or native variable whose Java type is anything other than the types specified above.

For strings and arrays, there is no default C type. Rather, the C type must be specified using a `//*' comment. When specifying a pointer type, this comment begins with [type:size] where type must be a C type that is a pointer (e.g., float*) and where size specifies how many elements there are in the string or array. For instance, in the spExample class, the C type spTransform points to a vector of 17 floats.

When pointer types are passed as arguments to functions, they are passed whenever possible by reference via a pointer. However, when pointer types are passed between C and Java, the data is typically copied so that appropriate data structures can be maintained separately in C and Java.

As with scalar types, SPOT typically does nothing special with individual pointer types. It merely needs to know what types to use in Java and in C and what the memory size in C is. (For ease of allocation and communication, strings and arrays stored in shared or native variables are always stored in-line in the C representation for an object.) However, several pointer types get special treatment.

The shared object types and the type spFn get special treatment so that appropriate objects will be available efficiently in both Java and C. In addition, Strings get special treatment.

A difference between Java and C is that Strings in Java use Unicode characters while strings in C use ASCII characters. To accommodate this, Java strings are encoded as null terminated UTF8 strings when communicated to C. (If a string only contains 7-bit ASCII characters, this encoding leaves the bits unchanged.)

The C type spFixedAscii specifies a string of variable length that can only be set at the moment when a shared object is being created and cannot be changed later. To minimize the memory used for spFixedAscii values, they are placed in a special variable-sized part of an object. (A consequence of this is that it is not possible to obtain the old value of an spFixedAscii variable.)

The type spFixedAscii can only be used for shared variables as opposed to ones that are merely native. There can be at most one spFixedAscii variable in a shared object. Unlike other array-like types, no explicit size can be specified when using the type spFixedAscii.

1.6.7 Methods

The methods in the definition of a shared class are specified using entirely standard Java code. However, for a method to be available in C, it must be native, or redefine one of a few special methods that the system core uses.

The specification of a native method in a shared class is obligatorily followed by a //* comment containing the signature of the C function that implements the method. The signatures are used by SPOT both to create appropriate C .h files and to produce appropriate stub files linking the Java and C API's.

In order to make it possible to create stubs correctly, types in the C function signature that correspond to arrays must obligatorily contain a specification of their sizes as illustrated below. This is the same convention that is used when specifying native or shared variables that contain arrays. In general, lengths must also be included for string types. However, it can be omitted if the string is null terminated.

  native public static int New(float [] Orientation);
   //* [sp spExampleNew(spTransform:17 Orientation)]

For the generation of stubs, the names of the arguments are used to determine the correspondence between the arguments of the Java and C signatures. The Java and C type of an argument of a native method must be one of the types that are valid for native variables. The corresponding C type of the argument must be one of the C types that are permitted to correspond to the Java type. Automatic conversions are performed when passing values between Java and C.

If a method is not a static method, then the object the method is applied to is passed to the C function via the first argument whose name is not the same as the name of any argument in the Java method. Otherwise, if an argument appears only in the C signature, it is passed the value 0. If an argument appears only in the Java signature it is not be passed to the C function.

In the standard API classes, the convention is followed that if a class spK has a method M, then the name of the corresponding C function is spKM, the arguments are in the same order, and the argument to the C function that receives the object the method is applied to is the first argument.

The following methods are interpreted in special ways. (Note that for all these methods, there can be at most one method with the indicated name in a given shared class definition.)

Initialization - As noted above, you cannot have initialization expressions for native variables. However, you can define a method called Initialization that initializes variables to any values you want. (Note that unlike merely using initialization expressions, this approach allows you to change the initialization of variables that are inherited from an ancestor class.) If no Initialization method is provided, SPOT defines one that does nothing.

New - You can define a static method called New that can be called from C to create an instance of the class. This method can take various arguments and initialize various values. If no New method is provided, then SPOT creates one with no arguments that does nothing other than call spClassNewObj, which in turn calls the Initialization methods for the class and every ancestor class (calling the ancestor methods first). (Operating in Mixed or Java-only mode SPOT generates a creation method for each shared class which calls the New method.)

C - A static method called C is automatically generated by SPOT. This method returns the class object corresponding to the class being defined. You cannot define a method with this name.

Returning to the example above.

public class spExample extends spThing { //* [+SendToContact]
  shared public float[] Orientation;            //* [spTransform:17]
  shared public/protected spAction Agent;
  native int Timeout;                           //* [spDuration]

  native public static int New(float [] Orientation);
   //* [sp spExampleNew(spTransform Orientation)]

  native public void Initialization();
   //* [void spExampleInitialization(sp Object)]

  native void SetTimeout(int Timeout);
   //* [void spExampleSetTimeout(sp Object, spDuration Timeout)]

  native public final void Setup(int Timeout, spAction Action);
   //* [void spExampleSetup(sp ExampleObj, spDuration Timeout, sp Action)]
}

SPOT expects the following C functions to be defined separately:

extern sp spExampleNew(spTransform Orientation);
extern void spExampleInitialization(sp Object);
extern void spExampleSetTimeout(sp Object, spDuration Timeout);
extern void spExampleSetup(sp ExampleObj, spDuration Timeout, sp Action);

Operating in C-only or mixed mode, SPOT generates the following functions:

extern sp spExampleC();
extern spTransform spExampleGetOrientation(sp Object);
extern spTransform spExampleGetOldOrientation(sp Object);
extern void spExampleSetOrientation(sp Object, spTransform Orientation);
extern sp spExampleGetAgent(sp Object);
extern sp spExampleGetOldAgent(sp Object);
extern void spExampleSetAgent(sp Object, sp Agent);
extern spDuration spExampleGetTimeout(sp Object);

A Java file input to SPOT can define non-shared classes that are meaningful to Java and will be available in Java. These classes cannot use the keyword shared. However, they can have native static variables, native static final variables, and methods. These three constructs are handled in exactly the same way as in shared classes. In particular, the native variables are accessible in both C and Java, and SPOT automatically creates stubs so that the native methods are available in Java and C.

A Java file input to SPOT can define a non-shared class that does not contain anything that is either native or shared. When that is the case, the class has no relationship whatever to the system. However, anything that is acceptable to Java can be used in the definition of such a class.

A shared class can contain instance variables that are neither shared nor native. Such a variable can be specified in any way that is acceptable to Java. However, the variable will not be accessible from C.

The central data structure in the API is the world model. There can be only one world model object at a time. It contains the various shared objects that are communicated among a group of processes. The spWM type does not extend the class sp and does not correspond to an object in the world model.

To start up a process, the first thing one does is create the world model to operate on. When the process wishes to terminate, it should remove the world model. In between, the world model is repetitively updated to reflect changes in the objects in the world model caused by other processes.

The class spWM defines the following instance variables:

2.1 Me

native public static int Me; //* [spName]

native public/ static int MainOwner; //* [spName]

native public static String Error; //* [char *:500]

native public/ static String LastError; //* [char *:500]

native public/ static spDuration Interval; //* [spDuration]

native public static spDuration DesiredInterval; //* [spDuration]

native public static int Window; //* [spWindow]

spWM spWMNew(char * Server, spTransferVector V)

• Server - DNS address string of the server to connect to.
• V - Transfer vector specifying functions to use for key operations.
• Return value - The world model created.

Creates the world model. As part of this, establishes a connection to a session via a session server. A process can only create one world model at a time.

The first argument is a DNS string that identifies the session server to connect to (e.g., "node.myUniv.edu"). If the server address string is Null, then all phases of initialization are performed except contacting the session server. This is useful for some kinds of single-user testing.

A process must create the world model before using any shared object operation. After initialization, the world model contains nothing but definitions of the built-in shared classes and a few internal objects that are not observable by applications.

void spWMRemove()

• Return value - There is no return value.

void spWMUpdate()

• Return value - There is no return value.

Causes the local world model copy to be updated to reflect changes made by other processes. The fundamental operation of an application process is based on a cycle of: updating the world model (based on information received from other processes); running the application, waiting until the desired update interval has been reached, updating the world model again, and so on.

A number of important things happen each time spWMUpdate is called.

(1) Other processes are notified of changes made in the local world model copy only when spWMUpdate is called. This gives the application control over when other processes see changes. (For instance, one can ensure that several instance variables of an object will change simultaneously).

(2) The world model is brought up to date by processing messages from other processes. It is guaranteed that the world model will not change in any way between calls to spWMUpdate, unless the application makes the changes itself.

spName spWMGenerateOwner()

• Return value - A newly generated owner id.

Activities in processes are identified by 32-bit session-wide unique ids of type spName. These owner ids are used to tag the objects created by different activities. The main owner id of a process is assigned by the session manager. Additional ids can be created by using the function spWMGenerateOwner. Each time this function is called it returns an additional owner id.

There are two kinds of owner ids: system and ordinary. spWMGenerateOwner returns ordinary owner ids. System owner ids are only used by the system core; there is no function in the API for creating them.

void spWMReportError(sp Object, long Code, char * Description)

• Object - The object that is the target of the error.
• Code - Integer identifying the error.
• Description - Textual description of the error.
• Return value - There is no return value.

The API utilizes a uniform approach to error reporting. This centers around the error reporting strings created by spWMReportError. Whenever an error occurs, spWMReportError is called and an error reporting string is stored so that it can be easily retrieved.

An error is created based on the data passed to spWMReportError as follows. The description string becomes the heart of the error report. It should be human readable, containing as much contextual information as possible. The system does not modify the descriptive string and does not retain a pointer to it.

The code is converted to ASCII and appended to the front of the description followed by a blank. The code should be a unique identifier of the error. (The codes for the errors reported by the system are all negative and every different error has its own unique error code. Applications are advised to use positive error codes.) Programs that want to handle errors can tell which error occurred by looking at the error code portion of the report string.

The error string created is stored so that it can be retrieved as the value of spWMGetError and spWMGetLastError.

As an example of the way error reporting is used, consider that a careful program that was not completely sure that the variable X contained an spThing, might retrieve the Transform from X as follows:

  spWMSetError(NULL);
  transform = spThingGetTransform(X);
  if (spWMGetError()) ...

2.13 spWMRegister

void spWMRegister(sp * Pointer)

• Pointer - Pointer to be registered.
• Return value - There is no return value.

void spWMDeregister(sp * Pointer)

• Pointer - Pointer to be deregistered.
• Return value - There is no return value.

An important part of the API is functions that map functional arguments over objects. There are three basic kinds of mapping functions.

• Examiners - Inspect objects existing in the local world model copy.
• Monitors - Inspect objects existing in the local world model copy and then continue inspecting similar objects that appear in the local world model copy in the future. (Monitors are a combination of an examiner and a callback.)
• Callbacks - Apply functions to objects in the local world model copy when events occur in the future.

In C, spFn is the following functional type:

typedef spBoolean spFn(sp Object, void * State)

• Object - The object the mapped function is being applied to.
• State - Passed to the operation each time it is called (modifiable).
• Return value - True signals that mapping should stop.

The following spFn could be used to count.

spBoolean spCount(sp ignore, void * state) {
  int * count = (int *)state;
  *count = *count+1;
  return FALSE;
}

For instance, the following code counts the number of children of an object X.

int Counter = 0;
spExamineChildren(X, spMaskNORMAL, spCount, &Counter);
Result = Counter;

Note that the state value that is passed to spExamineChildren and then on to the spFn spCount, is passed directly without copying. This is essential so that it can communicate information by side-effect. However, it means that the state must be in existance for the full period of time that spExamineChildren runs. This is not a problem for spExamineChildren, but requires more thought for operations like spExamineBeacons where the operate continues asynchronously for a potentially long period of time.

When an spFn is used as a callback predicate, the return value is interpreted as specifying whether an event has occurred. Specifically, the predicate should return True or False depending on whether it observes that the event it tests for has occurred.

Callback predicates define events in terms of changes to shared instance variables. In particular, they compare the current state of these variables with the state of these variables at the end of the last call on spWMUpdate. (Since callback predicates are evaluated during each call on spWMUpdate, this ensures that any state change will be detected.)

The following shows an example of a simple callback predicate.

spBoolean spChangedParent(sp object, void * ignore) {
  return spThingGetOldParent(object) != spThingGetParent(object);
}

There are several key things to note about callback predicates. First, since callbacks are only applied to objects whose shared variables have changed, callback predicates are not called in situations where there has been no change in the shared instance variables of an object. Therefore, events must involve some change in these variables.

Second, the event generally must focus on changes in the shared instance variables of an object. The API does not provide any way to look at old values of local instance variables.

Third, callback predicates should not modify the object passed to them.

The API includes the following predefined callback predicates. Users can define any other predicates they want.

• spJustNew - True if object just created.
• spJustRemoved - True if object just removed.
• spChanged - True if object changed in any way.
• spChangedTransform - True if Transform of thing changed.
• spChangedVisualDefinition - True if visual definition of thing changed.
• spChangedParent - True if Parent of thing changed.
• spChangedRegion - True if the region an object is in has changed.
• spChangedBeaconWithTag - True if object is a changed beacon with the specified tag.
• spRelevantOwnershipRequest - True if object is a newly appeared spOwnershipRequest for an object owned by the local process.

4 spMask

A fundamental feature of the API is the notion of a view mask for the world model. The purpose of these masks is to control the visibility of objects when using functions like spClassExamine. The spMask type does not extend the class sp and does not correspond to objects in the shared world model. Rather, spMask data is stored in shared objects and used in intermediate computation.

The class spMask defines the following instance variables:

• spMaskMINE - (1) View objects owned by spWMGetMe.
• spMaskOTHERS - (2) View objects not owned by spWMGetMe.
• spMaskNORMAL - (3) View all ordinary objects.

The data type spTransform is used as the fundamental representation of the position, orientation, and scaling of objects. A key advantage of an spTransform is that the various components are easy to understand. The components are also well suited to interpolation. The spTransform type does not extend the class sp and does not correspond to objects in the shared world model. Rather, spTransform data is stored in shared objects and used in intermediate computation.

The class spTransform defines the following instance variables:

• spTransformX - (0) X coordinate.
• spTransformY - (1) Y coordinate.
• spTransformZ - (2) Z coordinate.
• spTransformRX - (3) X coordinate of rotation axis vector.
• spTransformRY - (4) Y coordinate of rotation axis vector.
• spTransformRZ - (5) Z coordinate of rotation axis vector.
• spTransformRA - (6) Amount of rotation.
• spTransformSX - (7) Scaling along X axis.
• spTransformSY - (8) Scaling along Y axis.
• spTransformSZ - (9) Scaling along Z axis.
• spTransformSOX - (10) X coordinate of scaling axis vector.
• spTransformSOY - (11) Y coordinate of scaling axis vector.
• spTransformSOZ - (12) Z coordinate of scaling axis vector.
• spTransformSOA - (13) Amount of scaling rotation.
• spTransformCX - (14) X coordinate of center.
• spTransformCY - (15) Y coordinate of center.
• spTransformCZ - (16) Z coordinate of center.

For example, you might write.

spTransform P;
P[spTransformX] = P[spTransformY] + 2.0;

5.2 spTransformCopy

spTransform spTransformCopy(spTransform Destination, spTransform Source)

• Destination - spTransform to be filled with copied data.
• Source - spTransform that is the source of the data.
• Return value - Modified spTransform.

spTransform spTransformFromIdent(spTransform Transform)

• Transform - spTransform to be initialized.
• Return value - Initialized spTransform.

spVector spTransformGetTranslation(spTransform Transform)

• Transform - spTransform from which to obtain translation.
• Return value - Translation vector.

spTransform spTransformSetTranslation(spTransform Transform, spVector Translation)

• Transform - spTransform whose translation is to be set.
• Translation - Vector specifying translation.
• Return value - Modified spTransform.

spRotation spTransformGetRotation(spTransform Transform)

• Transform - spTransform from which to extract rotation information.
• Return value - Rotation component of spTransform.

spTransform spTransformSetRotation(spTransform Transform, spRotation Rotation)

• Transform - spTransform whose Rotation is to be set.
• Rotation - Rotation value.
• Return value - Modified spTransform.

spVector spTransformGetScale(spTransform Transform)

• Transform - spTransform from which to obtain Scale values.
• Return value - Scale vector.

Returns the Scale portion of an spTransform. In C, the spVector returned shares memory with the spTransform.

spTransform spTransformSetScale(spTransform Transform, spVector Vector)

• Transform - spTransform whose Scale is to be set.
• Vector - Vector of Scale values.
• Return value - Modified spTransform.

spRotation spTransformGetScaleOrientation(spTransform Transform)

• Transform - spTransform from which to obtain ScaleOrientation information.
• Return value - ScaleOrientation rotation.

spTransform spTransformSetScaleOrientation(spTransform Transform, spRotation R)

• Transform - Transform to set ScaleOrientation in.
• R - ScaleOrientation rotation.
• Return value - Modified spTransform.

spVector spTransformGetCenter(spTransform Transform)

• Transform - spTransform from which to obtain center point.
• Return value - Center point vector.

spTransform spTransformSetCenter(spTransform Transform, spVector Center)

• Transform - Transform to set Center in.
• Center - Center point vector.
• Return value - Modified spTransform.

The type spVector is a 3-element vector of floats. It is used to represent several distinct things. The spVector type does not extend the class sp and does not correspond to objects in the shared world model. Rather, spVector data is stored in shared objects and used in intermediate computation.

The class spVector defines the following instance variables:

• spVectorX - (0) X coordinate.
• spVectorY - (1) Y coordinate.
• spVectorZ - (2) Z coordinate.

For example, you might write.

spVector V;
V[spVectorX] = P[spVectorY] + 2.0;

The following four constants contain particular vectors that are useful as arguments to various API functions. (In C, these constants are external variables initialized to appropriate values.)

• spVectorZERO - (0,0,0) Zero vector.
• spVectorAXISX - (1,0,0) Vector along X axis.
• spVectorAXISY - (0,1,0) Vector along Y axis.
• spVectorAXISZ - (0,0,1) Vector along Z axis.

For example, you might write.

spRotation R;
spRotationLookAt(R, spVectorZERO, spVectorAXISX, spVectorAXISY);

6.2 spVectorCopy

spVector spVectorCopy(spVector Destination, spVector Source)

• Destination - spVector to set.
• Source - spVector to copy.
• Return value - Modified vector.

spVector spVectorSetFromScalar(spVector Vector, float Scalar)

• Vector - spVector whose elements are to be set.
• Scalar - Value to set elements to.
• Return value - Modified spVector.

spBoolean spVectorEquals(spVector A, spVector B)

• A - Vector to compare.
• B - Vector to compare.
• Return value - True if vectors are equal.

spBoolean spVectorEqualsDelta(spVector A, spVector B, float Tolerance)

• A - Vector to compare.
• B - Vector to compare.
• Tolerance - Precision of comparison.
• Return value - True if vectors are equal within delta.

spVector spVectorAdd(spVector A, spVector B)

• A - spVector to add vector to.
• B - spVector to add.
• Return value - Modified vector.

spVector spVectorSubtract(spVector A, spVector B)

• A - spVector to subtract vector from.
• B - spVector to subtract.
• Return value - Modified vector.

spVector spVectorMultiplyByScalar(spVector Vector, float Scalar)

• Vector - spVector to multiply by scalar.
• Scalar - Value to multiply by.
• Return value - Modified vector.

spVector spVectorDivideByScalar(spVector Vector, float Scalar)

• Vector - spVector to divide by scalar.
• Scalar - Value to divide by.
• Return value - Modified vector.

spVector spVectorCrossProduct(spVector A, spVector B)

• A - First spVector to multiply.
• B - Second spVector to multiply.
• Return value - Modified vector.

float spVectorDotProduct(spVector A, spVector B)

• A - The first vector to multiply.
• B - The second spVector to multiply.
• Return value - The dot product.

spVector spVectorComposeScales(spVector A, spVector B)

• A - spVector of scale values that is to be modified.
• B - spVector of values to compose with existing scale values.
• Return value - Modified spVector.

float spVectorLength(spVector Vector)

• Vector - The vector whose length is desired.
• Return value - The length.

spVector spVectorNormalize(spVector Vector)

• Vector - Vector to normalize.
• Return value - Modified vector.

The principle way that rotations are specified is in terms of a rotation axis passing through the origin and a rotation angle about this axis in radians. Typically, the rotation angle is between plus or minus PI. A key advantage of an spRotation is that the various components are easy to understand. In addition, because the components are relatively independent, they are well suited to interpolation. The spRotation type does not extend the class sp and does not correspond to objects in the shared world model. Rather, spRotation data is stored in shared objects and used in intermediate computation.

The class spRotation defines the following instance variables:

• spRotationX - (0) Index of X value in spRotation.
• spRotationY - (1) Index of Y value in spRotation.
• spRotationZ - (2) Index of Z value in spRotation.
• spRotationA - (3) Index of Angle value in spRotation.

For example, you might write.

spRotation R;
R[spRotationX] = A[spRotationY] + 2.0;

7.2 spRotationCopy

spRotation spRotationCopy(spRotation Destination, spRotation Source)

• Destination - spRotation to be modified.
• Source - spRotation to be copied.
• Return value - Modified spRotation.

spRotation spRotationFromIdent(spRotation Rotation)

• Rotation - spRotation to be initialized.
• Return value - Initialized spRotation.

spVector spRotationGetAxis(spRotation Rotation)

• Rotation - spRotation to obtain Axis from.
• Return value - Axis portion of spRotation.

spRotation spRotationSetAxis(spRotation Rotation, spVector Axis)

• Rotation - spRotation to modify.
• Axis - Rotation axis.
• Return value - Modified spRotation.

float spRotationGetAngle(spRotation Rotation)

• Rotation - spRotation to get Angle from.
• Return value - Rotation Angle.

spRotation spRotationSetAngle(spRotation Rotation, float Angle)

• Rotation - spRotation to modify.
• Angle - Rotation Angle.
• Return value - Modified spRotation.

spQuaternion spRotationToQuat(spRotation Rotation, spQuaternion Quat)

• Rotation - spRotation to be converted.
• Quat - spQuaternion to modify.
• Return value - Modified spQuaternion.

spRotation spRotationFromQuat(spRotation Rotation, spQuaternion Quat)

• Rotation - spRotation to be modified.
• Quat - spQuaternion to get rotation information from.
• Return value - Modified spRotation.

spVector spRotationToAngles(spRotation Rotation, spVector Vector)

• Rotation - spRotation to convert.
• Vector - spVector to be modified.
• Return value - Modified spVector containing Euler angles.

spRotation spRotationFromAngles(spRotation Rotation, spVector Angles)