x_ite 4.2.17 → 4.7.7

package/docs/tutorials/Naming-nodes.md

@@ -0,0 +1,161 @@
+# Naming Nodes
+
+## Motivation
+
+- If several shapes have the same geometry or appearance, you must use multiple duplicate nodes, one for each use
+- Instead, define a name for the first occurrence of a node
+- Later, use that name to share the same node in a new context
+
+## Syntax: DEF
+
+The **DEF** syntax gives a name to a node.
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material DEF='RedColor'
+        diffuseColor='1.0 0.0 0.0'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material DEF RedColor Material {
+      diffuseColor 1.0 0.0 0.0
+    }
+  }
+  geometry ...
+}
+```
+
+## Using DEF
+
+- **DEF** must be in upper-case
+- You can name any node
+- Names can be most any sequence of letters and numbers
+  - Names must be unique within a file
+
+## Syntax: USE
+
+The **USE** syntax uses a previously named node
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material USE='RedColor'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material USE RedColor
+  }
+  geometry ...
+}
+```
+
+## Using USE
+
+- **USE** must be in upper-case
+- A re-use of a named node is called an instance
+- A named node can have any number of instances
+  - Each instance shares the same node description
+  - You can only instance names defined in the same file
+
+## Using named nodes
+
+Naming and using nodes:
+
+- Saves typing
+- Reduces file size
+- Enables rapid changes to shapes with the same attributes
+- Speeds browser processing
+
+Names are also necessary for animation ...
+
+## A sample use of node names
+
+### XML Encoding
+
+```xml
+<Inline
+    url='"table.x3dv"'/>
+<Transform
+    translation='0.95 0 0'>
+  <Inline DEF='Chair'
+      url='"chair.x3dv"'/>
+</Transform>
+<Transform
+    translation='-0.95 0 0'
+    rotation='0 1 0 3.14'>
+  <Inline USE='Chair'/>
+</Transform>
+<Transform
+    translation='0 0 0.95'
+    rotation='0 1 0 4.71318530717959'>
+  <Inline USE='Chair'/>
+</Transform>
+<Transform
+    translation='0 0 -0.95'
+    rotation='0 1 0 1.57'>
+  <Inline USE='Chair'/>
+</Transform>
+```
+
+### Classic Encoding
+
+```js
+Inline {
+  url "table.x3dv"
+}
+
+Transform {
+  translation 0.95 0.0 0.0
+  children DEF Chair Inline {
+    url "chair.x3dv"
+  }
+}
+
+Transform {
+  translation -0.95 0.0 0.0
+  rotation 0.0 1.0 0.0 3.14
+  children USE Chair
+}
+
+Transform {
+  translation 0.0 0.0 0.95
+  rotation 0.0 1.0 0.0 -1.57
+  children USE Chair
+}
+
+Transform {
+  translation 0.0 0.0 -0.95
+  rotation 0.0 1.0 0.0 1.57
+  children USE Chair
+}
+```
+
+[![Dinette](https://create3000.github.io/media/tutorials/scenes/dinette/screenshot.png)](https://create3000.github.io/media/tutorials/scenes/dinette/example.html)
+
+[View scene in this window.](https://create3000.github.io/media/tutorials/scenes/dinette/example.html)
+
+[Download ZIP Archive](https://create3000.github.io/media/tutorials/scenes/dinette/dinette.zip)
+
+## Summary
+
+- **DEF** names a node
+- **USE** uses a named node

package/docs/tutorials/Providing-information-about-your-world.md

@@ -0,0 +1,30 @@
+# Providing Information About Your World
+
+## Motivation
+
+- After you've created a great world, sign it!
+- You can provide a title and a description embedded within the file
+
+## Syntax: WorldInfo
+
+A [WorldInfo](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#WorldInfo) node provides title and description information for your world:
+
+- *title* - the name for your world
+- *info* - any additional information
+
+### XML Encoding
+
+```xml
+<WorldInfo
+    title='Our Masterpiece'
+    info='"License GPLv3, https://www.gnu.org/licenses/gpl-3.0.en.html"'/>
+```
+
+### Classic Encoding
+
+```js
+WorldInfo {
+  title "Our Masterpiece"
+  info  [ "License GPLv3, https://www.gnu.org/licenses/gpl-3.0.en.html" ]
+}
+```

package/docs/tutorials/Sensing-the-viewer.md

@@ -0,0 +1,205 @@
+# Sensing the Viewer
+
+## Motivation
+
+Sensing the viewer enables you to trigger animations:
+
+- when a region is visible to the viewer
+- when the viewer is within a region
+- when the viewer collides with a shape
+
+The [LOD](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#LOD) and [Billboard](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Billboard) nodes are special-purpose viewer sensors with built-in responses.
+
+## Sensing the viewer
+
+There are three types of viewer sensors:
+
+- A [VisibilitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#VisibilitySensor) node senses if the viewer can see a region
+- A [ProximitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#ProximitySensor) node senses if the viewer is within a region
+- A [Collision](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Collision) node senses if the viewer has collided with shapes
+
+## Using visibility and proximity sensors
+
+[VisibilitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#VisibilitySensor) and [ProximitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#ProximitySensor) nodes sense a box-shaped region:
+
+- *center* - region center
+- *size* - region dimensions
+
+Both nodes have similar outputs:
+
+- *enterTime* - sends time on visible or region entry
+- *exitTime* - sends time on not visible or region exit
+- *isActive* - sends true on entry, false on exit
+
+## Syntax: VisibilitySensor
+
+A [VisibilitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#VisibilitySensor) node senses if the viewer sees or stops seeing a region:
+
+- *center* and *size* - the region's location and size
+- *enterTime* and *exitTime* - sends time on entry/exit
+- *isActive* - sends true/false on entry/exit
+
+### XML Encoding
+
+```xml
+<VisibilitySensor DEF='Sensor'
+    center='0.0 0.0 0.0'
+    size='14.0 14.0 14.0'/>
+
+<ROUTE fromNode='Sensor' fromField='enterTime' toNode='Clock' toField='set_startTime'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Sensor VisibilitySensor {
+  center 0.0 0.0 0.0
+  size   14.0 14.0 14.0
+}
+
+ROUTE Sensor.enterTime TO Clock.set_startTime
+```
+
+## Syntax: ProximitySensor
+
+A [ProximitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#ProximitySensor) node senses if the viewer enters or leaves a region:
+
+- *center* and *size* - the region's location and size
+- *enterTime* and *exitTime* - sends time on entry/exit
+- *isActive* - sends true/false on entry/exit
+
+### XML Encoding
+
+```xml
+<ProximitySensor DEF='Sensor'
+    center='0.0 0.0 0.0'
+    size='14.0 14.0 14.0'/>
+
+<ROUTE fromNode='Sensor' fromField='enterTime' toNode='Clock' toField='set_startTime'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Sensor ProximitySensor {
+  center 0.0 0.0 0.0
+  size   14.0 14.0 14.0
+}
+
+ROUTE Sensor.enterTime TO Clock.set_startTime
+```
+
+A [ProximitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#ProximitySensor) node senses the viewer while in a region:
+
+- *position* and *orientation* - sends position and orientation while viewer is in the region
+
+### XML Encoding
+
+```xml
+<ProximitySensor DEF='Sensor' ... />
+
+<ROUTE fromNode='Sensor' fromField='position_changed' toNode='PetRobotFollower' toField='set_translation'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Sensor ProximitySensor { ... }
+
+ROUTE Sensor.position_changed TO PetRobotFollower.set_translation
+```
+
+## Detecting viewer-shape collision
+
+A [Collision](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Collision) grouping node senses shapes within the group:
+
+- Detects if the viewer collides with any shape in the group
+- Automatically stops the viewer from going through the shape
+
+Collision occurs when the viewer's avatar gets close to a shape:
+
+- Collision distance is controlled by the avatar size in the [NavigationInfo](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#NavigationInfo) node
+
+## Creating collision groups
+
+Collision checking is expensive so, check for collision with a proxy shape instead:
+
+- Proxy shapes are typically extremely simplified versions of the actual shapes
+- Proxy shapes are never drawn
+
+A collision group with a proxy shape, but no children, creates an invisible collidable shape:
+
+- Windows and invisible railings
+- Invisible world limits
+
+## Syntax: Collision
+
+A [Collision](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Collision) grouping node senses if the viewer collides with group shapes:
+
+- *enabled* - enable/disable sensor
+- *proxy* - simple shape to sense instead of children
+- *children* - children to sense
+- *collideTime* - sends time on collision
+
+### XML Encoding
+
+```xml
+<Collision DEF='Collide'
+    enabled='true'>
+  <Shape containerField='proxy'>
+    <Box ... />
+  </Shape>
+  <!-- children ... -->
+</Collision>
+
+<ROUTE fromNode='Collide' fromField='collideTime' toNode='OuchSound' toField='set_startTime'/>
+```
+
+### Classic Encoding
+
+```js
+DEF Collide Collision {
+  enabled TRUE
+  proxy Shape {
+    geometry Box { ... }
+  }
+  children [ ... ]
+}
+
+ROUTE Collide.collideTime TO OuchSound.set_startTime
+```
+
+## Optimizing collision detection
+
+- Collision is on by default
+  - Turn it off whenever possible!
+- However, once a parent turns off collision, a child can't turn it back on!
+- Collision results from viewer colliding with a shape, but not from a shape colliding with a viewer
+
+## Using multiple sensors
+
+Any number of sensors can sense at the same time:
+
+- You can have multiple visibility, proximity, and collision sensors
+- Sensor areas can overlap
+- If multiple sensors should trigger, they do
+
+## Summary
+
+A [VisibilitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#VisibilitySensor) node checks if a region is visible to the viewer:
+
+- The region is described by a center and a size
+- Time is sent on entry and exit of visibility
+- True/false is sent on entry and exit of visibility
+
+A [ProximitySensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/envsensor.html#ProximitySensor) node checks if the viewer is within a region:
+
+- The region is described by a center and a size
+- Time is sent on viewer entry and exit
+- True/false is sent on viewer entry and exit
+- Position and orientation of the viewer is sent while within the sensed region
+
+A [Collision](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Collision) grouping node checks if the viewer has run into a shape:
+
+- The shapes are defined by the group's children or a proxy
+- Collision time is sent on contact

package/docs/tutorials/Sensing-viewer-actions.md

@@ -0,0 +1,214 @@
+# Sensing Viewer Actions
+
+## Motivation
+
+You can sense when the viewer's cursor:
+
+- Is over a shape
+- Has touched a shape
+- Is dragging atop a shape
+
+What can you do:
+
+- You can trigger animations on a viewer's touch
+- You can enable the viewer to move and rotate shapes
+
+## Using action sensors
+
+There are four main action sensor types:
+
+- [TouchSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#TouchSensor) senses touch
+- [SphereSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#SphereSensor) senses drags
+- [CylinderSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#CylinderSensor) senses drags
+- [PlaneSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#PlaneSensor) senses drags
+
+The [Anchor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#Anchor) node is a special-purpose action sensor with a built-in response.
+
+## Sensing shapes
+
+- All action sensors sense all shapes in the same group
+- Sensors trigger when the viewer's cursor touches a sensed shape
+
+## Syntax: TouchSensor
+
+A [TouchSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#TouchSensor) node senses the cursor's touch:
+
+- *isOver* - send true/false when cursor over/not over
+- *isActive* - send true/false when mouse button pressed/released
+- *touchTime* - send time when mouse button released
+
+### XML Encoding
+
+```xml
+<Transform>
+  <TouchSensor DEF='Touched'/>
+  <Shape><!-- ... --></Shape>
+  <!-- ... -->
+</Transform>
+```
+
+### Classic Encoding
+
+```js
+Transform {
+  children [
+    DEF Touched TouchSensor { }
+    Shape { ... }
+    ...
+  ]
+}
+```
+
+## A sample use of a TouchSensor node
+
+### 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
+```
+
+## Syntax: SphereSensor
+
+A [SphereSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#SphereSensor) node senses a cursor drag and generates rotations as if rotating a ball:
+
+- *isActive* - sends true/false when mouse button pressed/released
+- *rotation\_changed* - sends rotation during a drag
+
+### XML Encoding
+
+```xml
+<Transform>
+  <SphereSensor DEF='Rotator'/>
+  <Transform DEF='RotateMe'><!-- ... --></Transform>
+</Transform>
+<ROUTE fromNode='Rotator' fromField='rotation_changed' toNode='RotateMe' toField='set_rotation'/>
+```
+
+### Classic Encoding
+
+```js
+Transform {
+  children [
+    DEF Rotator  SphereSensor { }
+    DEF RotateMe Transform { ... }
+  ]
+}
+ROUTE Rotator.rotation_changed TO RotateMe.set_rotation
+```
+
+## Syntax: CylinderSensor
+
+A [CylinderSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#CylinderSensor) node senses a cursor drag and generates rotations as if rotating a cylinder:
+
+- *isActive* - sends true/false when mouse button pressed/released
+- *rotation\_changed* - sends rotation during a drag
+
+### XML Encoding
+
+```xml
+<Transform>
+  <CylinderSensor DEF='Rotator'/>
+  <Transform DEF='RotateMe'><!-- ... --></Transform>
+</Transform>
+<ROUTE fromNode='Rotator' fromField='rotation_changed' toNode='RotateMe' toField='set_rotation'/>
+```
+
+### Classic Encoding
+
+```js
+Transform {
+  children [
+    DEF Rotator  CylinderSensor { }
+    DEF RotateMe Transform { ... }
+  ]
+}
+ROUTE Rotator.rotation_changed TO RotateMe.set_rotation
+```
+
+## Syntax: PlaneSensor
+
+A [PlaneSensor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/pointingsensor.html#PlaneSensor) node senses a cursor drag and generates translations as if sliding on a plane:
+
+- *isActive* - sends true/false when mouse button pressed/released
+- *translation\_changed* - sends translations during a drag
+
+### XML Encoding
+
+```xml
+<Transform>
+  <PlaneSensor DEF='Mover'/>
+  <Transform DEF='MoveMe'><!-- ... --></Transform>
+</Transform>
+<ROUTE fromNode='Mover' fromField='translation_changed' toNode='MoveMe' toField='set_translation'/>
+```
+
+### Classic Encoding
+
+```js
+Transform {
+  children [
+    DEF Mover  PlaneSensor { }
+    DEF MoveMe Transform { ... }
+  ]
+}
+ROUTE Mover.translation_changed TO MoveMe.set_translation
+```
+
+## Using multiple sensors
+
+Multiple sensors can sense the same shape but ...
+
+If sensors are in the same group:
+
+- They all respond
+
+If sensors are at different depths in the hierarchy:
+
+- The deepest sensor responds
+- The other sensors do not respond
+
+## Summary
+
+Action sensors sense when the viewer's cursor:
+
+- is over a shape
+- has touched a shape
+- is dragging atop a shape
+
+Sensors convert viewer actions into events to:
+
+- Start and stop animations
+- Orient shapes
+- Position shapes