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

About This Book

What This   Book Contains

How to Use   This Book

Getting Started


About the Authors



About This Book

The Annotated VRML 97 Reference Manual contains the complete specification of the Virtual Reality Modeling Language, as of April 4,1997. In addition, throughout this book you will find a variety of technical annotations, authoring tips, and illustrative examples. While the VRML specification is technically accurate and precise, it is not intended to address questions on why it is designed the way it is, what's the best way to use it, what to avoid, or how to implement it. These issues and more are featured throughout this book. The annotations relate the various separate parts of VRML into a coherent whole. The contents of this book are relevant to implementors of the VRML specifications as well as to authors and users of VRML.

This book is not a tutorial on VRML. There are a variety of books that teach basic and advanced VRML concepts, and serve as excellent companions to this book (see Appendix F, Recommended Reading).

This book does not rely on or describe any single specific implementation of VRML, rather it presents the ideal definition of VRML and suggests typical implementation pitfalls and difficulties to watch out for. See Appendix E, VRML Compendium, for a summary of the browser and authoring tools available for you to choose from.

---------- separator bar ------------
What This Book Contains

The first chapter, Introduction, describes the motivation, history, and basis for VRML. Chapter 2, Key Concepts, presents a technical overview of the VRML file format and underlying architecture. This chapter introduces you to the file format syntax and goes on to discuss a variety of important architectural fundamentals of VRML, such as prototypes, routing, scripting, execution model, and binding node behavior. The third chapter, Node Reference, contains the largest and most significant aspect of the book. It defines the syntax and semantics of every node in the specification, as well as complete working examples for each node, and a variety of annotations and tips. Chapter 4, Field and Event Reference, describes the syntax and semantics of the VRML data types--fields and events. The fifth chapter, Conformance and Minimum Support Requirements, specifies the baseline requirements to which VRML implementations must adhere. This chapter is useful to authors and implementors alike, as a benchmark of which features are required in a conforming VRML application. Appendix A, VRML Grammar Definition, provides a precise grammar definition of the VRML file format. Appendix B, Java Scripting Reference, describes the integration of the Java programming language with VRML. This appendix defines the specific classes and methods that may be invoked from a VRML Script node using Java. Appendix C, JavaScript Scripting Reference, defines the integration of the JavaScript scripting language with VRML. It includes a detailed specification of the JavaScript objects and functions available to a VRML Script node. Appendix D, Examples, includes the revised sample files found in the VRML specification. Appendix E, VRML Compendium, lists a variety of Uniform Resource Locators (URLs) to VRML-related sources and topics. Appendix F, Recommended Reading, lists a variety of books that supplement the material contained in this book. Appendix G, Summary of Java Scripting API, provides a quick reference to the Java classes and methods. Appendix H, Summary of JavaScript Scripting API, provides a quick reference to the JavaScript objects and methods.

---------- separator bar ------------
How to Use This Book

There are several ways to use this book. First you can read Chapter 1, Introduction, and Chapter 2, Key Concepts, for an in-depth description of the fundamentals of VRML, and use Appendix E, VRML Compendium, to find a variety of references on VRML-related information sources. Advanced technical readers should have no problem using these chapters as their introduction to VRML, while novices may wish to start with an introductory book before reading these chapters. The second way to use this book is as an everyday reference guide. It is organized for fast access and daily use: specification text is easily distinguished from the annotations; and notes, tips, and examples are located in the section containing the relevant topic. The third way to use this book is to read the notes, tips, and examples to enhance your knowledge and gain new insight into VRML.

The examples included in this book conform to the VRML specification and are accurate to the best of our knowledge, but may not work in all browsers (see the browser's release notes for supported features and known bugs).

This book contains references to a variety of URLs. Note that it is possible that URLs may change or become inactive after the publication of this book, and that it may be necessary to employ a search engine to find a more up-to-date URL.

---------- separator bar ------------
Getting Started

There are only two things needed to get started with VRML: a VRML browser and a text editor. When choosing from the wide variety of VRML browsers available, keep in mind which system you are using, which system(s) you expect your users to have, and the essential VRML features that you intend to use (not all browsers support all features in the specification). VRML files are plain text files, so you can create them using any text editor. Most word processors can read and write text files; be sure to "Save As" plain text. Special-purpose programming editors are even better for editing VRML files because they support features such as matching opening and closing braces and automatically indenting each line.

There are also VRML authoring tools available. These range from file converters to single-task utilities to full-fledged authoring environments. VRML has become so popular as a three-dimensional (3D) file exchange format that many 3D applications output VRML. File converters from most 3D formats are also readily available. Note that there is a big difference between an authoring system that outputs VRML and one that authors VRML. Typically, native VRML systems support more features and produce better results, but some of the systems that output VRML are just as good.

---------- separator bar ------------
Conventions Used

1. There are three types of annotations in the book: technical notes, authoring tips, and examples. Each annotation type is labeled with an icon in the margin for easy recognition:

TIP: This is an example of an authoring tip. Tips range from suggestions on proper usage to warnings on problem areas to nonobvious ideas for combining and using VRML.

TECHNICAL NOTE: This is an example technical note. It may contain historical footnotes concerning the design of VRML, advanced technical notes, or implementation details. These notes are typically of interest to implementors and advanced authors.

EXAMPLE (click to run): This is an example of a VRML example file. Most of the examples start with an explanatory introduction; some include an image illustrating the results on screen. Most of the examples are complete, but some may include "..." to imply that valid VRML syntax goes here:
    #VRML V2.0 utf8 
    Transform { children [ 


2. New terms, field names, and event names are printed in italic type:

A prototype is a . . .

The radius field . . .

The isActive eventOut . . .

3. Node definitions specify the complete set of events and fields for a given node type. The parts of the definition that correspond to the file format are given in a bold, fixed-space font, while the rest of the definition is given in a plain, fixed-space font:

     Collision {
       eventIn       MFNode    addChildren
       eventIn       MFNode    removeChildren
       exposedField  MFNode    children       []
       exposedField  SFBool    collide        TRUE
       field         SFVec3f   bboxCenter     0 0 0
       field         SFVec3f   bboxSize       -1 -1 -1
       field         SFNode    proxy          NULL
       eventOut      SFTime    collideTime

4. Programming interfaces, VRML file examples, and URLs are printed in a plain, fixed-space font:

    void createVrmlFromString( String vrmlSyntax );
    Cylinder { radius 3 height 5 }

5. DEF and USE names are usually chosen as an abbreviation of the node type and are numbered if there are more than one of the same type in the file. For example, if an example file contains two ProximitySensors, the first one would be named PS1 and the second one PS2:

#VRML V2.0 utf8
Transform { children [
  DEF PS1 ProximitySensor {...}
  DEF PS2 ProximitySensor {...}

6. Background nodes have been added to most of the examples to produce white backgrounds for printing.

7. The colors in most of the examples were chosen to be in gray scale since the images are printed in gray scale.

8. Field values and closing braces and brackets are often combined on one line to compress the examples in the book:

    #VRML V2. utf8
    Transform { children [
      Sphere { radius 4 }
      Cylinder { height 5 radius 3 }
      Transform {
        children [

---------- separator bar ------------

This book would not be possible without the dedication and help of many people. The following is a short list of some of those people. We cannot possibly thank everyone (although we would like to); please forgive us if we've neglected to mention you here.

Special thanks to Paul Strauss for his pioneering efforts on Open Inventor, which eventually led to VRML. Thanks to the rest of the Open Inventor engineering team for laying the groundwork that VRML is based on: Thad Beier, Alain Dumesny, Dave Immel, Paul Isaacs, Howard Look, David Mott, Nick Thompson, and Helga Thorvaldsdóttir. Thanks to Chris Marrin for his work on the Java and JavaScript appendices, as well as a variety of other important areas of the VRML Specification.

Thanks to Mark Pesce and Tony Parisi for writing the first prototype of a 3D web browser, Labyrinth, and for their tireless contribution and dedication to VRML.

Thanks to Mitra, Kouichi Matsuda, Rodger Lea, and Yasuaki Honda for their work on the Moving Worlds proposal and the Java appendix. Thanks to the many unnamed people who contributed ideas and work to the VRML Specification--you know who you are.

Thanks to Silicon Graphics, Inc., for creating a fantastic work environment and for taking a risk on VRML.

Thanks to Mary Treseler, John Fuller, Keith Wollman, and the Addison Wesley Longman staff for guidance and support. Thanks to our book reviewers: Scott S. Ross, Stephen Chenney, Len Bullard, Cindy Reed-Ballreich, Jan C. Hardenbergh, Chet Murphy, Jai Natarajan, Matt O'Donnell, David Story, and Mason Woo. Thanks to Sam Chen and Silicon Graphics, Inc., for providing the cover image for this book. Thanks also to Sam Chen, Silicon Graphics, Inc. and Construct Internet Design for the O2 Out of Box Experience images used in the color plates.

And last, but not least, thanks to the members of the www-vrml mailing list for your ideas, passion, and hard work.

---------- separator bar ------------
About The Authors

Photo of Rikk

Rikk Carey lives in California and spends his his time on 3d graphics stuff, his gardens, taking care of his bunny FooFoo, looking at his guitar, and playing golf.

Photo of Gavin

Gavin Bell lives in Wisconsin where he enjoys 3d graphics stuff, bicycling, and playing with his cats Tekka and Echo.

If you wish to contact the authors:

email: Rikk Carey

email: Gavin Bell

email to both: Rikk Carey and Gavin Bell