The purpose of this document is to assist you in creating your own display configuration files. In addition to a model configuration file, vrNav2 requires a base configuration file and a display configuration file in order to run. Two base configuration files and a set of display configuration files used for the various machines we support at UCLA can be found in the VRNAV_HOME/config directory. When you run vrNav2, the vrNav2 script selects the correct base and display configuration file for your hardware setup and it passes them to the vrNav2App application. Display configuration files are provided for single-machine environments as well as for tiled displays and 3-projector spherical displays. If there is a display configuration file, as distributed, that is suitable for your display, there is no need to create a new one; you do not have to read this document.
When you run vrNav2 from the vrNav2 script, you can use the script's -D or -displayconfig option to override the script's display config file selection process and run with a display configuration file that you have created. For example:
vrNav2 -D mydisplayconfig.jconf mymodelconfig.jconf7
To change the default display config file that the vrNav2 script uses, modify the $VRNAV_HOME/config/CONFIG_FILE_VARIABLES file.
When you run vrNav2 directly via the vrNavApp executable, include the filename of the display configuration file that you have created along with your other configuration files after the -configfiles argument. For example:
vrNavApp -mouse -configfiles base.1pipe.jconf \ mydisplayconfig.jconf mymodelconfig.jconf7
A Note about Graphics Pipes
vrNav2 is distributed with two base configuration files:
- base.1pipe.jconf
- This file specifies 1 graphics pipe. Use this configuration file on all single display systems and on each tile of a tiled display.
- base.3pipe.jconf.
- This file specifies 3 graphics pipes. This is a legacy base config file from IRIX systems. Note that base.3pipe.jconf has not been tested with vrNav2osg because vrNav2osg has never been run on IRIX. It is distributed for your information only. For IRIX systems with more than 3 graphics pipes you could make a base config file based on base.3pipe.jconf which supports the number of pipes you have.
The elements in a display configuration file must be consistent with the elements in the base configuration file that it is used with. The base config file contains a display_system chunk that defines the number of graphics pipes and the pipes themselves. The display configuration file contains one or more display_window elements (chunks). The number of display_window elements in a display configuration file must be the same as the number of pipes specified in the base configuration file you are using. Note that we at UCLA ATS are always using just a single pipe and all of the display config files that we use have a single display_window element.
We do ship a file named portal.display.3.jconf for information purposes only. This file has three display_window elements and is the correct file to accompany base.3pipe.jconf. This file has NOT been tested with vrNav2osg as vrNav2osg has never been run on IRIX systems.
Every display configuration file MUST have a display_window element named FrontScreen. If you have additional displays, you can name them anything.
The origin and size tags in the display_window chunk are used to specify the origin and size of your display window. You can set up the graphics window to either fill your display or to be a small window on your display. To have the graphics window fill the display, set the origin at 0,0 and the size at your display width and height. For a smaller window, set the size at something smaller than your display; the origin (lower left corner of the graphics window) can be anywhere that will not cause the graphics window to be cut off. The border tag is used to specify whether there should be a window-system border around the graphics window or whether the graphics window should be borderless.
To determine the maximum screen size of your display:
/usr/X11R6/bin/xwininfo -root
Output looks like:
xwininfo: Window id: 0xad (the root window) (has no name) Absolute upper-left X: 0 Absolute upper-left Y: 0 Relative upper-left X: 0 Relative upper-left Y: 0 Width: 1024 Height: 768 etc.
You can use the values you obtain (1024 and 768) in the <size> tags for horizontal and vertical screen size.
On IRIX systems:
/usr/gfx/ircombine -source file whatever.cmb -global size
Output looks like:
Global Combination Attributes: ----------------------------- Managed Size: (1280, 1024)
You can use the values you obtain (1280 and 1024) in the <size> tags for horizontal and vertical screen size.
If you are using base.1pipe.jconf, this value should be 0. Otherwise, use the index (starting with 0) into the list of pipes (x11_pipes) in the display_system chunk of the base config file that this display_window element of the display config file corresponds to.
Each display_window chunk must contain a frame_buffer_config chunk. This chunk specifies the visual to be used for the graphics. Specify a visual_id of -1 to have the system choose the visual for you. In that case, specify 1 for the other tags as shown in the config file display.jconf. In this context, 1 means 1 or more. So, for example, specifying 1 for red_size normally results in a bit depth of 8 bits for red. fsaa_enable if set to true requests that anti-aliasing be turned on. Specifying false turns it off. Anti-aliasing may be dependent on system variables, see System Variables for nVidia below.
Each display_window chunk must contain a surface_viewport chunk. In the surface_viewport chunk corner elements are used to to specify the locations of the four corners of a plane going through the viewing frustum which is parallel to the back plane. Each corner element is repeated three times, to specify the x, y, and z positions of that corner. For example:
<lower_left_corner>-2.275</lower_left_corner> <lower_left_corner>-1.82</lower_left_corner> <lower_left_corner>-3.81</lower_left_corner>
where the first occurrence describes the location of the corner in x (left or right), the second occurrence describes the location in y (height), and the third occurrence describes the location of the corner in z (depth).
vrNav2 is ultimately built on OpenGL and two OpenGL functions determine the appearance of the graphics on the screen. These set the viewport and the viewing frustum. The viewport is set using the width and height of the screen in pixels and the viewing frustum is either set with:
left, right, bottom, top, near, far
which is the way that vrJuggler and vrNav set it, or with:
field_of_view, aspect_ratio, near, far
near is the distance of the near clipping plane of the viewing frustum from the eye point. far is the distance of the far clipping plane from the eye point. vrNav2 by default uses .1 for near and 200000 for far. If you don't like these defaults you can change them by including the FarPlane and NearPlane elements in the model config file used with your model.
In order to prevent distortion, aspect_ratio or
( right - left ) / ( top - bottom )
must be the same as:
width / height
where width and height are the width and height of the screen in pixels.
The display config file is read by vrJuggler. vrJuggler takes the the figures you give for the corners and converts them into left, right, bottom, top, near, far format. In this format, left, right, bottom and top are the positions of the left, right, top, and bottom corners at the near clipping plane. vrJuggler figures out what these should be from the numbers you put in for the corners. The corners that you supply are for an arbitrary plane through the viewing frustum. You specify the Z value of the corners to indicate just where this plane is.
The field of view can be computed from the values that you give for the corners, and here it is the Z value that determines the field of view.
vrNav2 always uses a symmetrical viewing frustum which is right angled and aligned with the Z axis. That is, vrNav2 always places the navigator/viewer at the center of the screen. To ensure that this is so, the x and y locations of the corners in the display_window named FrontScreen must be centered at x=0, y=0. i.e., the left corner X values must be the negative of the right corner X values and the lower corner Y values must be the negative of the upper corner Y values.
The viewing frustum can be thought of as being composed of 4 right triangles.
Two in the X=0 plane extending up and down in Y and two in the
Y=0 plane extending left and right in X. They meet along the line extending
from the eye point to the frustum back plane. The following figure shows you
what two of the right triangles look like. The other two are similar in
appearance except that the triangles are in Y and Z
instead.
If you use an incorrect field of view, vrNav2 will produce a
"fish-eye" (convex) or receding (concave) appearance which will
distort your graphics.
To figure out a field of view that will work for you, measure
the distance from your eye to the screen and the height of the screen.
It the case of my desktop workstation, I am sitting 15" from the screen and
the screen is 12" top to bottom. Since we are only concerned with one of the
two triangles, I will use half of that or 6". The angle is
arctan( 6/15 ) = 21.8 degrees (43.6 degrees for both triangles).
For the large spherical screen in our visualization portal, we can use the
distance from the screen to the design eye point as Z and half the height
of the screen as Y and make a similar computation. As shown in the next
diagram, in the Visualization Portal at UCLA ATS, the design eye point is
12.5' from the screen and the screen itself is 12.2' high and 42' wide.
The values you supply for the corner elements do not need to have any specific values. What is important is that their ratio be consistent. That is, The X and Y coordinates do have to produce a plane of the correct aspect ratio, and the Z coordinate has to be consistent. For example, if your screen is 1400x1050 that is a 4:3 or 1.33 ratio, and the corresponding corner values must be in that same ratio in order for your model to display properly. However, if your screen is 1280x1024, that is a 5:4 or 1.25 ratio and your corner values must be in that same ratio for your model to display properly. The actual numbers chosen for X and Y, depend on the number chosen for Z.
Continuing with the example discussed above illustrates this. If my display is 1280x1024, a 1.25 aspect ratio, I could specify my corners with:
X from: -7.5 to 7.5
Y from: -6.0 to 6.0
Z at: -15.0
or with:
X from: -15.0 to 15.0
Y from: -12.0 to 12.0
Z at: -30.0
or with any other combination of numbers that is proportional to these. The file display.jconf, which is shipped with vrNav2, also specifies a screen size of 1280x1024, a 5:4 or 1.25 aspect ratio. That file uses a slightly different field of view and has:
X from: -2.275 to 2.275
Y from: -1.82 to 1.82
Z at: -3.81
But note what vrJuggler does with these when it sets up the viewing frustum. For the figures I computed for my screen, it sets left, right, bottom and top at near at: -.05, .05, -.04 and .04. For the figures given in display.jconf, it sets them at: -.059, .059, -.047, and .047. These two sets of numbers are very similar and the view of the model looks the same.
Other tiles can be considered continuations of the central tile. vrNav is shipped with two sets of config files each for a different type of 3 tile tiled display. tiledDisplay.display.1x1.jconf, tiledDisplay.display.1x2.jconf, and tiledDisplay.display.1x3.jconf are each used with a tile of a flat, single row, three column tiled display.
In this set the central tile has corners at:
X from: -2.275 to 2.275
Y from: -1.82 to 1.82
Z at: -3.81
The viewing frustum plane at Z=-3.81 extends 4.55 in X. The tile to the left of this tile has corners at:
X from: -6.825 to -2.275
Y from: -1.82 to 1.82
Z at: -3.81
A plane through its viewing frustum at Z=-3.81 also extends 4.55 in X and occupies the space just to the left of the same plane of the central tile. Since this tile is in the same row as the central tile, its Y range is identical to the Y range of that tile and, of course, its Z is also identical. Likewise, the tile to the right of the central tile extends in X from 2.275 to 6.825.
portal.display.3.center.jconf, portal.display.3.left.jconf, and portal.display.3.right.jconf are each used with a tile of a single row, three column tiled display whose output is displayed on a curved screen with overlap and edge blending. Here we start with the central tile which has corners at:
X from: -4.0 to 4.0
Y from: -3.0 to 3.0
Z at: -7.172
For our particular setup, we have to apply a rotation of 51.4 degrees left and right to the corners of this plane in the viewing frustum to get the corners of corresponding planes in our other two viewing frustums. Y will not change. The number 51.4 degrees is related to the way the projectors were installed. You might need to use a different number at your installation. We apply the rotation as follows to the right corners to get the coordinates of the right corners of the tile to the right of the center tile:
| cos( 51.4) -sin( 51.4) | | 4.0 | = | 4 cos( 51.4) + 7.172 sin( 51.4) |
| sin( 51.4) cos( 51.4) | | -7.172 | = | 4 sin( 51.4) - 7.172 cos( 51.4) |
Multiplying this out gives us X = 8.101 and Z = -1.348 for the right corners. Substituting the coordinates of the left corners in the equation we get X = 3.109 and Z = -7.601.
For the tile to the left of this one, we use -51.4 degrees instead of 51.4 degrees:
| cos(-51.4) -sin(-51.4) | | 4.0 | = | 4 cos(-51.4) + 7.172 sin(-51.4) |
| sin(-51.4) cos(-51.4) | | -7.172 | = | 4 sin(-51.4) - 7.172 cos(-51.4) |
This gives us X = -3.109 and Y = -7.601 at the right corners.
The display configuration file for a stereographic display differs from a monographic display in the following ways:
<user name="stereoUser" version="1"> <head_position>Head Proxy</head_position> <interocular_distance>0.06</interocular_distance> </user>
The interocular_distance element in the base configuration file specifies the stereo separation, in meters. The vrNav2 script may change this value based on its -stereo argument. Model specific interocular distance values may be saved in a modelname.rc file -- see $VRNAV_HOME/utils/run_arch run_sci or run_model sample scripts.
visual x bf lv rg d st colorbuffer ax dp st accumbuffer ms cav id dep cl sp sz l ci b ro r g b a bf th cl r g b a ns b eat ---------------------------------------------------------------------- 0x25 24 tc 0 32 0 r y y 8 8 8 8 4 24 8 16 16 16 16 0 0 None
This is a sample display configuration file with comments shown in html-type brackets <!-- and -->.
The sample shows only one display_window chunk for a single screen display. If you have more than one pipe, for example on an IRIX system, you need a display_window chunk for each screen. For a 3-pipe display you need three display_window chunks, e.g., "FrontScreen", "LeftScreen", and "RightScreen".
One of the display_window chunks must be named "FrontScreen". This is required by the vrNavApp executable.
<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
name="Configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration
http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">
<elements>
<display_window name="FrontScreen" version="4">
<origin>0</origin>
<origin>0</origin>
<size>1280</size> <!-- 5:4 width:height ratio -->
<size>1024</size>
<pipe>0</pipe>
<!-- which x11_pipe of the display_system is to be used -->
<frame_buffer_config>
<opengl_frame_buffer_config name="GL Frame Buffer" version="1">
<visual_id>-1</visual_id>
<!-- Code -1 to have vrJuggler choose the visual
for you or enter glxinfo (X Windows) or wglinfo
(Windows) to find out what visuals are available on
your system. Select one and code the decimal
equivalent of its number here to choose that visual.
If you do that, all remaining property settings shown
here below will be ignored as the properties of the .
visual you have selected will be the ones used. -->
<red_size>1</red_size>
<green_size>1</green_size>
<blue_size>1</blue_size>
<alpha_size>1</alpha_size>
<!-- if you set these to a number such as 8, then the only
visuals that could be selected would have a bit
depth of 8 or more. If one doesn't exist, then THE
WINDOW WILL NOT BE ABLE TO OPEN.
If you set these to 1, then the highest visual
available with >= 1 bit will be used.
If you set these to 0 then, the visual with the smallest
available bit size will be used
Enter glxinfo (X Windows) or wglinfo (Windows) to find
out what visuals are available on your system -->
<depth_buffer_size>1</depth_buffer_size>
<fsaa_enable>false</fsaa_enable>
<!-- full-screen anti-aliasing -->
</opengl_frame_buffer_config>
</frame_buffer_config>
<stereo>false</stereo>
<!-- true for stereo -->
<border>true</border>
<hide_mouse>false</hide_mouse>
<active>true</active>
<!-- if false, this whole display window will be ignored -->
<surface_viewports>
<!-- describes the surfaces of the display device -->
<surface_viewport name="FrontScreen viewport" version="2">
<origin>0.0</origin>
<origin>0.0</origin>
<size>1.0</size>
<size>1.0</size>
<view>Left Eye</view>
<user>monoUser</user>
<active>true</active>
<vertical_fov>0.0</vertical_fov>
<lower_left_corner>-2.275</lower_left_corner>
<lower_left_corner>-1.82</lower_left_corner>
<lower_left_corner>-3.81</lower_left_corner>
<lower_right_corner>2.275</lower_right_corner>
<lower_right_corner>-1.82</lower_right_corner>
<lower_right_corner>-3.81</lower_right_corner>
<upper_right_corner>2.275</upper_right_corner>
<upper_right_corner>1.82</upper_right_corner>
<upper_right_corner>-3.81</upper_right_corner>
<upper_left_corner>-2.275</upper_left_corner>
<upper_left_corner>1.82</upper_left_corner>
<upper_left_corner>-3.81</upper_left_corner>
<tracked>false</tracked>
<tracker_proxy />
</surface_viewport>
</surface_viewports>
<keyboard_mouse_device_name>KeyboardMouse Device</keyboard_mouse_device_name>
<!-- use this display for keyboard mouse input
the value is the name of a keyboard_mouse_device chunk
which is the input handler to which the keyboard/mouse
events will be fed -->
<!-- TO MAKE THE WHOLE SCREEN ACTIVE IN A 3PIPE SETUP, WE CAN
SPECIFY THIS ON ALL THREE DISPLAYS -->
<lock_key>KEY_NONE</lock_key>
<!-- when this key is pressed, the mouse pointer is locked
to the center of the window. Useful when the mouse must
remain within the borders of the window at all times -->
<start_locked>false</start_locked>
<!-- start up with the mouse pointer locked -->
<sleep_time>75</sleep_time>
<!-- prevents the display window thread from starving other
threads, it will sleep 75 milliseconds between event
handling passes,
ADJUST FOR PERFORMANCE -->
</display_window>
</elements>
</configuration>
Applications should set their own values for Full-Screen Anti-Aliasing (fsaa) and Anisotropic texture filtering (aniso). The system default is to turn off fsaa and aniso.
from: /etc/profile.d/nvidia-glx.csh
#!/bin/sh # These variables are used to control image quality and performance. # See /usr/share/doc/nvidia-glx-<version>/README.txt for more information. # Setting this to 1 might prevent certain OpenGL apps from crashing. setenv __GL_SINGLE_THREADED 0 # This setting controls full scene antialiasing. # Depending on your chipset, different values give different types of FSAA. setenv __GL_FSAA_MODE 0 # Anisotropic filtering. This setting is also chip dependent, see above. setenv __GL_DEFAULT_LOG_ANISO 0 # Sync buffer swap with monitor refresh. A value > 0 enables. setenv __GL_SYNC_TO_VBLANK 0 # If you have more than one monitor, this setting determines which display # should be synced. setenv __GL_SYNC_DISPLAY_DEVICE
Note that $VRNAV_HOME/ENVIRONS.linux.csh overrides the value for the __GL_SYNC_TO_VBLANK environment variable. The ENVIRONS.linux.csh file also has its own defaults for anti-aliasing and anisotropic texture filtering, if these values are not already set. If the fsaa and aniso variables are set to zero, for example by nvidia-glx.csh, then the commands in ENVIRONS.linux.csh will not take effect. You might want each of your models to have different fsaa and aniso values. You could set the fsaa and aniso environment variables for each model in a startup script.
from: $VRNAV_HOME/ENVIRONS.linux.csh
# ----------------------------- start fsaa/aniso # for antialiasing, see vrjuggler <fsaa_enable> display config file element if( ! $?__GL_FSAA_MODE ) then setenv __GL_FSAA_MODE 5 endif if( ! $?__GL_LOG_MAX_ANISO && ! $?__GL_DEFAULT_LOG_ANISO) then setenv __GL_LOG_MAX_ANISO 2 endif # ----------------------------- end fsaa/aniso
For a list of nVidia GPU-specific values for the __GL environment variables, see "APPENDIX E: OPENGL ENVIRONMENT VARIABLE SETTINGS" in ftp://download.nvidia.com/XFree86/Linux-x86/1.0-7174/README.txt
09Jan2006