December 1, 1994 Research SRC Report 129 Obliq-3D Tutorial and Reference Manual Marc A. Najork d i g i t a l Systems Research Center 130 Lytton Avenue Palo Alto, California 94301 Systems Research Center The charter of SRC is to advance both the state of knowledge and the state of the art in computer systems. From our establishment in 1984, we have performed basic and applied research to support Digital's business objectives. Our current work includes exploring distributed personal computing on multiple platforms, network- ing, programming technology, system modelling and management techniques, and selected applications. Our strategy is to test the technical and practical value of our ideas by building hardware and software prototypes and using them as daily tools. Interesting systems are too complex to be evaluated solely in the abstract; extended use allows us to investigate their properties in depth. This experience is useful in the short term in re®ning our designs, and invaluable in the long term in advancing our knowledge. Most of the major advances in information systems have come through this strategy, including personal computing, distributed systems, and the Internet. We also perform complementary work of a more mathematical ¯avor. Some of it is in established ®elds of theoretical computer science, such as the analysis of algorithms, computational geometry, and logics of programming. Other work explores new ground motivated by problems that arise in our systems research. We have a strong commitment to communicating our results; exposing and testing our ideas in the research and development communities leads to improved un- derstanding. Our research report series supplements publication in professional journals and conferences. We seek users for our prototype systems among those with whom we have common interests, and we encourage collaboration with uni- versity researchers. Robert W. Taylor, Director Obliq-3D Tutorial and Reference Manual Marc A. Najork December 1, 1994 c Digital Equipment Corporation 1994 This work may not be copied or reproduced in whole or in part for any commercial purpose. Permission to copy in whole or in part without payment of fee is granted for nonpro®t educational and research purposes provided that all such whole or partial copies include the following: a notice that such copying is by permission of the Systems Research Center of Digital Equipment Corporation in Palo Alto, California; an acknowledgment of the authors and individual contributors to the work; and all applicable portions of the copyright notice. Copying, reproducing, or republishing for any other purpose shall require a license with payment of fee to the Systems Research Center. All rights reserved. Abstract Obliq-3D is an interpreted language that is embedded into the 3D animation system Anim3D. Anim3D is based on a few simple, yet powerful constructs that allow a programmer to describe three-dimensional scenes and animations of such scenes. Obliq-3D, by virtue of its interpretive nature, provides the programmer with a fast turnaround environment. The combination of sim- plicity and fast turnaround allows application programmers to construct non-trivial animations quickly and easily. The ®rst half of this report contains a tutorial to Obliq-3D, which develops the various concepts of the animation system. The second part contains a reference manual, which describes the functionality of Obliq-3D module by module. Contents 1 Introduction 1 1.1 Related Work ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 1 2Tutorial 4 2.1 Obliq-3D in a Nutshell : ::: ::: ::: :: ::: ::: ::: ::: ::: :: 4 2.2 A First Example : ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 4 2.3 Properties : ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 6 2.4 The On-Line Help Facility :: ::: ::: :: ::: ::: ::: ::: ::: :: 11 2.5 Non-Tree Scene Graphs ::: ::: ::: :: ::: ::: ::: ::: ::: :: 11 2.6 More on Property Values ::: ::: ::: :: ::: ::: ::: ::: ::: :: 13 2.7 Overloading ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 15 2.8 Behaviors : ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 16 2.9 Asynchronous Behaviors ::: ::: ::: :: ::: ::: ::: ::: ::: :: 17 2.10 Synchronous Behaviors ::: ::: ::: :: ::: ::: ::: ::: ::: :: 18 2.11 Dependent Behaviors :: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 20 2.12 Locking :: ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 21 2.13 Callbacks :: ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 24 2.14 Extending Objects ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 26 2.15 Naming Graphical Objects :: ::: ::: :: ::: ::: ::: ::: ::: :: 28 2.16 Requests :: ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 29 2.17 Depth Cueing :: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 32 2.18 Light Objects ::: ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 33 2.19 Camera Objects : ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 34 2.20 Creating Root Objects : ::: ::: ::: :: ::: ::: ::: ::: ::: :: 38 3 Reference Manual 41 3.1 The Point3 Module ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 44 3.2 The Matrix4 Module :: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 45 3.3 The Anim3D Module : ::: ::: ::: :: ::: ::: ::: ::: ::: :: 46 3.4 The ProxiedObj Module ::: ::: ::: :: ::: ::: ::: ::: ::: :: 46 3.5 The GraphicsBase Module :: ::: ::: :: ::: ::: ::: ::: ::: :: 47 3.6 The X`Pex`Base Module ::: ::: ::: :: ::: ::: ::: ::: ::: :: 47 3.7 The AnimHandle Module :: ::: ::: :: ::: ::: ::: ::: ::: :: 48 3.8 The GO Module : ::: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 49 3.9 The GroupGO Module : ::: ::: ::: :: ::: ::: ::: ::: ::: :: 54 3.10 The RootGO Module :: ::: ::: ::: :: ::: ::: ::: ::: ::: :: 55 3.11 The LightGO Module : ::: ::: ::: :: ::: ::: ::: ::: ::: :: 57 3.12 The AmbientLightGO Module :: ::: ::: ::: ::: ::: :: ::: ::: 57 3.13 The VectorLightGO Module : :: ::: ::: ::: ::: ::: :: ::: ::: 58 3.14 The PointLightGO Module :: :: ::: ::: ::: ::: ::: :: ::: ::: 59 3.15 The SpotLightGO Module :: :: ::: ::: ::: ::: ::: :: ::: ::: 61 3.16 The CameraGO Module ::: :: ::: ::: ::: ::: ::: :: ::: ::: 63 3.17 The OrthoCameraGO Module :: ::: ::: ::: ::: ::: :: ::: ::: 65 3.18 The PerspCameraGO Module :: ::: ::: ::: ::: ::: :: ::: ::: 66 3.19 The LineGO Module :: ::: :: ::: ::: ::: ::: ::: :: ::: ::: 68 3.20 The MarkerGO Module ::: :: ::: ::: ::: ::: ::: :: ::: ::: 69 3.21 The SurfaceGO Module ::: :: ::: ::: ::: ::: ::: :: ::: ::: 70 3.22 The PolygonGO Module ::: :: ::: ::: ::: ::: ::: :: ::: ::: 72 3.23 The BoxGO Module :: ::: :: ::: ::: ::: ::: ::: :: ::: ::: 73 3.24 The DiskGO Module :: ::: :: ::: ::: ::: ::: ::: :: ::: ::: 74 3.25 The SphereGO Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 75 3.26 The CylinderGO Module ::: :: ::: ::: ::: ::: ::: :: ::: ::: 76 3.27 The ConeGO Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 77 3.28 The TorusGO Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 78 3.29 The QuadMeshGO Module : :: ::: ::: ::: ::: ::: :: ::: ::: 79 3.30 The Prop Module : ::: ::: :: ::: ::: ::: ::: ::: :: ::: ::: 80 3.31 The BooleanProp Module :: :: ::: ::: ::: ::: ::: :: ::: ::: 82 3.32 The RealProp Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 85 3.33 The PointProp Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 86 3.34 The ColorProp Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 88 3.35 The TransformProp Module : :: ::: ::: ::: ::: ::: :: ::: ::: 90 3.36 The LineTypeProp Module :: :: ::: ::: ::: ::: ::: :: ::: ::: 93 3.37 The MarkerTypeProp Module :: ::: ::: ::: ::: ::: :: ::: ::: 94 3.38 The RasterModeProp Module :: ::: ::: ::: ::: ::: :: ::: ::: 95 3.39 The ShadingProp Module :: :: ::: ::: ::: ::: ::: :: ::: ::: 96 3.40 The MouseCB Module : ::: :: ::: ::: ::: ::: ::: :: ::: ::: 97 3.41 The PositionCB Module ::: :: ::: ::: ::: ::: ::: :: ::: ::: 98 3.42 The KeyCB Module :: ::: :: ::: ::: ::: ::: ::: :: ::: ::: 99 Acknowledgments 100 References 101 Index 105 1 1 Introduction Obliq [3] is a lexically-scoped, untyped, interpreted language that supports distributed object- oriented computation. The Obliq interpreter is written in Modula-3 [17], and is designed to be both easy to extend and easy to embed into other programs. Anim3D is a Modula-3 library for building programs that use interactive, animated three- dimensional graphics. It uses the X Window System [21] as the underlying window system, and MPEX (Digital's extension of PEX [8], the 3D extension of X) as the underlying graphics library. Support for other window systems (e.g. Trestle [14, 15]) and graphics libraries (e.g. OpenGL [18]) is under way. Anim3D is designed to interconnect easily with an embedded language, although it does not rely on one. Possible choices for such a language are Lisp, Python, or any other interpreted language that can be easily embedded. We chose Obliq, because its linguistic features closely match those of Modula-3, and because it is particularly easy to embed an Obliq interpreter into some other Modula-3 program. The resulting embedded language is called Obliq-3D. Obliq-3D is a superset of Obliq; it provides the same syntactic constructs, as well as all the built-in libraries described in SRC Research Report 122 [3]. In addition, it provides 42 extra modules that support the construction of 3D animations. This report is divided into two parts. The ®rst part gives an example-driven introduction to the basic concepts of the animation system. It assumes the reader is familiar with SRC Report 122, but does not make any further assumptions. The second part contains a reference manual for Obliq-3D. The manual contains a section for each module that is speci®c to Obliq-3D. Our initial motivation for developing a fast-turnaround