The Virtual Reality Modeling Language

Annex C
(normative)

ECMAScript scripting reference

C.1 Introduction and table of contents

This annex describes the ECMAScript programming language that enables Script nodes (see 6.40, Script) to interact with VRML scenes. See 4.12, Scripting, for a general description of scripting languages in ISO/IEC 14772. Note that support for the ECMAScript is not required by ISO/IEC 14772, but any access of ECMAScript from within VRML Script nodes shall conform with the requirements specified in this annex.

C.1 Introduction
C.2 Language
C.3 Supported Protocol in the Script node's url field
       C.3.1 url  field
       C.3.2 File extension
       C.3.3 MIME type
C.4 eventIn handling
       C.4.1 Receiving eventIns
       C.4.2 Parameter passing and the eventIn function
       C.4.3 eventsProcessed( ) function
       C.4.4 initialize( ) function
       C.4.5 shutdown( ) function
C.5 Accessing fields and events
       C.5.1 Accessing fields and eventOuts of the script
       C.5.2 Accessing fields and eventOuts of other nodes
       C.5.3 Sending eventOuts
C.6 ECMAScript objects
       C.6.1 Notational conventions
       C.6.2 VRML field to ECMAScript variable conversion
       C.6.3 Browser object
       C.6.4 SFColor object
       C.6.5 SFImage object
       C.6.6 SFNode object
       C.6.7 SFRotation object
       C.6.8 SFVec2f object
       C.6.9 SFVec3f object
       C.6.10 MFColor object
       C.6.11 MFFloat object
       C.6.12 MFInt32 object
       C.6.13 MFNode object
       C.6.14 MFRotation object
       C.6.15 MFString object
       C.6.16 MFTime object
       C.6.17 MFVec2f object
       C.6.18 MFVec3f object
       C.6.19 VrmlMatrix object
C.7 Examples

C.2 Language

ECMAScript is a general purpose, cross-platform programming language that can be used with ISO/IEC 14772 to provide scripting of events, objects, and actions. ECMAScript is fully described in 2.[ESCR]. Prior to standardization as ECMA-262, ECMAScript was known as Netscape JavaScript. Several syntactic entities in this annex reflect this origin.

C.3 Supported protocol in the Script node's url field

C.3.1 url field

The url field of the Script node may contain URL references to ECMAScript code as illustrated below:

    Script { url "http://foo.com/myScript.js" }

The javascript: protocol allows the script to be placed inline as follows:

    Script { url "javascript: function foo( ) { ... }" }

Browsers supporting the ECMAScript scripting language shall support the javascript: protocol as well as the the other required protocols (see 7, Conformance and minimum support requirements).

The url field may contain multiple URL's referencing either a remote file or in-line code as shown in the following example:

    Script {
      url [ "http://foo.com/myScript.js",
      "javascript: function foo( ) { ... }" ]
    }

C.3.2 File extension

The file extension for ECMASCript source code is '.js', unless a protocol returning mime types is used (such as HTTP). In that case, any suffix is allowed as long as the proper mime type is returned (see C.3.3, Mime type).

C.3.3 MIME type

The MIME type for ECMAScript source code is defined as follows:

     application/x-javascript

C.4 eventIn handling

C.4.1 Receiving eventIns

Events sent to the Script node are passed to the corresponding ECMAScript function in the script. The script is specified in the url field of the Script node. The function's name is the same as the eventIn and is passed two arguments, the event value and its timestamp (see C.4.2, Parameter passing and the eventIn function). If there is no corresponding ECMAScript function in the script, the browser's behaviour is undefined.

For example, the following Script node has one eventIn field whose name is start:

    Script {
      eventIn SFBool start
      url "javascript: function start(value, timestamp) { ... }"
    }

In the above example, when the start eventIn is sent, the start( ) function is executed.

C.4.2 Parameter passing and the eventIn function

When a Script node receives an eventIn, a corresponding function in the file specified in the url field of the Script node is called. This function has two arguments. The value of the eventIn is passed as the first argument and the timestamp of the eventIn is passed as the second argument. The type of the value is the same as the type of the eventIn and the type of the timestamp is SFTime. C.6.1, VRML field to ECMAScript variable conversion, provides a description of how VRML types appear in ECMAScript. The values of the parameters have no visibility outside the function.

C.4.3 eventsProcessed( ) function

Authors may define an eventsProcessed() function that is called after some set of events has been received. This allows Script nodes that do not rely on the ordering of events received to generate fewer events than an equivalent Script node that generates events whenever events are received (see C.4.1, Receiving eventIns).

The eventsProcessed( ) function takes no parameters. Events generated from it are given the timestamp of the last event processed.

C.4.4 initialize( ) function

Authors may define a function named initialize( ) which is invoked before the browser presents the world to the user and before any events are processed by any nodes in the same VRML file as the Script node containing this script (see 4.12.3, Initialize() and shutdown()).

The initialize( ) function has no parameters. Events generated from initialize( ) are given the timestamp of when the Script node was loaded.

C.4.5 shutdown( ) function

Authors may define a function named shutdown( ) which is invoked when the corresponding Script node is deleted or when the world containing the Script node is unloaded or replaced by another world (see 4.12.3, Initialize() and shutdown()).

The shutdown( ) function has no parameters. Events generated from shutdown( ) are given the timestamp of when the Script node was deleted.

C.5 Accessing fields and events

C.5.1 Accessing fields and eventOuts of the Script

The fields and eventOuts of a Script node are accessible from its ECMAScript functions. As in all other nodes, the fields are accessible only within the Script. The eventIns are not accessible. The Script node's eventIns can be routed to and its eventOuts can be routed from. Another Script node with a reference to this node can access its eventIns and eventOuts as for any other node.

A field defined in a Script node is available to the script by using its name. Its value can be read or written. This value is persistent across function calls. EventOuts defined in the script node can also be read. The value is the last value assigned.

C.5.2 Accessing fields and eventOuts of other nodes

The script can access any exposedField, eventIn or eventOut of any node to which it has access:

    DEF SomeNode Transform { }
    Script {
      field SFNode node USE SomeNode
      eventIn SFVec3f pos
      directOutput TRUE
      url "javascript:
        function pos(value) {
          node.set_translation = value;
        }"
    }

This example sends a set_translation eventIn to the Transform node. An eventIn on a passed node can appear only on the left side of the assignment. An eventOut in the passed node can appear only on the right side, which reads the last value sent out. Fields in the passed node cannot be accessed. However, exposedFields can either send an event to the "set_..." eventIn or read the current value of the "..._changed" eventOut. This follows the routing model of the rest of ISO/IEC 14772.

Events generated by setting an eventIn on a node are sent at the completion of the currently executing function. The eventIn shall be assigned a value of the same datatype; no partial assignments are allowed. For example, it is not possible to assign the red value of an SFColor eventIn. Since eventIns are strictly write-only, the remainder of the partial assignment would have invalid field values. Assigning to the eventIn field multiple times during one execution of the function still only sends one event and that event is the last value assigned.

C.5.3 Sending eventOuts

Assigning to an eventOut of a Script node, or a component of an eventOut (i.e. MF eventOut or a property of an SF eventOut), sends an event to that eventOut. Events are sent at the end of script execution. An eventOut may be assigned a value multiple times within the script, but the value sent shall be the last value assigned to the eventOut. If the value of individual components of an eventOut are changed, the last value given to each component shall be sent. Components that are not changed in the script, send their initial value determined at the beginning of the script execution. For example, the following script segment produces an eventOut value of (4, 3, 1) for the eventOut SFVec3f foo_changed with an initial value of (6, 6, 6):

	a = foo_changed; // copy by reference a(6,6,6)
	a.x = 5;         // foo_changed(5,6,6)
	a.z = 1;         // foo_changed(5,6,1)
	b = foo_changed; // copy by reference b(5,6,1)
	b.x = 4;         // foo_changed(4,6,1)
	c = a;           // copy by reference c(4,6,1)
	c.y = 3;         // foo_changed(4,3,1))

C.6 ECMAScript objects

C.6.1 Notational conventions

Since ECMAScript is an untyped language it has no language constructs to describe the types of parameters passed to, or values returned from, functions. Therefore this annex uses a notational convention to describe these types. Parameters passed are preceded by their type, and the type of any return value precedes the function name. Normally these types correspond to VRML field types, so those names are used. In the case of no return value, the identifier void is used. In the case of a ECMAScript numeric value or numeric array return, the identifier numeric or numeric[ ] is used. In the case of a string return, the identifier String is used.

C.6.2 VRML field to ECMAScript variable conversion

ECMAScript native datatypes consist of boolean, numeric and string. The language is not typed, so datatypes are implicit upon assignment. The VRML SFBool is mapped to the ECMAScript boolean. In addition to the ECMAScript true and false constants, the VRML TRUE and FALSE values may be used. The VRML SFInt32, SFFloat and SFTime fields are mapped to the numeric datatype and will be maintained in double precision accuracy. These types are passed by value in function calls. All other VRML fields are mapped to ECMAScript objects. ECMAScript objects are passed by reference.

The ECMAScript boolean, numeric and string are automatically converted to other datatypes when needed. See 2.[ESCR] for more details.

In ECMAScript, assigning a new value to a variable gives the variable the datatype of the new value, in addition to the value. Scalar values (boolean and numeric) are assigned by copying the value. Other objects are assigned by reference.

When assignments are made to eventOuts and fields, the values are converted to the VRML field type. Values assigned are always copied. This contrasts with normal assignment in ECMAScript where all assignments except for scalar are performed by reference.

For eventOut objects, assignment copies the value to the eventOut, which will be sent upon completion of the current function. Assigning an eventOut to an internal variable copies by reference. Subsequent assignments to that internal variable will behave like assignments to the eventOut (i.e., an event will be sent at the end of the function). Field objects behave identically to eventOut objects, except that no event is sent upon completion of the function.

Assigning an element of an MF object to an internal variable creates a reference to that element. The type shall be the corresponding SF object type. If the MF object is an eventOut and an assignment is made to the internal variable, an event will be sent at the end of the function. Assigning an SF object to an element of an MF object which is a field or eventOut (which shall be of the corresponding type) copies the value of the SF object into the MF object element. If the MF object is an eventOut an event will be sent at the end of the function.

C.6.3 Browser object

This subclause lists the class static functions available in the Browser object which allow scripts to get and set browser information. Descriptions of the functions are provided in 4.12.10, Browser script interface. The syntax for a call is:

    mymfnode = Browser.createVrmlFromString('Sphere {}');

Table C.1 describes the Browser object's functions, parameters, and return values.

Table C.1 -- Browser object functions

C.6.4 SFColor object

C.6.4.1 Description

The SFColor object corresponds to a VRML SFColor field. All properties are accessed using the syntax sfColorObjectName.<property>, where sfColorObjectName is an instance of an SFColor object. The properties may also be accessed by the indices [0] for red, [1] for green and [2] blue. All functions are invoked using the syntax sfColorObjectName.method(<argument-list>), where sfColorObjectName is an instance of an SFColor object.

C.6.4.2 Instance creation function

sfColorObjectName = new SFColor(float r, float g, float b)

where

r, g, and b are the red, green, and blue values of the colour. Missing values will be filled by 0.0.

C.6.4.3 Properties

The properties of the SFColor object are described in Table C.2.

Table C.2 -- SFColor properties

C.6.4.4 Functions

The functions of the SFColor object are described in Table C.3.

Table C.3 -- SFColor functions

C.6.5 SFImage object

C.6.5.1 Description

The SFImage object corresponds to a VRML SFImage field.

C.6.5.2 Instance creation function

sfImageObjectName = new SFImage(numeric x, numeric y, numeric comp, MFInt32 array)

where

x is the x-dimension of the image. y is the y-dimension of the image. comp is the number of components of the image (1 for greyscale, 2 for greyscale+alpha, 3 for rgb, 4 for rgb+alpha). Array contains the x × y values for the pixels of the image. The format of each pixel is an SFImage as in the PixelTexture node.

C.6.5.3 Properties

The properties of the SFImage object are listed in Table C.4.

Table C.4 -- SFImage properties

C.6.5.4 Functions

The function of the SFImage object is described in Table C.5.

Table C.5 -- SFImage function

C.6.6 SFNode object

C.6.6.1 Description

The SFNode object corresponds to a VRML SFNode field.

C.6.6.2 Instance creation function

sfNodeObjectName = new SFNode(String vrmlstring)

where

vrmlstring is an ISO 10646 string containing a legal VRML string as described in 4.12.10.9, MFNode createVrmlFromString( SFString vrmlSyntax ). If the string produces other than one top-level node, the results are undefined. The string may contain any number of ROUTE's, PROTO's, and EXTERNPROTO's in accordance with 4.12.10.9, MFNode createVrmlFromString( SFString vrmlSyntax ).

C.6.6.3 Properties

Each node may assign values to its eventIns and obtain the last output values of its eventOuts using the sfNodeObjectName.eventName syntax.

C.6.6.4 functions

The function of the SFNode object is described in Table C.6.

Table C.6 -- SFNode function

C.6.7 SFRotation object

C.6.7.1 Description

The SFRotation object corresponds to a VRML SFRotation field. It has four numeric properties: x, y, z (the axis of rotation) and angle. These may also be addressed by indices [0] through [3].

C.6.7.2 Instance creation functions

sfRotationObjectName = new SFRotation(numeric x, numeric y, numeric z, numeric angle)

where

x, y, and z are the axis of the rotation. angle is the angle of the rotation (in radians). Missing values default to 0.0, except y, which defaults to 1.0.

sfRotationObjectName = new SFRotation(SFVec3f axis, numeric angle)

where

axis is the axis of rotation. angle is the angle of the rotation (in radians)

sfRotationObjectName = new SFRotation(SFVec3f fromVector, SFVec3f toVector)

where

fromVector and toVector are normalized and the rotation value that would rotate from the fromVector to the toVector is stored in the object.

C.6.7.3 Properties

The properties of the SFRotation object are described in Table C.7.

Table C.7 -- SFRotation properties

C.6.7.4 Functions

The functions of the SFRotation object are described in Table C.8.

Table C.8 -- SFRotation functions

C.6.8 SFVec2f object

C.6.8.1 Description

The SFVec2f object corresponds to a VRML SFVec2f field. Each component of the vector can be accessed using the x and y properties or using C-style array dereferencing (i.e., sfVec2fObjectName[0] or sfVec2fObjectName[1]).

C.6.8.2 Instance creation function

sfVec2fObjectName = new SFVec2f(numeric x, numeric y)

Missing values default to 0.0.

C.6.8.3 Properties

The properties of the SFVec2f object are described in Table C.9.

Table C.9 -- SFVec2f properties

C.6.8.4 Functions

The functions of the SFVec2f object are described in Table C.10.

Table C.10 -- SFVec2f functions

C.6.9 SFVec3f object

C.6.9.1 Description

The SFVec3f object corresponds to a VRML SFVec3f field. Each component of the vector can be accessed using the x, y, and z properties or using C-style array dereferencing (i.e., sfVec3fObjectName[0], sfVec3fObjectName[1] or sfVec3fObjectName[2]).

C.6.9.2 Instance creation function

sfVec3fObjectName = new SFVec3f(numeric x, numeric y, numeric z)

Missing values default to 0.0.

C.6.9.3 Properties

The properties of the SFVec3f object are described in Table C.11.

Table C.11 -- SFVec2f properties

C.6.9.4 Functions

The functions of the SFVec3f object are described in Table C.12.

Table C.12 -- SFVec3f functions

C.6.10 MFColor object

C.6.10.1 Description

The MFColor object corresponds to a VRML MFColor field. It is used to store a one-dimensional array of SFColor objects. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfColorObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to SFColor (0, 0, 0).

C.6.10.2 Instance creation function

mfColorObjectName = new MFColor(SFColor c1, SFColor c2, ...)

The creation function shall initialize the array using 0 or more SFColor-valued expressions passed as parameters.

C.6.10.3 Property

The property of the MFColor object is described in Table C.13.

Table C.13 -- MFColor properties

C.6.10.4 Function

The single function of the MFColor object is described in Table C.14.

Table C.14 -- MFColor functions

C.6.11 MFFloat object

C.6.11.1 Description

The MFFloat object corresponds to a VRML MFFloat field. It is used to store a one-dimensional array of SFFloat values. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfFloatObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to 0.0.

C.6.11.2 Instance creation function

mfFloatObjectName = new MFFloat(numeric n1, numeric n2, ...)

where

The creation function shall initialize the array using 0 or more numeric-valued expressions passed as parameters.

C.6.11.3 Property

The property of the MFFloat object is described in Table C.15.

Table C.15 -- MFFloat properties

C.6.11.4 Function

The single function of the MFFloat object is described in Table C.16.

Table C.16 -- MFFloat function

C.6.12 MFInt32 object

C.6.12.1 Description

The MFInt32 object corresponds to a VRML MFInt32 field. It is used to store a one-dimensional array of SFInt32 values. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfInt32ObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to 0.

C.6.12.2 Instance creation function

mfInt32ObjectName = new MFInt32(numeric n1, numeric n2, ...)

where

The creation function shall initialize the array using 0 or more integer-valued expressions passed as parameters.

C.6.12.3 Property

The property of the MFInt32 object is described in Table C.17.

Table C.17 -- MFInt32 property

C.6.12.4 Function

The single function of the MFInt32 object is described in Table C.18.

Table C.18 -- MFInt32 function

C.6.13 MFNode object

C.6.13.1 Description

The MFNode object corresponds to a VRML MFNode field. It is used to store a one-dimensional array of SFNode objects. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfNodeObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to NULL.

C.6.13.2 Instance creation function

mfNodeObjectName = new MFNode(SFNode n1, SFNode n2, ...)

where

The creation function shall initialize the array using 0 or more SFNode-valued expressions passed as parameters.

C.6.13.3 Property

The property of the MFNode object is described in Table C.19.

Table C.19 -- MFNode property

C.6.13.4 Function

The single function of the MFNode object is described in Table C.20.

Table C.20 -- MFNode function

C.6.14 MFRotation object

C.6.14.1 Description

The MFRotation object corresponds to a VRML MFRotation field. It is used to store a one-dimensional array of SFRotation objects. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfRotationObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to SFRotation (0, 0, 1, 0).

C.6.14.2 Instance creation function

mfRotationObjectName = new MFRotation(SFRotation r1, SFRotation r2, ...)

where

The creation function shall initialize the array using 0 or more SFRotation-valued expressions passed as parameters.

C.6.14.3 Property

The property of the MFRotation object is described in Table C.21.

Table C.21 -- MFRotation property

C.6.14.4 Function

The single function of the MFRotation object is described in Table C.22.

Table C.22 -- MFRotation function

C.6.15 MFString object

C.6.15.1 Description

The MFString object corresponds to a VRML 2.0 MFString field. It is used to store a one-dimensional array of String objects. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfStringObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to the empty string.

C.6.15.2 Instance creation function

mfStringObjectName = new MFString(String s1, String s2, ...)

where

The creation function shall initialize the array using 0 or more String-valued expressions passed as parameters.

C.6.15.3 Property

The property of the MFString object is described in Table C.23.

Table C.23 -- MFString property

C.6.15.4 Function

The single function of the MFString object is described in Table C.24.

Table C.24 -- MFString function

C.6.16 MFTime object

C.6.16.1 Description

The MFTime object corresponds to a VRML MFTime field. It is used to store a one-dimensional array of SFTime values. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfTimeObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to 0.0.

C.6.16.2 Instance creation function

mfTimeObjectName = new MFTime(numeric n1, numeric n2, ...)

The creation function shall initialize the array using 0 or more numeric-valued expressions passed as parameters.

C.6.16.3 Property

The property of the MFTime object is described in Table C.25.

Table C.25 -- MFTime property

C.6.16.4 Function

The function of the MFTime object is described in Table C.26.

Table C.26 -- MFTime function

C.6.17 MFVec2f object

C.6.17.1 Description

The MFVec2f object corresponds to a VRML MFVec2f field. It is used to store a one-dimensional array of SFVec2f objects. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfVec2fObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to SFVec2f (0, 0).

C.6.17.2 Instance creation function

mfVec2fObjectName = new MFVec2f(SFVec2f v1, SFVec2f v2, ...)

The creation function shall initialize the array using 0 or more SFVec2f-valued expressions passed as parameters.

C.6.17.3 Property

The property of the MFVec2f object is described in Table C.27.

Table C.27 -- MFVec2f property

C.6.17.4 Function

The single function of the MFVec2f object is described in Table C.28.

Table C.28 -- MFVec2f function

C.6.18 MFVec3f object

C.6.18.1 Description

The MFVec3f object corresponds to a VRML MFVec3f field. It is used to store a one-dimensional array of SFVec3f objects. Individual elements of the array can be referenced using the standard C-style dereferencing operator (e.g., mfVec3fObjectName[index], where index is an integer-valued expression with 0 <= index < length and length is the number of elements in the array). Assigning to an element with index >= length results in the array being dynamically expanded to contain length elements. All elements not explicitly initialized are set to SFVec3f (0, 0, 0).

C.6.18.2 Instance creation function

mfVec3fObjectName = new MFVec3f(SFVec3f v1, SFVec3f v2,...)

where

The creation function shall initialize the array using 0 or more SFVec3f-valued expressions passed as parameters.

C.6.18.3 Property

The property of the MFVec3f object is described in Table C.29.

Table C.29 -- MFVec3f property

C.6.18.4 Function

The single function of the MFVec3f object is described in Table C.30.

Table C.30 -- MFVec3f function

C.6.19 VrmlMatrix object

C.6.19.1 Description

The VrmlMatrix object provides many useful functions for performing manipulations on 4x4 matrices. Each of element of the matrix can be accessed using C-style array dereferencing (i.e., vrmlMatrixObjectName[0][1] is the element in row 0, column 1). The results of dereferencing a VrmlMatrix object using a single index (i.e., vrmlMatrixObjectName[0]) are undefined. The translation elements are in the fourth row. For example, vrmlMatrixObjectName[3][0] is the X offset.

C.6.19.2 Instance creation functions

VrmlMatrixObjectName = new VrmlMatrix(
                                                                      numeric f11, numeric f12, numeric f13, numeric f14,
                                                                      numeric f21, numeric f22, numeric f23, numeric f24,
                                                                      numeric f31, numeric f32, numeric f33, numeric f34,
                                                                      numeric f41, numeric f42, numeric f43, numeric f44)

A new matrix initialized with the values in f11 through f44 is created and returned. The translation values will be f41, f42, and f43.

VrmlMatrixObjectName = new VrmlMatrix( )

A new matrix initialized with the identity matrix is created and returned.

C.6.19.3 Properties

The VRMLMatrix object has no properties.

C.6.19.4 Functions

The functions of the VRMLMatrix object are listed in Table C.31.

Table C.31 -- VRMLMatrix functions

C.7 Examples

The following is an example of a Script node which determines whether a given colour contains a lot of red. The Script node exposes a Color field, an eventIn, and an eventOut:

DEF Example_1 Script {
        field    SFColor currentColor 0 0 0
    eventIn  SFColor colorIn
    eventOut SFBool  isRed

    url "javascript: 
        function colorIn(newColor, ts) {
            // This function is called when a colorIn event is received
            currentColor = newColor;
        }

        function eventsProcessed( ) {
            if (currentColor[0] >= 0.5)
                // if red is at or above 50%
                isRed = true;
        }"
}

Details on when the functions defined in Example_1 Script are called are provided in 4.12.2, Script execution.

The following example illustrate use of the createVrmlFromURL( ) function:

 DEF Example_2 Script { 
    field   SFNode myself USE Example_2
    field   SFNode root USE ROOT_TRANSFORM
    field   MFString url "foo.wrl"
    eventIn MFNode   nodesLoaded
    eventIn SFBool   trigger_event

    url "javascript:
        function trigger_event(value, ts){
            // do something and then fetch values
            Browser.createVRMLFromURL(url, myself, 'nodesLoaded');
        }

        function nodesLoaded(value, timestamp){
            if (value.length > 5) {
                 // do something more than 5 nodes in this MFNode...
            }
            root.addChildren = value;
        }"
}

The following example illustrates use of the addRoute( ) function:

DEF Sensor TouchSensor {}

DEF Baa Script {
    field   SFNode myself USE Baa
    field   SFNode fromNode USE Sensor
    eventIn SFBool clicked
    eventIn SFBool trigger_event

    url "javascript: 
        function trigger_event(eventIn_value){
            // do something and then add routing
            Browser.addRoute(fromNode, 'isActive', myself, 'clicked');
        }

        function clicked(value){
            // do something
        }"
}

The following example illustrates assigning with references and assigning by copying:

Script {
    eventIn  SFBool  eI
    eventOut SFVec3f eO
    field    MFVec3f f []

    url "javascript:
        function eI( ) {
            eO = new SFVec3f(0,1,2);  // 'eO' contains the value
                                      // (0,1,2) which will be sent
                                      // out when the function 
                                      // is complete.
            a = eO;                   // 'a' references the eventOut
                                      // 'e0'
            b = a;                    // 'a' and 'b' now both reference
                                      // 'e0'
            a.x = 3;                  // 'e0' will send (3,1,2) at the
                                      // end of the function
            f[1] = a;                 // 'f[1]' contains the value
                                      // (3,1,2).
            c = f[1];                 // 'c' reference the field 
                                      // element f[1]
            f[1].y = 4;               // 'f[1]' and 'c' both contain
                                      // (3,4,2)
        }"
}

The following example illustrates uses of the fields and functions of SFVec3f and MFVec3f:

DEF SCR-VEC3F Script {
    eventIn SFTime touched1
    eventIn SFTime touched2
    eventIn SFTime touched3
    eventIn SFTime touched4
    eventOut SFVec3f new_translation
    field SFInt32 count 1
    field MFVec3f verts  []

    url "javascript: 
        function initialize( ) {
            verts[0] = new SFVec3f(0, 0, 0);
            verts[1] = new SFVec3f(1, 1.732, 0);
            verts[2] = new SFVec3f(2, 0, 0); 
            verts[3] = new SFVec3f(1, 0.577, 1.732);
        }

        function touched1 (value) {
            new_translation = verts[count]; // move sphere around tetra
            count++;
            if (count >= verts.length) count = 1;
        }

        function touched2 (value) {
            var tVec;
            tVec = new_translation.divide(2); // Zeno's paradox to origin
            new_translation = new_translation.subtract(tVec);
        }

        function touched4 (value) {
            new_translation = new_translation.negate( );
        }

        function touched3 (value) {
            var a;
            a = verts[1].length( ); 
            a = verts[3].dot(verts[2].cross(verts[1]));
            a = verts[1].x;
            new_translation = verts[2].normalize( );
            new_translation = new_translation.add(new_translation);
        }"
}

Questions or comments.
Copyright © 1997 The VRML Consortium Incorporated.
http://www.vrml.org/Specifications/VRML97/part1/javascript.html