x_ite 4.0.5 → 4.7.5

package/docs/tutorials/Creating-new-node-types.md

@@ -0,0 +1,313 @@
+# Creating New Node Types
+
+## Motivation
+
+You can create new node types that encapsulate:
+
+- Shapes
+- Sensors
+- Interpolators
+- Scripts
+- anything else ...
+
+This creates high-level nodes:
+
+- Robots, menus, new shapes, etc.
+
+## Syntax: PROTO
+
+A PROTO statement declares a new node type (a prototype):
+
+- name - the new node type name
+- fields, inputs, and outputs - interface to the prototype
+
+### XML Encoding
+
+```xml
+<ProtoDeclare name='BouncingBall'>
+  <ProtoInterface>
+    <field accessType='inputOutput' type='SFTime' name='cycleInterval' value='1'/>
+    <field accessType='inputOutput' type='SFFloat' name='bounceHeight' value='1'/>
+  </ProtoInterface>
+  <ProtoBody>
+    <!-- ... -->
+  </ProtoBody>
+</ProtoDeclare>
+```
+
+### Classic Encoding
+
+```js
+PROTO BouncingBall [
+  inputOutput SFTime  cycleInterval 1.0
+  inputOutput SFFloat bounceHeight  1.0
+]
+{
+  ...
+}
+```
+
+## Defining prototype bodies
+
+**PROTO** defines:
+
+- body - nodes and routes for the new node type
+
+### XML Encoding
+
+```xml
+<ProtoDeclare name='BouncingBall'>
+  <ProtoInterface>
+    <!-- ... -->
+  </ProtoInterface>
+  <ProtoBody>
+    <Transform>
+      <!-- children ... -->
+    </Transform>
+  </ProtoBody>
+</ProtoDeclare>
+```
+
+### Classic Encoding
+
+```js
+PROTO BouncingBall [
+  ...
+]
+{
+  Transform {
+    children [ ... ]
+  }
+  ROUTE ...
+}
+```
+
+## Syntax: IS
+
+The IS syntax connects a prototype interface field, input, or output to the body:
+
+- Like an assignment statement
+- Assigns interface field or input to body
+- Assigns body outputs to interface
+
+Interface items connected by IS need not have the same name as an item in the body, but often do:
+
+### XML Encoding
+
+```xml
+<ProtoDeclare name='BouncingBall'>
+  <ProtoInterface>
+    <field accessType='inputOutput' type='SFTime' name='cycleInterval' value='1'/>
+    <field accessType='inputOutput' type='SFFloat' name='bounceHeight' value='1'/>
+  </ProtoInterface>
+  <ProtoBody>
+    <!-- ... -->
+    <TimeSensor DEF='Clock' ... >
+      <IS>
+        <connect nodeField='cycleInterval' protoField='cycleInterval'/>
+        <!-- ... -->
+      </IS>
+    </TimeSensor>
+    <!-- ... -->
+  </ProtoBody>
+</ProtoDeclare>
+```
+
+### Classic Encoding
+
+```js
+PROTO BouncingBall [
+  inputOutput SFTime  cycleInterval 1.0
+  inputOutput SFFloat bounceHeight  1.0
+]
+{
+  ...
+  DEF Clock TimeSensor {
+    cycleInterval IS cycleInterval
+    ...
+  }
+  ...
+}
+```
+
+## Using IS
+
+May **IS** to ...
+
+| Interface      | initializeOnly | inputOnly | outputOnly | inputOutput |
+|----------------|----------------|-----------|------------|-------------|
+| initializeOnly | yes            | no        | no         | yes         |
+| inputOnly      | no             | yes       | no         | yes         |
+| outputOnly     | no             | no        | yes        | yes         |
+| inputOutput    | no             | no        | no         | yes         |
+
+## Using prototyped nodes
+
+The new node type can be used like any other type.
+
+### XML Encoding
+
+```xml
+<ProtoInstance name='BouncingBall'>
+  <fieldValue name='cycleInterval' value='2'/>
+  <fieldValue name='bounceHeight' value='3'/>
+</ProtoInstance>
+```
+
+### Classic Encoding
+
+```js
+BouncingBall {
+  cycleInterval 2.0
+  bounceHeight  3.0
+}
+```
+
+## Controlling usage rules
+
+Recall that node use must be appropriate for the context:
+
+- A [Shape](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Shape) node specifies shape, not color
+- A [Material](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Material) node specifies color, not shape
+- A [Box](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Box) node specifies geometry, not shape or color
+
+The context for a new node type depends upon the first node in the **PROTO** body.
+
+For example, if the first node is a geometry node:
+
+- The prototype creates a new geometry node type
+
+The new node type can be used wherever the first node of the prototype body can be used.
+
+## A sample prototype use
+
+Create a **BouncingBall** node type that:
+
+- Builds a beachball
+  - Creates an animation clock
+  - Using a **PROTO** field to select the cycle interval
+- Bounces the beachball
+  - Using the bouncing ball program script
+  - Using a **PROTO** field to select the bounce height
+
+Fields needed:
+
+- Bounce height
+- Cycle interval
+
+### XML Encoding
+
+```xml
+<ProtoDeclare name='BouncingBall'>
+  <ProtoInterface>
+    <field accessType='inputOutput' type='SFTime' name='cycleInterval' value='1'/>
+    <field accessType='inputOutput' type='SFFloat' name='bounceHeight' value='1'/>
+  </ProtoInterface>
+  <ProtoBody>
+    <!-- ... -->
+  </ProtoBody>
+</ProtoDeclare>
+```
+
+### Classic Encoding
+
+```js
+PROTO BouncingBall [
+  inputOutput SFTime  cycleInterval 1.0
+  inputOutput SFFloat bounceHeight 1.0
+]
+{
+  ...
+}
+```
+
+Inputs and outputs needed:
+
+- None - a TimeSensor node is built in to the new node
+
+Body needed:
+
+- A ball shape inside a transform
+- An animation clock
+- A bouncing ball program script
+- Routes connecting it all together
+
+### XML Encoding
+
+```xml
+<ProtoDeclare name='BouncingBall'>
+  <ProtoInterface>
+    <!-- ... -->
+  </ProtoInterface>
+  <ProtoBody>
+    <Transform DEF='Ball'>
+      <Shape><!-- ... --></Shape>
+    </Transform>
+    <TimeSensor DEF='Clock' ... />
+    <Script DEF='Bouncer' ... />
+    <ROUTE ... />
+  </ProtoBody>
+</ProtoDeclare>
+```
+
+### Classic Encoding
+
+```js
+PROTO BouncingBall [
+  ...
+]
+{
+  DEF Ball Transform {
+    children [
+      Shape { ... }
+    ]
+  }
+  DEF Clock   TimeSensor { ... }
+  DEF Bouncer Script { ... }
+  ROUTE ...
+}
+```
+
+## Changing a prototype
+
+If you change a prototype, all uses of that prototype change as well
+
+- Prototypes enable world modularity
+- Large worlds make heavy use of prototypes
+
+For the **BouncingBall** prototype, adding a shadow to the prototype makes all balls have a shadow.
+
+## Syntax: EXTERNPROTO
+
+Prototypes are typically in a separate external file, referenced by an **EXTERNPROTO**
+
+- name, fields, events - as from **PROTO,** minus initial values
+- url - the URL of the prototype file
+- \#name - name of **PROTO** in file
+
+### XML Encoding
+
+```xml
+<ExternProtoDeclare name='BouncingBall' url='"bounce.x3dv#BouncingBall", "bounce.x3d#BouncingBall"'>
+  <field accessType='inputOutput' type='SFTime' name='cycleInterval'/>
+  <field accessType='inputOutput' type='SFFloat' name='bounceHeight'/>
+</ExternProtoDeclare>
+```
+
+### Classic Encoding
+
+```js
+EXTERNPROTO BouncingBall [
+  inputOutput SFTime  cycleInterval
+  inputOutput SFFloat bounceHeight
+]
+[
+  "bounce.x3dv#BouncingBall",
+  "bounce.x3d#BouncingBall"
+]
+```
+
+## Summary
+
+- **PROTO** declares a new node type and defines its node body
+- **EXTERNPROTO** declares a new node type, specified by URL

package/docs/tutorials/Grouping-nodes.md

@@ -0,0 +1,237 @@
+# Grouping Nodes
+
+## Motivation
+
+You can group shapes to compose complex shapes
+
+X3D has several grouping nodes, including:
+
+### XML Encoding
+
+```xml
+<Group><!-- ... --></Group>
+<Switch><!-- ... --></Switch>
+<Transform><!-- ... --></Transform>
+<Billboard><!-- ... --></Billboard>
+<Anchor><!-- ... --></Anchor>
+<Inline/>
+<!-- and more -->
+```
+
+### Classic Encoding
+
+```js
+Group       { ... }
+Switch      { ... }
+Transform   { ... }
+Billboard   { ... }
+Anchor      { ... }
+Inline      { ... }
+and more
+```
+
+## Syntax: Group
+
+The [Group](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Group) node creates a basic group.
+
+- Every child node in the group is displayed.
+
+### XML Encoding
+
+```xml
+<Group>
+  <!-- children ... -->
+</Group>
+```
+
+### Classic Encoding
+
+```js
+Group {
+  children [ ... ]
+}
+```
+
+## Syntax: Switch
+
+The [Switch](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Switch) group node creates a switched group
+
+- Only one child node in the group is displayed
+- You select which child
+  - Children implicitly numbered from 0
+  - A -1 selects no children
+
+### XML Encoding
+
+```xml
+<Switch
+    whichChoice='0'>
+  <!-- children ... -->
+</Switch>
+```
+
+### Classic Encoding
+
+```js
+Switch {
+  whichChoice 0
+  children [ ... ]
+}
+```
+
+## Syntax: Transform
+
+The [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) group node creates a group with its own coordinate system.
+
+- Every child node in the group is displayed.
+
+### XML Encoding
+
+```xml
+<Transform
+    translation='0.0 0.0 0.0'
+    rotation='0.0 1.0 0.0 0.0'
+    scale='1.0 1.0 1.0'>
+  <!-- children ... -->
+</Transform>
+```
+
+### Classic Encoding
+
+```js
+Transform {
+  translation 0.0 0.0 0.0
+  rotation 0.0 1.0 0.0 0.0
+  scale 1.0 1.0 1.0
+  children [ ... ]
+}
+```
+
+## Syntax: Billboard
+
+The [Billboard](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Billboard) group node creates a group with a special coordinate system.
+
+- Every child node in the group is displayed.
+- The coordinate system is turned to face viewer.
+
+### XML Encoding
+
+```xml
+<Billboard
+    axisOfRotation='0.0 1.0 0.0'>
+  <!-- children ... -->
+</Billboard>
+```
+
+### Classic Encoding
+
+```js
+Billboard {
+  axisOfRotation 0.0 1.0 0.0
+  children [ ... ]
+}
+```
+
+## Billboard rotation axes
+
+- A rotation axis defines a pole to rotate round
+- Similar to a Transform node's rotation field, but no angle (auto computed)
+- A standard rotation axis limits rotation to spin about that axis
+- A zero rotation axis enables rotation around any axis
+
+| Rotate about | Axis        |
+|--------------|-------------|
+| X-Axis       | 1.0 0.0 0.0 |
+| Y-Axis       | 0.0 1.0 0.0 |
+| Z-Axis       | 0.0 0.0 1.0 |
+| Any Axis     | 0.0 0.0 0.0 |
+
+## A sample billboard group
+
+### XML Encoding
+
+```xml
+<!-- Y-axis -->
+<Billboard
+    axisOfRotation='0.0 1.0 0.0'>
+  <Shape><!-- ... --></Shape>
+  <Shape><!-- ... --></Shape>
+  <Shape><!-- ... --></Shape>
+  <!-- ... -->
+</Billboard>
+```
+
+### Classic Encoding
+
+```js
+Billboard {
+  # Y-axis
+  axisOfRotation 0.0 1.0 0.0
+  children [
+    Shape { ... }
+    Shape { ... }
+    Shape { ... }
+    ...
+  ]
+}
+```
+
+## Syntax: Anchor
+
+An [Anchor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#Anchor) node creates a group that acts as a clickable anchor
+
+- Every child node in the group is displayed
+- Clicking any child follows a URL
+- A description names the anchor
+
+### XML Encoding
+
+```xml
+<Anchor
+    url='"stairwy.wrl"'
+    description='Twisty Stairs'>
+  <!-- children ... -->
+</Anchor>
+```
+
+### Classic Encoding
+
+```js
+Anchor {
+  url "stairwy.wrl"
+  description "Twisty Stairs"
+  children [ ... ]
+}
+```
+
+## Syntax: Inline
+
+An [Inline](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#Inline) node creates a special group from another X3D file's contents
+
+- Children read from file selected by a URL
+- Every child node in group is displayed
+
+### XML Encoding
+
+```xml
+<Inline
+  url='"table.wrl"'/>
+```
+
+### Classic Encoding
+
+```js
+Inline {
+  url "table.wrl"
+}
+```
+
+## Summary
+
+- The [Group](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Group) node creates a basic group
+- The [Switch](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Switch) node creates a group with 1 choice used
+- The [Transform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/group.html#Transform) node creates a group with a new coordinate system
+- The [Billboard](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Billboard) node creates a group with a coordinate system that rotates to face the viewer
+- The [Anchor](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#Anchor) node creates a clickable group
+  - Clicking any child in the group loads a URL
+- The [Inline](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/networking.html#Inline) node creates a special group loaded from another X3D file