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.

Dedication Acknowledgements About The Authors

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.

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; reference topics are alphabetized and tabbed; 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 fourth way to use this book is to access the on-line World Wide Web (WWW) site, which includes most of the book, including live versions of the examples:

       http://www.aw.com/devpress/titles/41974.html

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.

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.

Conventions Used in this Book (HTML version)

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:

design 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.

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.

example

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 [ 
      ... 
    ]}

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

A prototype is a . . .

The radius field . . .

The isActive eventOut . . .
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
     }

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

    void createVrmlFromString( String vrmlSyntax );

    Cylinder { radius 3 height 5 }

    http://www.aw.com
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 {...}
  ...
]}
Background nodes have been added to most of the examples to produce white backgrounds for printing.
The colors in most of the examples were chosen to be in gray scale since the images are printed in gray scale.
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 [
          ...
    ]}]}