http://www.virtualgl.org/vgldoc/2_1_1/

Intended audience: System Administrators, Graphics Programmers, Researchers, and others with knowledge of the Linux or Solaris operating systems, OpenGL and GLX, and X windows.

1 Legal Information

This document and all associated illustrations are licensed under the . Any works which contain material derived from this document must cite The VirtualGL Project as the source of the material and list the current URL for the VirtualGL web site.

This product includes software developed by the  for use in the OpenSSL Toolkit. Further information is contained in LICENSE-OpenSSL.txt, which can be found in the same directory as this documentation.

The VirtualGL server components include software developed by the  and distributed under the terms of the 

The VirtualGL Windows packages include PuTTY, which is released under this license.

VirtualGL includes portions of X.org, which is released under this license.

2 Overview

VirtualGL is an open source package which gives any Unix or Linux remote display software the ability to run OpenGL applications with full 3D hardware acceleration. Some remote display software, such as VNC, lacks the ability to run OpenGL applications at all. Other remote display software forces OpenGL applications to use a slow software-only OpenGL renderer, to the detriment of performance as well as compatibility. The traditional method of displaying OpenGL applications to a remote X server (indirect rendering) supports 3D hardware acceleration, but this approach causes all of the OpenGL commands and 3D data to be sent over the network to be rendered on the client machine. This is not a tenable proposition unless the data is relatively small and static, unless the network is very fast, and unless the OpenGL application is specifically tuned for a remote X-Windows environment.

With VirtualGL, the OpenGL commands and 3D data are instead redirected to a 3D graphics accelerator on the application server, and only the rendered 3D images are sent to the client machine. VirtualGL thus “virtualizes” 3D graphics hardware, allowing it to be co-located in the “cold room” with compute and storage resources. VirtualGL also allows 3D graphics hardware to be shared among multiple users, and it provides “workstation-like” levels of performance on even the most modest of networks. This makes it possible for large, noisy, hot 3D workstations to be replaced with laptops or even thinner clients. More importantly, however, VirtualGL eliminates the workstation and the network as barriers to data size. Users can now visualize gigabytes and gigabytes of data in real time without needing to copy any of the data over the network or sit in front of the machine that is rendering the data.

Normally, a Unix OpenGL application would send all of its drawing commands and data, both 2D and 3D, to an X-Windows server, which may be located across the network from the application server. VirtualGL, however, employs a technique called “split rendering” to force the 3D commands from the application to go to a 3D graphics card in the application server. VGL accomplishes this by pre-loading a dynamic shared object (DSO) into the application at run time. This DSO intercepts a handful of GLX, OpenGL, and X11 commands necessary to perform split rendering. Whenever a window is created by the application, VirtualGL creates a corresponding 3D pixel buffer (“Pbuffer”) on a 3D graphics card in the application server. Whenever the application requests that an OpenGL rendering context be created for the window, VirtualGL intercepts the request and creates the context on the corresponding Pbuffer instead. Whenever the application swaps or flushes the drawing buffer to indicate that it has finished rendering a frame, VirtualGL reads back the Pbuffer and sends the rendered 3D image to the client.

The beauty of this approach is its non-intrusiveness. VirtualGL monitors a few X11 commands and events to determine when windows have been resized, etc., but it does not interfere in any way with the delivery of 2D X11 commands to the X server. For the most part, VGL does not interfere with the delivery of OpenGL commands to the graphics card, either (there are some exceptions, such as its handling of color index rendering.) VGL merely forces the OpenGL commands to be delivered to a server-side graphics card rather than a client-side graphics card. Once the OpenGL rendering context has been established in a server-side Pbuffer, everything (including esoteric OpenGL extensions, fragment/vertex programs, etc.) should “just work.” In most cases, if an application runs locally on a 3D server/workstation, that same application will run remotely from that same machine using VirtualGL. However, if it were really as simple as that, we could all turn out the lights and go home. Most of the time spent developing VirtualGL has been spent working around “stupid application tricks.”

VirtualGL can currently use one of three “image transports” to send rendered 3D images to the client machine:

1. VGL Image Transport (Formerly “Direct Mode”)

The VGL Image Transport is most often used whenever the 2D X server (the X server used to draw the application’s GUI and transmit keyboard and mouse events back to the application server) is located across the network from the application server, for instance if the 2D X server is running on the user’s desktop machine. VirtualGL uses its own protocol on a dedicated TCP socket to send the rendered 3D images to the client machine, and the VirtualGL Client application decodes the images and composites them into the appropriate X window. The VGL Transport can either deliver uncompressed images (RGB encoded), or it can compress images in real time using a high-speed JPEG codec. It also supports the delivery of stereo image pairs, which can be reconstructed into a stereo image by the VirtualGL Client.

Figure 2.1: The VGL Image Transport with a Remote 2D X Server

2. X11 Image Transport (Formerly “Raw Mode”)

The X11 Image Transport simply draws the rendered 3D images into the appropriate X window using XPutImage() and similar X-Windows commands. This is most useful in conjunction with an “X Proxy”, which can be one of any number of Unix remote display applications, such as VNC. These X proxies are essentially “virtual” X servers. They appear to the application as a normal X server, but they perform X11 rendering to a virtual framebuffer in main memory rather than to a real framebuffer on a graphics card. This allows the X proxy to send only images to the client machine rather than chatty X-Windows rendering commands. When using the X11 Transport, VirtualGL does not perform any image compression or encoding itself. It instead relies upon an X proxy to encode and deliver the images to the client(s). Since the use of an X proxy eliminates the need to send X-Windows commands over the network, this is the best means of using VirtualGL over high-latency or low-bandwidth networks. The VirtualGL Project provides an accelerated version of VNC, called “TurboVNC”, which is meant to be used with VirtualGL’s X11 Transport. The combination of the two provides a highly-performant remote 3D solution, even on slow networks. TurboVNC also provides rudimentary collaboration capabilities, allowing multiple users to simultaneously interact with the same 3D application.

Figure 2.2: The X11 Image Transport with an X Proxy

3. Sun Ray Image Transport

The Sun Ray thin client environment from Sun Microsystems consists of an X proxy (the Sun Ray Server Software) and a series of ultra-thin hardware clients that connect to this proxy over a network. It is similar in concept to VNC, in that a virtual X server is created for every user and that only images, not rendering commands, are sent to the client. Unlike VNC, however, the client is not a piece of software running on a workstation or laptop. The client is a fanless, diskless little box with only a monitor port, USB ports, a network jack, and a smart card slot (used for authentication.)

This environment presents unique challenges to VirtualGL The first challenge is that the Sun Ray 1 and Sun Ray 2 series clients contain relatively slow CPUs, so they are not fast enough to decompress JPEG in real time. The second challenge is that Sun Ray servers are generally provisioned to handle a lot of simultaneous users, so using VirtualGL’s X11 Transport would put undue stress on both the Sun Ray servers and the network on which they reside. Thus, Sun Microsystems designed a plugin for VirtualGL which allows VGL to compress images using a protocol that can be sent directly to the Sun Ray hardware client without having to pass through the Sun Ray server first. Since the plugin uses the proprietary Sun Ray image compression technology, it is currently closed source, but the binary packages can be downloaded for free as part of the  product. This product also includes VirtualGL, TurboVNC, and other goodies.

Figure 2.3: The Sun Ray Image Transport

3 System Requirements

3.1 Linux/x86

3.2 Linux/Itanium

VirtualGL should build and run on Itanium Linux, but it has not been thoroughly tested.  if you encounter any difficulties. A pre-built TurboJPEG binary package is not available for Linux/Itanium, so it will be necessary to build TurboJPEG from source using the Intel Integrated Performance Primitives for Itanium processors.

3.3 Solaris/x86

* mediaLib 2.5 is included in Solaris 10 update 4 and newer. If you are running an older version of Solaris, it is recommended that you download and install the mediaLib 2.5 upgrade from the link above. mediaLib 2.5 improves the performance of VirtualGL significantly on Solaris/x86 systems, when compared to mediaLib 2.4.

3.4 Solaris/SPARC

3.5 Mac/x86

3.6 Windows

3.7 Additional Requirements for Stereographic Rendering

The client requirements do not apply to anaglyphic stereo. See Chapter 16 for more details.

3.8 Additional Requirements for Transparent Overlays

4 Obtaining and Installing VirtualGL

VirtualGL must be installed on any machine that will act as a VirtualGL server or as a client for the VGL Image Transport. It is not necessary to install VirtualGL on the client machine if using VNC or another type of X proxy.

4.1 Installing VirtualGL on Linux

Installing TurboJPEG

1. Download the appropriate TurboJPEG binary package (v1.10 or later) for your system from the  of the . 
   

   The “i386” RPM and DEB packages are for 32-bit-only systems. The “x86_64” RPM and “amd64” DEB packages are for 64-bit systems. The 64-bit packages contain both 32-bit and 64-bit libraries.

2. Log in as root, cd to the directory where you downloaded the binary package, and issue one of the following commands:

   RPM-based systems

   rpm -U turbojpeg*.rpm
   

   Debian-based systems

   dpkg -i turbojpeg*.deb
   

Installing VirtualGL

1. Download the appropriate VirtualGL binary package for your system from the  of the . 
   

   The “i386” RPM and DEB packages are for 32-bit-only systems. The “x86_64” RPM and “amd64” DEB packages are for 64-bit systems. The 64-bit packages contain both 32-bit and 64-bit VirtualGL components.

2. Log in as root, cd to the directory where you downloaded the binary package, and issue the following commands:

   RPM-based systems

   rpm -e VirtualGL
   rpm -i VirtualGL*.rpm
   

   Debian-based systems

   dpkg -r VirtualGL
   dpkg -i VirtualGL*.deb
   

4.2 Installing VirtualGL on Solaris

1. Download the VirtualGL Solaris package (SUNWvgl-{version}.pkg.bz2 for SPARC or SUNWvgl-{version}-x86.pkg.bz2 for x86) from the  of the . 
   

   Both packages provide both 32-bit and 64-bit VirtualGL components.

2. Log in as root, cd to the directory where you downloaded the package, and issue the following commands:

   pkgrm SUNWvgl
   

   (answer “Y” when prompted.)

   bzip2 -d SUNWvgl-{version}.pkg.bz2
   pkgadd -d SUNWvgl-{version}.pkg
   

   Select the SUNWvgl package (usually option 1) from the menu.

VirtualGL for Solaris installs into /opt/SUNWvgl.

4.3 Installing VirtualGL on Mac (Client Only)

1. Download the VirtualGL Mac disk image (VirtualGL-{version}.dmg) from the  of the .
2. Open the disk image, then open VirtualGL-{version}.pkg inside the disk image. Follow the instructions to install the Mac client. The Mac package installs files in the same locations as the Linux packages.

4.4 Installing VirtualGL on Windows (Client Only)

1. Download the VirtualGL Windows installer package (VirtualGL-{version}.exe) from the  of the .
2. Run the VirtualGL installer. The installation of VirtualGL should be self-explanatory. The only configuration option is the directory into which you want the files to be installed.

NOTE: The VirtualGL Windows installer does not remove any previous versions of VirtualGL that may be installed on your machine. If you wish, you can remove these older versions manually by using the “Add or Remove Programs” applet in the Control Panel (or the “Programs and Features” applet if you are running Vista.)

4.5 Installing VirtualGL from Source

If you are using a platform for which there is not a pre-built VirtualGL binary package available, then log in as root, download the VirtualGL source tarball (VirtualGL-{version}.tar.gz) from the  of the , uncompress it, cd vgl, and read the contents of BUILDING.txt for further instructions on how to build and install VirtualGL from source.

4.6 Obtaining and Installing the Sun Ray Plugin

The VirtualGL Sun Ray plugin is a proprietary add-on developed by Sun Microsystems to integrate VirtualGL with the Sun Ray thin client environment. If you plan to use this functionality, then it is recommended that you download and install the  software. This software product is available as a free download (Sun charges for support), and it includes VirtualGL, TurboVNC, the proprietary Sun Ray plugin, and enhancements to N1 GridEngine to allow it to manage VirtualGL jobs across a cluster of 3D servers.

4.7 Uninstalling VirtualGL

Linux

As root, issue one of the following commands:

RPM-based systems

rpm -e VirtualGL

Debian-based systems

dpkg -r VirtualGL

Solaris

As root, issue the following command:

pkgrm SUNWvgl

Answer “yes” when prompted.

Mac

• Download and install the latest version of OSXPM
• Launch OSXPM
• Click the “Delete Package” button
• Find VirtualGL-{version}.pkg in the list of packages and highlight it
• Click “Delete Selected”
• Enter your password if prompted
• Complain to Apple about the lack of a built-in package uninstaller for OS X

Windows

Use the “Add or Remove Programs” applet in the Control Panel (or the “Programs and Features” applet if you’re running Vista.)

5 Obtaining and Installing TurboVNC

TurboVNC must be installed on any machine that will act as a TurboVNC server or client. It is not necessary to install TurboVNC to use the VGL Image Transport. Also, TurboVNC need not necessarily be installed on the same server as VirtualGL.

5.1 Installing TurboVNC on Linux

Installing TurboJPEG

1. Download the appropriate TurboJPEG binary package (v1.10 or later) for your system from the  of the . 
   

   The “i386” RPM and DEB packages are for 32-bit-only systems. The “x86_64” RPM and “amd64” DEB packages are for 64-bit systems. The 64-bit packages contain both 32-bit and 64-bit libraries.

2. Log in as root, cd to the directory where you downloaded the binary package, and issue one of the following commands:

   RPM-based systems

   rpm -U turbojpeg*.rpm
   

   Debian-based systems

   dpkg -i turbojpeg*.deb
   

Installing TurboVNC

1. Download the appropriate TurboVNC binary package for your system from the  of the . 
   
2. Log in as root, cd to the directory where you downloaded the binary package, and issue one of the following commands:

   RPM-based systems

   rpm -U turbovnc*.rpm
   

   Debian-based systems

   dpkg -i turbovnc*.deb
   

5.2 Installing TurboVNC on Solaris

1. Download the TurboVNC Solaris package (SUNWtvnc-{version}.pkg.bz2 for SPARC or SUNWtvnc-{version}-x86.pkg.bz2 for x86) from the  of the . 
   
2. Log in as root, cd to the directory where you downloaded the package, and issue the following commands:

   pkgrm SUNWvgl
   

   (answer “Y” when prompted.)

   bzip2 -d SUNWtvnc-{version}.pkg.bz2
   pkgadd -d SUNWtvnc-{version}.pkg
   

   Select the SUNWtvnc package (usually option 1) from the menu.

TurboVNC for Solaris installs into /opt/SUNWtvnc.

5.3 Installing TurboVNC on Mac (Client Only)

1. Download the TurboVNC Mac disk image (TurboVNC-{version}.dmg) from the  of the .
2. Open the disk image, then open TurboVNC-{version}.pkg inside the disk image. Follow the instructions to install the Mac client. The Mac package installs files in the same locations as the Linux packages.

5.4 Installing TurboVNC on Windows (Client Only)

1. Download the TurboVNC Windows installer package (TurboVNC-{version}.exe) from the  of the .
2. Run the TurboVNC installer. The installation of TurboVNC should be self-explanatory. The only configuration option is the directory into which you want the files to be installed.

5.5 Installing TurboVNC from Source

If you are using a platform for which there is not a pre-built TurboVNC binary package available, then log in as root, download the TurboVNC source tarball (turbovnc-{version}.tar.gz) from the  of the , uncompress it,cd vnc/vnc_unixsrc, and read the README file for further instructions on how to build TurboVNC from source.

5.6 Uninstalling TurboVNC

Linux

As root, issue one of the following commands:

RPM-based systems

rpm -e turbovnc

Debian-based systems

dpkg -r turbovnc

Solaris

As root, issue the following command:

pkgrm SUNWtvnc

Answer “yes” when prompted.

Mac

• Download and install the latest version of OSXPM
• Launch OSXPM
• Click the “Delete Package” button
• Find TurboVNC-{version}.pkg in the list of packages and highlight it
• Click “Delete Selected”
• Enter your password if prompted
• Complain to Apple about the lack of a built-in package uninstaller for OS X

Windows

Use the “Add or Remove Programs” applet in the Control Panel (or the “Programs and Features” applet if you’re running Vista.)

6 Configuring a Linux or Solaris Machine as a VirtualGL Server

6.1 GLP: Using VirtualGL Without a 3D X Server

Sun’s OpenGL library for Solaris/SPARC systems has a special extension called “GLP” which allows VirtualGL to directly access a 3D graphics card even if there is no X server running on the card. GLP greatly improves the overall security of the VirtualGL server, since it eliminates the need to grant VirtualGL users access to the 3D X server running on that machine. In addition, GLP makes it easy to assign VirtualGL jobs to any graphics card in a multi-card system.

When using GLP, the architecture of VirtualGL changes as follows:

Figure 6.1: The VGL Image Transport with a Remote 2D X Server and GLP

Figure 6.2: The X11 Image Transport with an X Proxy and GLP

Figure 6.3: The Sun Ray Image Transport with GLP

If the application server is running  1.5 for Solaris/SPARC, then it is recommended that you configure it to use GLP:

1. Log in as root.
2. Run

   /opt/VirtualGL/bin/vglserver_config
   

3. Select option 3 (Configure server for use with VirtualGL in GLP mode.)

4. Restrict framebuffer device access to vglusers group (recommended)?
   [Y/n]
   

   Yes

   Only users in the vglusers group can run OpenGL applications on the VirtualGL server (the configuration script will create the vglusers group if it doesn’t already exist.) This limits the possibility that an unauthorized user could snoop the 3D framebuffer device(s) and thus see (or alter) the output of a 3D application that is being used with VirtualGL.

   No

   Any authenticated user can run OpenGL applications on the VirtualGL server. If it is necessary for users outside of the vglusers group to log in locally to this server and run OpenGL applications, then this option must be selected.

5. If you chose to restrict framebuffer device access to the vglusers group, then edit /etc/group and add root to the vglusers group. If you choose, you can also add additional users to the group at this time. Note that any user you add to vglusers must log out and back in again before their new group permissions will take effect.
6. Edit the /etc/dt/config/GraphicsDevices file as necessary. This file contains a list of paths to 3D framebuffer devices (such as /dev/fbs/kfb0, /dev/fbs/jfb0, etc.) that you wish to use with VirtualGL.

Sanity Check

To verify that the application server is ready to run VirtualGL, log out of the server, log back into the server using SSh, and execute the following command in the SSh session:

/opt/VirtualGL/bin/glxinfo -d glp

This command should output a list of visuals and should complete with no errors.

Using GLP by Default in VirtualGL

If you wish VirtualGL to use GLP by default, then you can add

VGL_