The Virtual Reality Modeling Language

Annex C. JavaScript Scripting Reference

(normative)

ISO/IEC DIS 14772-1

January 15, 1997

C.1 Introduction and table of contents

This annex describes the use of JavaScript with the Script node. "Concepts - Scripting" contains a general overview of scripting in VRML while "Nodes Reference - Script" describes the Script node.

C.1 Introduction

C.2 Language

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

C.3.1 Access

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() Method

C.4.4 initialize() Method

C.4.5 shutdown() Method

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

D.5.3 Sending EventOuts

C.6 JavaScript Objects

C.6.1 VRML Field to JavaScript variable conversion

C.6.2 Browser Object

C.6.3 SFColor object

C.6.4 SFImage object

C.6.5 SFNode object

C.6.6 SFRotation object

C.6.7 SFVec2f object

C.6.8 SFVec3f object

C.6.9 MFColor object

C.6.10 MFFloat object

C.6.11 MFInt32 object

C.6.12 MFNode object

C.6.13 MFRotation object

C.6.14 MFString object

C.6.15 MFTime object

C.6.16 MFVec2f object

C.6.17 MFVec3f object

C.6.18 VrmlMatrix object

C.7 Examples

C.2 Language

Netscape JavaScript was created by Netscape Communications Corporation (http://home.netscape.com). JavaScript is a programmable API that allows cross-platform scripting of events, objects, and actions. The JavaScript Specification, Version 1.1, can be found at: http://home.netscape.com/eng/javascript/. It is expected that JavaScript, Version 1.2, will be the scripting language of a Script node when JavaScript becomes a standard. The difference for VRML is that objects in numeric expression will have valueOf() called and if that fails, then toString() will be called.

JavaScript is currently undergoing standardization through ECMA.

The Math object is required to be supported by the JavaScript implementation. This includes the constants: E, LN10, LN2, PI, SQRT1_2, SQRT2 and the methods: abs(), acos(), asin(), atan(), atan2(), ceil(), cos(), exp(), floor(), log(), max(), min(), pow(), random(), round(), sin(), sqrt(), tan().

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

C.3.1 Access

The url field of the Script node may contain a URL that references JavaScript code:

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

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

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

The url field may contain multiple URL's and thus reference a remote file or in-line code:

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

C.3.2 File extension

The file extension for JavaScript source code is .js.

C.3.3 MIME type

The MIME type for JavaScript 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 JavaScript 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 "Parameter passing and the EventIn function"). If there is no corresponding JavaScript function in the script, the browser's behavior 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 method in the file specified in the url field of the Script node is called. This method 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. "Mapping between JavaScript types and VRML types" provides a description of how VRML types appear in JavaScript.

C.4.3 eventsProcessed() method

Authors may define a function named eventsProcessed which is to be called after some set of events has been received. Some implementations call this function after the return from each EventIn function, while others call it only after processing a number of EventIn functions. In the latter case, an author can improve performance by placing lengthy processing algorithms which do not need to execute for every event received into the eventsProcessed function.

The following example illustrates the use of eventIns:
The author needs to compute a complex inverse kinematics operation at each time step of an animation sequence. The sequence is single-stepped using a TouchSensor and button geometry. Normally the author would have an EventIn function execute whenever the button is pressed. This function would increment the time step then run the inverse kinematics algorithm. But this would execute the complex algorithm at every button press and the user could easily get ahead of the algorithm by clicking on the button rapidly. To solve this the EventIn function can be changed to simply increment the time step and the IK algorithm can be moved to an eventsProcessed function. In an efficient implementation the clicks would be queued. When the user clicks quickly the time step would be incremented once for each button click but the complex algorithm will be executed only once. This way the animation sequence will keep up with the user.

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

C.4.4 initialize() method

Authors may define a function named initialize which is invoked at some time after the VRML file containing the corresponding Script node has been loaded and before any events are processed. This allows initialization tasks to be performed prior to events being received. These might include such actions as constructing geometry or initializing external mechanisms.

The initialize function takes no parameters. Events generated from it are given the timestamp of when the Script node was loaded.

C.4.5 shutdown() method

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. This function can be used to send events informing external mechanisms that the Script node is being deleted so they can clean up allocated resources.

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

C.5 Accessing fields

C.5.1 Accessing Fields and EventOuts of the Script

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

Fields defined in the Script node are 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 a pointer:

    
    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 VRML.

Events generated by setting an eventIn on a node are sent at the completion of the currently executing function. The eventIn must be assigned a value of the same datatype; no partial assignments are allowed. For example, one cannot assign the red value of an SFColor eventIn. Since eventIns are strictly write-only, the remainder of the partial assignment would have invalid fileds. 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 sends that event at the completion of the currently executing function. Assigning to the eventOut multiple times during one execution of the function still only sends one event and that event is the value of the eventOut at the completion of script execution.

C.6 JavaScript objects

C.6.1 VRML Field to JavaScript variable conversion

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

The JavaScript boolean, numeric and string are automatically converted to other datatypes when needed. See section 3.1.2 in the JavaScript Reference Specification for more details.

In JavaScript, 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. Scalar values (boolean and numeric) are assigned by copying the value. Other objects are assigned by reference. There is an example on assigning to illustrate the differences.

The SF objects will be assigned as references, except for assigning to or from eventOut, fields, and MF objects. The exceptions for eventOut, field and MF objects are at the interface between VRML field values and JavaScript variables. The VRML fields are maintained in the correct datatype must be copied at assignment.

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 creates a new object of the same type as the eventOut with the current value of the eventOut. 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 SF object creates a new object of the corresponding SF object type with the current value of the specified MF element. Assigning an SF object to an element of an MF object (which must be of the corresponding type) copies the value of the SF object into the dereferenced element of the MF object.

C.6.2 Browser object

This subclause lists the class static methods available in the Browser object which allow scripts to get and set browser information. Descriptions of the methods are provided under the Browser Interface topic of the Scripting clause of ISO/IEC 14772. The syntax for a call would be:

Table 30: Browser object functions

Return value
Method Name
String
getName()
String
getVersion()
numeric
getCurrentSpeed()
numeric
getCurrentFrameRate()
String
getWorldURL()
void
replaceWorld(MFNode nodes)
MFNode
createVrmlFromString(String vrmlSyntax)
void
createVrmlFromURL(MFString url, Node node, String event)
void
addRoute(SFNode fromNode, SFString fromEventOut, SFNode toNode, String toEventIn)
void
deleteRoute(SFNode fromNode, String fromEventOut, SFNode toNode, String toEventIn)
void
loadURL(MFString url, MFString parameter)
void
setDescription(String description)

C.6.3 SFColor object

C.6.3.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 methods are invoked using the syntax sfColorObjectName.method(<argument-list>), where sfColorObjectName is an instance of an SFColor object.

C.6.3.2 Instance creation method

sfColorObjectName = new SFColor(r, g, b)

C.6.3.3 Properties

The properties of the SFColor object are:

Table 31: SFColor properties

Property
Description
r
red component of the colour
g
greeencomponent of the colour
b
blue component of the colour

C.6.3.4 Methods

The methods of the SFColor object are:

Table 32: SFColor methods

Method
Description
setHSV (h, s, v)
Sets the value of the color by specifying the scalar values of hue (h), saturation (s), and value (v).
getHSV ()
Returns the value of the color in a 3 element numeric array, with hue at index 0, l saturation at index 1, and value at index 2.
toString()
Returns a String containing the value of r, g and b.

C.6.4 SFImage object

C.6.4.1 Description

The SFImage object corresponds to a VRML SFImage field.

C.6.4.2 Instance creation method

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

C.6.4.3 Properties

The properties of the SFImage object are:

Table 33: SFImage properties

Property
Description
x
x dimension of the image
y
y dimension of the image
comp
number of components of the image
1: greyscale
2: greyscale + alpha
3: rgb
4: rgb + alpha)
array
image data

C.6.4.4 Methods

Table 33A: SFImage methods

Method
Description
toString()
Returns a String containing the value of x, y, comp and array.

C.6.5 SFNode object

C.6.5.1 Description

The SFNode object corresponds to a VRML SFNode field.

C.6.5.2 Instance creation method

sfNodeObjectName = new SFNode(vrmlstring)

C.6.5.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.5.4 Methods

Table 33A: SFNode methods

Method
Description
toString()
Returns a String containing the ASCII VRML 2.0 equivalent of the node, or, if that is not available, the empty string.

C.6.6 SFRotation object

C.6.6.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.6.2 Instance creation methods

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

sfRotationObjectName = new SFRotation(axis, angle)

sfRotationObjectName = new SFRotation(fromVector, toVector)

C.6.6.3 Properties

The properties of the SFRotation object are:

Table 34: SFRotation properties

Property
Description
x
first value of the axis vector
y
second value of the axis vector
z
third value of the axis vector
angle
numeric corresponding to the angle of the rotation (in radians)

C.6.6.4 Methods

The methods of the SFRotation object are:

Table 35: SFRotation methods

Method
Description
getAxis ()
Returns the axis of rotation as an SFVec3f object.
inverse ()
Returns a SFRotation object whose value is the inverse of this object's rotation.
multiply (rotation)
Returns an SFRotation whose value is the object multiplied by the passed SFRotation.
multVec (vec)
Returns a SFVec3f whose value is the SFVec3f vec multiplied by the matrix corresponding to this object's rotation.
setAxis (vec)
Sets the axis of rotation to the vector passed in vec.
slerp (destRotation, t)
Returns a SFRotation whose value is the spherical linear interpolation between this object's rotation and destRotation at value 0 <= t <= 1. For t = 0, the value is this object's rotation. For t = 1, the value is destRotation.
toString()
Returns a String containing the value of x, y, z, and angle.

C.6.7 SFVec2f object

C.6.7.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.7.2 Instance creation method

sfVec2fObjectName = new SFVec2f(number1, number2)

C.6.7.3 Properties

The properties of the SFVec2f object are:

Table 40: SFVec2f properties

Property
Description
x
First value of the vector.
y
Second value of the vector.

C.6.7.4 Methods

The methods of the SFVec2f object are:

Table 41: SFVec2f methods

Method
Description
add (vec)
Returns an SFVec2f whose value is the passed SFVec2f added, component-wise, to the object.
divide (number)
Returns an SFVec2f whose value is the object divided by the passed numeric value.
dot (vec)
Returns the dot product of this vector and SFVec2f vec.
length ()
Returns the geometric length of this vector.
multiply (number)
Returns an SFVec2f whose value is the object multiplied by the passed numeric value.
normalize ()
Returns an SFVec2f object converted to unit length .
subtract (vec)
Returns an SFVec2f whose value is the passed SFVec2f subtracted, component-wise, from the object.
toString()
Returns a String containing the value of x and y.

C.6.8 SFVec3f object

C.6.8.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.8.2 Instance creation method

sfVec3fObjectName = new SFVec3f(number1, number2, number3)

C.6.8.3 Properties

The properties of the SFVec3f object are:

Table 42: SFVec2f properties

Property
Description
x
First value of the vector.
y
Second value of the vector.
z
Third value of the vector.

C.6.8.4 Methods

The methods of the SFVec3f object are:

Table 43: SFVec3f methods

Method
Description
add (vec)
Returns an SFVec3f whose value is the passed SFVec3f added, component-wise, to the object.
cross (vec)
Returns the cross product of the object and the passed SFVec3f.
divide (number)
Returns an SFVec3f whose value is the object divided by the passed numeric value.
dot (vec)
Returns the dot product of this vector and SFVec3f vec.
length ()
Returns the geometric length of this vector.
multiply (number)
Returns an SFVec3f whose value is the object multiplied by the passed numeric value.
negate ()
Returns an SFVec3f whose value is the component-wise negation of the object.
normalize ()
Returns an SFVec3f object converted to unit length .
subtract (vec)
Returns an SFVec3f whose value is the passed SFVec3f subtracted, component-wise, from the object.
toString()
Returns a String containing the value of x, y, and z.

C.6.9 MFColor object

C.6.9.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.9.2 Instance creation method

mfColorObjectName = new MFColor([SFColor, SFColor, ...])

C.6.9.3 Property

The property of the MFColor object is:

Table 44: MFColor properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.9.4 Method

The method of the MFColor object is:

Table 45: MFColor methods

Method
Description
toString()
Returns a String containing the value of the MFColor array.

C.6.10 MFFloat object

C.6.10.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.10.2 Instance creation method

mfFloatObjectName = new MFFloat([number, number...])

C.6.10.3 Property

The property of the MFFloat object is:

Table 46: MFFloat properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.10.4 Method

The method of the MFFloat object is:

Table 47: MFFloat methods

Method
Description
toString()
Returns a String containing the value of the MFFloat array.

C.6.11 MFInt32 object

C.6.11.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.11.2 Instance creation method

mfInt32ObjectName = new MFInt32([number, number, ...])

C.6.11.3 Property

The property of the MFInt32 object is:

Table 48: MFInt32 properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.11.4 Method

The method of the MFInt32 object is:

Table 49: MFInt32 methods

Method
Description
toString()
Returns a String containing the value of the MFInt32 array.

C.6.12 MFNode object

C.6.12.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.12.2 Instance creation method

mfNodeObjectName = new MFNode([SFNode, SFNode, ...])

C.6.12.3 Property

The property of the MFNode object is:

Table 50: MFNode properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.12.4 Method

The method of the MFNode object is:

Table 51: MFNode methods

Method
Description
toString()
Returns a String containing the VRML 2.0 ASCII representation of each node, or an empty MFNode "[]".

C.6.13 MFRotation object

C.6.13.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.13.2 Instance creation method

mfRotationObjectName = new MFRotation([MFRotation, MFRotation, ...])

C.6.13.3 Property

The property of the MFRotation object is:

Table 52: MFRotation properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.13.4 Method

The method of the MFRotation object is:

Table 53: MFRotation methods

Method
Description
toString()
Returns a String containing the value of the MFRotation array.

C.6.14 MFString Object

C.6.14.1 Description

The MFString object corresponds to a VRML 2.0 MFString field. It is used to store a one-dimensional array of SFString 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.14.2 Instance creation method

mfStringObjectName = new MFString([SFString, SFString, ...])

C.6.14.3 Property

The property of the MFString object is:

Table 52: MFString properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.14.4 Method

The method of the MFString object is:

Table 53: MFString methods

Method
Description
toString()
Returns a String containing the value of the MFString array.

C.6.15 MFTime object

C.6.15.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.15.2 Instance creation method

mfTimeObjectName = new MFTime([numeric, numeric, ...])

C.6.15.3 Property

The property of the MFTime object is:

Table 52: MFTime properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.15.4 Method

The method of the MFTime object is:

Table 53: MFTime methods

Method
Description
toString()
Returns a String containing the value of the MFTime array.

C.6.16 MFVec2f object

C.6.16.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.16.2 Instance creation method

mfVec2fObjectName = new MFVec2f([SFVec2f, SFVec2f, ...])

C.6.16.3 Property

The property of the MFVec2f object is:

Table 52: MFVec2f properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.16.4 Method

The method of the MFVec2f object is:

Table 53: MFVec2f methods

Method
Description
toString()
Returns a String containing the value of the MFVec2f array.

C.6.17 MFVec3f object

C.6.17.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.17.2 Instance creation method

mfVec3fObjectName = new MFVec3f([SFVec3f, SFVec3f,...])

C.6.17.3 Property

The property of the MFVec3f object is:

Table 52: MFVec3f properties

Property
Description
length
Integer field for getting/setting the number of elements in the array.

C.6.17.4 Method

The method of the MFVec3f object is:

Table 53: MFVec3f methods

Method
Description
toString()
Returns a String containing the value of the MFVec3f array.

C.6.18 VrmlMatrix Object

C.6.18.1 Description

The VrmlMatrix object provides many useful methods 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 will be in the fourth row. For example, vrmlMatrixObjectName[3][0] is the X offset.

C.6.18.2 Instance creation methods

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

VrmlMatrixObjectName = new VrmlMatrix()

C.6.18.3 Properties

The VRMLMatrix object has no properties.

C.6.18.4 Methods

C.6.8.4 Methods

The methods of the VRMLMatrix object are:

Table 41: VRMLMatrix methods

Method
Description
setTransform (translation, rotation, scale, scaleOrientation, center)
Sets the VrmlMatrix to the passed values. Translation is an SFVec3f object, rotation is a SFRotation object, scale is an SFVec3f object, scaleOrientation is an SFRotation object, and center is an SFVec3f object. Any of the rightmost parameters may be omitted. The method has 0 to 5 parameters. For example, specifying 0 parameters results in an identity matrix while specifying 1 parameter results in a translation and specifying 2 parameters results in a translation and a rotation. Any unspecified parameter is set to its default as specified for the Transform node.
getTransform (translation, rotation, scale)
Decomposes the VrmlMatrix and returns the components in the passed translation (SFVec3f), rotation (SFRotation), and scale (SFVec3f) objects. The types of these passed objects is the same as the first three arguments to setTransform. If any passed object is not sent, or if the null object is sent for any value, that value is not returned. Any projection or shear information in the matrix is ignored.
inverse ()
Returns a VrmlMatrix whose value is the inverse of this object.
transpose ()
Returns a VrmlMatrix whose value is the transpose of this object.
multLeft (matrix)
Returns a VrmlMatrix whose value is the object multiplied by the passed matrix on the left.
multRight (matrix)
Returns a VrmlMatrix whose value is the object multiplied by the passed matrix on the right.
multVecMatrix (vec)
Returns an SFVec3f whose value is the object multiplied by the passed row vector.
multMatrixVec (vec)
Returns an SFVec3f whose value is the object multiplied by the passed column vector.
toString()
Returns a String containing the values of the VrmlMatrix.

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 method 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 methods defined in Example_2 Script are called are provided in "Concepts - Execution Model".

The following two examples illustrate the use of browser access:

createVrmlFromURL method

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;
        }"
}


addRoute method
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' contains a SFVec3f 
                                      // object with the value (0,1,2)

            b = a;                    // 'b' references the same
                                      // object as 'a'.

            a.x = 3;                  // 'a' and 'b' both contain 
                                      // (3,1,2). 'eO' is unchanged.

            f[1] = a;                 // 'f[1]' contains the value
                                      // (3,1,2).

            c = f[1];                 // 'b' contains a SFVec3f
                                      // object with the value (3,1,2)

            f[1].y = 4;               // 'f[1]' contains the value
                                      // (3,4,2). 'c' is unchanged.
        }"
}

The following example illustrates uses the fields and methods 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);
        }"
}