Lighthouse3d.com

[an error occurred while processing this directive] Send me bugs and suggestions, please
VRML Interactive Tutorial
Full list

Script Tutorial

Introduction and Sintax
Defining Fields and Events
Accessing Fields and Events
When are scripts executed
Script Example: Highlight
Browser Script Interface
Appendix: Data types

Script Node Tutorial


This article is translated to Serbo-Croatian language by Anja Skrba from Webhostinggeeks.com.

Introduction and Syntax

You've already seen how to build basic animations and simple behaviours with the events predefined for several nodes in VRML. Although these nodes can perform wonders in your VRML world they are limited in the type of actions you can perform.

The Scritp node provides the missing flexibility to expand almost limitless your behaviour requirements. The Script node allows you to define behaviours using programming languages such as JAVA, JavaScript, or the recently proposed VRMLScript by Silicon Graphics.

A Script can specify an action each time it receives an event (you use ROUTE to send an event to a Script as with any other node). Furthermore you can define initialization and shutdown procedures. In each action a script can generate multiple events.

As opposed to other nodes, in the Script node you can define the events the node receives and sends. A Script node can also have fields. Fields work as persistent local variables to the script and can be used to define an internal state.

A scritp can receive any number of events, the values where these events are stored are eventIn type variables. The name of the variables specify the name of the events the Script can receive. These variables are read-only, i.e. you can't set a value to one of these variables, you can only read its current value. There is also no limit to the number of events a Script can generate. The values associated with these events are stored in eventOut type variables. These variables, as well as fields, are persistent.

Note: you can't define an exposedField in a Script. In order to define the equivalent to an exposedField you'll have to define a field, an eventIn and an eventOut. For instance the following declaration is equivalent to the definition of an exposed field:
Example:
field myField
eventIn set_myField
eventOut myField_changed


Syntax:
Script {
url []
directOutput FALSE
mustEvaluate FALSE
#and any number of :
eventIn type eventName
eventOut type eventName
field type fieldName initialValue
}

The type can be any of the standard VRML data types.

The url specifies the program script to be executed. The languages currently supported are JAVA, JavaScript, VRMLScript. Note that many if not all browsers do not support these three languages. The script can be inlined or in a different file.

In this tutorial JavaScript was chosen as the language for the examples. This language is implemented by several browsers, for instance Cosmo Player, the Silicon Graphics plug in for VRML.

There are two ways in which you can change your world using a Script: using an eventOut variable and then routing the event to another node, or by accessing other node's fields directly. The former method requires routing the event sent by the Script to other nodes, whereas the later requires only an attribution. The directOutput field of a Script specifies if the later method is allowed, i.e. if directOutput is FALSE you can only affect the rest of your world by sending events from the Script and then routing them to the desired nodes.

Because drawing VRML worlds is a very intensive task it can be hard for the browser to draw and process events at the same time. When a large number of Scripts are present in your world it is preferable to give priority to drawing instead of processing events. In the Script node there is a field which controls when the events are processed. You can either specify that events should be processed as soon as they arrive, or only when the browser is capable of doing so without decreasing the drawing performance. The field mustEvaluate is used to set the execution model, setting it to FALSE allows the browser to pick a convenient time to process the events, whereas setting it to TRUE tells the browser to process the events as soon as they arrive. This latter setting, TRUE, should only be used in critical situations.

Defining fields and events, setting initial values

Only fields can have initial values according to the specification. All the other variable types, eventIn and eventOut, can't define an initial value.

To define a field you must specify a data type for it, see the data type list for the data types available in VRML.

The following are valid field definitions:
Example:
field SFRotation myRot 0 0 1 0
field MFVec3f myPos [0 0 0, 1 1 1]
field MFString myURLs ["clock2.wrl","land.wrl"]

For eventIn and eventOut fields you do not define an initial value. The following are valid eventIn and eventOut definitions:
Example:
eventIn SFRotation rot_changed
eventOut SFBool set_start

Accesing and setting fields and events defined in the script

  • fields: can be set and read.
  • eventIn: can be read
  • eventOut: can be set and read
    • In all cases the values are persistent, i.e. their values are kept between function calls.

    Reading and setting values to a field or event is done in the same way as with standard variables in most programming languages.

    Suppose a script as a SFRotation field named myField. To set the value of myField to a rotation of 1.57 ( in radians) on the Z axis you can do the following:
    Example:
    myField[0] = 0; // x value
    myField[1] = 0; // y value
    myField[2] = 1; // z value
    myField[3] = 1.57; // angle value

    If myField was defined as an eventOut then an event would be generated by the script as soon as the function is done. The event could then be ROUTED to any node which has SFRotation exposedFields or eventIns. For example: ROUTE myScript.myField TO myTransform.set_rotation where myScript is the name you DEF'ed your script, and myTransform is the name you DEF'ed a Transform node.

    When are scripts executed

    Functions define inside a Script can serve three purposes:
  • initialization procedures
  • processing events
  • shutdown procedures
    • The function initialize will perform after the file in which it is contained is loaded and before any other events are generated, it is the first function to be executed in your script. This function can be used to initialize fields in your script or to send events before any other node does it. The initialize function has no parameters.

    The following example defines the template for the initialize function:
    Example:
    function initialize() {
      ...
    }

    The shutdown function has no parameters as well, the template is as follows:
    Example:
    function shutdown() {
    ...
    }

    For each eventIn in the Script node you must define a handler. The handler is a function, with two parameters, which has the same name as the eventIn. The two parameters are: the event's value and the timestamp. The function will be executed when the script receives the corresponding event.

    The template for eventIn handlers is
    Example:
    function myEventIn(value,time) {
    ...
    }

    Script Example

    Highlight
    Three ways to highlight a shape when the cursor is over it. It shows how to switch between shapes, changing the material's field of a shape, and how to access fields directly fromt the script.