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:
NameTypeDescription
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

NameDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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.

NameDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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:
NameTypeDescription
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