x_ite 4.2.17 → 4.7.7

package/docs/tutorials/Introducing-animation.md

@@ -0,0 +1,211 @@
+# Introducing Animations
+
+## Motivation
+
+- Nodes like [Billboard](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Billboard) and [Anchor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#Anchor) have built-in behavior
+- You can create your own behaviors to make shapes move, rotate, scale, blink, and more
+- We need a means to trigger, time, and respond to a sequence of events in order to provide better user/world interactions
+
+## Building animation circuits
+
+Almost every node can be a component in an animation circuit
+
+- Nodes act like virtual electronic parts
+- Nodes can send and receive events
+- Wired routes connect nodes together
+
+An event is a message sent between nodes
+
+- A data value (such as a translation)
+- A time stamp (when did the event get sent)
+
+## Examples
+
+To spin a shape:
+
+- Connect a node that sends rotation events to a [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) node's *rotation* field
+
+To blink a shape:
+
+- Connect a node that sends color events to a [Material](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Material) node's *diffuseColor* field
+
+## Routing events
+
+To set up an animation circuit, you need three things:
+
+1. A node which sends events
+  - The node must be named with **DEF**
+2. A node which receives events
+  - The node must be named with **DEF**
+3. A route connecting them
+
+## Using node inputs and outputs
+
+Every node has fields, inputs, and outputs:
+
+- initializeOnly: A stored value
+- inputOnly: An input
+- outputOnly: An output
+
+An inputOutput field is a short-hand for a initializeOnly, inputOnly, and outputOnly
+
+## Sample inputs
+
+A [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) node has these input fields:
+
+- *set\_translation*
+- *set\_rotation*
+- *set\_scale*
+
+A [Material](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Material) node has these input fields:
+
+- *set\_diffuseColor*
+- *set\_emissiveColor*
+- *set\_transparency*
+
+## Sample outputs
+
+An [OrientationInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#OrientationInterpolator) node has this output field:
+
+- *value\_changed* to send rotation values
+
+A [PositionInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#PositionInterpolator) node has this output field:
+
+- *value\_changed* to send position (translation) values
+
+A [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node has this output field:
+
+- *time* to send time values
+
+## Syntax: ROUTE
+
+A **ROUTE** statement connects two nodes together using
+
+- The sender's node name and output field name
+- The receiver's node name and input field name
+
+### XML Encoding
+
+```xml
+<ROUTE fromNode='MySender' fromField='rotation_changed' toNode='MyReceiver' toField='set_rotation'/>
+```
+
+### Classic Encoding
+
+```js
+ROUTE MySender.rotation_changed TO MyReceiver.set_rotation
+```
+
+**ROUTE** and **TO** must be in upper-case
+
+## Field data types
+
+Sender and receiver field data types must match!
+
+Data types have names with a standard format, such as:
+
+- **SFString,****SFRotation,** or **MFColor**
+
+| Character | Values                                                                |
+|-----------|-----------------------------------------------------------------------|
+| 1         | \*\*S:\*\* Single value \*\*M:\*\* Multiple values                    |
+| 2         | Always an \*\*F\*\* (for field)                                       |
+| remainder | Name of data type, such as \*\*String, Rotation,\*\* or \*\*Color\*\* |
+
+| Data type                | Meaning                                     |
+|--------------------------|---------------------------------------------|
+| SFBool, MFBool           | Boolean, true or false value                |
+| SFColor, MFColor         | RGB color value                             |
+| SFColorRGBA, MFColorRGBA | RGBA color value                            |
+| SFDouble, MFDouble       | Double precision floating point value       |
+| SFFloat, MFFloat         | Floating point value                        |
+| SFImage, MFImage         | Image value                                 |
+| SFInt32, MFInt32         | Integer value                               |
+| SFMatrix3d, MFMatrix3d   | 3×3 matrix value, double precision          |
+| SFMatrix3f, MFMatrix3f   | 3×3 matrix value                            |
+| SFMatrix4d, MFMatrix4d   | 4×4 matrix value, double precision          |
+| SFMatrix4f, MFMatrix4f   | 4×4 matrix value                            |
+| SFNode, MFNode           | Node value                                  |
+| SFRotation, MFRotation   | Rotation value                              |
+| SFString, MFString       | Text string value                           |
+| SFTime, MFTime           | Time value                                  |
+| SFVec2d, MFVec2d         | XY floating point value, double precision   |
+| SFVec2f, MFVec2f         | XY floating point value                     |
+| SFVec3d, MFVec3d         | XYZ floating point value, double precision  |
+| SFVec3f, MFVec3f         | XYZ floating point value                    |
+| SFVec4d, MFVec4d         | XYZW floating point value, double precision |
+| SFVec4f, MFVec4f         | XYZW floating point value                   |
+
+## Following naming conventions
+
+Most nodes have inputOutput fields.
+
+If the inputOutput field name is *xxx*, then:
+
+- *set\_xxx* is an input to set the field
+- *xxx\_changed* is an output that sends when the field changes
+- The *set\_* and *\_changed* sufixes are optional but recommended for clarity
+
+The [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) node has:
+
+- *rotation* field
+- *set\_rotation* input
+- *rotation\_changed* output
+
+## A sample animation
+
+### XML Encoding
+
+```xml
+<TouchSensor DEF='Touch'/>
+
+<TimeSensor DEF='Timer1' ... />
+
+<OrientationInterpolator DEF='Rot1' ... />
+
+<Transform DEF='Frame1'>
+  <Shape><!-- ... --></Shape>
+</Transform>
+
+<ROUTE fromNode='Touch' fromField='touchTime' toNode='Timer1' toField='set_startTime'/>
+<ROUTE fromNode='Timer1' fromField='fraction_changed' toNode='Rot1' toField='set_fraction'/>
+<ROUTE fromNode='Rot1' fromField='value_changed' toNode='Frame1' toField='set_rotation'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Touch TouchSensor { }
+
+DEF Timer1 TimeSensor { ... }
+
+DEF Rot1 OrientationInterpolator { ... }
+
+DEF Frame1 Transform {
+  children [
+    Shape { ... }
+  ]
+}
+
+ROUTE Touch.touchTime         TO Timer1.set_startTime
+ROUTE Timer1.fraction_changed TO Rot1.set_fraction
+ROUTE Rot1.value_changed      TO Frame1.set_rotation
+```
+
+## Using multiple routes
+
+You can have **fan-out**
+
+- Multiple routes out of the same sender
+
+You can have **fan-in**
+
+- Multiple routes into the same receiver
+
+## Summary
+
+- Connect senders to receivers using routes
+- input fields are inputs, and output fields are outputs
+- A route names the sender.output, and the receiver.input
+  - Data types must match
+- You can have multiple routes into or out of a node

package/docs/tutorials/Introducing-script-use.md

@@ -0,0 +1,127 @@
+# Introducing Script Use
+
+## Motivation
+
+Many actions are too complex for animation nodes:
+
+- Computed animation paths (eg. gravity)
+- Algorithmic shapes (eg. fractals)
+- Collaborative environments (eg. games)
+
+You can create new sensors, interpolators, etc., using program scripts written in:
+
+- JavaScript - easy-to-learn language
+- ECMAScript - same as JavaScript
+
+## Syntax: Script
+
+A [Script](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/scripting.html#Script) node selects a program script to run:
+
+- *url* - choice of program script
+
+### XML Encoding
+
+```xml
+<Script DEF='Bouncer'>
+<![CDATA[ecmascript:
+...
+]]>
+</Script>
+
+<!-- or -->
+
+<Script DEF='Bouncer'
+    url='"bouncer.js"'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Bouncer Script {
+  url "ecmascript: ..."
+  #or...
+  url "bouncer.js"
+}
+```
+
+## Defining the program script interface
+
+A Script node also declares the program script interface:
+
+- **initializeOnly, inputOnly, outputOnly, inputOutput** - inputs and outputs
+  - Each has a name and data type
+  - Fields have an initial value
+
+### XML Encoding
+
+```xml
+<Script DEF='Bouncer'>
+  <field accessType='initializeOnly' type='SFFloat' name='bounceHeight' value='3'/>
+  <field accessType='inputOnly' type='SFFloat' name='set_fraction'/>
+  <field accessType='outputOnly' type='SFVec3f' name='value_changed'/>
+  <field accessType='inputOutput' type='SFBool' name='enabled' value='true'/>
+</Script>
+```
+
+### Classic Encoding
+
+```js
+DEF Bouncer Script {
+  initializeOnly  SFFloat bounceHeight 3.0
+  inputOnly       SFFloat set_fraction
+  outputOnly      SFVec3f value_changed
+  inputOutput     SFBool  enabled TRUE
+}
+```
+
+## A sample using a program script
+
+### XML Encoding
+
+```xml
+<TimeSensor DEF='Clock' ... />
+
+<Transform DEF='Ball' ... />
+
+<Script DEF='Bouncer'>
+  <field accessType='initializeOnly' type='SFFloat' name='bounceHeight' value='3'/>
+  <field accessType='inputOnly' type='SFFloat' name='set_fraction'/>
+  <field accessType='outputOnly' type='SFVec3f' name='value_changed'/>
+  <field accessType='inputOutput' type='SFBool' name='enabled' value='true'/>
+<![CDATA[ecmascript:
+...
+]]>
+</Script>
+
+<ROUTE fromNode='Clock' fromField='fraction_changed' toNode='Bouncer' toField='set_fraction'/>
+<ROUTE fromNode='Bouncer' fromField='value_changed' toNode='Ball' toField='set_translation'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Clock TimeSensor { ... }
+
+DEF Ball Transform { ... }
+
+DEF Bouncer Script {
+  initializeOnly  SFFloat bounceHeight 3.0
+  inputOnly       SFFloat set_fraction
+  outputOnly      SFVec3f value_changed
+  inputOutput     SFBool  enabled TRUE
+  url "ecmascript: ..."
+}
+
+ROUTE Clock.fraction_changed TO Bouncer.set_fraction
+ROUTE Bouncer.value_changed  TO Ball.set_translation
+```
+
+## Summary
+
+The [Script](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/scripting.html#Script) node selects a program script, specified by a URL.
+
+Program scripts have field and event interface declarations, each with:
+
+- A data type
+- A name
+- An initial value (fields only)

package/docs/tutorials/Lighting-your-world.md

@@ -0,0 +1,139 @@
+# Lighting Your World
+
+## Motivation
+
+- By default, you have one light in the scene, attached to your head
+- For more realism, you can add multiple lights
+  - Suns, light bulbs, candles
+  - Flashlights, spotlights, firelight
+- Lights can be positioned, oriented, and colored
+- Lights do not cast shadows
+
+## Using types of lights
+
+There are three types of X3D lights:
+
+- Point lights - radiate in all directions from a point
+- Directional lights - aim in one direction from infinitely far away
+- Spot lights - aim in one direction from a point, radiating in a cone
+
+## Using common lighting features
+
+All lights have several common fields:
+
+- *on* - turn it on or off
+- *intensity* - control brightness
+- *ambientIntensity* - control ambient effect
+- *color* - select color
+
+Point lights and spot lights also have:
+
+- *location* - position
+- *radius* - maximum lighting distance
+- *attenuation* - drop off with distance
+
+Directional lights and spot lights also have:
+
+- *direction* - aim direction
+
+## Syntax: PointLight
+
+A [PointLight](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/lighting.html#PointLight) node illuminates radially from a point:
+
+### XML Encoding
+
+```xml
+<PointLight
+    location='0.0 0.0 0.0'
+    intensity='1.0'
+    color='1.0 1.0 1.0'/>
+```
+
+### Classic Encoding
+
+```js
+PointLight {
+  location  0.0 0.0 0.0
+  intensity 1.0
+  color     1.0 1.0 1.0
+}
+```
+
+## Syntax: DirectionalLight
+
+A [DirectionalLight](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/lighting.html#DirectionalLight) node illuminates in one direction from infinitely far away:
+
+### XML Encoding
+
+```xml
+<DirectionalLight
+    direction='1.0 0.0 0.0'
+    intensity='1.0'
+    color='1.0 1.0 1.0'/>
+```
+
+### Classic Encoding
+
+```js
+DirectionalLight {
+  direction 1.0 0.0 0.0
+  intensity 1.0
+  color     1.0 1.0 1.0
+}
+```
+
+## Syntax: SpotLight
+
+A [SpotLight](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/lighting.html#SpotLight) node illuminates from a point, in one direction, within a cone:
+
+### XML Encoding
+
+```xml
+<SpotLight
+    location='0.0 0.0 0.0'
+    direction='1.0 0.0 0.0'
+    intensity='1.0'
+    color='1.0 1.0 1.0'
+    cutOffAngle='0.785'/>
+```
+
+### Classic Encoding
+
+```js
+SpotLight {
+  location    0.0 0.0 0.0
+  direction   1.0 0.0 0.0
+  intensity   1.0
+  color       1.0 1.0 1.0
+  cutOffAngle 0.785
+}
+```
+
+- The maximum width of a spot light's cone is controlled by the cutOffAngle field
+- An inner cone region with constant brightness is controlled by the beamWidth field
+
+### XML Encoding
+
+```xml
+<SpotLight
+    ...
+    cutOffAngle='0.785'
+    beamWidth='0.52'/>
+```
+
+### Classic Encoding
+
+```js
+SpotLight {
+  ...
+  cutOffAngle 0.785
+  beamWidth   0.52
+}
+```
+
+## Summary
+
+- There are three types of lights: point, directional, and spot
+- All lights have an on/off, intensity, ambient effect, and color
+- Point and spot lights have a location, radius, and attenuation
+- Directional and spot lights have a direction

package/docs/tutorials/Mapping-textures.md

@@ -0,0 +1,212 @@
+# Mapping Textures
+
+## Motivation
+
+You can model every tiny texture detail of a world using a vast number of colored faces:
+
+- Takes a long time to write the X3D
+- Takes a long time to draw
+
+Use a trick instead:
+
+- Take a picture of the real thing
+- Paste that picture on the shape, like sticking on a decal
+
+This technique is called Texture Mapping
+
+## Using image textures
+
+Image texture:
+
+- Uses a single image from a file in one of these formats:
+
+|      |                                                                                                                              |
+|------|------------------------------------------------------------------------------------------------------------------------------|
+| GIF  | 8-bit lossless compressed images 1 transparency color                                                                        |
+| JPEG | Usually a poor choice for texture mapping 8-bit thru 24-bit lossy compressed images No transparency support                  |
+| PNG  | An adequate choice for texture mapping 8-bit thru 24-bit lossless compressed images 8-bit transparency per pixel Best choice |
+
+## Using pixel textures
+
+Pixel texture:
+
+- A single image, given in the VRML file itself
+- The image is encoded using hex
+  - Up to 10 bytes per pixel
+  - Very inefficient
+  - Only useful for very small textures
+  - Stripes
+  - Checkerboard patterns
+
+## Using movie textures
+
+Movie texture:
+
+- A movie from an MP4 file
+- The movie plays back on the textured shape
+
+## Syntax: Appearance
+
+An [Appearance](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Appearance) node describes overall shape appearance:
+
+- *texture* - texture source
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material ... />
+    <ImageTexture ... />
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { ... }
+    texture ImageTexture { ... }
+  }
+  geometry ...
+}
+```
+
+## Syntax: ImageTexture
+
+An [ImageTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#ImageTexture) node selects a texture image for texture mapping:
+
+- *url* - texture image file URL
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material/>
+    <ImageTexture
+        url='"wood.jpg"'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { }
+    texture ImageTexture {
+      url "wood.jpg"
+    }
+  }
+  geometry ...
+}
+```
+
+## Syntax: PixelTexture
+
+A [PixelTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#PixelTexture) node specifies texture image pixels for texture mapping:
+
+- *image* - texture image pixels
+- Image data - width, height, bytes/pixel, pixel values
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material/>
+    <PixelTexture
+        image='2 1 3
+          0xFFFF00 0xFF0000'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { }
+    texture PixelTexture {
+      image 2 1 3
+        0xFFFF00 0xFF0000
+    }
+  }
+  geometry ...
+}
+```
+
+## Syntax: MovieTexture
+
+A [MovieTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture) node selects a texture movie for texture mapping:
+
+- *url* - texture movie file URL
+- When to play the movie, and how quickly (like a TimeSensor node)
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material/>
+    <MovieTexture
+        url='"movie.mp4"'
+        loop='true'
+        speed='1.0'
+        startTime='0.0'
+        stopTime='0.0'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { }
+    texture MovieTexture {
+      url "movie.mp4"
+      loop TRUE
+      speed 1.0
+      startTime 0.0
+      stopTime 0.0
+    }
+  }
+  geometry ...
+}
+```
+
+## Using materials with textures
+
+- Color textures override the color in a [Material](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Material) node
+- Grayscale textures multiply with the Material node color
+  - Good for colorizing grayscale textures
+- If there is no Material node, the texture is applied emissively
+
+## Using transparent textures
+
+Texture images can include color and transparency values for each pixel:
+
+- Pixel transparency is also known as alpha
+
+Pixel transparency enables you to make parts of a shape transparent:
+
+- Windows, grillwork, holes
+- Trees, clouds
+
+## Summary
+
+- A texture is like a decal pasted to a shape
+- Specify the texture using an [ImageTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#ImageTexture), [PixelTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#PixelTexture), or [MovieTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture) node in an [Appearance](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Appearance) node
+- Color textures override material, grayscale textures multiply
+- Textures with transparency create holes