x_ite 4.7.5 → 4.7.9

package/docs/Accessing-the-External-Browser.md

@@ -8,10 +8,10 @@ If you want combine DOM access with X3D access in your JavaScript functions then
 
 ## Introduction
 
-There is the X3D object which is always available, it expects at least one function handler that is called when the browsers (<X3DCanvas> elements) are ready, or the second function handler is called if an error occurred.
+There is the X3D object which is always available, it expects one function handler that is called when the browsers (<X3DCanvas> elements) are ready, and a second function handler, that is called if an error occurred. These two arguments are optional. The return value of the X3D function is a Promise, which can be used instead of the arguments.
 
 ```js
-X3D (callback[, errorCallback]);
+Promise X3D ([callback[, errorCallback]]);
 ```
 
 The callback function is called when the browser is available. The callback function takes no arguments. The error callback is called if an error occurred, it has one argument *error.*
@@ -65,6 +65,35 @@ function (error)
 </script>
 ```
 
+### Using the Promise return value
+
+```js
+X3D () .then (function ()
+{
+  const Browser = X3D .getBrowser ();
+})
+.catch (function (error)
+{
+  // ooops an error.
+  console .error (error);
+});
+```
+
+### Async use of X3D object
+
+```js
+async function foo (url)
+{
+  await X3D ();
+
+  const Browser = X3D .getBrowser ();
+
+  await Browser .loadURL (new MFString (url));
+
+  console .log (`Done loading scene '${Browser .currentScene .worldURL}'.`);
+}
+```
+
 ## X3D Object
 
 ### Functions
@@ -265,7 +294,7 @@ function spin ()
 ### The HTML
 
 ```html
-<X3DCanvas src="external-browser.x3d" onload="init ()"/>
+<X3DCanvas src="external-browser.x3d" onload="init ()"></X3DCanvas>
 
 <div class="buttons">
   <button id="center" class="button" onclick="center ()">Center</button>

package/docs/Custom-Shaders.md

@@ -64,7 +64,7 @@ Once the X3D is defined we can now write the vertex and the fragment shader sour
 
 ### Vertex Shader
 
-```c
+```glsl
 #version 300 es
 
 precision mediump float;
@@ -73,7 +73,7 @@ uniform mat4 x3d_TextureMatrix [x3d_MaxTextures];
 uniform mat4 x3d_ModelViewMatrix;
 uniform mat4 x3d_ProjectionMatrix;
 
-in vec4 x3d_TexCoord;
+in vec4 x3d_TexCoord0;
 in vec4 x3d_Vertex;
 
 out vec4 texCoord;
@@ -81,7 +81,7 @@ out vec4 texCoord;
 void
 main ()
 {
-  texCoord = x3d_TextureMatrix [0] * x3d_TexCoord;
+  texCoord = x3d_TextureMatrix [0] * x3d_TexCoord0;
 
   gl_Position = x3d_ProjectionMatrix * x3d_ModelViewMatrix * x3d_Vertex;
 }
@@ -89,7 +89,7 @@ main ()
 
 ### Fragment Shader
 
-```c
+```glsl
 #version 300 es
 
 precision mediump float;
@@ -127,9 +127,9 @@ A ComposedShader node provides the capability to define custom fields like the S
 <table class=" table">
    <thead>
       <tr>
-         <th scope="col">X3D field type</th>
-         <th scope="col">GLSL variable type</th>
-         <th scope="col"></th>
+         <th>X3D field type</th>
+         <th>GLSL variable type</th>
+         <th></th>
       </tr>
    </thead>
    <tbody>
@@ -357,9 +357,9 @@ A ComposedShader defines a number of special variables for the various shader st
 <table class=" table">
    <thead>
       <tr>
-         <th scope="col">Type</th>
-         <th scope="col">Name</th>
-         <th scope="col">Comment</th>
+         <th>Type</th>
+         <th>Name</th>
+         <th>Comment</th>
       </tr>
    </thead>
    <tbody>
@@ -374,8 +374,7 @@ A ComposedShader defines a number of special variables for the various shader st
          <td>x3d_Points, x3d_Lines, x3d_Geometry2D, x3d_Geometry3D</td>
       </tr>
       <tr>
-         <td colspan="3"><hr/>
-         </td>
+         <td colspan="3"><hr/></td>
       </tr>
       <tr>
          <td>uniform int</td>
@@ -392,6 +391,22 @@ A ComposedShader defines a number of special variables for the various shader st
          <td>x3d_Fog</td>
          <td>see table »Uniform Struct x3d_FogParameters«</td>
       </tr>
+      <tr>
+         <td colspan="3"><hr/></td>
+      </tr>
+      <tr>
+         <td>uniform int</td>
+         <td>x3d_NumLights</td>
+         <td>number of lights in x3d_LightSource</td>
+      </tr>
+      <tr>
+         <td>uniform x3d_LightSourceParameters</td>
+         <td>x3d_LightSource [x3d_MaxLights]</td>
+         <td>see table »Uniform Struct x3d_LightSourceParameters«</td>
+      </tr>
+      <tr>
+         <td colspan="3"><hr/></td>
+      </tr>
       <tr>
          <td>uniform float</td>
          <td>x3d_AlphaCutoff</td>
@@ -413,9 +428,7 @@ A ComposedShader defines a number of special variables for the various shader st
          <td>see table »Uniform Struct x3d_FillPropertiesParameters«</td>
       </tr>
       <tr>
-         <td></td>
-         <td></td>
-         <td></td>
+         <td colspan="3"><hr/></td>
       </tr>
       <tr>
          <td>uniform bool</td>
@@ -423,36 +436,15 @@ A ComposedShader defines a number of special variables for the various shader st
          <td>true if X3DColorNode attached</td>
       </tr>
       <tr>
-         <td>uniform int</td>
-         <td>x3d_NumLights</td>
-         <td>Number of lights in x3d_LightSource</td>
-      </tr>
-      <tr>
-         <td>uniform x3d_LightSourceParameters</td>
-         <td>x3d_LightSource [x3d_MaxLights]</td>
-         <td>see table »Uniform Struct x3d_LightSourceParameters«</td>
-      </tr>
-      <tr>
-         <td colspan="3"><hr/>
-         </td>
-      </tr>
-      <tr>
-         <td>uniform float</td>
-         <td>x3d_AlphaCutoff</td>
-         <td>alphaCutoff value from Appearance</td>
-      </tr>
-      <tr>
-         <td colspan="3"><hr/>
-         </td>
+         <td colspan="3"><hr/></td>
       </tr>
       <tr>
          <td>uniform x3d_MaterialParameters</td>
-         <td>x3d_tMaterial</td>
+         <td>x3d_Material</td>
          <td>see table »Uniform Struct x3d_MaterialParameters«</td>
       </tr>
       <tr>
-         <td colspan="3"><hr/>
-         </td>
+         <td colspan="3"><hr/></td>
       </tr>
       <tr>
          <td>uniform int</td>
@@ -480,8 +472,7 @@ A ComposedShader defines a number of special variables for the various shader st
          <td>see table »Uniform Struct x3d_TextureCoordinateGeneratorParameters«</td>
       </tr>
       <tr>
-         <td colspan="3"><hr/>
-         </td>
+         <td colspan="3"><hr/></td>
       </tr>
       <tr>
          <td>uniform ivec4</td>
@@ -514,8 +505,7 @@ A ComposedShader defines a number of special variables for the various shader st
          <td>transformation matrix of the camera</td>
       </tr>
       <tr>
-         <td colspan="3"><hr/>
-         </td>
+         <td colspan="3"><hr/></td>
       </tr>
       <tr>
          <td>attribute float</td>
@@ -545,7 +535,7 @@ A ComposedShader defines a number of special variables for the various shader st
       <tr>
          <td>attribute vec4</td>
          <td>x3d_Vertex</td>
-         <td>vertex coordinate, **required**</td>
+         <td>vertex coordinate, <b>required</b></td>
       </tr>
    </tbody>
 </table>
@@ -628,7 +618,7 @@ If the shader node is part of a ParticleSystem node the following attributes are
 | Type            | Name                     | Comment                                                   |
 |-----------------|--------------------------|-----------------------------------------------------------|
 | attribute float | x3d\_ParticleId          | integer id of the particle                                |
-| attribute float | x3d\_ParticleLife        | integer number of current life                            |
+| attribute float | x3d\_ParticleLife        | integer number of current life cycle                      |
 | attribute float | x3d\_ParticleElapsedTime | elapsed time normalized in the range \[0, 1\]             |
 | attribute vec4  | x3d\_ParticlePosition    | center coordinate of particle, in relation to x3d\_Vertex |
 
@@ -636,205 +626,205 @@ If the ParticleSystem.*geometryType* is GEOMETRY the following uniforms are avai
 
 | Type                            | Name          | Comment                                            |
 |---------------------------------|---------------|----------------------------------------------------|
-| uniform x3d\_ParticleParameters | x3d\_Particle | See table »Uniform Struct x3d\_ParticleParameters« |
+| uniform x3d\_ParticleParameters | x3d\_Particle | see table »Uniform Struct x3d\_ParticleParameters« |
 
 #### Uniform Struct x3d\_ParticleParameters
 
 | Type  | Name        | Comment                                       |
 |-------|-------------|-----------------------------------------------|
 | int   | id          | integer id of the particle                    |
-| int   | life        | integer number of current life                |
+| int   | life        | integer number of current life cycle          |
 | float | elapsedTime | elapsed time normalized in the range \[0, 1\] |
 
 ## Built-in Constants
 
-Some built-in variables are enumerated and have special values and meanings. The following table list all of them and their corresponding values. Note: as of version 1.27 these constant are buit-in.
+Some built-in variables are enumerated and have special values and meanings. The following table list all of them and their corresponding values. Note: as of version 1.27 these constant are built-in.
 
-<table class=" table" style="width: 1046px;">
+<table class=" table">
    <thead>
       <tr>
-         <th style="width: 297.767px;">Variable</th>
-         <th style="width: 41.7667px;">Type</th>
-         <th scope="col" style="width: 252.767px;">Name</th>
-         <th scope="col" style="width: 49.7667px;">Value</th>
-         <th style="width: 369.933px;">Comment</th>
+         <th>Variable</th>
+         <th>Type</th>
+         <th>Name</th>
+         <th>Value</th>
+         <th>Comment</th>
       </tr>
    </thead>
    <tbody>
       <tr>
-         <td style="width: 297.767px;">X_ITE</td>
-         <td style="width: 41.7667px;"></td>
-         <td style="width: 252.767px;"></td>
-         <td style="width: 49.7667px;"></td>
-         <td style="width: 369.933px;">defined</td>
+         <td>X_ITE</td>
+         <td></td>
+         <td></td>
+         <td></td>
+         <td>defined</td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">X3D_LOGARITHMIC_DEPTH_BUFFER</td>
-         <td style="width: 41.7667px;"></td>
-         <td style="width: 252.767px;"></td>
-         <td style="width: 49.7667px;"></td>
-         <td style="width: 369.933px;">defined if logarithmic depth buffer is enabled in [browser options](http://create3000.de/users-guide/ecmascript-object-and-function-definitions/browser-services/#browser-object).</td>
+         <td>X3D_LOGARITHMIC_DEPTH_BUFFER</td>
+         <td></td>
+         <td></td>
+         <td></td>
+         <td>defined if logarithmic depth buffer is enabled in <a href="https://create3000.github.io/x_ite/reference/Browser-Services.html#string-getbrowseroption-string-name">browser options</a>.</td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">x3d_GeometryType</td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_Points</td>
-         <td style="width: 49.7667px;">0</td>
-         <td style="width: 369.933px;">appears on PointSet and Polypoint2D</td>
+         <td>x3d_GeometryType</td>
+         <td>int</td>
+         <td>x3d_Points</td>
+         <td>0</td>
+         <td>appears on PointSet and Polypoint2D</td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_Lines</td>
-         <td style="width: 49.7667px;">1</td>
-         <td style="width: 369.933px;">appears on IndexedLineSet, LineSet and Polyline2D</td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_Lines</td>
+         <td>1</td>
+         <td>appears on IndexedLineSet, LineSet and Polyline2D</td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_Geometry2D</td>
-         <td style="width: 49.7667px;">2</td>
-         <td style="width: 369.933px;">appears on Geometry2D nodes</td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_Geometry2D</td>
+         <td>2</td>
+         <td>appears on Geometry2D nodes</td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_Geometry3D</td>
-         <td style="width: 49.7667px;">3</td>
-         <td style="width: 369.933px;">appears on Geometry3D nodes and other 3D nodes</td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_Geometry3D</td>
+         <td>3</td>
+         <td>appears on Geometry3D nodes and other 3D nodes</td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">x3d_ClipPlane</td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_MaxClipPlanes</td>
-         <td style="width: 49.7667px;">6</td>
-         <td style="width: 369.933px;"></td>
+         <td>x3d_ClipPlane</td>
+         <td>int</td>
+         <td>x3d_MaxClipPlanes</td>
+         <td>6</td>
+         <td></td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">x3d_FogType</td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_None</td>
-         <td style="width: 49.7667px;">0</td>
-         <td style="width: 369.933px;"></td>
+         <td>x3d_FogType</td>
+         <td>int</td>
+         <td>x3d_None</td>
+         <td>0</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_LinearFog</td>
-         <td style="width: 49.7667px;">1</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_LinearFog</td>
+         <td>1</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_ExponentialFog</td>
-         <td style="width: 49.7667px;">2</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_ExponentialFog</td>
+         <td>2</td>
+         <td></td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_MaxLights</td>
-         <td style="width: 49.7667px;">8</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_MaxLights</td>
+         <td>8</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">x3d_LightType</td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_DirectionalLight</td>
-         <td style="width: 49.7667px;">1</td>
-         <td style="width: 369.933px;"></td>
+         <td>x3d_LightType</td>
+         <td>int</td>
+         <td>x3d_DirectionalLight</td>
+         <td>1</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_PointLight</td>
-         <td style="width: 49.7667px;">2</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_PointLight</td>
+         <td>2</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_SpotLight</td>
-         <td style="width: 49.7667px;">3</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_SpotLight</td>
+         <td>3</td>
+         <td></td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_MaxTextures</td>
-         <td style="width: 49.7667px;">2</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_MaxTextures</td>
+         <td>2</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">x3d_TextureType</td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_TextureType2D</td>
-         <td style="width: 49.7667px;">2</td>
-         <td style="width: 369.933px;"></td>
+         <td>x3d_TextureType</td>
+         <td>int</td>
+         <td>x3d_TextureType2D</td>
+         <td>2</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_TextureType3D</td>
-         <td style="width: 49.7667px;">3</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_TextureType3D</td>
+         <td>3</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_TextureTypeCubeMapTexture</td>
-         <td style="width: 49.7667px;">4</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_TextureTypeCubeMapTexture</td>
+         <td>4</td>
+         <td></td>
       </tr>
       <tr>
-         <td colspan="5" style="width: 1036px;"><hr/>
+         <td colspan="5"><hr/>
          </td>
       </tr>
       <tr>
-         <td style="width: 297.767px;">x3d_ColorMode</td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_PointColor</td>
-         <td style="width: 49.7667px;">0</td>
-         <td style="width: 369.933px;">PointProperties colorMode constants</td>
+         <td>x3d_ColorMode</td>
+         <td>int</td>
+         <td>x3d_PointColor</td>
+         <td>0</td>
+         <td>PointProperties colorMode constants</td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_TextureColor</td>
-         <td style="width: 49.7667px;">1</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_TextureColor</td>
+         <td>1</td>
+         <td></td>
       </tr>
       <tr>
-         <td style="width: 297.767px;"></td>
-         <td style="width: 41.7667px;">int</td>
-         <td style="width: 252.767px;">x3d_TextureAndPointColor</td>
-         <td style="width: 49.7667px;">2</td>
-         <td style="width: 369.933px;"></td>
+         <td></td>
+         <td>int</td>
+         <td>x3d_TextureAndPointColor</td>
+         <td>2</td>
+         <td></td>
       </tr>
    </tbody>
 </table>
@@ -857,9 +847,11 @@ function initialize ()
 
 To address the issue of the depth not being interpolated in perspectively-correct way, output the following interpolant to the vertex shader:
 
-```c
+```glsl
+#version 300 es
+
 #ifdef X3D_LOGARITHMIC_DEPTH_BUFFER
-varying float depth;
+out float depth;
 #endif
 
 void
@@ -867,7 +859,7 @@ main ()
 {
    ...
    #ifdef X3D_LOGARITHMIC_DEPTH_BUFFER
-   // Assuming gl_Position was already computed
+   // Assuming gl_Position was already computed.
    depth = 1.0 + gl_Position .w;
    #endif
 }
@@ -875,14 +867,13 @@ main ()
 
 and then in the fragment shader add:
 
-```c
-#ifdef X3D_LOGARITHMIC_DEPTH_BUFFER
-#extension GL_EXT_frag_depth : enable
-#endif
+```glsl
+#version 300 es
 
 #ifdef X3D_LOGARITHMIC_DEPTH_BUFFER
+#extension GL_EXT_frag_depth : enable
 uniform float x3d_LogarithmicFarValue1_2;
-varying float depth;
+in float depth;
 #endif
 
 void