VR Juggler
   Next

VR Juggler

The Programmer's Guide

Version 3.0

Copyright © 2001–2010 Iowa State University

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with the Invariant Sections being Appendix A. GNU Free Documentation License, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in Appendix A. GNU Free Documentation License.

$Date: 2010-06-10 20:45:28 -0500 (Thu, 10 Jun 2010) $

Table of Contents

I. Introduction
1. Getting Started
Necessary Experience
Required Background
Other VR Software Tools
Organization
2. Application Basics
Application Object Overview
No main()—“Don't call me, I'll call you”
Application Objects Derive from Base Classes for Specific Graphics APIs
Writing an Application Means Filling in the Blanks
Benefits of Application Objects
Allow for Run-Time Changes
Low Coupling
Allows Implementation Changes
Multi-Language Interaction
VR Juggler Startup
No main()—Sort Of
Structure of a main() Function
Mac OS X Considerations
Kernel Loop
Definition of a Frame
Base Application Object Interface
Initialization
Frame Functions
Draw Manager-Specific Application Classes
OpenGL Application Class
OpenGL Performer Application Class
3. Helper Classes
The gmtl::Vec<S, T> Helper Class
High-Level Description
Using gmtl::Vec3f and gmtl::Vec4f
Creating Vectors and Setting Their Values
Inversion (Finding the Negative of a Vector)
Normalization
Length Calculation
Multiplication by a Scalar
Division by a Scalar
Converting to an OpenGL Performer Vector
Assignment
Equality/Inequality Comparison
Dot Product
Cross Product
Addition
Subtraction
Full Transformation by a Matrix
The Gory Details
The gmtl::Matrix44f Helper Class
High-Level Description
Using gmtl::Matrix44f
Creating Matrices and Setting Their Values
Assignment
Equality/Inequality Comparison
Transposing
Finding the Inverse
Addition
Subtraction
Multiplication
Scaling by a Scalar Value
Making an Identity Matrix Quickly
Zeroing a Matrix in a Single Step
Making an XYZ, a ZYX, or a ZXY Euler Rotation Matrix
Making a Translation Transformation Matrix
Making a Scale Transformation Matrix
Extracting Specific Transformation Information
Converting to an OpenGL Performer Matrix
The Gory Details
Device Proxies and Device Interfaces
High-Level Description of Device Proxies
High-Level Description of Device Interfaces
Using Device Interfaces
Stupefied Proxies
The Gory Details
II. Application Programming
4. Application Authoring Basics
Application Review
Basic Application Information
Draw Manager-Specific Application Classes
Getting Input
How to Get Input
Where to Get Input
Tutorial: Getting Input
5. Using Graphics Programming Interfaces
OpenGL Applications
Clearing the Color and Depth Buffers
OpenGL Drawing: vrj::opengl::App::draw()
Tutorial: Drawing a Cube with OpenGL
Context-Specific Data
Using Context-Specific Data
Context-Specific Data Details
Tutorial: Drawing a Cube using OpenGL Display Lists
OpenGL Performer Applications
Scene Graph Initialization: vrj::pf::App::initScene()
Scene Graph Access: vrj::pf::App::getScene()
Tutorial: Loading a Model with OpenGL Performer
Other vrj::pf::App Methods
pfExit(): To Call or Not to Call
OpenSG Applications
Scene Graph Initialization: vrj::opensg::App::initScene()
Scene Graph Access: vrj::opensg::App::getScene()
Tutorial: Loading a Model with OpenSG
Open Scene Graph Applications
Scene Graph Initialization: vrj::osg::App::initScene()
Scene Graph Access: vrj::osg::App::getScene()
Tutorial: Loading a Model with Open Scene Graph
VTK Applications
6. Additional Application Programming Topics
Cluster Application Programming
Shared Input Data
Application-Specific Shared Data
General Cluster Programming Issues
Troubleshooting Cluster Problems
Adding Audio
Using Sonix Directly
Using the VR Juggler Sound Manager
7. Porting to VR Juggler from the CAVElibs™
The Initialize, Draw, and Frame Routines
Getting Input from Devices
Configuration
Important Notes
Shared Memory
OpenGL Context-Specific Data
Source Code
The Form of a Basic CAVElibs™ Program
The Form of a Basic VR Juggler Program
8. Porting to VR Juggler from GLUT
Window Creation and Management
The Initialize, Draw, and Frame Routines
Getting Input from Devices
Configuration
Important Notes
Shared Memory
OpenGL Context-Specific Data
Source Code
The Form of a Basic GLUT Program
The Form of a Basic VR Juggler Program
III. Advanced Topics
9. System Interaction
10. Multi-threading
Techniques
Tutorial: Perform Computations Asynchronously to Rendering with intraFrame()
Class Declaration and Data Members
The preFrame() Member Function
The draw() Member Function
Exercise
Helper Classes
vpr::Thread
Thread Functors
Using the vpr::Semaphore Interface
Using the vpr::Mutex Interface
Using Data Buffering
Triple Buffering
Optimizing Triple Buffering
Using Triple Buffering in an Application
Tutorial: Perform Computations Using Triple Buffering
11. Run-Time Reconfiguration
How Run-Time Reconfiguration Works
Reasons to Use Run-Time Reconfiguration
Using Run-Time Reconfiguration in an Application
Create Application-Specific Configuration Definitions
Implement the Dynamic Reconfiguration Interface
Procesing Configuration Elements
Loading and Saving Configurations
Tutorial: Using Application-Specific Configurations
Class Declaration
Application Configuration
The configCanHandle() Member Function
The configAdd() Member Function
The draw() Member Function
Exercise
12. Extending VR Juggler
Device Drivers
Custom Simulators
Simulator Components
13. Advanced Topics
Customizing Render Thread Processor Affinity
Making a Custom NSApplication Delegate on Mac OS X
Data Members
Designated Initializer
-setLoadConfigs:
-applicationShouldTerminateAfterLastWindowClosed:
-applicationDidFinishLaunching:
-application:openFile:
-application:openFiles:
Defining Custom Cocoa/VR Juggler Bridging on Mac OS X
IV. Appendices
A. GNU Free Documentation License
PREAMBLE
APPLICABILITY AND DEFINITIONS
VERBATIM COPYING
COPYING IN QUANTITY
MODIFICATIONS
COMBINING DOCUMENTS
COLLECTIONS OF DOCUMENTS
AGGREGATION WITH INDEPENDENT WORKS
TRANSLATION
TERMINATION
FUTURE REVISIONS OF THIS LICENSE
ADDENDUM: How to use this License for your documents
Glossary of Terms
Index

List of Figures

2.1. vrj::App hierarchy
2.2. Kernel loop sequence
2.3. Application object interface
2.4. vrj::opengl::App interface extensions to vrj::App
2.5. vrj::pf::App interface extensions to vrj::App
4.1. VR Juggler kernel control loop
5.1. vrj::opengl::App application class
5.2. VR Juggler OpenGL system
5.3. vrj::pf::App application class
5.4. vrj::opensg::App application class
5.5. vrj::osg::App application class
6.1. Basic Sonix Interface
6.2. The Sonix Design
6.3. Use of Plug-ins in Sonix

List of Tables

3.1. Row-major access indices
3.2. Column-major access indices

List of Examples

2.1. Ignoring Command Line Arguments on Mac OS X
2.2. Handling Optional Command Line Arguments on Mac OS X
3.1. Using gadget::DigitalInterface in an Application Object
3.2. Using gadget::KeyboardMouseInterface in an Application Object
3.3. Requesting Positional Data in Application-Specific Units
5.1. Initializing context-specific data
5.2. Using pfExit() with a Heap-Allocated Application Object
5.3. Using pfExit() with a Stack-Allocated Application Object
6.1. Declaration of a Serializable Type
6.2. Serializing an Application-Specific Type
6.3. Sample Third-Party Type
6.4. Serializing a Third-Party Type Using vpr::SerializableObjectMixin<T>
6.5. Declaring Instances of cluster::UserData<T>
6.6. Initializing Application-Specific Shared Data
6.7. Application-Specific Shared Data Configuration
6.8. Writing to Application-Specific Shared Data
6.9. Reading from Application-Specific Shared Data in latePreFrame()
6.10. Reading from Application-Specific Shared Data in draw()
6.11. Calculating Frame Deltas Using vpr::Interval
6.12. Initializing the Sonix Sound APi
6.13. Setting Up a Sonix Sound Handle
6.14. Sonix Frame Update
6.15. Complete Sonix Program Using OpenAL
6.16. Reconfiguring Sonix at Run Time
6.17. Example Sonix Sound Manager Conifguration
6.18. Declaring Sound Handles in Application Object Class
6.19. Initializing Sound Handles in an Application Object
6.20. Triggering Sounds in an Application Object
10.1. Thread Functors from Free Functions
10.2. Thread Functor from a Static Member Function
10.3. Thread Functor from a Non-Static Member Function
10.4. Thread Functor from Callable Object
10.5. Handling Thread Spawn Failure
11.1. Complete listing of config_app.jdef
11.2. ConfigApp.jconf
13.1. MyDelegate.mm: Basic Delegate Implementation
   Next
   Part I. Introduction