VRGL

Off-Axis Projections for OpenGL Applications

by Willem de Jonge


VRGL is a modified OpenGL libarary which makes it possible to use off-axis projections with Unreal Tournament 2004. In principle, VRGL is generic and can also be used with other OpenGL applications to get an off-axis frustum.

It is a custom OpenGL library that calls the original system OpenGL library for most of its work. It changes the projection of the application to a user-defined (by means of parameters in an .ini file) off-axis frustum.

Note that while VRGL is a generic tool for off-axis projections it is developed for, and tested with UT2004. VRGL is used by CaveUT2004 to allow UT2004 to work on multiscreen immersive displays. It is this package, part of the game itself, which synchronizes the rotation and position for all display clients. It calls VRGL to handle the perspective effects.

Configuration and usage


For an application to use the custom OpenGL library it should load this one instead of the system one, this is accomplished by placing the library in the same directory as the executable, this directory is searched before the system directory for any dll’s to load by Windows. For UT2004 this directory is <install-dir>\System.

The parameters for the off-axis projection are read from the file CaveUT.ini in this same directory. Four parameters, FOVleft, FOVright, FOVtop and FOVbottom , are used to define the projection. These parameters are the angles for all sides of field-of-view in degrees relative to the view axis (perpendicular to the viewing plane through the center of projection).


If the part of the new off-axis is outside the original field-of-view it is possible that objects in that part aren’t rendered because the application thinks they won’t be visible and thus doesn’t send them to OpenGL. In UT2004 this is fixed by setting the fov as large as needed to fit the whole off-axis frustum.

VRGL reads its parameters from the CaveUT.ini configuration file. The parameter OffAxis can be set to Yes or No to turn on or off the off-axis effect. VRGL ignores the other parameters, (Roll, Pitch,...,CaveFOV) which are used by the CaveUT2004 mutator.

Example CaveUT.ini file:

[CaveUT.Spectator]
CaveRoll=0.000000
CavePitch=0.000000
CaveYaw=0.000000
CaveOffsetX=0.000000
CaveOffsetY=0.000000
CaveOffsetZ=0.000000
CaveFOV=100.000000
OffAxis=No
FOVleft=-45
FOVright=45
FOVtop=36.87
FOVbottom=-36.87

[CaveUT.CaveUTInteraction]
RotateIncrement=0.250000
OffsetIncrement=0.500000
FOVIncrement=0.500000

Download

The source and executable are in:   VRGL.zip.

The source code was originally compiled with MSVC++ 6.0, though it should be compatible for other compilers.


Inner workings

This section gives an overview how VRGL works; exact details can be found in the source code.

Basic operation of VRGL consists of the following:


A copy of the matrix stack is kept to ensure that the behavior custom OpenGL library appears the same as the real one to the application, ie stapling and/or querying the projection matrix works as expected. For non-perspective projection matrices the intended matrix is used directly and not the user defined one, the reason for this is a practical one: Even if you have a really odd user projection you can still 2D elements such as the game menus and console in UT2004.

To build the user defined projection matrix we need a near and a far plane besides the 4 FOV parameters. To ensure that behavior is as much as was intended by the application we extract the values for the near and far planes from the intended projection matrix.

To pass calls to OpenGL the custom library implements a jumptable to the real OpenGL functions is maintained. To fill this table the original OpenGL library is dynamically loaded and the table filled on initialization. We can’t link directly/statically to OpenGL as we are building the same library (as far as interfaces are concerned).

As this jumptable and the code to initialize is quite dump (for all the calls that are passed unchanged) we automatically generate is. This is done with the genstub.pl perl script, it takes for input OpenGL header files, gl.h (the mesa header file is used for this one) and wgl.h (specifically composed for this purpose), the latter containing the function declaration for the Windows specific calls. In addition to the header files two files containing function names are read:


From this the following is generated:

Copyright (c) 2005
Willem de Jonge and PublicVR
All rights reserved

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:

"This product includes software developed and owned by Willem de Jonge and PublicVR (http://publicvr.org)."

Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.

4. VRGL is a trademark belonging to PublicVR and Willem de Jonge Accordingly, products derived from this software may not be called "VRGL", nor may "VRGL" appear in their name, without prior written permission from PublicVR or Willem de Jonge PublicVR.

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PublicVR OR THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Last updated March 11, 2004.
URL: http://www.planetjeff.net/ut/CUT4VRGL.html
This page is copyright © 2004 by Jeffrey Jacobson.
See this web site's copyright notice for information
on duplicating or distributing this page or its contents.