The Annotated VRML 97 Reference

1 Intro     Concepts     3 Nodes     4 Fields/Events    Conformance
A Grammar     B Java     C JavaScript     D Examples     E Related Info    References
Quick Java         Quick JavaScript         Quick Nodes   

  About the Book
  Copyright © 1997-99
  Purchase the book from

Chapter 3:
Node Reference


+3.28 MovieTexture

MovieTexture { 
  exposedField SFBool   loop             FALSE
  exposedField SFFloat  speed            1.0      # (-INF,INF)
  exposedField SFTime   startTime        0        # (-INF,INF)
  exposedField SFTime   stopTime         0        # (-INF,INF)
  exposedField MFString url              []
  field        SFBool   repeatS          TRUE
  field        SFBool   repeatT          TRUE
  eventOut     SFTime   duration_changed
  eventOut     SFBool   isActive

The MovieTexture node defines a time dependent texture map (contained in a movie file) and parameters for controlling the movie and the texture mapping. A MovieTexture node can also be used as the source of sound data for a Sound node. In this special case, the MovieTexture node is not used for rendering.

TIP: It is most useful to use a sound-and-video MovieTexture as both a texture and source for a sound, so you can both see and hear it. This is easily accomplished with DEF/USE. For example:

   Shape {
     appearance Appearance {
       texture DEF MOVIE MovieTexture {
         url "http://..."
     geometry Box { }
   Sound { source USE MOVIE }
The audio and video will be automatically synchronized, since there is only one MovieTexture node and only one set of start/stop/repeat controls.

Texture maps are defined in a 2D coordinate system (s, t) that ranges from 0.0 to 1.0 in both directions. The bottom edge of the image corresponds to the S-axis of the texture map, and left edge of the image corresponds to the T-axis of the texture map. The lower-left pixel of the image corresponds to s=0.0, t=0.0, and the top-right pixel of the image corresponds to s=1.0, t=1.0. Figure 3-37 depicts one frame of the movie texture.

TIP: See Figure 3-37 for an illustration of the image space of a texture map movie (specified in the url field). Notice how the movie defines the 0.0 to 1.0 s and t boundaries. Regardless of the size and aspect ratio of the texture map movie, the left edge of the movie always represents s = 0; the right edge, s = 1.0; the bottom edge, t = 0.0; and the top edge, t = 1.0. Also, notice how we have illustrated the texture map infinitely repeating in all directions. This shows what happens conceptually when s and t values, specified by the TextureCoordinate node, are outside of the 0.0 to 1.0 range.


Image space of a texture map

Figure 3-37: Texture Map Image Space

The url field that defines the movie data shall support MPEG1-Systems (audio and video) or MPEG1-Video (video-only) movie file formats [MPEG]. Details on the url field may be found in "2.5 VRML and the World Wide Web."

See "2.6.11 Texture maps" for a general description of texture maps.

Section "2.14 Lighting model" contains details on lighting equations and the interaction between textures, materials, and geometries.

TIP: The only common movie file format that currently (early 1997) supports transparency is Animated GIF (GIF89-a), and it doesn't support partial transparency.

As soon as the movie is loaded, a duration_changed eventOut is sent. This indicates the duration of the movie in seconds. This eventOut value can be read (for instance, by a Script node) to determine the duration of a movie. A value of "-1" implies the movie has not yet loaded or the value is unavailable for some reason.

TECHNICAL NOTE: In the August 1996 draft of the VRML specification, duration_changed was an SFFloat field. It was changed to an SFTime field to be consistent with AudioClip and because it was a more convenient type for performing arithmetic in a script.

TIP: Movies tend to be very large and can take a long time to load. The duration_changed eventOut can be very useful for giving the user feedback when you know they will have to wait for a movie to be downloaded. You might have a Switch with a Text node that displays "Movie loading, please wait . . ." and a Script that removes the text by changing the Switch when it receives the MovieTexture's duration_changed event, indicating that the movie has been loaded and is ready to play. Because loading a movie can be such an expensive operation, implementations might defer loading it until it is scheduled to be played. Content creators should try to help the implementations by setting the MovieTexture's startTime field as early as possible, hopefully allowing the browser enough time to complete the download before the scheduled starting time. So, for example, if you animate a Transform when the user presses a button and play a movie after the animation is done, it is much better to set the startTime of both the animation and the movie based on the time of the button press, rather than waiting to set the MovieTexture's startTime when the first animation is finished.

The loop, startTime, and stopTime exposedFields and the isActive eventOut, and their effects on the MovieTexture node, are discussed in detail in the "2.6.9 Time dependent nodes" section. The cycle of a MovieTexture node is the length of time in seconds for one playing of the movie at the specified speed.

The speed exposedField indicates how fast the movie shall be played. A speed of 2 indicates the movie plays twice as fast. The duration_changed output is not affected by the speed exposedField. set_speed events are ignored while the movie is playing. A negative speed implies that the movie will play backwards.

If a MovieTexture node is inactive when the movie is first loaded, frame 0 of the movie texture is displayed if speed is non-negative or the last frame of the movie texture is shown if speed is negative (see "2.11.3 Discrete and continuous changes"). A MovieTexture node shall display frame 0 if speed = 0. For positive values of speed, an active MovieTexture node displays the frame at movie time t as follows (i.e., in the movie's local time system with frame 0 at time 0 with speed = 1):

    t = (now - startTime) modulo (duration/speed)

If speed is negative, the MovieTexture node displays the frame at movie time:

    t = duration - ((now - startTime) modulo ABS(duration/speed))

When a MovieTexture node becomes inactive, the frame corresponding to the time at which the MovieTexture became inactive will remain as the texture.

MovieTexture nodes can be referenced by an Appearance node's texture field (as a movie texture) and by a Sound node's source field (as an audio source only).

TIP: If you want an object to appear as if it has no texture at all before the MovieTexture starts or after it finishes, either insert a single-color movie frame at the beginning or end of the movie file or use a Script and a Switch node to switch between two Shapes that share the same geometry (use DEF/USE to share the geometry) but have different appearances (one with a MovieTexture and one without).

TIP: Playing movies backward is also likely to result in very poor performance, if it works at all, because video hardware and software is optimized to play movies forward. The MPEG-2 standard, for example, relies heavily on a compression technique where the differences from one frame to the next are encoded, making it much more expensive to recreate the frames of the movie out of order.

TIP: See the ImageTexture section for important tips on texture mapping tricks.

TECHNICAL NOTE: The size of a typical movie file and the memory and computational expense of supporting animating texture maps make it somewhat impractical for most VRML users. However, 3D graphics hardware and network bandwidth are getting better every year, and what is only barely achievable today will soon be commonplace. It will be interesting to see how much the VRML standard will influence the development of other graphics and networking standards. It will also be interesting to see how much VRML changes over the years because of changes in other graphics and networking standards.

TECHNICAL NOTE: Anchor is equivalent to a prototype containing a couple of Group nodes, a Touch-Sensor, and a Script. It is a standard node partly because it makes it easier to convert VRML 1.0 files (which use WWWAnchor) to VRML 2.0, and partly because it is convenient to have simple hyperlinking support prepackaged in a convenient form. There are many hyperlinking tasks for which Anchor is inadequate. For example, if you want a hyperlink to occur after the user has accomplished some task, then you must use a Script node that calls loadURL(). If you want to load several different pieces of information into several other frames you will also have to use a Script that makes several calls to loadURL(). The basic building blocks of Scripts and sensors allow you to do almost anything; the Anchor node is only meant to address the most basic hyperlinking tasks

EXAMPLE (click to run): The following example illustrates a simple case of the MovieTexture node. The MovieTexture is assigned to the texture of a rectangular polygon. A TouchSensor is used to trigger the movie play sequence. Each time the user clicks on the rectangle, the movie starts from the beginning (unless it is already running):

#VRML V2.0 utf8
Group { children [
  Shape {
    appearance Appearance {
      texture DEF MT1 MovieTexture {
        url "test.mpeg"
        loop FALSE
      material DEF M Material { diffuseColor 1 1 1 }
    geometry DEF IFS IndexedFaceSet {
      coord Coordinate { point [ -1.1 -1 0, 1 -1 0, 1 1 0, -1.1 1 0 ] }
      coordIndex [ 0 1 2 3 ]
  DEF TS1 TouchSensor {}
  Background { skyColor 1 1 1 }
ROUTE TS1.touchTime TO MT1.startTime