official documentation

  1. x3dom.org
  2. documentation
  3. Scene Author API

Introduction

DOM Element Functions

Welcome to the X3DOM Scene Author API Documentation! Within this documentation package, you will find detailed information about all X3DOM Nodes and their Fields. Like in the X3D standard, X3DOM nodes are grouped into Components. There are several ways to find what you are looking for:

The Node Index allows you to directly browse nodes by their name, while the Component Index lists all Components and provides a list of nodes for each of them. The following sections on this overview page furthermore introduce the general DOM methods that are available on all X3DOM nodes to dynamically manipulate field values.

Scope

This API documentation is automatically generated during a nightly build process, using the latest available code from the X3DOM development branch. It is therefore intended for use with this branch of X3DOM.
Please note that the X3DOM API documentation project started during the development of version 1.6, therefore there is unfortunately no such documentation available for older versions of X3DOM. However, the X3DOM team will provide a proper snapshot of this documentation for each upcoming release.

Runtime functions and configuration

You want to write javascript code that interacts with the x3dom runtime? Head over to the runtime documentation to find a reference of all available functions and callbacks. On the configuration page you will find a list of possible options that are used to change the behavior of the runtime in a declarative way.

Manipulating Fields with DOM Element Functions

Within a typical X3DOM application, nodes are a regular part of the HTML DOM. You can access and dynamically manipulate the fields of all X3DOM nodes inside the DOM in three ways, and it depends on your particular needs and your application which one suits best.

Using getAttribute and setAttribute

Like regular HTML attributes, your can manipulate X3DOM values with the standard getAttribute and setAttribute methods. You may, for instance, have this HTML representation of a material node: 


    <material id='myMaterial' diffuseColor='1 0 0'></material>

Imagine you would want to change the diffuseColor field of this material node. This can be easily achieved with the getAttribute and setAttribute methods: 


    var oldMaterial = document.getElementById('myMaterial').getAttribute('diffuseColor');
    console.log('The old value was ' + oldMaterial);    
    var newMaterial = document.getElementById('myMaterial').setAttribute('diffuseColor', '0 1 0');
    console.log('The new value is ' + newMaterial);

Since HTML attributes are not case sensitive, X3DOM attributes behave in the same way. You may therefore write 'diffuseColor' as well as 'DiffuseColor' or 'diffusecolor', for example.

The standard DOM getAttribute and setAttribute methods are defined as follows:

getAttribute (fieldname) → String ⤴

Returns the value of the field with the given name. The value is returned as a string, just like it appears in the DOM.

Parameters:
NameTypeDescription
fieldname String the name of the field

Returns:
the current field value, as a string

setAttribute (fieldname, fieldvalue) ⤴

Sets the value of the field with the given name to the given value. The value is specified as a string, as it appears in the DOM.

Parameters:
NameTypeDescription
fieldname String the name of the field where the value should be set
fieldvalue String the new field value


Using getFieldValue and setFieldValue

If you are interested in manipulating the value of a field in a more sophisticated way than just giving it a fixed value in a string representation, for example because you want to change a single coordinate value or a single channel of a color, you might find the standard DOM methods a bit inconvenient. Therefore, X3DOM also offers methods to directly access the typed field values. This means that you will no longer need to operate on strings, but instead you can directly use objects with the types of the corresponding fields. For the above example with the diffuseColor attribute, this means that you can also directly get and set the field value as an SFColor object: 


    var myColor = document.getElementById('myMaterial').getFieldValue('diffuseColor');
    myColor.r = 1.0;    //the myColor object is of type 'SFColor', so we can directly set RGB values 
    document.getElementById('myMaterial').setFieldValue('diffuseColor', myColor);

The X3DOM getFieldValue and setFieldValue methods, which are available on all X3DOM nodes, are defined as follows:

getFieldValue (fieldname) → FIELDTYPE ⤴

Returns the value of the field with the given name. The value is returned as an object of the corresponding field type.

Parameters:
NameTypeDescription
fieldname String the name of the field

Returns:
the current field value, as a field object

setFieldValue (fieldname, fieldvalue) ⤴

Sets the value of the field with the given name to the given value. The value is specified as an object of the corresponding field type.

Parameters:
NameTypeDescription
fieldname String the name of the field where the value should be set
fieldvalue FIELDTYPE the new field value


Using requestFieldRef and releaseFieldRef

If you want to manipulate specific field values in a more convenient way, the getField and setField methods already do a good job. However, getField will always return field object by value, which means you will get a copy of the corresponding field object that X3DOM uses internally. For many use cases, this is perfectly fine: you will rececive a copy of the field object, manipulate the copy and and use it somewhere, without affecting the value of the field - just like you would probably expect it, and just like it already works for other methods like setAttribute, for instance. The problem of getting everything by value is that it involves copy operations, which will potentially become time-consuming. This is especially the case if the following assumptions apply:

  • The field value is changed very frequently (for example, 60 times in a second)
  • The field value is a large array of values

Please note that requestFieldRef is especially thought for such cases and does not work on fields that represent single, primitive javascript datatypes, such as SFFloat or SFString. A field value that consists of a large array of values is usually a multi-valued field, with its type starting with "MF". For example, MFVec3f denotes a field type which represents an array of three-element float vectors. Such a field may contain an arbitrary number of elements, therefore you may want to avoid to copy the corresponding field object every time you change some of its values. The solution in this case is to operate on a reference to the original field object which is internally used by X3DOM, instead of using a copy. This is possible by using the X3DOM requestFieldRef method, which returns the original field object by reference. Of course, you should be aware that you are manipulating the original object used by X3DOM, and that any change you make to it will potentially directly be reflected in X3DOM's output. Still, there might be cases where your changes have to be internally processed by X3DOM before they finally take place in the rendered result. X3DOM might, for example, need to update some values on the GPU after you changed a certain field in your application. In order to do so, X3DOM also needs a notification that you have finished your changes to the internal field object, so it can process the changes properly. To do so, you will have to call the releaseFieldRef method. You can think of this process as of "borrowing" the object, manipulating it and giving it back to X3DOM. For example, imagine you have an array of colors provided as color multi value field of type MFColor by the Color node. To change the red channel of the entry at index 23 you do the following: 


    var myColorArray = document.getElementById('myColorNode').requestFieldRef('color');
    myColorArray[23].r = 1.0;    //the myColorArray object is of type 'MFColor', and it is the same object that is internally used by X3DOM
    document.getElementById('myColorNode').releaseFieldRef('color');

The X3DOM requestFieldRef and releaseFieldRef methods, which are available on all X3DOM nodes, are defined as follows:

requestFieldRef (fieldname) → FIELDTYPE ⤴

Returns the field object of the field with the given name. The returned object is no copy, but instead a reference to X3DOM's internal field object. Changes to this object should be committed using the releaseFieldRef function.

Parameters:
NameTypeDescription
fieldname String the name of the field

Returns:
the current field object, as it is also used by X3DOM

releaseFieldRef (fieldname) ⤴

Commits all changes made to the internal field object of the field with the given name. This must be done in order to notify X3DOM to process all related changes internally.

Parameters:
NameTypeDescription
fieldname String the name of the field