x_ite 4.2.17 → 4.7.7

package/docs/tutorials/Adding-sound.md

@@ -0,0 +1,326 @@
+# Adding Sound
+
+## Motivation
+
+- Sounds can be triggered by viewer actions
+  - Clicks, horn honks, door latch noises
+- Sounds can be continuous in the background
+  - Wind, crowd noises, elevator music
+- Sounds emit from a location, in a direction, within an area
+
+## Creating sounds
+
+Sounds have two components:
+
+- A sound source providing a sound signal
+  - Like a stereo component
+- A sound emitter converts a signal to virtual sound
+  - Like a stereo speaker
+
+## Syntax: AudioClip
+
+An [AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) node creates a digital sound source:
+
+- *url* - a sound file URL
+- *pitch* - playback speed
+- playback controls, like a [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node
+
+### XML Encoding
+
+```xml
+<Sound>
+  <AudioClip
+      url='"myfile.mp3"'
+      pitch='1.0'
+      startTime='0.0'
+      stopTime='0.0'
+      loop='false'/>
+</Sound>
+```
+
+### Classic Encoding
+
+```js
+Sound {
+  source AudioClip {
+    url "myfile.mp3"
+    pitch 1.0
+    startTime 0.0
+    stopTime  0.0
+    loop FALSE
+  }
+}
+```
+
+## Syntax: MovieTexture
+
+A [MovieTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture) node creates a movie sound source:
+
+- *url* - a texture movie file URL
+- *speed* - playback speed
+- playback controls, like a [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node
+
+### XML Encoding
+
+```xml
+<Sound>
+  <MovieTexture containerField='source'
+      url='"movie.mp4"'
+      speed='1.0'
+      startTime='0.0'
+      stopTime='0.0'
+      loop='false'/>
+</Sound>
+```
+
+### Classic Encoding
+
+```js
+Sound {
+  source MovieTexture {
+    url "movie.mp4"
+    speed 1.0
+    startTime 0.0
+    stopTime  0.0
+    loop FALSE
+  }
+}
+```
+
+## Selecting sound source types
+
+Supported by the [AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) node:
+
+- MP3 or WAV - digital sound files
+  Good for sound effects
+
+Supported by the [MovieTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture) node:
+
+- MP4 - movie file with sound
+  Good for virtual TVs
+
+## Syntax: Sound
+
+A [Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node describes a sound emitter:
+
+- *source* - [AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) or [MovieTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture) node
+- *location* and *direction* - emitter placement
+
+### XML Encoding
+
+```xml
+<Sound
+    location='0.0 0.0 0.0'
+    direction='0.0 0.0 1.0'>
+  <AudioClip ... />
+</Sound>
+```
+
+### Classic Encoding
+
+```js
+Sound {
+  source AudioClip { ... }
+  location  0.0 0.0 0.0
+  direction 0.0 0.0 1.0
+}
+```
+
+A [Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node describes a sound emitter:
+
+- *intensity* - volume
+- *spatialize* - use spatialize processing
+- *priority* - prioritize the sound
+
+### XML Encoding
+
+```xml
+<Sound
+    ...
+    intensity='1.0'
+    spatialize='true'
+    priority='0.0'>
+</Sound>
+```
+
+### Classic Encoding
+
+```js
+Sound {
+  ...
+  intensity 1.0
+  spatialize TRUE
+  priority 0.0
+}
+```
+
+A [Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node describes a sound emitter:
+
+- *minFront, minBack* - inner ellipsoid
+- *maxFront, maxBack* - outer ellipsoid
+
+## Setting the sound range
+
+- The sound range fields specify two ellipsoids
+  - *minFront* and *minBack* control an inner ellipsoid
+  - *maxFront* and *maxBack* control an outer ellipsoid
+- Sound has a constant volume inside the inner ellipsoid
+- Sound drops to zero volume from the inner to the outer ellipsoid
+
+## Creating triggered sounds
+
+[AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) node:
+
+- *loop* **FALSE**
+- Set *startTime* from a sensor node
+
+[Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node:
+
+- *spatialize* **TRUE**
+- *minFront* etc. with small values
+- *priority* 1.0
+
+## A sample using triggered sound
+
+### XML Encoding
+
+```xml
+<Group>
+  <Shape>
+    <Appearance>
+      <Material
+          diffuseColor='1 1 1'/>
+    </Appearance>
+    <Box
+        size='0.23 0.1 1.5'/>
+  </Shape>
+  <TouchSensor DEF='C4'/>
+  <Sound
+      maxBack='100'
+      maxFront='100'>
+    <AudioClip DEF='PitchC4'
+        url='"tone1.mp3"'/>
+  </Sound>
+</Group>
+<ROUTE fromNode='C4' fromField='touchTime' toNode='PitchC4' toField='set_startTime'/>
+```
+
+### Classic Encoding
+
+```js
+Group {
+  children [
+    Shape {
+      appearance Appearance {
+        material Material {
+          diffuseColor 1.0 1.0 1.0
+        }
+      }
+      geometry Box {
+        size 0.23 0.1 1.5
+      }
+    }
+    DEF C4 TouchSensor { }
+    Sound {
+      maxFront 100.0
+      maxBack 100.0
+      source DEF PitchC4 AudioClip {
+        url "tone1.mp3"
+        pitch 1.0
+      }
+    }
+  ]
+}
+ROUTE C4.touchTime TO PitchC4.set_startTime
+```
+
+[![LOD](https://create3000.github.io/media/tutorials/scenes/sound/screenshot.png)](https://create3000.github.io/media/tutorials/scenes/sound/example.html)
+
+[View scene in this window.](https://create3000.github.io/media/tutorials/scenes/sound/example.html)
+
+[Download ZIP Archive](https://create3000.github.io/media/tutorials/scenes/sound/sound.zip)
+
+## Creating continuous localized sounds
+
+[AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) node:
+
+- *loop* **TRUE**
+- *startTime* 0.0 (default)
+- *stopTime* 0.0 (default)
+
+[Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node:
+
+- *spatialize* **TRUE** (default)
+- *minFront* etc. with medium values
+- *priority* 0.0 (default)
+
+## A sample using continuous localized sound
+
+### XML Encoding
+
+```xml
+<Sound
+    minBack='5'
+    minFront='5'>
+  <AudioClip
+      url='"willow1.mp3"'
+      loop='true'
+      startTime='1'/>
+</Sound>
+<Transform
+    translation='0 -1.65 0'>
+  <Inline
+      url='"sndmark.wrl"'/>
+</Transform>
+```
+
+### Classic Encoding
+
+```js
+Sound {
+  minFront 5.0
+  minBack  5.0
+  maxFront 10.0
+  maxBack  10.0
+  source AudioClip {
+    url "willow1.mp3"
+    loop TRUE
+    startTime 1.0
+    stopTime 0.0
+  }
+}
+Transform {
+  translation 0.0 -1.65 0.0
+  children [
+    Inline {
+      url "sndmark.wrl"
+    }
+  ]
+}
+```
+
+## Creating continuous background sounds
+
+[AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) node:
+
+- *loop* **TRUE**
+- *startTime* 0.0 (default)
+- *stopTime* 0.0 (default)
+
+[Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node:
+
+- *spatialize* **FALSE** (default)
+- *minFront* etc. with large values
+- *priority* 0.0 (default)
+
+## Summary
+
+An [AudioClip](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#AudioClip) node or a [MovieTexture](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#MovieTexture) node describe a sound source:
+
+- A URL gives the sound file
+- Looping, start time, and stop time control playback
+
+A [Sound](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/sound.html#Sound) node describes a sound emitter:
+
+- A source node provides the sound
+- Range fields describe the sound volume

package/docs/tutorials/Animating-transforms.md

@@ -0,0 +1,385 @@
+# Animating Transforms
+
+## Motivation
+
+An animation changes something over time:
+
+- position - a car driving
+- orientation - an airplane banking
+- color - seasons changing
+
+Animation requires control over time:
+
+- When to start and stop
+- How fast to go
+
+## Controlling time
+
+- A [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node is similar to a stop watch
+  - You control the start and stop time
+- The sensor generates time events while it is running
+- To animate, route time events into other nodes
+
+## Using absolute time
+
+- A [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node generates absolute and fractional time events
+- Absolute time events give the wall-clock time
+  - Absolute time is measured in seconds since 12:00am January 1, 1970!
+  - Useful for triggering events at specific dates and times
+
+## Using fractional time
+
+- Fractional time events give a number from 0.0 to 1.0
+  - When the sensor starts, it outputs a 0.0
+  - At the end of a cycle, it outputs a 1.0
+  - The number of seconds between 0.0 and 1.0 is controlled by the cycle interval
+- The sensor can loop forever, or run through only one cycle and stop
+
+## Syntax: TimeSensor
+
+- A [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node generates events based upon time
+  - *startTime* and *stopTime* - when to run
+  - *cycleInterval* - how long a cycle is
+  - *loop* - whether or not to repeat cycles
+
+### XML Encoding
+
+```xml
+<TimeSensor
+    cycleInterval='1.0'
+    loop='false'
+    startTime='0.0'
+    stopTime='0.0'/>
+```
+
+### Classic Encoding
+
+```js
+TimeSensor {
+  cycleInterval 1.0
+  loop FALSE
+  startTime 0.0
+  stopTime 0.0
+}
+```
+
+## Using timers
+
+To create a continuously running timer:
+
+- *loop* **TRUE**
+- *stopTime* &lt;= *startTime*
+
+When stop time &lt;= start time, stop time is ignored
+
+To run until the stop time:
+
+- *loop* **TRUE**
+- *stopTime* &gt; *startTime*
+
+To run one cycle then stop:
+
+- *loop* **FALSE**
+- *stopTime* &lt;= *startTime*
+
+The *set\_startTime* input event:
+
+- Sets when the timer should start
+
+The *set\_stopTime* input event:
+
+- Sets when the timer should stop
+
+## Using timer outputs
+
+The isActive output event:
+
+- Outputs TRUE at timer start
+- Outputs FALSE at timer stop
+
+The time output event:
+
+- Outputs the absolute time
+
+The fraction\_changed output event:
+
+- Outputs values from 0.0 to 1.0 during a cycle
+- Resets to 0.0 at the start of each cycle
+
+## A sample time sensor
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material DEF='Monolith1Facade'
+        diffuseColor='0.2 0.2 0.2'/>
+  </Appearance>
+  <Box size='2.0 4.0 0.3'/>
+</Shape>
+<TimeSensor DEF='Monolith1Timer'
+    cycleInterval='4.0'
+    loop='false'
+    startTime='0.0'
+    stopTime='0.1'/>
+
+<ROUTE fromNode='Monolith1Touch' fromField='touchTime' toNode='Monolith1Timer' toField='set_startTime'/>
+<ROUTE fromNode='Monolith1Timer' fromField='fraction_changed' toNode='Monolith1Facade' toField='set_transparency'/>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material DEF Monolith1Facade Material {
+      diffuseColor 0.2 0.2 0.2
+    }
+  }
+  geometry Box { size 2.0 4.0 0.3 }
+}
+DEF Monolith1Timer TimeSensor {
+  cycleInterval 4.0
+  loop FALSE
+  startTime 0.0
+  stopTime  0.1
+}
+
+ROUTE Monolith1Touch.touchTime TO Monolith1Timer.set_startTime
+ROUTE Monolith1Timer.fraction_changed TO Monolith1Facade.set_transparency
+```
+
+## Converting time to position
+
+To animate the position of a shape you provide:
+
+- A list of key positions for a movement path
+- A time at which to be at each position
+
+An interpolator node converts an input time to an output position
+
+- When a time is in between two key positions, the interpolator computes an intermediate position
+
+## Interpolating positions
+
+Each key position along a path has:
+
+- A key value (such as a position)
+- A key fractional time
+
+Interpolation fills in values between your key values:
+
+| Fractional Time | Position      |
+|-----------------|---------------|
+| 0.0             | 0.0 0.0 0.0   |
+| *0.1*           | *0.4 0.1 0.0* |
+| *0.2*           | *0.8 0.2 0.0* |
+| *...*           | *...*         |
+| 0.5             | 4.0 1.0 0.0   |
+| *...*           | *...*         |
+
+## Syntax: PositionInterpolator
+
+A [PositionInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#PositionInterpolator) node describes a position path
+
+- *key* - key fractional times
+- *keyValue* - key positions
+
+### XML Encoding
+
+```xml
+<PositionInterpolator
+    key='0.0, ...'
+    keyValue='0.0 0.0 0.0, ...'/>
+```
+
+### Classic Encoding
+
+```js
+PositionInterpolator {
+  key [ 0.0, ... ]
+  keyValue [ 0.0 0.0 0.0, ... ]
+}
+```
+
+Typically route into a [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) node's *set\_translation* input
+
+## Using position interpolator inputs and outputs
+
+The *set\_fraction* input:
+
+- Sets the current fractional time along the key path
+
+The *value\_changed* output:
+
+- Outputs the position along the path each time the fraction is set
+
+## A sample using position interpolators
+
+### XML Encoding
+
+```xml
+<Transform DEF='Particle1'
+  <Shape><!-- ... --></Shape>
+</Transform>
+
+<TimeSensor DEF='Timer1'
+    cycleInterval='12.0'
+    loop='true'
+    startTime='0.0'
+    stopTime='-1.0'/>
+
+<PositionInterpolator DEF='Position1'
+    key='0.0, ...'
+    keyValue='0.0 0.0 0.0, ...'/>
+
+<ROUTE fromNode='Timer1' fromField='fraction_changed' toNode='Position1' toField='set_fraction'/>
+<ROUTE fromNode='Position1' fromField='value_changed' toNode='Particle1' toField='set_translation'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Particle1 Transform {
+  children [
+    Shape { ... }
+  ]
+}
+
+DEF Timer1 TimeSensor {
+  cycleInterval 12.0
+  loop TRUE
+  startTime 0.0
+  stopTime -1.0
+}
+
+DEF Position1 PositionInterpolator {
+  key  [ 0.0, ... ]
+  keyValue [ 0.0 0.0 0.0, ... ]
+}
+
+ROUTE Timer1.fraction_changed TO Position1.set_fraction
+ROUTE Position1.value_changed TO Particle1.set_translation
+```
+
+## Using other types of interpolators
+
+|                      |                             |
+|----------------------|-----------------------------|
+| Animate position     | [PositionInterpolator][]    |
+| Animate rotation     | [OrientationInterpolator][] |
+| Animate scale        | [PositionInterpolator][]    |
+| Animate color        | [ColorInterpolator][]       |
+| Animate transparency | [ScalarInterpolator][]      |
+
+  [PositionInterpolator]: https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#PositionInterpolator
+  [OrientationInterpolator]: https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#OrientationInterpolator
+  [ColorInterpolator]: https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#ColorInterpolator
+  [ScalarInterpolator]: https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#ScalarInterpolator
+
+## Syntax: OrientationInterpolator
+
+A [OrientationInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#OrientationInterpolator) node describes an orientation path
+
+- *key* - key fractional times
+- *keyValue* - key rotations (axis and angle)
+
+### XML Encoding
+
+```xml
+<OrientationInterpolator
+    key='0.0, ...'
+    keyValue='0.0 1.0 0.0 0.0, ...'/>
+```
+
+### Classic Encoding
+
+```js
+OrientationInterpolator {
+  key [ 0.0, ... ]
+  keyValue [ 0.0 1.0 0.0 0.0, ... ]
+}
+```
+
+Typically route into a [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) node's *set\_rotation* input
+
+## Syntax: ColorInterpolator
+
+[ColorInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#ColorInterpolator) node describes a color path
+
+- *key* - key fractional times
+- *keyValue* - key colors (red, green, blue)
+
+### XML Encoding
+
+```xml
+<ColorInterpolator
+    key='0.0, ...'
+    keyValue='1.0 1.0 0.0, ...'/>
+```
+
+### Classic Encoding
+
+```js
+ColorInterpolator {
+  key [ 0.0, ... ]
+  keyValue [ 1.0 1.0 0.0, ... ]
+}
+```
+
+Typically route into a [Material](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Material) node's *set\_diffuseColor* or *set\_emissiveColor* inputs
+
+## Syntax: ScalarInterpolator
+
+[ScalarInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#ScalarInterpolator) node describes a scalar path
+
+- *key* - key fractional times
+- *keyValue* - key scalars (used for anything)
+
+### XML Encoding
+
+```xml
+<ScalarInterpolator
+    key='0.0, ...'
+    keyValue='4.5, ...'/>
+```
+
+### Classic Encoding
+
+```js
+ScalarInterpolator {
+  key [ 0.0, ... ]
+  keyValue [ 4.5, ... ]
+}
+```
+
+Often route into a [Material](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Material) node's *set\_transparency* input
+
+## Summary
+
+The [TimeSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/time.html#TimeSensor) node's fields control:
+
+- Timer start and stop times
+- The cycle interval
+- Whether the timer loops or not
+
+The sensor outputs:
+
+- true/false on *isActive* at start and stop
+- absolute time on time while running
+- fractional time on *fraction\_changed* while running
+
+Interpolators use key times and values and compute intermediate values
+
+All interpolators have:
+
+- a *set\_fraction* input to set the fractional time
+- a *value\_changed* output to send new values
+
+Some interpolators are:
+
+- The [PositionInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#PositionInterpolator) node converts times to positions (or scales)
+- The [OrientationInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#OrientationInterpolator) node converts times to rotations
+- The [ColorInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#ColorInterpolator) node converts times to colors
+- The [ScalarInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#ScalarInterpolator) node converts times to scalars (such as transparencies)