OpenSceneGraph Quick Start Guide A Quick Introduction to the Cross-Platform Open Source Scene Graph APl Paul Martz SKEW MATRIX S O F T W A R E
OpenSceneGraph Quick Start Guide A Quick Introduction to the Cross-Platform Open Source Scene Graph API Paul Martz
Front cover image courtesy of Professor Mark Bryden and VRAC at lowa State University. Back cover top two images generated with 3DNature's NatureViewExpress and Visual Nature Studio with Scene Express. Back cover bottom image courtesy of Andes Computer Engineering. The author and publisher have taken care in the publication of this book,but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions.No liability is assumed for any damages arising out of the use of the information or programs contained herein. Many of the designations used by manufacturers and sellers to designate their products are claimed as trademarks.Where the designations appear in this manual,and the author was aware of a trademark claim,the designations have been printed with initial capital letters or in all capitals. OpenSceneGraph Quick Start Guide Copyright 2007 Skew Matrix Software LLC This book is protected by the Creative Commons Attribution-NonCommercial-ShareAlike 2.0 license.You may copy,distribute,transmit,and alter this work for non-commercial purposes provided you attribute the work to Paul Marts and Skew Matrix Sofvare LLCand lcense any altered or derivative works under similar terms.For more information,view the following URL: http://creativecommons.org/licenses/by-nc-sa/2.0/ For inquiries regarding exceptions to this license,please contact the author and publisher. Paul Martz Skew Matrix Software LLC 284 W.Elm St. Louisville,CO 80027 USA pmartz@skew-matrix.com
Front cover image courtesy of Professor Mark Bryden and VRAC at Iowa State University. Back cover top two images generated with 3DNature's NatureViewExpress and Visual Nature Studio with Scene Express. Back cover bottom image courtesy of Andes Computer Engineering. The author and publisher have taken care in the publication of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for any damages arising out of the use of the information or programs contained herein. Many of the designations used by manufacturers and sellers to designate their products are claimed as trademarks. Where the designations appear in this manual, and the author was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals. OpenSceneGraph Quick Start Guide Copyright © 2007 Skew Matrix Software LLC This book is protected by the Creative Commons Attribution-NonCommercial-ShareAlike 2.0 license. You may copy, distribute, transmit, and alter this work for non-commercial purposes provided you attribute the work to Paul Martz and Skew Matrix Software LLC and license any altered or derivative works under similar terms. For more information, view the following URL: http://creativecommons.org/licenses/by-nc-sa/2.0/ For inquiries regarding exceptions to this license, please contact the author and publisher: Paul Martz Skew Matrix Software LLC 284 W. Elm St. Louisville, CO 80027 USA pmartz@skew-matrix.com
This book is dedicated to all developers new to scene graφh technolog
This book is dedicated to all developers new to scene graph technology
Contents Preface....... Acknowledgements.… iⅸ 1 An Overview of Scene Graphs and OpenSceneGraph...................1 1./History of OpenSceneGraph.. 1 1.2 Installing OSG...... 3 1.2./Hardware Requirements..... .4 1.2.2 Apple Mac OS X. .4 1.2.3 Fedora Linux… .4 1.2.4 Microsoft Windows .......... 5 1.2.5 Verifying Your OSG Installation 6 1.3Running osgviewer. .6 1.3.1 Getting Help… .7 1.3.2 Display Modes. ..8 1.3.3 Environment Variables. .8 1.3.4 Statistics Display........... 9 1.3.5 Recording an Animation......... 4.10 1.4 Compiling OSG Applications... .11 1.5 Introduction to Scene Graphs ..13 1.5./Scene Graph Features....... .14 1.5.2 How Scene Graphs Render... 15 1.6 Overview of OpenSceneGraph 17 1.6./Design and Architecture.... .17 1.6.2 Naming Conventions.. 18 1.6.3 Components.… 18 2 Building a Scene Graph................ 31 OpenSceneGraph Quick Start Guide
OpenSceneGraph Quick Start Guide i Contents Preface.................................................................................................... v Acknowledgements ................................................................................ ix 1 An Overview of Scene Graphs and OpenSceneGraph ...................1 1.1 History of OpenSceneGraph ...................................................................................................1 1.2 Installing OSG ...........................................................................................................................3 1.2.1 Hardware Requirements...................................................................................................4 1.2.2 Apple Mac OS X...............................................................................................................4 1.2.3 Fedora Linux......................................................................................................................4 1.2.4 Microsoft Windows ..........................................................................................................5 1.2.5 Verifying Your OSG Installation....................................................................................6 1.3 Running osgviewer ....................................................................................................................6 1.3.1 Getting Help ......................................................................................................................7 1.3.2 Display Modes...................................................................................................................8 1.3.3 Environment Variables.....................................................................................................8 1.3.4 Statistics Display................................................................................................................9 1.3.5 Recording an Animation ................................................................................................10 1.4 Compiling OSG Applications................................................................................................11 1.5 Introduction to Scene Graphs ...............................................................................................13 1.5.1 Scene Graph Features.....................................................................................................14 1.5.2 How Scene Graphs Render ...........................................................................................15 1.6 Overview of OpenSceneGraph .............................................................................................17 1.6.1 Design and Architecture.................................................................................................17 1.6.2 Naming Conventions......................................................................................................18 1.6.3 Components.....................................................................................................................18 2 Building a Scene Graph.................................................................31
Contents 2./Memory Management ..... 31 2.1./The Referenced Class..... 33 2.1.2 The ref_ptr<>Template Class 34 2.1.3 Memory Management Examples............... 34 2.2 Geodes and Geometry...... .36 2.2.1 An Overview of Geometry Classes. 40 2.3 Group Nodes.. .44 2.3./The Child Interface 44 2.3.2The Parent Interface 45 2.3.3Transform Nodes............. .46 2.3.4The LOD Node............. 50 2.3.5The Switch Node.... 51 2.4 Rendering State.… 53 2.4./Attributes and Modes ............. 54 2.4.2State Inheritance..... 56 2.4.3 Example Code for Setting State 57 2Texture Mapping..... 61 2.4.51 ighting… 64 2.5 File I/O.. 69 2.5.1 Interface… …70 2.5.2 Plugin Discovery and Registration .71 2.6 NodeKits and osgText............ 72 2.6./osgText Components..... 73 2.6.2 Using osgText.… 73 2.6.3 Text Example Code... 77 2.6.4 The .osg File Format.... 78 3 Using OpenSceneGraph in Your Application......................83 3./Rendering... 83 3.1./The Viewer Class.................. 84 3.1.2 SimpleViewer and CompositeViewer. 87 3.2 Dynamic Modification............ 88 3.2.1 Data Variance..… 88 322Cabacks89 3.2 NOde ViSitOrS94 3.2.4 Picking.… .95 Appendix:Where to Go From Here............103
ii Contents 2.1 Memory Management ............................................................................................................ 31 2.1.1 The Referenced Class..................................................................................................... 33 2.1.2 The ref_ptr<> Template Class .................................................................................... 34 2.1.3 Memory Management Examples.................................................................................. 34 2.2 Geodes and Geometry ........................................................................................................... 36 2.2.1 An Overview of Geometry Classes.............................................................................. 40 2.3 Group Nodes........................................................................................................................... 44 2.3.1 The Child Interface ........................................................................................................ 44 2.3.2 The Parent Interface ...................................................................................................... 45 2.3.3 Transform Nodes........................................................................................................... 46 2.3.4 The LOD Node.............................................................................................................. 50 2.3.5 The Switch Node............................................................................................................ 51 2.4 Rendering State ....................................................................................................................... 53 2.4.1 Attributes and Modes .................................................................................................... 54 2.4.2 State Inheritance............................................................................................................. 56 2.4.3 Example Code for Setting State ................................................................................... 57 2.4.4 Texture Mapping ............................................................................................................ 61 2.4.5 Lighting............................................................................................................................ 64 2.5 File I/O.................................................................................................................................... 69 2.5.1 Interface........................................................................................................................... 70 2.5.2 Plugin Discovery and Registration............................................................................... 71 2.6 NodeKits and osgText ........................................................................................................... 72 2.6.1 osgText Components..................................................................................................... 73 2.6.2 Using osgText ................................................................................................................. 73 2.6.3 Text Example Code ....................................................................................................... 77 2.6.4 The .osg File Format...................................................................................................... 78 3 Using OpenSceneGraph in Your Application.................................83 3.1 Rendering................................................................................................................................. 83 3.1.1 The Viewer Class............................................................................................................ 84 3.1.2 SimpleViewer and CompositeViewer .......................................................................... 87 3.2 Dynamic Modification............................................................................................................ 88 3.2.1 Data Variance.................................................................................................................. 88 3.2.2 Callbacks.......................................................................................................................... 89 3.2.3 NodeVisitors................................................................................................................... 94 3.2.4 Picking.............................................................................................................................. 95 Appendix: Where to Go From Here .....................................................103
OpenSceneGraph Quick Start Guide 战 105 Sa门. Bibliography 109 Revision History .111
OpenSceneGraph Quick Start Guide iii Glossary ..............................................................................................105 Bibliography.........................................................................................109 Revision History ..................................................................................111
Preface This book is a concise introduction to OpenSceneGraph (OSG)-the cross-platform open source scene graph application programmer interface (APD).Specifically,this book documents OSG v1.3.OSG plays a key role in the 3D application software stack.It's the middleware above the lower-level OpenGL hardware abstraction layer (HAL),providing extensive higher-level rendering,I/O,and spatial organization functionality to the 3D application. For many years,OSG has thrived with only its source code as documentation.The OSG distribution includes several examples that illustrate various rendering effects,and methods for integrating OSG with end-user applications.These illustrative examples,along with the ability to step through core OSG in a debugger,have enabled several developers to become proficient in the OSG API. Although source code has sufficed as documentation in the past,it is no substitute for more traditional forms of documentation.Manuals lend themselves quite easily to pedagogical instruments such as figures and tables,which are difficult to embed in source code.As OSG has grown and become more complex,lack of formal documentation has unacceptably lengthened the learning curve for new users.Prior to this book's release,the lack of formal OSG documentation has caused some developers to wonder if OSG is mature and robust enough to support professional-quality applications. By mid-2006,both Don Burns and Robert Osfield had recognized the need for an OSG book.Don had a client,Computer Graphics Systems Development Corporation(CGSD), whose contract called for OSG documentation,so he subcontracted the documentation development to Paul Martz.Robert suggested that the first OSG book should be freely available and concise in nature.Thus,the Open.SceneGrapb Ouick Start Guide was born. The OpenSceneGruph Ouice Start Guide is a short programming guide that covers the basic and essential elements of the OSG API.It is the first in a series of planned books to document OSG with more comprehensive material to follow.The goals of the OpenSceneGraph Ouick Start Guide are listed below. Provide new OSG developers with a quick and affordable introduction to OSG basics. Familiarize the reader with the OSG distribution and source code organization. Illustrate proper use of the commonly used elements of the OSG API. Direct the reader to sources of more thorough documentation. OpenSceneGraph Quick Start Guide
OpenSceneGraph Quick Start Guide v Preface This book is a concise introduction to OpenSceneGraph (OSG)—the cross-platform open source scene graph application programmer interface (API). Specifically, this book documents OSG v1.3. OSG plays a key role in the 3D application software stack. It’s the middleware above the lower-level OpenGL hardware abstraction layer (HAL), providing extensive higher-level rendering, I/O, and spatial organization functionality to the 3D application. For many years, OSG has thrived with only its source code as documentation. The OSG distribution includes several examples that illustrate various rendering effects, and methods for integrating OSG with end-user applications. These illustrative examples, along with the ability to step through core OSG in a debugger, have enabled several developers to become proficient in the OSG API. Although source code has sufficed as documentation in the past, it is no substitute for more traditional forms of documentation. Manuals lend themselves quite easily to pedagogical instruments such as figures and tables, which are difficult to embed in source code. As OSG has grown and become more complex, lack of formal documentation has unacceptably lengthened the learning curve for new users. Prior to this book’s release, the lack of formal OSG documentation has caused some developers to wonder if OSG is mature and robust enough to support professional-quality applications. By mid-2006, both Don Burns and Robert Osfield had recognized the need for an OSG book. Don had a client, Computer Graphics Systems Development Corporation (CGSD), whose contract called for OSG documentation, so he subcontracted the documentation development to Paul Martz. Robert suggested that the first OSG book should be freely available and concise in nature. Thus, the OpenSceneGraph Quick Start Guide was born. The OpenSceneGraph Quick Start Guide is a short programming guide that covers the basic and essential elements of the OSG API. It is the first in a series of planned books to document OSG with more comprehensive material to follow. The goals of the OpenSceneGraph Quick Start Guide are listed below. • Provide new OSG developers with a quick and affordable introduction to OSG basics. • Familiarize the reader with the OSG distribution and source code organization. • Illustrate proper use of the commonly used elements of the OSG API. • Direct the reader to sources of more thorough documentation
Preface In the spirit of open source,the OSGQSG is available for no charge as a PDF file. However,you can contribute to the OSG community by purchasing a full-color softbound copy.To place an online order for a copy of this book,visit the Lulu.com Web site and search for OpenSceneGraph. http://www.lulu.com Proceeds from sales of bound copies fund ongoing documentation revisions to ensure that the manual is always up-to-date. Regardless of whether you download this book for free,or purchase a bound copy,your feedback on the book is essential in ensuring this documentation remains current and useful.Please post your comments to the osg-users email list.See the Appendix,Where to Go From Here,for information on the osg-users email list. For information about new revisions to the book,visit the Open.SceneGraph Ouick Start Guide Web site: http://www.openscenegraph.org/osgwiki/pmwiki.php/ Documentation/QuickStartGuide This URL contains the most up-to-date information on obtaining the latest revision, downloading the book's example source code,and information on related publications. Target Audience This is a short book,and making it short was not an easy task.The scope is limited to a very narrow set of useful OSG functionality,and-just as importantly-the book targets a specific set of readers. This book is intended for software developers who are new to OSG and considering using it in their application.This book doesn't preclude a particular genre of application software,but provides information that will be useful to the visualization and simulation markets,which traditionally have been OSG's strength. OSG is a C++API,so it is assumed that you have some knowledge of C++.In particular, you should be familiar with C++features,such as public and private access,virtual functions,memory allocation,class derivation,and constructors and destructors.OSG makes extensive use of the standard template library (STL),so you should be familiar with STL constructs,especially list,vector,and map.Some familiarity with design patterns as implemented in C++is useful,but is not required. You should be familiar and comfortable working with data structures,such as trees and lists. If you are considering using OSG in your application,you are probably familiar with 3D graphics.For this book,you should be familiar with OpenGL,the standard cross-platform low-level 3D graphics API.You should know about different coordinate spaces at the conceptual level,and should be comfortable specifying three-dimensional Cartesian coordinates as geometric vertex data.You should know that texture mapping essentially
vi Preface In the spirit of open source, the OSGQSG is available for no charge as a PDF file. However, you can contribute to the OSG community by purchasing a full-color softbound copy. To place an online order for a copy of this book, visit the Lulu.com Web site and search for OpenSceneGraph. http://www.lulu.com Proceeds from sales of bound copies fund ongoing documentation revisions to ensure that the manual is always up-to-date. Regardless of whether you download this book for free, or purchase a bound copy, your feedback on the book is essential in ensuring this documentation remains current and useful. Please post your comments to the osg-users email list. See the Appendix, Where to Go From Here, for information on the osg-users email list. For information about new revisions to the book, visit the OpenSceneGraph Quick Start Guide Web site: http://www.openscenegraph.org/osgwiki/pmwiki.php/ Documentation/QuickStartGuide This URL contains the most up-to-date information on obtaining the latest revision, downloading the book’s example source code, and information on related publications. Target Audience This is a short book, and making it short was not an easy task. The scope is limited to a very narrow set of useful OSG functionality, and—just as importantly—the book targets a specific set of readers. This book is intended for software developers who are new to OSG and considering using it in their application. This book doesn’t preclude a particular genre of application software, but provides information that will be useful to the visualization and simulation markets, which traditionally have been OSG’s strength. OSG is a C++ API, so it is assumed that you have some knowledge of C++. In particular, you should be familiar with C++ features, such as public and private access, virtual functions, memory allocation, class derivation, and constructors and destructors. OSG makes extensive use of the standard template library (STL), so you should be familiar with STL constructs, especially list, vector, and map. Some familiarity with design patterns as implemented in C++ is useful, but is not required. You should be familiar and comfortable working with data structures, such as trees and lists. If you are considering using OSG in your application, you are probably familiar with 3D graphics. For this book, you should be familiar with OpenGL, the standard cross-platform low-level 3D graphics API. You should know about different coordinate spaces at the conceptual level, and should be comfortable specifying three-dimensional Cartesian coordinates as geometric vertex data. You should know that texture mapping essentially
OpenSceneGraph Quick Start Guide vi applies an image to geometry,but you need not know the specifics of how the graphics hardware accomplishes this. Some linear algebra experience is helpful.You should know that 3D locations are treated as vectors,and that graphics systems transform vectors by matrices as part of the rendering process.You should know that matrix concatenation combines transformations. Recommended Reading If you are a little rusty in any of the above areas,you might find the following list of recommend reading material useful. OpenGL Progrumming Guide,Fifth Edition,by OpenGL ARB,Dave Shreiner, Mason Woo,Jackie Neider and Tom Davis (Addison-Wesley)[ARBO5] Geometric Tools for Computer Gruphics,by Philip Schneider and David H.Eberly Morgan Kaufmann)）. Real-Time Rendering,Second Edition,by Tomas Akenine-Moller and Eric Haines (AK Peters). Computer Grapbics,Principles and Practice,Second Edition,by James D.Foley,Andries van Dam,Steven K.Feiner,and John F.Hughes (Addison-Wesley). The C++Programming Language,Third Edition,by Bjarne Stroustrup (Addison- Wesley). Organization of the Book The OpenSceneGraph Ouice Start Guide is composed of three main chapters and an appendix. Chapter 1,An Overview of Scene Graphs and OpenSceneGraph,opens with a brief history of OSG's origins,followed by instructions for obtaining and installing OSG and how to use some examples and applications included in the OSG distribution.The chapter includes an introduction to the concept of a scene graph,followed by an overview of OSG and its organization. In Chapter 2,Building a Scene Graph,you'll get your hands dirty assembling OSG data structures for storing and rendering geometry.Core OSG fundamentals,such as referenced pointers,scene graph nodes,drawable geometry,and state (including texture mapping and lighting)are described.This chapter also describes the osg Text node kit for quickly adding text to your scene,as well as file I/O for accessing stored scene graph data and images.You'll leave the chapter with a firm grasp of how to use OSG to build a scene graph that displays a variety of geometry. In Chapter 3,Using OpenSceneGraph in Your Application,you'll learn to do just that. The final chapter describes rendering,positioning and orienting the viewpoint,and animating and dynamically modifying your scene graph
OpenSceneGraph Quick Start Guide vii applies an image to geometry, but you need not know the specifics of how the graphics hardware accomplishes this. Some linear algebra experience is helpful. You should know that 3D locations are treated as vectors, and that graphics systems transform vectors by matrices as part of the rendering process. You should know that matrix concatenation combines transformations. Recommended Reading If you are a little rusty in any of the above areas, you might find the following list of recommend reading material useful. • OpenGL® Programming Guide, Fifth Edition, by OpenGL ARB, Dave Shreiner, Mason Woo, Jackie Neider and Tom Davis (Addison-Wesley) [ARB05] • Geometric Tools for Computer Graphics, by Philip Schneider and David H. Eberly (Morgan Kaufmann). • Real-Time Rendering, Second Edition, by Tomas Akenine-Moller and Eric Haines (AK Peters). • Computer Graphics, Principles and Practice, Second Edition, by James D. Foley, Andries van Dam, Steven K. Feiner, and John F. Hughes (Addison-Wesley). • The C++ Programming Language, Third Edition, by Bjarne Stroustrup (AddisonWesley). Organization of the Book The OpenSceneGraph Quick Start Guide is composed of three main chapters and an appendix. Chapter 1, An Overview of Scene Graphs and OpenSceneGraph, opens with a brief history of OSG’s origins, followed by instructions for obtaining and installing OSG and how to use some examples and applications included in the OSG distribution. The chapter includes an introduction to the concept of a scene graph, followed by an overview of OSG and its organization. In Chapter 2, Building a Scene Graph, you’ll get your hands dirty assembling OSG data structures for storing and rendering geometry. Core OSG fundamentals, such as referenced pointers, scene graph nodes, drawable geometry, and state (including texture mapping and lighting) are described. This chapter also describes the osgText node kit for quickly adding text to your scene, as well as file I/O for accessing stored scene graph data and images. You’ll leave the chapter with a firm grasp of how to use OSG to build a scene graph that displays a variety of geometry. In Chapter 3, Using OpenSceneGraph in Your Application, you’ll learn to do just that. The final chapter describes rendering, positioning and orienting the viewpoint, and animating and dynamically modifying your scene graph
viⅲ Preface Finally,the Appendix,Where to Go From Here,explains where you can find more information about OSG and how you can become involved in the OSG community. Conventions This book uses the following style conventions: .Bold-OSG classes and namespace names,OSG and OpenGL API methods and entry points,OSG and OpenGL types. Italic-Variables,parameter names,arguments,matrices,and spatial dimensions (such as x,y,and. Monospace-Code listings,short code segments within a text paragraph, enumerants,and constants. Furthermore,URL Web addresses are set aside from the text and use a monospace font and italics are used to introduce new terminology. About the Author Paul Martz is the president of Skew Matrix Software LLC,which provides custom software development,documentation,and developer training services.Paul has been involved in 3D graphics software development since 1987 and is the author of OpenGL*Distilled [Martz06].He plays drums and provides music instruction,and is known to enjoy an occasional game of poker
viii Preface Finally, the Appendix, Where to Go From Here, explains where you can find more information about OSG and how you can become involved in the OSG community. Conventions This book uses the following style conventions: • Bold—OSG classes and namespace names, OSG and OpenGL API methods and entry points, OSG and OpenGL types. • Italics—Variables, parameter names, arguments, matrices, and spatial dimensions (such as x, y, and z). • Monospace—Code listings, short code segments within a text paragraph, enumerants, and constants. Furthermore, URL Web addresses are set aside from the text and use a monospace font and italics are used to introduce new terminology. About the Author Paul Martz is the president of Skew Matrix Software LLC, which provides custom software development, documentation, and developer training services. Paul has been involved in 3D graphics software development since 1987 and is the author of OpenGL® Distilled [Martz06]. He plays drums and provides music instruction, and is known to enjoy an occasional game of poker
