Equalizer API Documentation

0.9

• 1. Introduction
• 1.1. Features
• 2. New in this release
• 2.1. New Features
• 2.2. Enhancements
• 2.3. Optimizations
• 2.4. Examples
• 2.5. Tools
• 2.6. API Changes
• 2.7. Documentation
• 2.8. Bug Fixes
• 2.9. Known Bugs
• 3. About
• 3.1. Operating System Support
• 3.2. Window System Support
• 3.3. Documentation
• 3.4. Support

1. Introduction

Welcome to Equalizer, the standard middleware to create and deploy parallel, scalable OpenGL applications. Equalizer 0.9 delivers major new features, most notably major new scalability features and a plugin API for image compression.

Equalizer 0.9 can be retrieved by downloading the source code.

1.1. Features

Equalizer provides the following major features to facilitate the development and deployment of scalable OpenGL applications. A detailed feature list can be found on the Equalizer website.

• Runtime Configurability: An Equalizer application is configured at runtime and can be deployed on laptops, multi-GPU workstations and large-scale visualization clusters without recompilation.
• Runtime Scalability: An Equalizer application can benefit from multiple graphics cards, processors and computers to scale rendering performance, visual quality and display size.
• Distributed Execution: Equalizer applications can be written to support cluster-based execution. The task of distributing the application data is facilitated by support for versioned, distributed objects.
• Support for Stereo and Immersive Environments: Equalizer supports both active and passive stereo rendering, as well as head tracking and head-mounted displays used in immersive Virtual Reality installations.

2. New in this release

Equalizer 0.9 contains the following features, enhancements, bug fixes and documentation changes:

2.1. New Features

• Automatic cross-segment load-balancing for multi-display installations
• Dynamic Frame Resolution (DFR) for constant framerate rendering
• Compression Plugin API for runtime-loadable image compression engines
• Canvas and Layout API for runtime-switchable layouts and resource configurations
• Simple configuration of physical projection system
• Logical view layouts on multi-segment projection surfaces
• Simple 2D operations on multi-segment projection surfaces
• Run-time (de-)activation of nodes, pipes, windows and channels
• Support for multiple observers in a single configuration
• Support for Head-Mounted Displays (HMD)
• Monitor Equalizer for the observation of other views
• Up- and down-scaling for source channel pixel viewports, including zoom support for compositing
• Support for hardware swapbuffer synchronization with nVidia G-Sync
• Support for Framebuffer Objects (FBO)
• Support for half_float and float PBuffers and FBOs
• Spacemouse support (AGL only)
• New helper class to handle dynamic libraries
• New helper class for memory-mapped files

2.2. Enhancements

• Improved statistics overlay (added legend, FPS counter, image compression ratio, pipe idle ratio, framerate throttle statistic)
• New helper class eq::Object for easier data distribution of dynamic, versioned objects
• Texture-based frames for optimal compositing on a single GPU
• Upgraded to VMMlib 1.0
• Abstraction for window-system specific code through OSPipe interface
• AGL event handling follows same threading model as GLX and WGL
• Config file versioning
• Synchronize clock used for logging across all nodes
• Improved handling for event-driven applications

2.3. Optimizations

• Lock-free network packet cache for low-latency, high-performance packet dispatch
• Network layer uses asynchronous IO semantics and has better performance on Windows
• Per-component and differential RLE image compressor
• Use GL_UNSIGNED_INT depth buffer instead of GL_FLOAT for better performance and compression
• DPlex framerate equalizer optimizations
• Faster serialization of std::vectors in distributed objects
• Named pipe connection for fast local communication on Windows

2.4. Examples

• eqOSG: new OpenSceneGraph-based example
• eqNBody: new, preliminary example showing integration with CUDA
• eqPly: added wireframe mode
• eqPly: added multi-model support
• eqPly: full support of the new layout API
• eqPly: added help overlay on 'F1'
• eqPly: optimized kD-tree layout
• eqPly: added walk-through mode
• eqPly: added loadable camera paths
• eqPly: added Spacemouse support (AGL only)
• eqPly: added command-line option to disable overlay logo
• eqPly: unified coloring to demonstrate decomposition

2.5. Tools

• affinityCheck: new command-line tool to list available affinity GPUs (WGL only)
• configTool: added support for having an async compositing GPU for DB
• configTool: added support for setting the destination window resolution

2.6. API Changes

The following changes breaking compatibility with Equalizer 0.6 source code were made:

• VMMlib, the vector and matrix library used by Equalizer, was upgraded to version 1.0. The API of this library changed, and all type definitions used by Equalizer now reside in the eq namespace instead of the vmml namespace.
• The View API introduced in 0.6 has been replaced by the more powerful Layout/Canvas/Observer API
• All window system specific calls have been moved from eq::Pipe to the corresponding eq::OSPipe implementation.
• Config::setHeadMatrix and Config::setEyeBase have been deprecated. Use Config::getObservers, Observer::setHeadMatrix and Observer::setEyeBase instead.
• The ChannelVisitor::Result type has been renamed to the generic VisitorResult type used by all visitors.
• The access to pixel data in eq::Image has been slightly changed by the introduction of compression plugins.
• The enum Node::IATTR_HINT_STATISTICS has been removed since it is not used anymore.
• Reference counting of OpenGL objects allocated by eq::ObjectManager has been removed. This functionality proved unnecessary and complicated the API.
• The enum value Event::EXPOSE has been renamed to Event::WINDOW_EXPOSE.

2.7. Documentation

The following documentation has been added or substantially improved since the last release:

• The Programming and User Guide has been extended to 86 pages and 52 figures.
• Quickstart and Demo Guide
• Equalizer: A Scalable Parallel Rendering Framework, IEEE Transactions on Visualization and Computer Graphics, vol. 15, no. 3, pp. 436-452, May/June 2009.
• API Documentation
• GPU Affinity Checker
• Hardware swapbarrier for synchronization of multipipe displays
• Compression Plugin API is the official interface to create binary plugins for data compression.
• Layout API provides a way to configure physical projection surfaces with logical layouts and multiple observers.

2.8. Bug Fixes

Equalizer 0.9 includes various bugfixes over the 0.6 release, including the following:

• 2822348: No latency when event-driven
• 2803528: assertion with zero area pvps
• 2797391: Error state in parser not reset
• 2788964: Suspicious compiler warning
• 2782038: Mapping of multiple Objects of type DELTA creates assertions
• 2778587: eqServer crashes when running without an appNode
• 2688797: Configs with no appNode crash
• 2592240: DPlex LB breaks swapbarrier
• 2556921: AGL context updates broken
• 2545209: crashes on specific configs
• 2458583: Mouse buttons are numbered differently between AGL and GLX
• 2268547: fullscreen windows not always active on Win32
• 1997583: eqPly: ortho frustum culling broken
• 1816670: eVolve: binary swap configs don't work

2.9. Known Bugs

The following bugs were known at release time. Please file a Bug Report if you find any other issue with this release.

• 2796444: Race during simultaneous node connect
• 2642034: Win32: max 64 connections possible
• 2609161: zoom: depth readback does not work
• 2556940: zoom: FBO usage
• 2003195: Ortho frustra ignores eye offset
• 1854948: eVolve: lighting ignores head transformation
• 1854929: eqPly GLSL shader has artefacts

3. About

Equalizer is a cross-platform toolkit, designed to run on any modern operating system, including all Unix variants and the Windows operating system. A compatibility matrix can be found on the Equalizer website.

Equalizer requires at least OpenGL 1.1, but uses newer OpenGL features when available. Version 0.9 has been tested on:

3.1. Operating System Support

• Linux: Ubuntu 8.04, 9.04 (i386)
• Windows: XP with Visual Studio 2005 (i386, x64)
• Mac OS X: 10.5 (PowerPC, i386)

3.2. Window System Support

• X11: Full support for all documented features.
• WGL: Full support for all documented features.
• AGL: Full support for all documented features.

3.3. Documentation

The Programming and User Guide is available as a hard-copy and online. API documentation can be found on the Equalizer website.

As with any open source project, the available source code, in particular the shipped examples provide a reference for developing or porting applications. The Developer Documentation on the website provides further design documents for specific features.

3.4. Support

Technical questions can be posted to the Developer Mailing List, or directly to [email protected].

Commercial support, custom software development and porting services are available from Eyescale. Please contact [email protected] for further information.