X3DOM Scene Author API Documentation: Overview

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>X3DOM Scene Author API Documentation: Overview</title> <link type="text/css" rel="stylesheet" href="../static/styles/x3dom-docs-new.css">  <script src="../static/scripts/prettify/run_prettify.js"></script> </head> <body> <div class="container page-header"> <div class="row"> <div class="col-xs-12"> <h2 style="display:inline;color:#266F97">official <img src="../static/images/x3dom_logo_without_claim.png" style="height:1em;vertical-align:top;"> documentation</h2> </div> </div> <div class="row" style="margin-top:20px;"> <div class="col-xs-12"> <ol class="breadcrumb"> <li><a href="http://x3dom.org">x3dom.org</a></li> <li><a href="../index.html">documentation</a></li> <li>Scene Author API</li> </ol> </div> </div> </div> <div class="container" style="text-align: center"> <ul class="nav nav-pills" style="display: inline-block;"> <li><a href="index.html" class="btn btn-primary">Overview</a></li> <li><a href="nodes.html">Nodes</a></li> <li><a href="components.html">Components</a></li> <li><a href="runtime.html">Runtime</a></li> <li><a href="configuration.html">Configuration</a></li> </ul> </div> <div class="container"> <section> <article> <h2 style="text-align: center">Introduction</h2> <div class="class-summary"> <div class="well" style="float:right; margin-left:20px;"> <h4>DOM Element Functions</h4> <ul> <li><a href="#getAttribute">➨ getAttribute</a></li> <li><a href="#setAttribute">➨ setAttribute</a></li> <li><a href="#getFieldValue">➨ getFieldValue</a></li> <li><a href="#setFieldValue">➨ setFieldValue</a></li> <li><a href="#requestFieldRef">➨ requestFieldRef</a></li> <li><a href="#releaseFieldRef">➨ releaseFieldRef</a></li> </ul> </div> </div> <p> Welcome to the <strong>X3DOM Scene Author API Documentation</strong>! Within this documentation package, you will find detailed information about all <strong>X3DOM Nodes</strong> and their <strong>Fields</strong>. Like in the X3D standard, X3DOM nodes are grouped into <strong>Components</strong>. There are several ways to find what you are looking for: <ul> <li><a href="nodes.html">Node Index</a></li> <li><a href="components.html">Component Index</a></li> </ul> 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. </p> <h2>Scope</h2> <p> This API documentation is automatically generated during a nightly build process, using the latest available code from the </strong>X3DOM development branch</strong>. It is therefore intended for use with this branch of X3DOM. <br> 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. </p> <h2>Runtime functions and configuration</h2> <p> You want to write javascript code that interacts with the x3dom runtime? Head over to the <a href="runtime.html">runtime documentation</a> to find a reference of all available functions and callbacks. On the <a href="configuration.html">configuration page</a> you will find a list of possible options that are used to change the behavior of the runtime in a declarative way. </p> <h2>Manipulating Fields with DOM Element Functions</h2> <p> 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. <h3>Using <code>getAttribute</code> and <code>setAttribute</code></h3> Like regular HTML attributes, your can manipulate X3DOM values with the standard <code>getAttribute</code> and <code>setAttribute</code> methods. You may, for instance, have this HTML representation of a <code>material</code> node: </p> <pre class="prettyprint"><code class="language-html"> <material id='myMaterial' diffuseColor='1 0 0'></material> </code></pre> <p> Imagine you would want to change the <code>diffuseColor</code> field of this material node. This can be easily achieved with the <code>getAttribute</code> and <code>setAttribute</code> methods: </p> <pre class="prettyprint"><code class="language-js"> 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); </code></pre> <p> Since HTML attributes are not case sensitive, X3DOM attributes behave in the same way. You may therefore write <code>'diffuseColor'</code> as well as <code>'DiffuseColor'</code> or <code>'diffusecolor'</code>, for example. </p> <p> The standard DOM <code>getAttribute</code> and <code>setAttribute</code> methods are defined as follows: </p>  <dl class="method-container"> <dt> <h4 class="name method-container-header"> getAttribute <span class="signature"> (fieldname) </span> <span class="type-signature"> &#8594 String </span> <a name="getAttribute" class="upwardsLink" href="#">⤴</a> </h4> </dt> <dd> <div class="description"> Returns the value of the field with the given name. The value is returned as a string, just like it appears in the DOM. </div> <br> <h5>Parameters:</h5> <div class="params"> <table class="table table-striped"> <tbody> <tr><th>Name</th><th>Type</th><th class="last">Description</th></tr> <tr> <td class="param-table-name"><code>fieldname</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the name of the field </td> </tr> </tbody> </table> </div> <br> <h5>Returns:</h5> <div class="param-desc">the current field value, as a string</div> </dd> </dl>  <dl class="method-container"> <dt> <h4 class="name method-container-header"> setAttribute <span class="signature"> (fieldname, fieldvalue) </span> <a name="setAttribute" class="upwardsLink" href="#">⤴</a> </h4> </dt> <dd> <div class="description"> 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. </div> <br> <h5>Parameters:</h5> <div class="params"> <table class="table table-striped"> <tbody> <tr><th>Name</th><th>Type</th><th class="last">Description</th></tr> <tr> <td class="param-table-name"><code>fieldname</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the name of the field where the value should be set </td> </tr> <tr> <td class="param-table-name"><code>fieldvalue</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the new field value </td> </tr> </tbody> </table> </div> <br> </dd> </dl> <br> <h3>Using <code>getFieldValue</code> and <code>setFieldValue</code></h3> <p> 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 <color>diffuseColor</color> attribute, this means that you can also directly get and set the field value as an <color>SFColor</color> object: </p> <pre class="prettyprint"><code class="language-js"> 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); </code></pre> <p> The X3DOM <code>getFieldValue</code> and <code>setFieldValue</code> methods, which are available on all X3DOM nodes, are defined as follows: </p>  <dl class="method-container"> <dt> <h4 class="name method-container-header"> getFieldValue <span class="signature"> (fieldname) </span> <span class="type-signature"> &#8594 FIELDTYPE </span> <a name="getFieldValue" class="upwardsLink" href="#">⤴</a> </h4> </dt> <dd> <div class="description"> Returns the value of the field with the given name. The value is returned as an object of the corresponding field type. </div> <br> <h5>Parameters:</h5> <div class="params"> <table class="table table-striped"> <tbody> <tr><th>Name</th><th>Type</th><th class="last">Description</th></tr> <tr> <td class="param-table-name"><code>fieldname</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the name of the field </td> </tr> </tbody> </table> </div> <br> <h5>Returns:</h5> <div class="param-desc">the current field value, as a field object</div> </dd> </dl>  <dl class="method-container"> <dt> <h4 class="name method-container-header"> setFieldValue <span class="signature"> (fieldname, fieldvalue) </span> <a name="setFieldValue" class="upwardsLink" href="#">⤴</a> </h4> </dt> <dd> <div class="description"> 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. </div> <br> <h5>Parameters:</h5> <div class="params"> <table class="table table-striped"> <tbody> <tr><th>Name</th><th>Type</th><th class="last">Description</th></tr> <tr> <td class="param-table-name"><code>fieldname</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the name of the field where the value should be set </td> </tr> <tr> <td class="param-table-name"><code>fieldvalue</code></td> <td class="param-table-type"> <span class="param-type">FIELDTYPE</span> </td> <td class="param-table-description"> the new field value </td> </tr> </tbody> </table> </div> <br> </dd> </dl> <br> <h3>Using <code>requestFieldRef</code> and <code>releaseFieldRef</code></h3> <p> If you want to manipulate specific field values in a more convenient way, the <code>getField</code> and <code>setField</code> methods already do a good job. However, <code>getField</code> will always return field object <i>by value</i>, 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 <code>setAttribute</code>, for instance. The problem of getting everything <i>by value</i> is that it involves copy operations, which will potentially become time-consuming. This is especially the case if the following assumptions apply: </p> <ul> <li>The field value is changed very frequently (for example, 60 times in a second)</li> <li>The field value is a large array of values</li> </ul> <p> 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, <code>MFVec3f</code> 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 <i>reference</i> to the <i>original field object</i> which is internally used by X3DOM, instead of using a copy. This is possible by using the X3DOM <code>requestFieldRef</code> method, which returns the original field object <i>by reference</i>. 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 <code>releaseFieldRef</code> 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 <code>color</code> multi value field of type <code>MFColor</code> by the <code>Color</code> node. To change the red channel of the entry at index 23 you do the following: </p> <pre class="prettyprint"><code class="language-js"> 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'); </code></pre> <p> The X3DOM <code>requestFieldRef</code> and <code>releaseFieldRef</code> methods, which are available on all X3DOM nodes, are defined as follows: </p>  <dl class="method-container"> <dt> <h4 class="name method-container-header"> requestFieldRef <span class="signature"> (fieldname) </span> <span class="type-signature"> &#8594 FIELDTYPE </span> <a name="requestFieldRef" class="upwardsLink" href="#">⤴</a> </h4> </dt> <dd> <div class="description"> 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 <code>releaseFieldRef</code> function. </div> <br> <h5>Parameters:</h5> <div class="params"> <table class="table table-striped"> <tbody> <tr><th>Name</th><th>Type</th><th class="last">Description</th></tr> <tr> <td class="param-table-name"><code>fieldname</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the name of the field </td> </tr> </tbody> </table> </div> <br> <h5>Returns:</h5> <div class="param-desc">the current field object, as it is also used by X3DOM</div> </dd> </dl>  <dl class="method-container"> <dt> <h4 class="name method-container-header"> releaseFieldRef <span class="signature"> (fieldname) </span> <a name="releaseFieldRef" class="upwardsLink" href="#">⤴</a> </h4> </dt> <dd> <div class="description"> 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. </div> <br> <h5>Parameters:</h5> <div class="params"> <table class="table table-striped"> <tbody> <tr><th>Name</th><th>Type</th><th class="last">Description</th></tr> <tr> <td class="param-table-name"><code>fieldname</code></td> <td class="param-table-type"> <span class="param-type">String</span> </td> <td class="param-table-description"> the name of the field </td> </tr> </tbody> </table> </div> <br> </dd> </dl> <br> </article> <br> </section> <footer>  </footer> </div> </div> </body> </html>

CINXE.COM

X3DOM Scene Author API Documentation: Overview