Version 1.0, July 10, 1995
Justifications and system architecture for VRBS are discussed in two papers on VRBS, both to be presented at VRML 95 in December. Those papers are available at:
"The Virtual Reality Behavior System (VRBS): Using Perl as a Behavior Language for VRML," John L. Moreland, David R. Nadeau, Proceedings of VRML95, 1995.
The VRBS protocol defines two types of communications packets: a message and a response. Messages are sent by the browser to the interpreter, or by the interpreter to the browser, whenever an action is intended.
Responses are acknowledgements of message receipt and execution and are sent by the browser to the interpreter, but never from the interpreter back to the browser. This non-symmetry is essential to avoid deadlocks. See the VRBS papers for more information.
Messages and responses always have three parts: the pre-header, the header, and the arguments. The pre-header part gives the size, in bytes, of the header. The header part gives the opcode class and opcode of the action desired, along with the size, in bytes, of the arguments. The arguments part gives a list of argument values that vary depending upon the opcode class and opcode.
The use of a pre-header byte count allows the header to have a different size in future versions of the protocol. Receivers of the message will read the entire header in, based upon the pre-header's stated size, but only process the fields they know about.
The use of an argument byte count in the header has the same purpose as that in the pre-header. This allows for a variable length list of arguments depending upon the opcode class and opcode.
Further discussion of these fields may be found in the VRBS papers.
Field Internal External Pre-header: Header_nBytes 8-bit 1 byte (binary) Header: Opcode_class 8-bit whatever Opcode 8-bit whatever Args_nBytes 32-bit ? whatever Args: Args... whatever whatever
Messages always give an Opcode_Class (general catagory of opcode), Opcode (the actual thing to do), and Args_nBytes (number of bytes in the arguments that follow).
Pre-header: Header_nBytes 8-bit 1 byte (binary) Header: Opcode_class 8-bit whatever Always "Response" Opcode 8-bit whatever Ack | Error Args_nBytes 32-bit ? whatever Args: Opcode_class 8-bit whatever Opcode 8-bit whatever Args... whatever whatever
Responses always give an Opcode_Class (always a "Response"), an Opcode (always either "Ack" or "Error"), and Args_nBytes (number of bytes in the arguments that follow).
In the argument list, the first two fields are always Opcode_class (a copy of the original message's Opcode_class field), and Opcode (also a copy from the original message). The remaining arguments are a return value (for "Ack" messages) or an error message (for "Error" messages).
All fields (except the Header_nBytes field) are NULL-terminated variable-length strings. The Header_nBytes field is a binary 1-byte value.
Opcode classes follow a naming convention. The first two characters are always "Cl" for "class". The next word is the name of the type of sender, such as "Behavior" or "Browser". Next is the word "To", followed by the name of the type of receiver, such as "Interpreter" or "World".
The following sections list each of the opcode classes and their opcodes.
[0] ClNone ------ [0] OpNone - Ack returns - [1] ClResponse ---------- [0] OpAck opcodeClass, opcode No Ack [1] OpError opcodeClass, opcode, erCode, erMsg No Ack [2] ClBehaviorToWorld ----------------- [0] OpGetWorldUrl worldId Ack returns url [1] OpGetNodeNames worldId Ack returns nameList, typeList [2] OpGetNodeBBox worldId, nodeName Ack returns w, h, d, x, y, z [3] OpGetNodeType worldId, nodeName Ack returns nodeType [4] OpSetNodeField worldId, nodeName, fieldName, fieldVal Ack returns - [5] OpGetNodeField worldId, nodeName, fieldName Ack returns fieldVal [6] OpSetNodeField1 worldId, nodeName, fieldName, index, val Ack returns - [7] OpGetNodeField1 worldId, nodeName, fieldName, index Ack returns val [8] OpDeleteNode worldId, nodeName Ack returns - [9] OpInsertNode worldId, nodeName, iLoc, vrmlText Ack returns - [10] OpReplaceNode worldId, nodeName, vrmlText Ack returns - [3] ClBehaviorToBehavior -------------------- No opcodes at this time [4] ClBehaviorToBrowser ------------------- [0] OpGetBrowserHost - Ack returns hostName [1] OpGetBrowserPort - Ack returns portNum [2] OpGetBrowserName - Ack returns browserName [3] OpGetBrowserVersion - Ack returns versionNum [4] OpGetBrowserFeatures - Ack returns featureList [5] OpGetBrowserNodeTypes - Ack returns typeList [6] OpGetBrowserNodeFields typeName Ack returns fieldList [7] OpGetBrowserViewerTypes - Ack returns viewerList [5] ClBehaviorToInterpreter ----------------------- No opcodes at this time [6] ClBrowserToWorld -------------- No opcodes at this time [7] ClBrowserToBehavior ----------------- No opcodes at this time [8] ClBrowserToBrowser ---------------- No opcodes at this time [9] ClBrowserToInterpreter -------------------- No opcodes at this time [10] ClInterpreterToWorld ------------------ [0] OpAddEventInterest worldId, eventType, eventParams... Ack returns - [1] OpRemoveEventInterest worldId, eventType, eventParams... Ack returns - [2] OpReady worldId Ack returns - [11] ClInterpreterToBehavior ----------------------- [12] ClInterpreterToBrowser ---------------------- [0] OpHello - Ack returns protoVersion, protoParams... [1] OpInformation worldId, erCode, erMsg Ack returns - [2] OpWawrning worldId, erCode, erMsg Ack returns - [3] OpError worldId, erCode, erMsg Ack returns - [13] ClInterpreterToInterpreter -------------------------- No opcodes at this time [14] ClWorldToWorld -------------- No opcodes at this time [15] ClWorldToBehavior ----------------- [0] OpBehaviorStart worldId, pkgName No Ack [1] OpBehaviorStop worldId, pkgName No Ack [2] OpBehaviorEvent worldId, eventType, eventParams... No Ack [16] ClWorldToBrowser ---------------- No opcodes at this time [17] ClWorldToInterpreter -------------------- [0] OpLoadBehavior worldId, pkgName, behaviorText No Ack [1] OpLoadBehaviorFile worldId, pkgName, localFileName No Ack [2] OpUnloadBehavior - No Ack [3] OpQuitInterpreter - No AckAll opcodeClass and opcode values are reserved for future expansion, including those not listed above.
browserName The name of the browser.
butMask A button mask indicating what buttons have been pressed on the user's mouse (or whatever).
d A depth.
erCode An error code. Always a number, positive or negative, less than or equal to 32-bits in length. Error codes may or may not be consequetively assigned, but are unique. See the error code list below.
erMessage An error message string. The message may, or may not, include embedded carriage returns. Messages are intended for display in user dialog boxes or to a stderr output.
eventParams A list of zero or more event parameters. The size, order, and content of the list depends upon the eventType. See the event list below.
eventType The name of an event. See the event list below.
featureList A list of zero or more featureTypes.
featureType A special feature or extension supported by a browser. See the feature list below.
fieldList A list of zero or more fieldNames.
fieldName The VRML name of a node field. Case sensitive.
fieldValue A field value string in VRML format.
h A height.
hostName The name of an Internet host.
iLoc Either "before" or "after", indicating whether to insert before or after a given node.
index The index at which to insert a value within a fieldList.
key The key number of a keyboard key that has been pressed.
keyMask A key mask indicating what keyboard modifier keys have been pressed on the user's keyboard (or whatever).
localFileName The full path name of a local file. Typically used as the name of a behavior file in /tmp that is passed to a locally executing interpreter.
nodeName The VRML name of a node. Case sensitive.
nodeType The VRML type name of a node. Case sensitive.
opcode A protocol opcode. Always a number, positive or negative, less than or equal to 32-bits in length. Opcodes may or may not be consequtive within a class and are not unique overall (i.e., the same opcode number may be reused in different opcode classes).
opcodeClass A protocol opcode class grouping together multiple opcodes with a similar purpose. Always a number, positive or negative, less than or equal to 32-bits in length. Opcode classes may or may not be consequtive within the system, and are unique.
pkgName The package name of a loaded behavior. Set to the name of the WWWBehavior node that loaded the behavior. If the node has no name, a string of the form "b#" is generated, where # is a unique random number having nothing to do with the worldId.
portNum The socket port number of the browser service to which an interpreter is connected. Numbers are unsigned 32-bit values.
protoParams A list of zero or more protocol feature parameters used to let an interpreter know about and adapt to variations and extensions to the behavior protocol supported by a browser. Format ** TBD **.
protoVersion The behavior protocol version number. Always a string of the form "M.m" where M is a major version number, and m is a minor version number. For example "1.0".
timeOffset A time difference from the present to a desired time. The value is in milliseconds.
typeList A list of zero or more nodeTypes.
url A URL.
val A single value component for a field supporting a list of values, such as a diffuseColor list.
versionNum The version number of the browser as an arbitrary string.
viewerList A list of zero or more viewerTypes.
viewerType The name of a viewer type supported by the browser. See the viewer list below.
vrmlText The text of a VRML file, including the first-line header string. The text is typically sent to the browser where it is parsed and the resulting scene components added to an existing world.
w A width.
worldId A unique unsigned 32-bit number assigned to each world when it is loaded in to the browser. worldId's are *not* pointers, *not* URLs, *not* world titles, and so forth. They are not guaranteed to be consequtive or, in fact, have any specific structure or order. SDSC WebView, in fact, generates each worldId as a unique random number using the time, in seconds, from 1972, as the seed for a random number generator.
x An X coordinate.
y A Y coordinate.
z A Z coordinate.
[0] ErIllegal [1] ErSyntax [2] ErResources [3] ErBadWorld [4] ErBadNodeName [5] ErBadFieldName [6] ErBadFieldValue
[0] EvNodeButtonPress [1] EvNodeButtonRelease Interest worldId, nodeName Delivery worldId, nodeName, butMask, keyMask [2] EvNodeKeyPress [3] EvNodeKeyRelease Interest worldId, nodeName Delivery worldId, nodeName, butMask, keyMask, key [4] EvNodePointerWithin2 [5] EvNodePointerEnter2 [6] EvNodePointerLeave2 Interest worldId, nodeName Delivery worldId, nodeName, butMask, keyMask, x, y [7] EvNodePointerWithin3 [8] EvNodePointerEnter3 [9] EvNodePointerLeave3 Interest worldId, nodeName Delivery worldId, nodeName, butMask, keyMask, x, y, z [10] EvNodeChange Interest worldId, nodeName Delivery worldId, nodeName [11] EvNodeFieldChange Interest worldId, nodeName, fieldName Delivery worldId, nodeName, fieldName [12] EvTimer Interest worldId, timeOffset Delivery worldId, timeOffset [13] EvWorldEnter [14] EvWorldLeave Interest worldId Delivery worldId
vrml1.0 Supports the full VRML 1.0 spec. vrml1.1 Supports the full VRML 1.1 spec. inventor1.0 Supports the full OpenInventor 1.0 spec. inventor2.0 Supports the full OpenInventor 2.0 spec.Viewer Codes
examiner Supports an examiner viewer. fly Supports a fly viewer. plane Supports a plane viewer. walk Supports a walk viewer.
A new PERL interpreter is started for each top-level world in a browser. The interpreter is killed when the browser flushes the top-level world from it's memory cache. So, there may be more than one interpreter running at any given time.
All functions return a -1 or NULL on failure, and 0 or a usable value on success.
World Attributes ---------------- $url = &GetWorldUrl( $worldId ) $id = &GetWorldId( ) @nodeNT = &GetNodeNames( $worldId ) Node Instance Attributes ------------------------ ( $w, $h, $d, $x, $y, $z ) = &GetNodeBBox( $worldId, $nodeName ) $nodeType = &GetNodeType( $worldId, $nodeName ) $status = SetNodeField( $worldId, $nodeName, $fieldName, $fieldVal ) $fieldValue = GetNodeField( $worldId, $nodeName, $fieldName ) $status = SetNodeField1( $worldId, $nodeName, $fieldName, $index, $val) $val = GetNodeField1( $worldId, $nodeName, $fieldName, $index ) $status = DeleteNode( $worldId, $nodeName ) $status = InsertNode( $worldId, $nodeName, $iLoc, $vrmlText ) $status = ReplaceNode( $worldId, $nodeName, $vrmlText ) Browser Attributes ------------------ $hostName = &GetBrowserHost( ) $portNum = &GetBrowserPort( ) $browserName = &GetBrowserName( ) $versionNum = &GetBrowserVersion( ) @featureList = &GetBrowserExtensions( ) @types = &GetBrowserNodeTypes( ) @fields = &GetBrowserNodeFields( $typeName ) @viewers = &GetBrowserViewerTypes( ) World Events ------------ $eventId = &AddEvent( $func, $data, $eventType, %eventParams ) $status = &RemoveEvent( $eventId ) Event functions will be called with: &func( $eventId, $data, $eventType, %eventParams ) Event parameters are tag-value pairs: "butMask" $butMask "fieldName" $fieldName "key" $key "keyMask" $keyMask "nodeName" $nodeName "timeOffset" $timeOffset "worldId" $worldId "x" $x "y" $y "z" $zSee the event discussion in the protocol section for event interest and detail parameters.