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 derived from the source 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
    }
};

noBackendFound()

This callback is executed once the system initialized and is not ready to render the first time because there is no backend found. By default this method noop. You can however override it with your own implementation.

x3dom.runtime.noBackendFound = function() {

alert(“No backend, what a bummer.”);

}

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.

Please note that this does not account for a installed, but disabled Flash plugin.

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.

viewpoint()

Returns the current viewpoint.

viewMatrix()

Returns:Matrix object

Returns the current view matrix object.

projectionMatrix()

Returns:Matrix object

Returns the current projection matrix object.

getWorldToCameraCoordinatesMatrix()

Returns:Matrix object

Returns the current world to camera coordinates matrix.

getCameraToWorldCoordinatesMatrix()

Returns:Matrix object

Returns the current camera to world coordinates matrix.

getViewingRay(x, y)

Arguments:

• x – Layer x position
• y – Layer y position

Returns:

Line object, from camera origin through (x, y)

Returns the viewing ray for a given (x, y) position on the canvas.

getWidth()

Returns:Width in pixels

Returns the width of the canvas element.

getHeight()

Returns:Height in pixels

Returns the height of the canvas element.

mousePosition(event)

Arguments:

• event – The event

Returns:

[x,y] position

Returns the 2d canvas layer position [x,y] for a given mouse event, i.e., the mouse cursor’s x and y positions relative to the canvas (x3d) element.

calcCanvasPos(wx, wy, xz)

Arguments:

• wx – World coordiante X axis
• wy – World coordiante Y axis
• wz – World coordiante Z axis

Returns:

Array with 2D corrdinates (x,y)

Takes world coordinates (x,y,z) of the scene and calculates the relating 2D X/Y coordinates respective to the canvas the scene is rendered on.

This allows you to relate 3D world coordinates to a specific position on the 2D canvas. This can be usable to position a HTML element over the canvaas (like a hint window for exmaple).

calcPagePos(wx, wy, xz)

Arguments:

• wx – World coordiante X axis
• wy – World coordiante Y axis
• wz – World coordiante Z axis

Returns:

Array with 2D corrdinates (x,y)

Takes world coordinates (x,y,z) of the scene and calculates the relating 2D X/Y coordinates relative to the document the scene is rendered in.

calcClientPos(wx, wy, xz)

Arguments:

• wx – World coordiante X axis
• wy – World coordiante Y axis
• wz – World coordiante Z axis

Returns:

Array with 2D corrdinates (x,y)

Takes world coordinates (x,y,z) of the scene and calculates the relating 2D X/Y coordinates relative to the window the scene is rendered in.

getScreenshot()

Returns:URL to image

Returns a Base64 encoded data URI containing png image consisting of the current rendering. The resulting URL will look similar to this:

data:image/png;base64,iVBORw0KGgo...

The browser will interpret this as a PNG image and display it. A list of browsers which support data URI can be found here.

The following example illustrates the usage:

var url = ...runtime.getScreenshot();
var img = document.createElement("img");
img.src = url;
...

lightMatrix()

Returns:The current light matrix

Returns the current light matrix.

resetView()

Navigates to the initial viewpoint.

lightView()

Returns:True if navigation was possible, false otherwise.

Navigates to the first light, if any.

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

showObject(obj, axis)

Arguments:

• obj – the scene-graph element on which to focus
• axis – the axis as string, one of: posX, negX, posY, negY, posZ, negZ

Zooms so that a given object is fully visible.

getCenter(domNode)

Arguments:

• domNode – the node for which its center shall be returned

Returns:

Node center or ‘null’ if donNode is not a Shape or Geometry

Returns the center of a X3DShapeNode or X3DGeometryNode as SF3Vec3f object.

getCurrentTransform(domNode)

Arguments:

• domNode – the node for which its transformation shall be returned

Returns:

Transformation matrix (or null no valid node is given)

Returns the current to world transformation of a given node. If no valid node is given null is returned.

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 parameter is omitted, the current visibility status 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.

helicopter()

Switches to helicopter mode.

resetExamin()

Resets all variables required by examin mode to init state

togglePoints()

Toggles points attribute

pickRect(x1, y1, x2, y2)

Arguments:

• x1 – x1 coordinate of rectangle
• y1 – y1 coordinate of rectangle
• x2 – x2 coordinate of rectangle
• z2 – y2 coordinate of rectangle

Returns:

Array of shape elements

Returns an array of all shape elements that are within the picked rectangle defined by (x1, y1) and (x2, y2) in canvas coordinates

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