A P P E N D I X  A

VirtualGL Reference

This appendix provides information about VirtualGL options and environment variables that are most pertinent to the Sun Shared Visualization 1.1 software. There is also a summary of the VirtualGL GUI. Topics include:


Common vglconnect Scenarios

TABLE A-2 describes different scenarios for invoking vglconnect, the command to run the scenario, and respective comments.


TABLE A-1 Common vglconnect Scenarios

Scenario

Command

Comment

VGL Image Transport with
X11 Forwarding

vglconnect user@graphics-server

  • Starts vglclient (if it isn’t running)
  • Opens ssh session to graphics-server with X tunnel.

X11 Forwarding, ssh-Encrypted VGL Image Transport

vglconnect -s user@graphics-server

ssh tunnel for VGL traffic can be useful through restrictive firewalls, and can create multilevel tunnels. You will probably be prompted twice for your password (on graphics-server).

Direct X11 Connection

vglconnect -x user@graphics-server

client host must allow remote (TCP) X connections.

From a Sun Ray

vglconnect is not used, use ssh -X to contact a remote graphics server.

See Using VirtualGL From a Sun Ray Client. vglclient is not needed when using the Sun Ray Image Transport.

Using VirtualGL with TurboVNC

vglconnect is not used, use ssh or putty.

See Manually Using TurboVNC. vglclient is not normally needed when using VNC.

After vglclient -kill, add the -force option to vglconnect

vglconnect -force user@graphics-server

 

This scenario forces vglconnect to start a vglclient, even if an earlier vglclient did not exit cleanly.

Granting SGE jobs access to the client’s 2D X server

vglconnect -k

This command does not make a connection to the graphics server. The client host must also allow remote (TCP) X connections.


On Solaris, Linux, and Mac OS X hosts, if /opt/VirtualGL/bin is not in your path, you will have to type the full path:


/opt/VirtualGL/bin/vglconnect

On a Windows client, precede vglconnect commands with:


C> cd /d "c:\program files\virtualgl-version-build"


Common vglrun Scenarios

TABLE A-2 describes different scenarios for vglrun, the command to run the scenario, and respective comments. The program in the Command column can be either an application executable or a script; $PATH is searched if a pathname is not specified.


TABLE A-2 Common vglrun Scenarios

Scenario

Command

Comment

Remotely display a graphics application

vglrun

Uses the default image transport.

 

In VGL Image Transport, enable SSL encryption of the images that are sent to vglclient

vglrun +s program

This option has no effect with other image transports. The SSL port (default is 4243 for the client’s first display) must be allowed through the client’s firewall.

VGL Image Transport over Gigabit Networks

vglrun -c rgb program

Disable image compression. This option decreases server CPU consumption but drastically increases network bandwidth consumption.

Turn off frame spoiling

vglrun -sp program

This option is necessary to obtain accurate results from benchmark applications. Frame spoiling should be left on when running interactive applications.

In VGL Image Transport, set the JPEG quality to the value q

vglrun -q q program

Where q is a number between 1 and 100 (default is 95). This option has no effect in any other mode.

In VGL Image Transport, set the JPEG chrominance subsampling to s

vglrun -samp s program

Where s is one of the values from TABLE A-3. 1x is the default for VirtualGL Image Transport. 16x is the default for Sun Ray Image Transport.


A more thorough explanation of vglrun options and the corresponding environment variables is provided in VirtualGL Options and Environment Variables.

Chrominance Subsampling

When an image is compressed using JPEG or using Sun Ray DPCM and YUV compression, each pixel in the image is first converted from RGB (Red/Green/Blue) to YUV. A YUV pixel has three values that specify the overall brightness of the pixel (Y, or luminance) and the overall color of the pixel (U and V, or chrominance.)

Since the human eye is less sensitive to changes in color than to changes in brightness, the chrominance components for some of the pixels can be discarded without much noticeable loss in image quality. This technique, called chrominance subsampling, significantly reduces the size of the compressed image.

TABLE A-3 introduces available chrominance subsampling choices. For example, 8x means to discard the chrominance components for 3 out of every 4 pixels horizontally and half the pixels vertically. (This option is also known as 4:1:0 or 4:2 subsampling.)


TABLE A-3 Chrominance Subsampling Characteristics

-samp Option

Subsampling

Performance

Image Bandwidth

Compression Artifacts

1x

4:4:4
(no subsampling)

Slowest

Most

None

2x

4:2:2 or 2:1 (discard 1/2 in X)

Medium slow

Medium high (about 20-25% less than 1x)

Some

4x

4:2:0 or 2:2 (discard 1/2 in X and Y)

Medium

Medium (about 35-40% less than 1x)

More

8x

4:1:0 or 4:2 (discard 3/4 in X and 1/2 in Y)

Medium fast

Medium low

Even more (available only with Sun Ray DPCM compression)

16x

4:4 (discard 3/4 in X and Y)

Fastest

Low

Still more (available only with Sun Ray DPCM compression)

gray

Discard all chrominance

Fastest

Least

Available only with JPEG compression


Narrow, aliased lines and other sharp features on a black background tend to produce very noticeable artifacts when chrominance subsampling is enabled. The gray option is useful when running applications (such as medical visualization applications) that are already generating grayscale images.

Gamma Correction

Gamma refers to the relationship between the intensity of light that your computer’s monitor is instructed to display, and the intensity that it actually displays. The curve is an exponential curve of the form Y = XG, where X is between 0 and 1. G is called the gamma of the monitor. PC monitors and TVs usually have a gamma of around 2.2.

Some of the mathematics involved in 3D rendering assumes a linear gamma (G = 1.0). Therefore, 3D applications will not display with mathematical correctness unless the pixels are gamma corrected to counterbalance the nonlinear response curve of the monitor. But some systems do not have any form of built-in gamma correction. Thus, the applications developed for such systems have usually been designed to display properly without gamma correction. Gamma correction involves passing pixels through a function of the form X = W1/G, where G is the gamma correction factor and should be equal to the gamma of the monitor. So the final output is Y = XG = (W1/G)G = W. This equation describes a linear relationship between the intensity of the pixels drawn by the application and the intensity of the pixels displayed by the monitor.

You can enable, disable, or fine tune the gamma correction feature in VirtualGL by using the VGL_GAMMA environment variable and the vglrun options -g, +g,
and -gamma. These operations are summarized in TABLE A-4.

Default Gamma Correction Behavior

By default, when VirtualGL remotely displays an OpenGL application, VirtualGL attempts to emulate the gamma correction behavior that would be observed when the same OpenGL application is displayed locally on the application server.

When an OpenGL application is displayed locally on a Solaris SPARC host, the application’s output is gamma corrected by default. Thus, VirtualGL will gamma correct the output of OpenGL applications that are displayed remotely from a Solaris SPARC host, unless you specify otherwise.

If VirtualGL Image Transport is used and the client is a Solaris SPARC system, then VirtualGL will attempt to use a gamma corrected visual to perform gamma correction. (The gamma corrected visual feature is only available with Solaris SPARC graphics drivers.) When a gamma corrected visual is used, you can adjust the gamma correction factor by running fbconfig on the client machine.

Otherwise (when a gamma corrected visual is not available or the client is not a Solaris SPARC system), VirtualGL uses its own internal gamma correction mechanism and the default gamma correction factor is 2.2.

When an OpenGL application is displayed locally on a Solaris x86 or Linux host, the application’s output will not be gamma corrected by default. Thus, VirtualGL will not gamma correct the output of OpenGL applications that are displayed remotely from a Solaris x86 or Linux host, unless you specify otherwise.

Most non-SPARC clients provide a mechanism that allows you to gamma correct the entire screen, either through the graphics driver or the OS itself. However, these systems do not provide a means of gamma correcting an individual application (a capability of gamma corrected visuals).


VirtualGL Options and Environment Variables

vglrun is located:

The syntax of vglrun is:

vglrun [vglrun-options] [--] OpenGL-application [OpenGL-app-arguments]

That is, any options for vglrun appear between vglrun and the name of the OpenGL application to start. If necessary, you can enter two hyphens to manually signify the end of vglrun options. Any options to the OpenGL application appear at the end of the line.

A more sophisticated example of the vglrun starting (which assumes vglrun is in your $PATH) is:


my_server% vglrun -g -d /dev/fbs/kfb0 my-program my-program-option my-program-argument

The most important vglrun option is controlled with -d (or with the VGL_DISPLAY environment variable). The value for the -d option is either an X display, or (on a Solaris SPARC host) the string glp or a GLP device name, such as /dev/fbs/kfb0, as seen in the example. When an X display is used, the display should be on the graphics server with 3D graphics acceleration. (An optional .screen indicates the screen or device for the X server.) For example:


my_server% vglrun -g -d :0.1 my-program my-program-option my-program-argument

If your graphics server has only one graphics device, start a 3D X server on the device and enable that X server to you (or to everyone on the graphics server), as described in the "Configuration and Information" section of the Sun Shared Visualization 1.1 Software Server Administration Guide. After that, the default X display (:0) is fine. Ask your system administrator if you need to provide the display or device to vglrun.

Sun Grid Engine can set VGL_DISPLAY for you, when running a job that requests graphics resources. On a graphics server with only one graphics accelerator, VGL_DISPLAY can be set to the empty string ““. The string is sufficient to cause VirtualGL to use the default X display (:0.0).

TABLE A-4, TABLE A-5, and TABLE A-6 list the VGL_ environment variables and equivalent vglrun options associated with general operation, Sun Ray Image Transport, and VGL Image Transport, respectively.


TABLE A-4 General VGL_ Environment Variables and vglrun Options

Environment

Variable

Name and Values

vglrun

Command-Line

Override

vglrun

Option Description

Default

Value

VGL_CLIENT =
client
:display

-client client:display

The host name, IP address, or X display where VirtualGL should send the VGL Image stream.

 

VGL Image Transport uses a dedicated TCP/IP connection to transmit compressed images of an application’s OpenGL rendering area from the application server to the client display. Thus, the server needs to know on which machine the VirtualGL client software is running, and which X display on that machine is used to draw the application’s windows and other 2D GUI elements. The server’s SSH_CLIENT or DISPLAY environment variable normally supplies this information to VirtualGL

 

But if necessary, set VGL_CLIENT to the display where the application’s GUI ends up. When using the VGL Image Transport, the display is the host name or IP address of the machine on which vglclient is running. When using the Sun Ray Image Transport, this display is the host name or IP address of the Sun Ray server. For example (using ksh/bash syntax):

export VGL_CLIENT=my_client_machine:0.0

Set automatically by use of vlgconnect or ssh (as instructed in Chapter 3), or read from the DISPLAY environment variable (otherwise).

VGL_COMPRESS=proxy

VGL_COMPRESS=jpeg

VGL_COMPRESS=rgb

VGL_COMPRESS=sr

VGL_COMPRESS=srrgb

VGL_COMPRESS=sryuv

-c [proxy | jpeg | rgb | sr | srrgb]

Selects image transport and image compression type. Each value selects a specific image transport:

  • proxy selects X11 Image Transport.
  • jpeg or rgb selects VGL Image Transport.
  • sr, srrgb, or sryuv selects Sun Ray Image Transport.

 

proxy = Sends images uncompressed using the X11 Image Transport. This option is useful when displaying to a local X server or X proxy such as TurboVNC.

 

jpeg = Compresses images using JPEG and sends using the VGL Image Transport. This option is used with vglclient when displaying to a remote X server.

 

rgb = Encodes images as uncompressed RGB and sends using the VGL Image Transport. This option is useful when displaying to a remote X server or X proxy across a very fast network.

 

sr* modes below all require that the proprietary Sun Ray plug-in be installed on the VirtualGL server, that the client is a Sun Ray ultrathin client, and that the Sun Ray Image Transport was active when VirtualGL started. The VGL default is to use sr compression in this case. VGL will fall back to using proxy compression if, for any given frame, it is unable to send the frame using the Sun Ray Image Transport. This situation could occur if, for example, the Sun Ray client is on a network that is not visible to the VirtualGL server.

 

sr = Compresses images using the Sun Ray default compression method (DPCM) and sends using the Sun Ray Image Transport.

 

srrgb = Encodes images as uncompressed RGB and sends using the Sun Ray Image Transport.

 

sryuv = Encodes images as uncompressed YUV and sends using the Sun Ray Image Transport.

If the X server is a Sun Ray server and the Sun Ray plug-in is installed on the VirtualGL server, use sr (if possible) and proxy (otherwise).

 

If the X server is not a Sun Ray server, use proxy if DISPLAY begins with : or with unix: (otherwise, use jpeg).

VGL_DISPLAY

-d display-or- GLP-device

The X display or GLP device to use for 3D rendering.

 

You may set VGL_DISPLAY to the name of any graphics-accelerated X display (such as :0.1). This functionality could be used, for instance, to support many application instances on a multipipe graphics server.

 

GLP mode (Solaris SPARC only) -

Setting this option to GLP or glp enables GLP mode and selects the first available GLP device for rendering. You can also set this option to the pathname of a specific GLP device (for example, /dev/fbs/jfb0 or /dev/fbs/kfb0). GLP is a special feature of the Sun SPARC OpenGL library that enables an application to render into Pbuffers on a jfb or kfb graphics card, even if there is no 3D X server running on that graphics card.

 

Sun Grid Engine can set VGL_DISPLAY for you, when running a job that requests graphics resources. On a host with only one graphics device, Sun Grid Engine might set VGL_DISPLAY to the null string (““). Consequently, the default X server (:0.0) is used.

:0

VGL_FPS=f

 

-fps f

 

Limits the client-server frame rate to f frames per second, where f is a floating point number > 0.0. This option can be used, for instance, as a crude way to control network bandwidth or CPU usage in multiuser environments where those resources are constrained.

 

This option prevents the VGL and X11 Image Transports from sending frames at a rate faster than the specified limit. If frame spoiling is disabled, then this option effectively limits the server’s graphics rendering frame rate as well.

No limit

VGL_GAMMA=1

 

+g

 

Enables gamma correction with default settings.

 

This option enables gamma correction using the best available method. The client’s gamma-corrected X visual is used, if available. Otherwise, VirtualGL performs gamma correction internally using a default gamma correction factor of 2.22. This option emulates the default behavior of OpenGL applications running locally on SPARC systems.

This is the default on Solaris SPARC application servers (gamma correction enabled,
factor=2.2)

VGL_GAMMA=0

 

-g

 

Disables gamma correction.

 

This option tells VGL not to use gamma-corrected visuals, even if they are available on the 2D X server, and disables VGL’s internal gamma correction system as well. This option emulates the default behavior of OpenGL applications running locally on Linux or Solaris x86 machines.

This is the default on Solaris x86 and Linux application servers (gamma correction disabled,
factor=1.0)

VGL_GAMMA=factor

-gamma factor

Enables VGL’s internal gamma-correction system with the gamma-correction factor specified.

 

If VGL_GAMMA is set to an arbitrary floating-point value (a decimal point should always be used), then VirtualGL performs gamma correction internally using the specified value as the gamma-correction factor. You can also specify a negative value to apply a de-gamma function. Specifying a gamma correction factor of G (where G < 0) is equivalent to specifying a gamma correction factor of -1/G.

2.2 for VGL_GAMMA=1

 

1.0 for VGL_GAMMA=0

VGL_GUI

 

Specifies key sequence to pop-up VirtualGL’s dynamic control GUI. See VirtualGL GUI for Quality and Performance Tradeoff.

Shift-Ctrl-F9

VGL_INTERFRAME=0

VGL_INTERFRAME=1

 

Disables and enables interframe comparison.

Interframe comparison only sends tiles of the image that have changes since the previous frame. This option has no effect in X11 Image Transport.

Comparison enabled.

VGL_LOG

 

Redirects the console output from VirtualGL to a log file.

 

Setting this environment to the pathname of a log file on the VirtualGL server causes the VirtualGL faker to redirect all of its messages to the specified log file rather than to stderr. Output content includes any profiling and trace output.

Print all messages to stderr.

VGL_PROFILE=0

VGL_PROFILE=1

-profile

+profile

Disables and enables profiling output.

 

If enabled, this option causes the VirtualGL faker to continuously benchmark itself and periodically print out the throughput of reading back, compressing, and sending pixels to the client. See also VGL_SPOIL.

Profiling disabled.

VGL_NPROCS=n

-np n

 

Selects the number of CPUs to use for multithreaded compression.

 

The VGL Image Transport can divide the task of compressing each frame among multiple server CPUs. This behavior might speed up the overall throughput in rare circumstances where the server CPUs are significantly slower than the client CPUs.

 

VirtualGL will not allow more than four processors total to be used for compression. Nor will VirtualGL allow you to set this parameter to a value greater than the number of processors in the system.

1

VGL_SPOIL=0

VGL_SPOIL=1

-spoil

+spoil

Disables and enables frame spoiling.

 

By default, VirtualGL drops frames so the newest rendered frame, perhaps based on the most recent mouse movement, is presented to the user as soon as possible. This functionality should produce the best results with interactive applications.

 

However, turn off frame spoiling when running benchmarks or other noninteractive applications. Turning off frame spoiling forces one frame to be read back and sent on each buffer swap, thus enabling benchmarks to accurately measure the frame rate of the entire VirtualGL pipeline. Note that in X proxy environments (for example, TurboVNC), the application’s frame rate might still not reflect the frame rate presented to the user. Disabling frame spoiling also prevents noninteractive applications from wasting graphics resources by rendering frames that are never seen. With frame spoiling turned off, the rendering pipeline behaves as if the pipeline’s fill-rate is limited to about 30 or 40 Megapixels/ second, the maximum throughput of the VirtualGL system on current CPUs.

Spoiling enabled.

VGL_STEREO=left

VGL_STEREO=right

VGL_STEREO=quad

VGL_STEREO=rc

-st [left | right | quad | rc]

Specifies the delivery method for stereo images (when an application renders a stereo frame).

 

left - Sends only the left eye buffer.

right - Sends only the right eye buffer.

quad - Attempts to use quad-buffered stereo, which will result in a pair of images being sent to the VirtualGL client on every frame. Quad-buffered stereo requires the VGL Image Transport, and it also requires that client support OpenGL and have a 3D accelerator that supports stereo rendering. If quad-buffered stereo is not available, either because the client or the Image Transport does not support it, then falls back to using anaglyphic stereo.

rc - Uses Red/Cyan (anaglyphic) stereo, even if quad-buffered stereo is available.

quad - use quad-buffered stereo if available, use anaglyphic stereo otherwise.

VGL_SUBSAMP=1x

VGL_SUBSAMP=2x

VGL_SUBSAMP=4x

VGL_SUBSAMP=8x

VGL_SUBSAMP=16x

VGL_SUBSAMP=gray

 

-samp [1x|
2x|4x|8x|16x|grey]

Subsamples chrominance (color) to improve performance at the expense of quality. Since the human eye is less sensitive to changes in color than it is to changes in brightness, the chrominance components for some of the pixels can be discarded without much noticeable loss in image quality.

 

1x - Full YUV color resolution (4:4:4).

2x - full resolution in Y, subsamples U and V by 2 in X (4:2:2).

4x - Subsamples U and V by 2 in X and Y (4:2:0).

8x - Subsamples U and V by 4 in X, 2 in Y (4:1:0).

16x - Subsamples U and V by 4 in X and Y (4:4).

gray - Discards all chrominance (color) components.

 

Applies to DPCM and YUV enccoding (Sun Ray Transport) and JPEG encoding (VGL image tranpsort). See Chrominance Subsampling Characteristics.

1x (full color resolution).

VGL_TRACE=0

VGL_TRACE=1

-tr
+tr

Disables or enables tracing.

 

When tracing is enabled, VirtualGL logs all calls to the GLX and X11 functions it is intercepting. VirtualGL also logs the arguments, return values, and execution times for those functions. This behavior is useful when diagnosing interaction problems between VirtualGL and a particular OpenGL application.

Disabled.

VGL_VERBOSE=0

VGL_VERBOSE=1

-v
+v

Disables or enables verbose VirtualGL messages.

 

When verbose mode is enabled, VirtualGL reveals some of its decisions, such as which code path it is using to compress images, which type of X11 drawing it is using, and so on. This behavior can be helpful when diagnosing performance problems.

Disabled.



TABLE A-5 VGL_ Environment Variables and vglrun Options for Sun Ray Image Transport

Environment

Variable

Name

vglrun

Command-Line

Override

vglrun

Option Description

Default

Value

VGL_ZOOM_X=2

 

Downsamples YUV an extra factor of 2 in X.

Disabled.

VGL_ZOOM_Y=2

 

Downsamples YUV an extra factor of 2 in Y.

Disabled.

VGL_PROGRESSIVE=0

VGL_PROGRESSIVE=1

-prog

+prog

This option is no longer recommended or supported. Disables and enables sending of a Lossless version of the image if a newer image is not provided. The transmission is interrupted if a new image arrives.

Disabled.



TABLE A-6 VGL_ Environment Variables and vglrun Options for VGL Image Transport

Environment

Variable

Name and Values

vglrun

Command-Line

Override

vglrun

Option Description

Default

Value

VGL_QUAL=[1-100]

-q [1-100]

An integer between 1 and 100 (inclusive).

 

This setting enables you to specify the quality of the JPEG compression. Lower is faster but also grainier. The default setting should produce visually lossless performance. 100 is is mathematically lossless except for round-off errors.

95

VGL_SSL=0

VGL_SSL=1

-s
+s

Disables or enables SSL encryption (of VGL images).

 

Enabling this option causes the VGL Image Transport to be tunneled through the secure socket layer (SSL).

Disabled.


Passing a configuration option as an argument to vglrun effectively overrides the environment variable setting corresponding to that configuration option.

For more information about vglrun options, start vglrun -help or consult the VirtualGL User’s Guide. See Related Documentation.

VirtualGL GUI for Quality and Performance Tradeoff

VirtualGL has a small graphical user interface (GUI) to enable you to dynamically control the VirtualGL compression and encoding. See FIGURE A-1. This functionality enables you to reconfigure visual quality and performance on-the-fly.

FIGURE A-1 VirtualGL’s Configuration Dialog (Showing LAN Defaults)


 


procedure icon  To Start the VirtualGL GUI

single-step bullet  Press the Control-Shift-F9 keys.

That is, hold the Control and Shift keys, and press the F9 function key. You can use the VGL_GUI environment variable to change the key combination if, for example, an application is already using that key sequence.

For example:


my_server% setenv VGL_GUI CTRL-F9

The command changes the key sequence to the Control-F9 keys for graphics programs started with vglrun from that shell.

Using the VirtualGL GUI

You can use this dialog to adjust various image compression and display parameters in VirtualGL. Changes are reflected immediately in the application. TABLE A-7 describes each of the setting fields for the GUI. Many of these descriptions refer to static settings described in tables in VirtualGL Options and Environment Variables. The GUI overrides those static settings from an environment variable or option to vglrun.


TABLE A-7 VirtualGL GUI Field Descriptions

Field

Description

Image Compression (Transport)

Selects the image compression and transport technique. Inappropriate choices are grayed out (for example, Sun Ray transport choices are unavailable on other clients).

None (X11 Transport) - Equivalent to VGL_COMPRESS=proxy. This option can be activated at any time, regardless of which transport was active when VirtualGL started.

 

JPEG (VGL Transport) - Equivalent to VGL_COMPRESS=jpeg. This option is only available if the VGL Image Transport was active when the application started.

 

RGB (VGL Transport) - Equivalent to VGL_COMPRESS=rgb. This option is only available if the VGL Image Transport was active when the application started.

 

DPCM (Sun Ray Transport) - Equivalent to VGL_COMPRESS=sr. This option is only available if the Sun Ray Image Transport was active when the application started.

 

RGB (Sun Ray Transport) - Equivalent to setting VGL_COMPRESS=srrgb. This option is only available if the Sun Ray Image Transport was active when the application started.

 

YUV (Sun Ray Transport) - Equivalent to setting VGL_COMPRESS=sryuv. This option is only available if the Sun Ray Image Transport was active when the application started.

Chrominance Subsampling

Selects the color compression (quality and performance tradeoff) when using JPEG or Sun Ray DPCM compression. This option overrides VGL_SUBSAMP, described in General VGL_ Environment Variables and vglrun Options and in Chrominance Subsampling Characteristics.

JPEG Quality

This slider enables you to set a percentage quality when using JPEG compression. A higher percentage means better quality, at the expense of reduced bandwidth. Changing this setting overrides VGL_QUAL.

Connection Profile

This drop-down menu is active only if the VGL Image Transport was active when the application started. All choices set the image compression type to JPEG (VGL Transport). It has the following options in release 1.1.1:

  • Low Qual (Low-Bandwidth Network) - Also sets the Chrominance Subsampling to 4X, and sets the JPEG Image Quality to 30.
  • Medium Qual - Also sets the Chrominance Subsampling to 2X, and sets the JPEG Image Quality to 80.
  • High Qual (High-Bandwidth Network) - Also sets the Chrominance Subsampling to 1X, and sets the JPEG Image Quality to 95. These settings are VirtualGL’s current defaults.

Gamma Correction Factor

This floating-point field is the equivalent of setting VGL_GAMMA. If using a gamma-corrected visual (SPARC clients only), then this field has no effect. Otherwise, this field enables VirtualGL’s internal gamma-correction system with the specified gamma-correction factor.

Frame Spoiling

Toggles between frame spoiling on (enabled) or off (disabled). Changing this setting overrides the value of VGL_SPOIL.

Interframe Comparison

Toggles interframe comparison on and off. Changing this setting overrides the value of VGL_INTERFRAME.

Stereographic Rendering Method

Drop-down menu overrides the value of VGL_STEREO.

Limit Frames/second

This floating-point field overrides VGL_FPS.




Note - VirtualGL monitors the application’s X event loop to determine whenever a particular key sequence has been pressed. If an application is not monitoring key press events in its X event loop, then the VirtualGL configuration dialog might not pop up at all.


vglclient options

The following table lists options honored by vglclient when using the VGL Image Transport. Note that vglclient is normally started implicitly by vglconnect.


TABLE A-8 vglclient Options for VGL Image Transport

Environment

Variable

Name and Values

vglclient

Command-Line

Override

vglclient

Option Description

Default

Value

VGLCLIENT_DRAWMODE=ogl | x11

-gl
-x

Specifies the method used to draw pixels into the application window. Options use OpenGL or X11.

ogl for Solaris SPARC systems with 3D accelerators, x11 otherwise

VGLCLIENT_LISTEN= sslonly | nossl

-sslonly
-nossl

Accepts only SSL connections or only unencrypted connections from the VirtualGL server.

Accept both

VGL_PROFILE=0

VGL_PROFILE=1

 

Disables or enables profiling output.

 

If profiling output is enabled, then VirtualGL will continuously benchmark itself and periodically print out the throughput of various stages in its image pipelines. See also VGL_SPOIL.

Disabled

VGL_VERBOSE=0

VGL_VERBOSE=1

 

Disables or enables verbose VirtualGL messages.

 

When verbose mode is enabled, VirtualGL reveals some of its decisions, such as which code path it is using to decompress images, which type of X11 drawing it is using, and so on. This behavior can be helpful when diagnosing performance problems.

Disabled



Advanced OpenGL Features

This section discusses VirtualGL features that support these advanced OpenGL Features:

Stereographic Rendering

Stereographic rendering is a feature of OpenGL that creates separate rendering buffers for the left and right eyes and allows the application to render a different image into each buffer. How the stereo images are subsequently displayed depends on the specifics of the 3D hardware and the user’s environment.

VirtualGL can support stereographic applications in two ways:


Stereographic Mode

Description

Requires

Quad-Buffered Stereo

Sends the stereo image pairs to the client to be displayed in stereo by the client’s 3D graphics card

Stereo-capable 3D graphics hardware on server and client.

Anaglyphic Stereo

Combines each stereo image pair into a single anaglyph that can be viewed with widely-available red/cyan 3D glasses

Stereo-capable 3D graphics hardware on server (3D graphics hardware is not needed on the client)


You can select a specific stereo mode by setting the VGL_STEREO environment variable, by using the -st argument with vglrun (see General VGL_ Environment Variables and vglrun Options), or by using the VirtualGL GUI (see VirtualGL GUI for Quality and Performance Tradeoff).

Quad-Buffered Stereo

The name quad-buffered stereo is derived from OpenGL using four buffers (left front, right front, left back, and right back) that support stereographic rendering with double buffering. 3D graphics cards with quad-buffered stereo capabilities typically provide a synchronization signal that can control active stereo 3D glasses of various types. Some 3D graphics cards support passive stereo, which displays the buffers for the left and right eyes to different monitor outputs. The outputs might be projected onto the same screen through polarized filters.

VirtualGL supports true quad-buffered stereo by rendering stereo images on the server and sending image pairs across the network. The image pairs are displayed by a 3D graphics card on the client.

Quad-Buffered Stereo Requirements

In most cases, the VirtualGL and TurboVNC clients use only 2D drawing commands, so the client host does not required a 3D graphics card. But displaying quad-buffered stereo images requires that the client host have a 3D graphics card. Since the 3D graphics card is only being used to display images, it does not need to be a high-end card of that type. In most cases, the least expensive 3D graphics card that has stereo capabilities will work fine in a VirtualGL client.

Also, the server must have a 3D graphics card that supports stereo, since this is the only way that a stereo Pbuffer is provided to VirtualGL.

When an application tries to render something in stereo, VirtualGL will use quad-buffered stereo rendering if all of the following characteristics are true:

If any of these conditions is not true, then VirtualGL falls back to using anaglyphic stereo (as described in Anaglyphic Stereo). You usually need to explicitly enable stereo in the graphics driver configuration for both the client and server machines. Verifying Advanced Feature Support describes how to verify that stereo visuals are available on both the client and server.

In quad-buffered mode, VirtualGL reads back both eye buffers on the server, then sends the contents as a pair of compressed images (one for each eye) to the VirtualGL client. The VirtualGL client then decompresses both images and draws them as a single stereo frame to the client machine’s X display using glDrawPixels(). Because of this process, enabling quad-buffered stereo in VirtualGL typically decreases performance by 50 percent or more, and twice the network bandwidth is used to maintain the same frame rate.

Anaglyphic Stereo

Anaglyphic stereo is the type of stereographic display used for old 3D movies. This method usually relies on a set of 3D glasses consisting of red transparency film over the left eye and cyan transparency film over the right eye. To generate a 3D anaglyph, the red color data from the left eye buffer is combined with the green and blue color data from the right eye buffer, enabling a single monographic image to contain stereo data. Within the capabilities of VirtualGL, an anaglyphic image is the same as a monographic image. Therefore, anaglyphic stereo images can be sent by any image transport to any type of client, regardless of the client’s capabilities.

VirtualGL falls back to using anaglyphic stereo when VirtualGL detects that an application has rendered something in stereo but quad-buffered stereo is not available. Quad-buffered stereo might be unavailable because the client doesn’t support it or because the image transport being used is not GL Image Transport. Anaglyphic stereo provides an inexpensive and simple way to view stereographic applications in X proxies (including TurboVNC) and on clients that do not support quad-buffered stereo. Additionally, anaglyphic stereo performs much faster than quad-buffered stereo, since quad-buffered stereo sends twice as much data to the client.

Transparent Overlays

Transparent overlays render an overlay image on top of an underlay rendered image. You can easily erase or redraw the overlay image without requiring the underlay to be redrawn. Transparent overlays have requirements and restrictions similar to those for quad-buffered stereo. For an application to use this feature, transparent overlay features must be provided by the client host’s 3D graphics card and OpenGL.

When an application performs OpenGL rendering to the transparent overlay, VirtualGL completely bypasses its own GLX faker. Instead, VirtualGL uses indirect OpenGL rendering to render to the transparent overlay on the client’s graphics card. The underlay is still, as always, rendered on the server host.

Use of overlays is becoming more and more infrequent. When they are used, it is typically only for drawing small, simple, static shapes and text. Usually it is faster to send the overlay geometry over to the client rather than to render it as an image and send the image.

As with stereo functions, sometimes overlays must be explicitly enabled in the client graphics card’s configuration. Unlike stereo requirements, overlays need to be supported and enabled only on the client machine.

Indexed color (8-bit) overlays have been tested and are known to work with VirtualGL. Use glxinfo (see Troubleshooting below) To verify whether your client’s X display supports overlays and if overlays are enabled, use glxinfo as described in To Verify Client Features. In Exceed 3D, make sure that the Overlay Support option is checked in the Exceed 3D and GLX applet.

Overlays do not work with X proxies, including TurboVNC. VirtualGL must be displaying to a real X server to use overlays.


Troubleshooting Common Errors

This section describes common user errors and how to avoid, detect, or recover from the errors.

vglconnect and ssh Issues

VirtualGL Issues

This message is probably caused by using a program such as ssh to log into the graphics server, rather than using vglconnect, which starts vglclient implicitly. Another possible cause is that the vglclient process exited. In that situation, a new vglclient needs to be started using the vglconnect -force option. Check the VirtualGL client log file for possible errors.

In this case, null indicates that the VirtualGL display or device specification was "" (a null string, which is the VirtualGL default, meaning the graphics server’s :0.0 display). The name of the display or device name that VirtualGL failed to open or access is printed.

This message might be caused by one of the following configuration or usage errors:

The same error can occur if the client’s “2D X server” does not offer a 24-bit true color (RGB) visual. Some Linux systems are configured for only 16-bit visuals. In this case, the system must be reconfigured for 24-bit true color visuals.

Another possible reason that the application can’t open a usable visual is that the graphics server’s 3D graphics card does not support OpenGL pixel buffers (Pbuffers). The graphics server might not have the proper driver installed for that 3D graphics card. On Linux, you probably need to use the driver supplied by the 3D graphics card vendor instead of the driver that was included with the operating system. For example, use the nvidia driver supplied by the 3D graphics card vendor rather than an nv driver from another source.

To configure X11 forwarding, see the Sun Shared Visualization 1.1 Server Administration Guide.

vglrun Issues With Set-UID Programs and Scripts

When a Solaris or Linux application (binary executable or script) must set the user or group ID when it runs (enabled with a UNIX file system’s setuid and setgid permission bits), that application might generate errors when it runs under VirtualGL. The error message depends on the operating system.

This error occurs because the VirtualGL faker library is preloaded into every executable that the script launches. When invoking an executable that is setuid or setgid, the operating system refuses to load virtualGL into those executables, because you are attempting to preload a library (VirtualGL) that the operating system does not consider secure into a process that needs to be secure.

Alternatives to Work With This Restriction

A system administrator can configure the operating system to consider the VirtualGL library to be secure, as is described in the Configuration chapter of the Sun Shared Visualization 1.1 Software Server Administration Guide.

If the application is a script, a more secure method is to edit the application script and have it run vglrun only for the executables that you want to run in the VirtualGL environment. Here are various ways to do this:

Here is an example of using these options. The script calls a binary needing setuid that is a 32-bit execuatable. However, the graphics application is a 64-bit executable. In this situation, you can use vglrun -64 to launch the application script. The result is that the 32-bit setuid binary will not attempt to preload VirtualGL’s faker library.

Rather than running this with vglrun my_script, you can create a similar script (called my_vgl_script) as follows:


#!/bin/sh
some_setuid_binary
/opt/VirtualGL/bin/vglrun some_application_binary

Invoke my_vgl_script directly (that is, do not enter vglrun my_vgl_script). The result is that this script does not attempt to preload VirtualGL into some_setuid_binary, but will preload VirtualGL into some_application_binary, as you wanted. Unfortunately, this method does allow the user invoking my_vgl_script to provide vglrun options on the command line. But the next technique does.

vglclient Messages (Normally in the Log for vglconnect)

vglclient prints messages as graphics server applications connect and disconnect. vglconnect normally redirects vglclient‘s output to a log file whose name is printed by vglconnect

After a connection, the vglconnect log file normally contains connection and disconnection messages from vglclient, such as:


++ Connection from 10.4.22.34.
Error receiving data from server.  Server may have disconnected.
   (this is normal if the application exited.)
rrsocket.cpp-- 394: Incomplete receive
-- Disconnecting 10.4.22.34

Depending on how the application exits, messages might be printed before the Disconnecting message, as the Incomplete receive message shown here. If the application was supposed to exit, these messages are of no concern. But these messages can be used to help analyze unexpected behavior.


vis_report Reporting Script

Sun Shared Visualization 1.1 software includes a reporting script, /opt/SUNWvrpt/bin/vis_report, that is helpful in debugging product installation, configuration, and usage problems.

Support engineers can use the script output to troubleshoot problematic behavior. Use of the script is dependent upon the situation when the problem occurs:

Attach the output of the script to an email of your problem. Describe what you were trying to do, what you expected to happen, and what actually occurred. Send the email to your service provider or to Shared-Viz-Support@Sun.com.


Verifying Advanced Feature Support

VirtualGL includes a modified version of glxinfo that can be used to determine whether or not the client and server have stereo, overlay, or Pseudocolor visuals enabled.


procedure icon  To Verify Quad-Buffered Stererographics on the Server

single-step bullet  Run one of the following command sequences on the VirtualGL server to determine whether the server has a suitable visual for stereographic rendering.

In the output, one or more of the visuals should list stereo=1 and should list Pbuffer as one of the Drawable Types.


procedure icon  To Verify Client Features

single-step bullet  Run the following command sequence on the VirtualGL server:


% /opt/VirtualGL/bin/glxinfo -v

Examine the output to determine whether the X display on the client has a suitable visual to support stereographic rendering, transparent overlays, or Pseudocolor


GLX Spheres Test Program

The GLX Spheres test program (glxspheres) is found in /opt/VirtualGL/bin. You can use this program to verify that VirtualGL has been configured and invoked properly.

This program supports the options shown in TABLE A-9.


TABLE A-9 glxspheres Options

Option

Description

-h

Help - Prints a summary of options and exit.

-c

Uses color index rendering. The default is true color (RGB).

-fs

Full Screen. Size the window to consume the entire X screen, without any window manager ornamentation. (Press q or Escape keys to exit the program.)

-i

Interactive mode. Frames advance only when the mouse is clicked or dragged. Continuously dragging the mouse in the window should produce a steady frame rate. This frame rate is a reasonable model of the frame rate that you can achieve when running interactive applications in VirtualGL.

-m

Uses immediate mode rendering. (The default is display list rendering for maximum performance. Many applications cannot use display lists, because the geometry they are rendering is dynamic. So this option models how such applications might perform when displayed remotely without VirtualGL.)

-o

Overlays. Renders text, a moving crosshair cursor, and a block of pixels to an 8-bit transparent overlay while animating the spheres in the underlay. Also changes the overlay’s color map periodically.

-s

Uses stereographic rendering initially. (Later, stereo can be switched on and off in the application using VirtualGL’s Configuration dialog. See VirtualGL GUI for Quality and Performance Tradeoff.)