API

The X3DOM API is currently split into two parts:

• Runtime
• Docs

The runtime api provides progrmmatic live access to the system. The Documnetation API allows to dynamically generate documentation artifacts embedded dreived from the souce code (e.g. a list of loaded nodes).

Runtime

The X3DOM runtime API provides proxy object to programmatically read and modify runtime parameters. The runtime proxy is attached to each X3D element and can be used in the following manner:

var e = document.getElementById('the_x3delement');
e.runtime.showAll();
e.runtime.resetView();
...

Some methods, like the x3dom.ready() function need to be called before the proxy object can be initialized. You can still override these functions globally. In order to provide you with the means to scope your actions to a specific X3D element, the methods receive the X3D element they are working on as first parameter:

x3dom.ready = function(element) {
    if (element == target_element) {
        // do something
    }
};

ready()

This method is called once the system initialized and is ready to render the first time. It is therefore possible to execute custom action by overriding this method in your code:

x3dom.runtime.ready = function() {
    alert("About to render something the first time");
};

It is important to create this override before the document onLoad event has fired. Therefore putting it directly under the inclusion of x3dom.js is the preferred way to ensure overloading of this function.

enterFrame()

This method is called just before the next frame is rendered. It is therefore possible to execute custom actions by overriding this method in your code:

var element = document.getElementById('my_element');
element.runtime.enterFrame = function() {
    alert('hello custom enter frame');
};

During initialization, just after ready() executed and before the very first frame is rendered, only the global override of this method works.

If you need to execute code before the first frame renders, it is therefore best to use the ready() function instead.

getActiveBindable(typeName)

Arguments:

• typeName (string) – A valid Bindable node (e.g. Viewpoint, Background,

Returns:

Active dom element

This method returns the currently active bindable DOM element of the given type.

For example:

var element, bindable;
element = doucment.getElementById('the_x3delement');
bindable = element.runtime.getActiveBindable('background');
bindable.setAttribute('set_bind', 'false');

nextView()

Navigates to the next viewpoint.

prevView()

Navigates to the previous viewpoint.

resetView()

Navigates to the initial viewpoint.

uprightView()

Navigates to upright view.

showAll()

Zooms so that all objects are visible.

Arguments:

• axis (string) – the axis as string: posX, negX, posY, negY, posZ, negZ

debug(show)

Arguments:

• show (boolean) – true/false to show or hide the debug window

Returns:

The current visibility status of the debug window (true/false)

Displays or hides the debug window. If the paramter is omitted, the current visibility satus is returned.

navigationType()

Returns:A string representing the active navigation type.

A readout of the currently active navigation type.

examine()

Switches to examine mode.

lookAt()

Switches to lookAt mode.

lookAround()

Switches to lookAround mode.

walk()

Switches to walk mode.

game()

Switches to game mode.

resetExamin()

Resets all variables required by examin mode to init state

pickMode(options)

Arguments:

• options (object) – An object of properties i.e. options = {‘internals’: true}

Returns:

The current intersect type value suitable to use with changePickMode

Get the current pickmode intersect type. If the option ‘internals’:true is provided, the interal representation is returned.

changePickMode(type, options)

Arguments:

• type (string) – The new intersect type: idbuf, color, textcoord, or box.

Returns:

True if the type hase been changed, false otherwise

Alter the value of intersct type. Can be one of: idbuf, color, textcoord, box. Other values are ignored.

speed(newSpeed)

Arguments:

• newSpeed (float) – The new speed value (optional)

Returns:

The current speed value

Get the current speed value. If parameter is given the new speed value is set accordingly.

statistics(mode)

Arguments:

• mode (boolean) – true/false to enable or disable the stats info

Returns:

The current visibility of the stats info (true/false)

Get or set the visibility of the statistics information. If parameter is omitted, this method returns the visibility status as boolean.

isA(domNode, nodeType)

Arguments:

• domNode (object) – the node to test for
• nodeType (string) – node name to test domNode against

Returns:

True or false

Test a DOM node object against a node type string. This method can be used to determine the “type” of a DOM node.

processIndicator(mode)

Arguments:

• mode (boolean) – true to show indicator, false to hide

Returns:

The current visibility of the process indicator info (true = visible, false = invisible)

Enable or disable the process indicator. If parameter is omitted, this method only returns the the visibility status of the statistics info overlay.

backendName()

Returns:The current render backend name as string

Returns the currently used render backend name.

properties()

Returns:Properties object

Returns the properties object of the X3D element. This holds all configuration parameters of the X3D element.

Docs

The documentation API is a set of static functions (object literal) which allows to obtain documetantion related information form the library:

var info;
var info_pane;
info = x3dom.docs.getNodeTreeInfo();
info_pane = getElementById('infopane');
info_pane.innerHTML = info;

The documentation module is optional and only provided with the x3dom-full package.

getNodeTreeInfo()

Returns:A div element containin the nodes and link to specification

Return a div filled with nodes implemented and link to documentation. This can be used to build interactive documentation.

Note: Unstable API method. Name and retrun value might change

getComponentInfo()

Returns:A div element containin the nodes and link to specification, grouped by components and sorted alphabetically

Return a div filled with nodes implemented and link to documentation. This particular method returns the the nodes grouped by components and sorted alphabetically.

This can be used to build interactive documentation.

Note: Unstable API method. Name and retrun value might change