This appendix describes the C datatypes and functions that allow scripts to interact with associated scenes.

Language

VRML browsers aren't required to support C in Script nodes. In fact, supporting C is problematic:

• Supporting C source code would require compiling and linking.
• Supporting C object code would be platform-dependent.
• Supporting any language without security features opens the door to allowing scripts to execute commands like "system("rm -r /*");".

Therefore, the bindings given in this document to provide interaction between VRML Script nodes and the rest of a VRML scene are provided for reference purposes only.

Events In and Out (Prototyped Data Structures and Functions)

/*
 * vrml.h - vrml support procedures for C
 */

typedef void * Field;
typedef char * String;
typedef int boolean;

typedef struct {
  unsigned char *value;
  int dims[3];
} SFImageType;

/*
 * Read-only (constant) type definitions, one for each field type:
 */

typedef        const boolean       *ConstSFBool;
typedef        const float         *ConstSFColor;
typedef        const float         *ConstMFColor;
typedef        const float         *ConstSFFloat;
typedef        const float         *ConstMFFloat;
typedef        const SFImageType   *ConstSFImage;
typedef        const int           *ConstSFInt32;
typedef        const int           *ConstMFInt32;
typedef        const Node          *ConstSFNode;
typedef        const Node          *ConstMFNode;
typedef        const float         *ConstSFRotation;
typedef        const float         *ConstMFRotation;
typedef        const String        ConstSFString;
typedef        const String        *ConstMFString;
typedef        const float         *ConstSFVec2f;
typedef        const float         *ConstMFVec2f;
typedef        const float         *ConstSFVec3f;
typedef        const float         *ConstMFVec3f;
typedef        const double        *ConstSFTime;


/*
 * And now the writeable versions of the above types:
 */

typedef        boolean     *SFBool;
typedef        float       *SFColor;
typedef        float       *MFColor;
typedef        float       *SFFloat;
typedef        float       *MFFloat;
typedef        SFImageType *SFImage;
typedef        int         *SFInt32;
typedef        int         *MFInt32;
typedef        Node        *SFNode;
typedef        Node        *MFNode;
typedef        float       *SFRotation;
typedef        float       *MFRotation;
typedef        String      SFString;
typedef        String      *MFString;
typedef        float       *SFVec2f;
typedef        float       *MFVec2f;
typedef        float       *SFVec3f;
typedef        float       *MFVec3f;
typedef        double      *SFTime;

/*
 * Event-related types and functions
 */

typedef        void *EventIn;

String getEventInName(EventIn eventIn);
int    getEventInIndex(EventIn eventIn);
SFTime getEventInTimeStamp(EventIn eventIn);
void   *getEventInValue(EventIn eventIn);

typedef        void *Node;

void *getNodeValue(Node *node, String fieldName);
void  postNodeEventIn(Node *node, String eventName, Field eventValue);

/*
 * C script
 */

typedef void *Script;

Field getScriptEventOut(Script script, String eventName);
Field getScriptField(Script script, String fieldName);

void exception(String error);

Browser Interface

This section lists the functions that allow scripts to get and set browser information. For descriptions of the functions, see the "Browser Interface" section of the "Scripting" section of the spec. Since these functions aren't defined as part of a "Browser" class in C, most of their names include the word "Browser" for clarity.

String  getBrowserName();
float   getBrowserVersion();

String  getBrowserNavigationType();
void    setBrowserNavigationType(String type);

float   getBrowserNavigationSpeed();
void    setBrowserNavigationSpeed(float speed);

float   getBrowserCurrentSpeed();

float   getBrowserNavigationScale();
void    setBrowserNavigationScale(float scale);

boolean getBrowserHeadlight();
void    setBrowserHeadlight(boolean onOff);

String  getBrowserWorldURL();
void    loadBrowserWorld(String url);

float   getBrowserCurrentFrameRate();

Node    createVrmlFromURL(String url);
Node    createVrmlFromString(String vrmlSyntax);

void    addRoute(Node fromNode, String fromEventOut,
                 Node toNode, String toEventIn);
void    deleteRoute(Node fromNode, String fromEventOut,
                    Node toNode, String toEventIn);

void    bindBrowserBackground(Node background);
void    unbindBrowserBackground();
boolean isBrowserBackgroundBound(Node background);

void    bindBrowserNavigationInfo(Node navigationInfo);
void    unbindBrowserNavigationInfo();
boolean isBrowserNavigationInfoBound(Node navigationInfo);

void    bindBrowserViewpoint(Node viewpoint);
void    unbindBrowserViewpoint();
boolean isBrowserViewpointBound(Node viewpoint);

System and Networking Libraries

[[anything special here, or do we just use standard C system and networking libraries?]]

Example

[[need to put in the actual Script node here... And I think the program needs to be completely rewritten to use new entrypoint model, with function named for each eventIn plus an eventsProcessed function. Is FooScriptType even necessary under new model?]]

/*
 * FooScript.c
 */

#include "vrml.h"

typedef struct {
    Script  parent;
    SFInt32 fooField;
    SFFloat barOutEvent;
} FooScriptType;

typedef FooScriptType *FooScript;

void constructFooScript(FooScript foo, Script p) {

    foo->parent = p;

    /* Initialize field(s) */
    foo->fooField = (SFInt32) getScriptField(foo->parent, "foo");

    /* Initialize eventOut field(s) */
    foo->barOutEvent = (SFFloat) getScriptEventOut(foo->parent, "bar");
}

void processFooScriptEvents(FooScript foo, EventIn *list, int length) {
    int i;
    for (i = 0; i < length; i++) {
       EventIn event = list[i];
       switch (getEventInIndex(event)) {
         case 0:
         case 1:
           *foo->barOutEvent = *(SFFloat) foo->fooField;
           break;
         default:
           exception("Unknown eventIn");
       }
    }
}