write and use a prototype

Prototype is an reusable VRML object.
A prototype is equivalent to a VRML node but it is create by developers.

Note:
Before write a prototype, see prototypes conventions chapter.

This tutorial present the creation of flower prototype (prototype draw a flower).

First, we create a new VRML file in src folder: flower.wrl.

A prototype definition start with PROTO keyword and the name of prototype.

Note:
<name> start by a upper case (by convention).

We start the prototype with the following code:

PROTO Flower[
  ...
] {
  ...
}

We define 7 circles to draw the flower.
Flower color is configurable via a color field and default color is yellow (exposedField SFColor color 0.9 0.9 0.0).
We use IS keyword to use the color field (emissiveColor IS color).
Flower prototype source code :

PROTO Flower [
  exposedField SFColor color 0.9 0.9 0.0
]
{
  Transform2D {
    translation 10.00 0.00
    children [
      Shape {
        appearance DEF CIRCLE_APP Appearance {
          material Material2D { emissiveColor IS color }
        }
        geometry Circle { radius 8 }
      }
    ]
  }
  Transform2D {
    translation 5.00 8.66
    children [
      Shape {
        appearance USE CIRCLE_APP
        geometry Circle { radius 8 }
      }
    ]
  }
  Transform2D {
    translation -5.00 8.66
    children [
      Shape {
        appearance USE CIRCLE_APP
        geometry Circle { radius 8 }
      }
    ]
  }
  Transform2D {
    translation -10.00 0
    children [
      Shape {
        appearance USE CIRCLE_APP
        geometry Circle { radius 8 }
      }
    ]
  }
  Transform2D {
    translation -5.00 -8.66
    children [
      Shape {
        appearance USE CIRCLE_APP
        geometry Circle { radius 8 }
      }
    ]
  }
  Transform2D {
    translation 5.00 -8.66
    children [
      Shape {
        appearance USE CIRCLE_APP
        geometry Circle { radius 8 }
      }
    ]
  }

  Transform2D {
    translation 0.00 0.00
    children [
      DEF CIRCLE Shape {
        appearance Appearance {
          material Material2D { emissiveColor 1.0 1.0 1.0 }
        }
        geometry Circle { radius 8 }
      }
    ]
  }
}

In previous part, we created the Flower prototype. In this part, we use the prototype.

On main VRML file, we declare and import prototype with EXTERNPROTO keyword:

EXTERNPROTO Flower [] "flower.wrl"

Prototype is imported. We can use the prototype in current scene like a node.

Note:
We can use the color field to modify flower color.

EXTERNPROTO Flower [] "flower.wrl"

Group {
  children [
    Transform2D {
      translation 20.00 20.00
      children [
        Flower {} # Default flower color
      ]
    }
    Transform2D {
      translation -20.00 -20.00
      children [
        Flower { color 1.0 0.0 0.0 } # Red flower
      ]
    }
  ]
}

To add interactivity with the prototype, we can use events.
We declare event in fields part with eventIn and eventOut keywords.
eventIn receive an event and we can process it. eventOut send an event and event can be catch by a ROUTE instruction.

Example with flower prototype:

Prototype can receive launchAnimation and stopAnimation event (to launch and stop flower rotation).
When animation start, prototype sends animationStarted event.
At the end of animation, prototype sends animationStopped event.

All flower events return the current time in second.

On flower.wrl file, we declare the events:

PROTO Flower [
  exposedField SFColor color 0.9 0.9 0.0
  eventIn SFTime launchAnimation
  eventIn SFTime stopAnimation
  eventOut SFTime animationStarted
  eventOut SFTime animationStopped
]
{
  ...
}

Flower animation require a timer and a scalar interpolator (See animation tutorial).
We add TimeSensor and ScalarInterpolator node to flower prototype.

Note:
cycleInterval field value is 0, else animation is started when widget is launched.

DEF ANIM_TIMER TimeSensor {
  isActive FALSE
  cycleInterval 0.0
  loop FALSE
}
DEF INTERPOLATOR ScalarInterpolator{
  key      [0.0,  1.0   ]
  keyValue [0.0,  3.1415] # 0 to PI (flower is symmetric, turn flower to 180°)
}

We move flower shapes into a Transform2D node to apply rotation at all circles.

DEF FLOWER_TRS Transform2D {
  children [
    #Flower shapes
    ...
  ]
}

And link timer to interpolator, and interpolator to flower shapes.

ROUTE ANIM_TIMER.fraction_changed TO INTERPOLATOR.set_fraction
ROUTE INTERPOLATOR.value_changed  TO FLOWER_TRS.rotationAngle

Animation part is created. Now, we create a script node to process events and manage animation.

DEF FLOWER_SCRIPT Script {
  ...
}

Into script node, we declare events and fields.
We use IS keyword to link script events to prototype events.

#Event received when user launch animation
eventIn  SFTime launchAnimation  IS launchAnimation
#Event received when user stop animation
eventIn  SFTime stopAnimation    IS stopAnimation
#Event received when animation is stopped (end of animation)
eventIn  SFTime endOfAnimation
#Event sent when animation is started
eventOut SFTime animationStarted IS animationStarted
#Event sent when animation is stopped (end of animation or user stop the animation)
eventOut SFTime animationStopped IS animationStopped
#Timer node (require to start/stop the animation)
field SFNode timer USE ANIM_TIMER;

We create 3 functions to process events.

launchAnimation() function is launched when launchAnimation event is received.
launchAnimation() function starts the timer (and the animation) also if animation is not already started.

//Launch the animation
function launchAnimation (time, now) {
  //Only if animation is not launched
  if ( timer.isActive == false ) {
    //Launch timer
    timer.cycleInterval = 3.0;
    timer.isActive  = true;
    timer.startTime = launchAnimation;
    //Send animationStarted event
    animationStarted = launchAnimation;
  }
}

stopAnimation() function is launched when stopAnimation event is received.
stopAnimation() function stops the timer (and the animation) and sends animationStopped event.

//Stop the animation
function stopAnimation (time, now) {
  //Launch timer
  if ( timer.isActive ) {
    timer.isActive = false;
  }
  //Send animationStarted event
  animationStopped = stopAnimation;
}

endOfAnimation() function is launched when timer is stopped.
endOfAnimation() function sends =animationStopped= event.

//End of animation
function endOfAnimation () {
  //Send animationStopped event
  animationStopped = endOfAnimation;
}

Final prototype source code:

PROTO Flower [
  exposedField SFColor color 0.9 0.9 0.0
  eventIn SFTime launchAnimation
  eventIn SFTime stopAnimation
  eventOut SFTime animationStarted
  eventOut SFTime animationStopped
]
{
  DEF ANIM_TIMER TimeSensor {
    cycleInterval 0.0
    isActive FALSE
    loop FALSE
  }
  DEF INTERPOLATOR ScalarInterpolator{
    key      [0.0,  1.0   ]
    keyValue [0.0,  3.1415] # 0 to PI (flower is symmetric, turn flower to 180°)
  }
  DEF FLOWER_TRS Transform2D {
    children [
      Transform2D {
        translation 10.00 0.00
        children [
          Shape {
            appearance DEF CIRCLE_APP Appearance {
              material Material2D { emissiveColor IS color }
            }
            geometry Circle { radius 8 }
          }
        ]
      }
      Transform2D {
        translation 5.00 8.66
        children [
          Shape {
            appearance USE CIRCLE_APP
            geometry Circle { radius 8 }
          }
        ]
      }
      Transform2D {
        translation -5.00 8.66
        children [
          Shape {
            appearance USE CIRCLE_APP
            geometry Circle { radius 8 }
          }
        ]
      }
      Transform2D {
        translation -10.00 0
        children [
          Shape {
            appearance USE CIRCLE_APP
            geometry Circle { radius 8 }
          }
        ]
      }
      Transform2D {
        translation -5.00 -8.66
        children [
          Shape {
            appearance USE CIRCLE_APP
            geometry Circle { radius 8 }
          }
        ]
      }
      Transform2D {
        translation 5.00 -8.66
        children [
          Shape {
            appearance USE CIRCLE_APP
            geometry Circle { radius 8 }
          }
        ]
      }
      Transform2D {
        translation 0.00 0.00
        children [
          DEF CIRCLE Shape {
            appearance Appearance {
              material Material2D { emissiveColor 1.0 1.0 1.0 }
            }
            geometry Circle { radius 8 }
          }
        ]
      }
    ]
  }
  DEF FLOWER_SCRIPT Script {
    #Event received when user launch animation
    eventIn  SFTime launchAnimation IS launchAnimation
    #Event received when user stop animation
    eventIn  SFTime stopAnimation   IS stopAnimation
    #Event received when animation is stopped (end of animation)
    eventIn  SFTime endOfAnimation
    #Event sent when animation is started
    eventOut SFTime animationStarted IS animationStarted
    #Event sent when animation is stopped (end of animation or user stop the animation)
    eventOut SFTime animationStopped IS animationStopped
    #Timer node (require to start/stop the animation)
    field SFNode timer USE ANIM_TIMER

    url "
    //Launch the animation
    function launchAnimation() {
      //Only if animation is not launched
      if ( timer.isActive == false ) {
        //Launch timer
        timer.cycleInterval = 3.0;
        timer.isActive  = true;
        timer.startTime = launchAnimation;
        //Send animationStarted event
        animationStarted = launchAnimation;
      }
    }
    //Stop the animation
    function stopAnimation () {
      //Launch timer
      if ( timer.isActive ) {
        timer.isActive = false;
      }
      //Send animationStarted event
      animationStopped = stopAnimation;
    }
    //End of animation
    function endOfAnimation () {
      //Send animationStopped event
      animationStopped = endOfAnimation;
    }
    "
  }
  #At end of animation, send event to script
  ROUTE ANIM_TIMER.cycleTime TO FLOWER_SCRIPT.endOfAnimation
  #Animation
  ROUTE ANIM_TIMER.fraction_changed TO INTERPOLATOR.set_fraction
  ROUTE INTERPOLATOR.value_changed  TO FLOWER_TRS.rotationAngle
}

Custom main VRML file to launch prototype animation:

EXTERNPROTO Flower [] "flower.wrl"

Group {
  children [
    #Background
    Shape {
      appearance Appearance {
        material Material2D {
          emissiveColor 1.0 1.0 1.0
          filled TRUE
        }
      }
      geometry Rectangle { size 200 200 }
    }

    #Flower 1
    Transform2D {
      translation 20.00 20.00
      children [
        DEF FLOWER1 Flower {}
      ]
    }
    #Flower 2
    Transform2D {
      translation -20.00 -20.00
      children [
        DEF FLOWER2 Flower { color 1.0 0.0 0.0 }
      ]
    }

    Script {
      field SFNode flower1 USE FLOWER1

      url "
      //Initialization
      function initialize (now) {
        flower1.launchAnimation = now;
      }
      "
    }

    ROUTE FLOWER1.animationStopped TO FLOWER2.launchAnimation
    ROUTE FLOWER2.animationStopped TO FLOWER1.launchAnimation
  ]
}

Note:
Circle shape does not support rotation...

MeMo SDK contains some prototypes.
See Prototypes chapter to more informations.