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
  
Help
  Copyright © 1997-99
  Purchase the book from Amazon.com

Chapter 3:
Node Reference


Intro
Anchor
Appearance
AudioClip
Background
Billboard
Box
Collision
Color
ColorInterpolator
Cone
Coordinate
CoordinateInterpolator
Cylinder
CylinderSensor
DirectionalLight
ElevationGrid
Extrusion
Fog
FontStyle
Group
ImageTexture
IndexedFaceSet
IndexedLineSet
Inline
LOD
Material
MovieTexture
NavigationInfo
Normal
NormalInterpolator
OrientationInterpolator
PixelTexture
PlaneSensor
PointLight
PointSet
PositionInterpolator
ProximitySensor
ScalarInterpolator
Script
Shape
Sound
Sphere
SphereSensor
SpotLight
Switch
Text
TextureCoordinate
TextureTransform
TimeSensor
TouchSensor
Transform
Viewpoint
VisibilitySensor
WorldInfo

+3.25 Inline

Inline { 
  exposedField MFString url        []
  field        SFVec3f  bboxCenter 0 0 0     # (-INF,INF)
  field        SFVec3f  bboxSize   -1 -1 -1  # (0,INF) or -1,-1,-1
}

The Inline node is a grouping node that reads its children data from a location in the World Wide Web. Exactly when its children are read and displayed is not defined (e.g. reading the children may be delayed until the Inline node's bounding box is visible to the viewer). The url field specifies the URL containing the children. An Inline node with an empty URL does nothing.

Each specified URL shall refer to a valid VRML file that contains a list of children nodes, prototypes, and routes at the top level as described in "2.6.5 Grouping and children nodes." The results are undefined if the URL refers to a file that is not VRML or if the file contains non-children nodes at the top level.

TECHNICAL NOTE: Because Inline nodes are grouping nodes, the file to which they point must not contain a scene graph fragment. For example, this is illegal:
  Shape { 
    appearance Appearance { 
      # The following line is ILLEGAL; Inline is a grouping node! 
      material Inline { url "http://..." } 
    } 
    geometry Box { } 
  } 

Restricting Inlines to be like a Group with across-the-Web children makes implementing them much simpler and satisfies the need for a simple mechanism to distribute different parts of the scene graph across the Web.


If multiple URLs are specified, the browser may display a URL of a lower preference file while it is obtaining, or if it is unable to obtain, the higher preference file. Details on the url field and preference order may be found in "2.5 VRML and the World Wide Web."

Results are undefined if the contents of the URL change after it has been loaded.

The bboxCenter and bboxSize fields specify a bounding box that encloses the Inline node's children. This is a hint that may be used for optimization purposes. If the specified bounding box is smaller than the actual bounding box of the children at any time, the results are undefined. A default bboxSize value, (-1, -1, -1), implies that the bounding box is not specified and if needed must be calculated by the browser. A description of the bboxCenter and bboxSize fields is in "2.6.4 Bounding boxes."

TIP: Use Inlines as children of LOD nodes wherever possible. This ensures that the Inline file is only considered for download when it is within a reasonable distance from the user (and avoids unnecessary downloads for objects that are out of view).

TECHNICAL NOTE: Many programmers expect Inline nodes to act like the C/C++ "#include" directive, simply textually including the URL given into the VRML file. They don't. Inline nodes are grouping nodes, not a syntax-parsing directive. If it were legal to Inline just a Material, the bbox* fields would not make sense--Material nodes have no bounding box. Inline is meant only as an easy-to-implement, easy-to-optimize solution for a common case. The more general EXTERNPROTO/PROTO mechanism can be used to define libraries of materials or other properties. The contents of the Inline node (the child nodes that are loaded across the Web) are completely opaque. Any nodes or prototypes defined inside the file to which the Inline points are not accessible outside of that file. Again, the more general EXTERNPROTO/PROTO mechanism can be used to create files with nonopaque interfaces. This Inline:
     Inline { 
       url "http://....." 
       bboxCenter 0 0 0 
       bboxSize 10 10 10 
     } 

is equivalent to:

     EXTERNPROTO _DummyName [ ] "http://..." 
     Group { 
       children _DummyName { } 
       bboxCenter 0 0 0 
       bboxSize 10 10 10 
     } 

Like EXTERNPROTO, each Inline is unique, even if two Inlines point to the same URL. Since Inline's cannot be changed "from the outside," the only time this matters is if the URL file contains user interface sensor nodes that might be triggered. For example, someone might define a completely self-contained Calculator object that had buttons, reacted to the user pressing the buttons, and so forth. You could include two such calculators in your world by simply doing:

     Group { children [ 
       Transform { 
         translation 10 0 0 
         children Inline { 
           url "http://...../Calculator.wrl" 
         } 
       } 
       Transform { translation -10 0 0 
         children Inline { 
           url "http://..../Calculator.wrl" 
         } 
       } 
     ]} 

Each of the calculators would calculate independently. You could, of course, also have the same calculator appear in two places in the world using DEF/USE:

     Group { children [ 
       Transform { 
         translation 10 0 0 
         children DEF Calculator Inline { 
           url "http://...../Calculator.wrl" 
         } 
       }
       Transform { 
         translation -10 0 0 
         children USE Calculator 
       } 
     ]} 

TECHNICAL NOTE: Since Inlines specify separate files, the DEF/USE namespace of the current file is not inherited by the referenced file and vice versa. Therefore, you cannot DEF a node in the current file and USE it from within the Inline's file, and you cannot DEF a node in an Inline file and USE the node later in the current file.

EXAMPLE (click to run): The following example illustrates a simple use of the Inline node. The file contains one Inline node that references the VRML file groundPlane.wrl. Notice that the Inline also specifies the bounding box for the contents of the file:
#VRML V2.0 utf8
Inline {
  bboxCenter 0 3 0
  bboxSize 100 6 100
  url "groundPlane.wrl"
}
Viewpoint {
  position 0 1.8 10
  description "In front of flag-pole"
}
Transform {    # Box
  translation -3 1 0
  children Shape {
    appearance Appearance {
      material Material { diffuseColor 0 0 1 }
    }
    geometry Box { }
  }
}
Transform {    # Cone
  translation 0 1 3
  children Shape {
    appearance Appearance {
      material Material { diffuseColor 0 1 0 }
    }
    geometry Cone { bottom FALSE }
  }
}
Transform {    # Sphere
  translation 3 1 0
  children Shape {
    appearance Appearance {
      material Material { diffuseColor 1 0 0 }
    }
    geometry Sphere { }
  }
}

groundPlane.wrl:

#VRML V2.0 utf8
# Bounds of this world:  (-50, 0 -50) to (50, 6, 50)
Transform { children [
  DirectionalLight { direction 0 -1 0  intensity 0.75 }
  # Grey ground-plane
  Shape {
    appearance DEF A Appearance { material Material { } }
    geometry IndexedFaceSet {
      coord Coordinate {
        point [ -50 0 -50  -50 0 50  50 0 50  50 0 -50 ]
      }
      coordIndex [ 0 1 2 3 -1 ]
    }
  }
  # Flag-pole at origin
  Shape {
    appearance USE A
    geometry IndexedFaceSet {
      coord Coordinate {
        point [ -.1 0 -.1  -.1 0 .1  .1 0 0
                -.1 6 -.1  -.1 6 .1  .1 6 0 ]
      }
      coordIndex [ 0 1 4 3 -1  1 2 5 4 -1
                   2 0 3 5 -1  3 4 5 -1 ]
    }
  }
  # Flag
  Shape {
    appearance Appearance {
      material Material { diffuseColor .9 0 0 }
    }
    geometry IndexedFaceSet {
      coord Coordinate {
        point [ .1 6 0  .1 5 0  1.4 5 0  1.4 6 0 ]
      }
      coordIndex [ 0 1 2 3 -1 ]
      solid FALSE
    }
  }
]}