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
        }
    };
            

Methods

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.

Usage:

        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:

Usage:

        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:

Usage:

        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.

exitFrame () ⤴

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

Usage:

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

triggerRedraw () ⤴

This method signals that a redraw of the scene is needed.

Usage:

        var element = document.getElementById('my_element');
        element.runtime.triggerRedraw();
                    

getActiveBindable (typeName) → Active dom element ⤴

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

Parameters:

Name	Type	Description
typeName	String	A valid Bindable node (e.g. Viewpoint, Background)

Returns:

Active dom element

Usage:

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

Viewpoints ⤴

Name	Description
nextView()	Navigates to the next viewpoint.
prevView()	Navigates to the previous viewpoint.
viewpoint()	Returns the current viewpoint.

viewMatrix () → Matrix object ⤴

Returns the current view matrix object.

projectionMatrix () → Matrix object ⤴

Returns the current projection matrix object.

getWorldToCameraCoordinatesMatrix () → Matrix object ⤴

Returns the current world to camera coordinates matrix.

getCameraToWorldCoordinatesMatrix () → Matrix object ⤴

Returns the current camera to world coordinates matrix.

getViewingRay (x, y) → Line object ⤴

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

Parameters:

Name	Type	Description
x	float	Layer x position
y	float	Layer y position

Returns:

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

getWidth () → Integer ⤴

Returns the width of the canvas element.

Returns:

Width in pixels

getHeight () → Integer ⤴

Returns the height of the canvas element.

Returns:

Height in pixels

mousePosition (event) → [x,y] ⤴

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.

Parameters:

Name	Type	Description
event	Event	The event
y	float	The event

Returns:

[x,y] position

calcCanvasPos (wx, wy, xz) → Array ⤴

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).

Parameters:

Name	Type	Description
wx		World coordinate X axis
wy		World coordinate Y axis
wz		World coordinate Z axis

Returns:

Array with 2D corrdinates (x,y)

calcClientPos (wx, wy, xz) → Array ⤴

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.

Parameters:

Name	Type	Description
wx		World coordinate X axis
wy		World coordinate Y axis
wz		World coordinate Z axis

Returns:

Array with 2D corrdinates (x,y)

getScreenshot () → DATA URI ⤴

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; ...

Returns:

URL to image

lightMatrix () → Matrix object ⤴

Returns the current light matrix.

Returns:

The current light matrix

resetView () ⤴

Navigates to the initial viewpoint.

lightView () → Boolean ⤴

Navigates to the first light, if any.

Returns:

True if navigation was possible, false otherwise

uprightView () ⤴

Navigates to upright view.

showAll (axis) ⤴

Zooms so that all objects are visible.

Parameters:

Name	Type	Description
axis		the axis as string, one of: posX, negX, posY, negY, posZ, negZ

showObject (obj, axis) ⤴

Zooms so that a given object is fully visible.

Parameters:

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

getCenter (domNode) → SF3Vec3f ⤴

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

Parameters:

Name	Type	Description
domNode		the node for which its center shall be returned

Returns:

Node center or null if domNode is not a Shape or Geometry

getCurrentTransform (domNode) → Transformation Matrix ⤴

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

Parameters:

Name	Type	Description
domNode		the node for which its transformation shall be returned

Returns:

Transformation matrix (or null no valid node is given).

debug (show) → Boolean ⤴

Displays or hides the debug window. If the parameter is omitted, the current visibility status is returned.

Parameters:

Name	Type	Description
show	Boolean	true/false to show or hide the debug window

Returns:

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

navigationType () → String ⤴

A readout of the currently active navigation type.

Returns:

A string representing the active navigation type.

Navigation Modes ⤴

Change current navigation mode.

Name	Description
examine()	Switches to examine mode.
lookAt()	Switches to lookAt 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) → 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

Parameters:

Name	Type	Description
x1		x1 coordinate of rectangle
y1		y1 coordinate of rectangle
x2		x2 coordinate of rectangle
y2		y2 coordinate of rectangle

pickMode (options) → Type Value ⤴

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

Parameters:

Name	Type	Description
options	object	An object of properties i.e. options = {‘internals’: true}

Returns:

The current intersect type value suitable to use with changePickMode.

changePickMode (type, options) → Boolean ⤴

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

Parameters:

Name	Type	Description
type	String	The new intersect type: idbuf, color, textcoord, or box

Returns:

True if the type hase been changed, false otherwise.

speed (newSpeed) → float ⤴

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

Parameters:

Name	Type	Description
newSpeed	float	The new speed value (optional)

Returns:

The current speed value.

statistics (mode) → Boolean ⤴

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

Parameters:

Name	Type	Description
mode	Boolean	true/false to enable or disable the stats info

Returns:

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

isA (domNode, nodeType) → Boolean ⤴

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

Parameters:

Name	Type	Description
domNode	object	the node to test for
nodeType	String	node name to test domNode against

Returns:

True or false

processIndicator (mode) → Boolean ⤴

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

Parameters:

Name	Type	Description
mode	Boolean	true to show indicator, false to hide

Returns:

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

backendName () → String ⤴

Returns the currently used render backend name.

Returns:

The current render backend name as string

properties () → Properties object ⤴

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

Returns:

Properties object

getPixelScale () → SF3Vec3f ⤴

Returns the virtual scale of one pixel for the current orthographic viewpoint. The returned vector contains scale values for the x and y direction. The z value is always null.

Returns:

x3dom.fields.SFVec3f or null if non orthographic view