VRML Scripting Language Plugin Proposal

Don't confuse these VRML Language plugins with NETSCAPE plugins!!

The functionality is very similar, but these plugins are plugged directly into the VRML browser, regardless of if the browser itself is running as a NETSCAPE plugin or not!!

  Script { 
    exposedField MFString url           [] 
    field        SFBool   directOutputs FALSE
    field        SFBool   mustEvaluate  FALSE
    # And any number of:
    eventIn      eventTypeName eventName
    field        fieldTypeName fieldName initialValue
    eventOut     eventTypeName eventName
  }

For our purposes we concentrate on the events and the url.

• If the protocol supports MIME-types (such as http:// transfers), the mime-type is used.

• If the protocol doesn't support MIME-types, but is a file-access protocl (such as file:// at local harddisk access, or other MIME-less file transports such as FTP), the extension is used.

• If the protocol isn't a file transport protocol, the protocol name itself is used (to support inline protocols such as SGI's proposed vrmlscript:// protocol or the data:// protocol.

• If a VRMLPLUGINS environment variable or .INI-file setting exists, the plugins are loaded from the directory/ies specified in that variable.
• If the variable is missing or the plugin not found, search the PLUGIN subdirectory under the VRML browser itself.

• Under Windows, these are 32-bit DLL files with a VRP extension.
• Under UNIX these are shared libraries of some kind (need more info!)
• Under MacOS these are ... <something mac'ish here?>

Each .VRP file is loaded (if not already loaded and known, of course!), and the first function in the file is called:

    int VPCanHandle( char *languageId ); // Ordinal #0

• Under Windows this is accomplised by calling the function with a fixed ordinal.
• Under other platforms ??? how ??? need more info.

The function is passed one parameter, the languageId as found in the earlier step:

• If it was a MIME type, the type is passed as a string, e.g. "language/javabc"

• If it was an extension, the extension including period is passed, e.g. ".lsp"

• If it was a protocol, the protocol including colon is passed, e.g. "javascript:"

(By including the period or the colon, the module can determine what is being passed).

The function being called simply returns 0 (can't handle this language) or 1 (can handle it). If it passes 1, the search ends.

If no appropriate plugin is found, an error message is displayed, and the user is if possible routed to http://www.vrml.org/plugins to download the appropriate plugin.

    void *VPInitInstance(char *URL, struct browserCallback *cbks);  // Ordinal #1

The second parameter is a pointer to a struct browserCallback which is a struct containing function pointers for calling back into the VRML browser from the plugin. This struct is described below.

The VPInitInstance function must also set up one "context" for this process to run in (remember, the same language plug-in can be called from many Script nodes in one file. Each of these instances need to keep their data separate.

The handle or pointer to this "local data" is then returned by VPinitInstance. (If there is an error, VPInitInstance returns NULL, and the browser must take appropriate action).

This pointer is kept by the VRML browser, and passed in all subsequent calls from the VRML Browser to the language plug-in.

    struct browserCallback {
        int   (*getStringNumeral)(char *string);             // Get a string numeral
        int   (*sendEvent)(int numeral, void *arguments);    // Send an event
        void *(*callFunction)(int numeral, void *arguments); // Call a browser function
        .
        . ?? more ??
        .
    };

• Available functions are:

  int getStringNumeral (char *string)

  This function enumerates all string expressions that would otherwize need to be passed over the interface into an integer representation. This can be used in many ways, depending on what kind of language is being implemented:

  • A "load time" (semi) compiling language can enumerate strings directly into it's bytecode representation.
  • A compiled language (C, Java) can explicitly use this function in it's code.
  • An interpreted language can keep a hash table of strings mapped to numerals.

  Numerals are used for node names, field names, function names for browser callbacks, e.t.c.

  Numerals are not used for actual string processing operations.

  int sendEvent (int numeral, void *data)

  This function sends an event (specified in the eventOut of the Script node). The name of the event is given as a numeral, "data" is a pointer to the data in the appropriate format (as declared in the Script node).

  void *callFunction (int numeral, void *data)

  This function calls a browser function. See moving worlds proposal about browser functions

    void *VPFunctionHandle(void *instance, char *name) // Ordinal #2

A handle can be anything (represented here as a void pointer), simply somthing that uniquely identifies a given event/function name, and that your plugin can understand, and know how to call the correct piece of the script.

You may want to have direct function pointers, you may want to have an index into an array of functions, or you might simply want to remember the string (strdup() it into the handle!).

VPFunctionHandle will be called once for each name the browser needs to resolve in that instance (Script node). The actual calls will be used using that handle, not the string.

If the event doesn't exist in the script, NULL is returned, and the Browser must report an error.

    void VPEventIn(void *instance, void *functionHandle, int dataType, void *data) // Ordinal #3

The event handler is called with the instance identifier, the functionHandle as established above (which exact meaning is defined by your VRML plugin), and the data member points to the event data, in the type declared in the Script node is passed in 'type'.