Appendix C
JavaScript Scripting Reference
This appendix describes the use of JavaScript with the Script node.
Section "2.12, Scripting"
contains a general overview of scripting in VRML while Section "3.40
Script " describes the Script node.
C.1 Introduction and table of contents
This appendix describes the use of JavaScript with the Script node.
Section "2.12 Scripting" contains
a general overview of scripting in VRML while section "3.40 Script" describes the Script node.
| TECHNICAL
NOTE: Support for JavaScript inside Script nodes is not required,
but if a browser does support JavaScript inside Script nodes, it
is required to adhere to the specifications in this appendix. |
| TIP:
JavaScript is generally easier to learn and use than Java, because
it is weakly typed and does not require code compilation. Simple
scripts written in JavaScript are generally smaller than the equivalent
script written in Java (the minimum size of a Java .class file is
about 200 bytes), and putting the script's code directly into the
VRML file means that the VRML browser has to make fewer HTTP fetch
requests. However, Java is more powerful than JavaScript and will
execute large scripts much faster. |
| TECHNICAL
NOTE: This appendix was initially created by Chris Marrin, and
was later enhanced and evolved by Jan Hardenbergh, Jim Kent, and
a variety of contributors on the www-vrml mailing list. |
 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 [JAVS]. It is expected that JavaScript,
Version 1.2, will be the scripting language of a Script node when JavaScript
becomes a standard. Version 1.2 is required for VRML. The difference
is that objects in numeric expressions will have valueOf( )
called and if that fails, then toString( ) will be called.
JavaScript is currently undergoing standardization through ECMA.
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( ) { ... }" ]
}
The file extension for JavaScript source code is .js.
The MIME type for JavaScript source code is defined as follows:
application/x-javascript
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 "C.4.2
Parameter passing and the EventIn function"). If there is no
corresponding JavaScript 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.
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. "C.6.1 VRML Field to JavaScript
variable conversion" provides a description of how VRML
types appear in JavaScript.
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 eventsProcessed( ) function takes no parameters. Events generated
from it are given the timestamp of the last event processed.
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 "2.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.
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 "2.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.
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
node'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.
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 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.
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.
Since JavaScript is an untyped language it has no language constructs
to describe the types of parameters passed to, or values returned from
methods. Therefore this document uses a notational convention to describe
these types. Parameters passed are preceded by their type, and the type
of any return value precedes the method 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 JavaScript
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.
JavaScript 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 JavaScript boolean. In addition to
the JavaScript 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 JavaScript objects. JavaScript objects
are passed by reference.
The JavaScript boolean, numeric and string are automatically converted
to other datatypes when needed. See [JAVS]
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 and are copied during 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 shall be of the corresponding type) copies the value
of the SF object into the dereferenced element of the MF object.
This section 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 in "2.12.10 Browser script interface".
The syntax for a call is:
mymfnode = Browser.createVrmlFromString('Sphere {}');
Table C-1 describes the Browser object's methods, parameters, and
return values.
Table C-1: Browser object functions
| Return value |
Method |
| 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, String 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.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 methods are invoked using the syntax sfColorObjectName.method(<argument-list>),
where sfColorObjectName is an instance of an SFColor object.
C.6.4.2 Instance creation method
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
| Property |
Description |
| numeric r |
red component of the colour |
| numeric g |
green component of the colour |
| numeric b |
blue component of the colour |
C.6.4.4 Methods
The methods of the SFColor object are described in Table C-3.
Table C-3: SFColor methods
|
Method
|
Description
|
| void setHSV(float h, float s, float
v) |
Sets the value of the colour by specifying the values of hue,
saturation, and value. |
| numeric[3] getHSV( ) |
Returns the value of the colour in a 3 element numeric array,
with hue at index 0, saturation at index 1, and value
at index 2. |
| String toString( ) |
Returns a String containing the VRML 97 utf8 encoded value of
r, g and b. |
C.6.5.1 Description
The SFImage object corresponds to a VRML SFImage field.
C.6.5.2 Instance creation method
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 x y values for the pixels of the image.
Format of each pixel is the same as the PixelTexture
file format.
C.6.5.3 Properties
The properties of the SFImage object are listed in Table C-4.
Table C-4: SFImage properties
| Property |
Description |
| numeric x |
x dimension of the image |
| numeric y |
y dimension of the image |
| numeric comp |
- number of components of the image:
- 1: greyscale
- 2: greyscale + alpha
- 3: rgb
- 4: rgb + alpha
|
| MFInt32 array |
image data |
C.6.5.4 Methods
The method of the SFImage object is described in Table C-5.
Table C-5: SFImage method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 UTF-8 encoded value of
x, y, comp and array. |
C.6.6.1 Description
The SFNode object corresponds to a VRML SFNode field.
C.6.6.2 Instance creation method
sfNodeObjectName = new SFNode(String vrmlstring)
where
vrmlstring is an ISO 646 string containing the definition
of a VRML node
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 Methods
The method of the SFNode object is described in Table C-6.
Table C-6: SFNode method
| Method |
Description |
| String toString( ) |
Returns the VRML utf8 string that, if parsed as the value of an
SFNode field, would produce this node. If the browser is unable
to reproduce this node, the name of the node followed by the open
brace and close brace shall be returned. Additional information
may be included as one or more VRML comment strings. |
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 methods
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
| Property |
Description |
| numeric x |
first value of the axis vector |
| numeric y |
second value of the axis vector |
| numeric z |
third value of the axis vector |
| numeric angle |
the angle of the rotation (in radians) |
C.6.7.4 Methods
The methods of the SFRotation object are described in Table C-8.
Table C-8: SFRotation methods
| Method |
Description |
| SFVec3f getAxis( ) |
Returns the axis of rotation. |
| SFRotation inverse( ) |
Returns the inverse of this object's rotation. |
| SFRotation multiply(SFRotation rot) |
Returns the object multiplied by the passed value. |
| SFVec3f multVec(SFVec3f vec) |
Returns the value of vec multiplied by the matrix corresponding
to this object's rotation. |
| void setAxis(SFVec3f vec) |
Sets the axis of rotation to the value passed in vec. |
| SFRotation slerp(SFRotation dest, numeric
t) |
Returns the value of the spherical linear interpolation between
this object's rotation and dest at value 0 <= t
<= 1. For t = 0, the value is this object's rotation.
For t = 1, the value is dest. |
| String toString( ) |
Returns a String containing the VRML 97 utf8 encoded value of
x, y, z, and angle. |
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 method
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
| Property |
Description |
| numeric x |
First value of the vector. |
| numeric y |
Second value of the vector. |
C.6.8.4 Methods
The methods of the SFVec2f object are described in Table C-10.
Table C-10: SFVec2f methods
| Method |
Description |
| SFVec2f add(SFVec2f vec) |
Returns the value of the passed value added, component-wise, to
the object. |
| SFVec2f divide(numeric n) |
Returns the value of the object divided by the passed value. |
| numeric dot(SFVec2f vec) |
Returns the dot product of this vector and the passed value. |
| numeric length( ) |
Returns the geometric length of this vector. |
| SFVec2f multiply(numeric n) |
Returns the value of the object multiplied by the passed value. |
| SFVec2f normalize( ) |
Returns the object converted to unit length . |
| SFVec2f subtract(SFVec2f vec) |
Returns the value of the passed value subtracted, component-wise,
from the object. |
| String toString( ) |
Returns a String containing the VRML 97 utf8 encoded value of
x and y. |
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 method
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
| Property |
Description |
| numeric x |
First value of the vector. |
| numeric y |
Second value of the vector. |
| numeric z |
Third value of the vector. |
C.6.9.4 Methods
The methods of the SFVec3f object are described in Table C-12.
Table C-12: SFVec3f methods
| Method |
Description |
| SFVec3f add(SFVec3f vec) |
Returns the value of the passed value added, component-wise, to
the object. |
| SFVec3f cross(SFVec3f vec) |
Returns the cross product of the object and the passed value. |
| SFVec3f divide(numeric n) |
Returns the value of the object divided by the passed value. |
| numeric dot(SFVec3f vec) |
Returns the dot product of this vector and the passed value. |
| numeric length( ) |
Returns the geometric length of this vector. |
| SFVec3f multiply(numeric n) |
Returns the value of the object multiplied by the passed value. |
| SFVec3f negate( ) |
Returns the value of the component-wise negation of the object. |
| SFVec3f normalize( ) |
Returns the object converted to unit length . |
| SFVec3f subtract(SFVec3f vec) |
Returns the value of the passed value subtracted, component-wise,
from the object. |
| String toString( ) |
Returns a String containing the VRML 97 utf8 encoded value of
x, y, and z. |
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 method
mfColorObjectName = new MFColor(SFColor c1, SFColor
c2, ...)
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.10.4 Method
The method of the MFColor object is described in Table C-14.
Table C-14: MFColor methods
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFColor array. |
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 method
mfFloatObjectName = new MFFloat(numeric n1, numeric
n2, ...)
where
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.11.4 Method
The method of the MFFloat object is described in Table C-16.
Table C-16: MFFloat method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFFloat array. |
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 method
mfInt32ObjectName = new MFInt32(numeric n1, numeric
n2, ...)
where
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.12.4 Method
The method of the MFInt32 object is described in Table C-18.
Table C-18: MFInt32 method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFInt32 array. |
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 method
mfNodeObjectName = new MFNode(SFNode n1, SFNode n2,
...)
where
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.13.4 Method
The method of the MFNode object is described in Table C-20.
Table C-20: MFNode method
| Method |
Description |
| String toString( ) |
Returns the VRML utf8 string that, if parsed as the value of a
MFNode field, would produce this array of nodes. If the browser
is unable to reproduce this node, the name of the node followed
by the open brace and close brace shall be returned. Additional
information may be included as one or more VRML comment strings |
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 method
mfRotationObjectName = new MFRotation(SFRotation r1, SFRotation
r2, ...)
where
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array.
|
C.6.14.4 Method
The method of the MFRotation object is described in Table C-22.
Table C-22: MFRotation method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFRotation array. |
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 method
mfStringObjectName = new MFString(String s1, String
s2, ...)
where
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.15.4 Method
The method of the MFString object is described in Table C-24.
Table C-24: MFString method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFString array. |
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 method
mfTimeObjectName = new MFTime(numeric n1, numeric
n2, ...)
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.16.4 Method
The method of the MFTime object is described in Table C-26.
Table C-26: MFTime method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFTime array. |
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 method
mfVec2fObjectName = new MFVec2f(SFVec2f v1, SFVec2f
v2, ...)
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.17.4 Method
The method of the MFVec2f object is described in Table C-28.
Table C-28: MFVec2f method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFVec2f array. |
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 method
mfVec3fObjectName = new MFVec3f(SFVec3f v1, SFVec3f
v2,...)
where
The creation method 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
| Property |
Description |
| numeric length |
property for getting/setting the number of elements in the array. |
C.6.18.4 Method
The method of the MFVec3f object is described in Table C-30.
Table C-30: MFVec3f method
| Method |
Description |
| String toString( ) |
Returns a String containing the VRML 97 utf 8 encoded value of
the MFVec3f array. |
C.6.19.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 are in the fourth row. For example,
vrmlMatrixObjectName[3][0] is the X offset.
C.6.19.2 Instance creation methods
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 Methods
The methods of the VRMLMatrix object are listed in Table C-31.
Table C-31: VRMLMatrix methods
| Method |
Description |
void setTransform(SFVec3f translation,
SFRotation
rotation,
SFVec3f
scale,
SFRotation
scaleOrientation,
SFVec3f
center) |
Sets the VrmlMatrix to the passed values. 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. |
void getTransform(SFVec3f translation,
SFRotation
rotation,
SFVec3f
scale) |
Decomposes the VrmlMatrix and returns the components in the passed
translation, rotation, and scale 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. |
| VrmlMatrix inverse( ) |
Returns a VrmlMatrix whose value is the inverse of this object.
|
| VrmlMatrix transpose( ) |
Returns a VrmlMatrix whose value is the transpose of this object.
|
| VrmlMatrix multLeft(VrmlMatrix matrix) |
Returns a VrmlMatrix whose value is the object multiplied by the
passed matrix on the left. |
| VrmlMatrix multRight(VrmlMatrix matrix) |
Returns a VrmlMatrix whose value is the object multiplied by the
passed matrix on the right. |
| SfVec3f multVecMatrix(SFVec3f vec) |
Returns an SFVec3f whose value is the object multiplied by the
passed row vector. |
| SFVec3f multMatrixVec(SFVec3f vec) |
Returns an SFVec3f whose value is the object multiplied by the
passed column vector. |
| String toString( ) |
Returns a String containing the values of the VrmlMatrix. |
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 "2.12.2 Script
Execution".
The following example illustrate use of the 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;
}"
}
The following example illustrates use of the 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 of 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);
}"
}
|
