* Using TurboVNC with VirtualGL

Referring to the VirtualGL User's Guide, VirtualGL's X11 Transport draws 3D
images onto an X display using standard X11 drawing commands.  Since this
results in the images being sent uncompressed to the X server, the X11
Transport is designed to be used with an "X Proxy."  An X proxy acts as a
virtual X server, receiving X11 commands from the application (and from
VirtualGL), rendering the X11 commands into images, compressing the resulting
images, and sending the compressed images over the network to a client or
clients.

Since VirtualGL is sending rendered 3D images to the X proxy at a very fast
rate, the proxy must be able to compress the images very quickly in order to
keep up.  Unfortunately, however, most X proxies can't.  They simply aren't
designed to compress, with any degree of performance, the large and complex
images generated by 3D applications.

Enter TurboVNC.  Although TurboVNC can be used with all types of applications,
it was initially designed as a fast X proxy for VirtualGL.  TurboVNC provides
an alternate means of delivering rendered 3D images from VirtualGL to a
client machine without using VirtualGL's embedded VGL Transport.

*** Advantages of TurboVNC (when compared to the VGL Transport)
#OPT: noList! plain!

	* When using the VGL Transport, non-3D portions of the application's GUI are
		sent over the network using remote X11, which will create performance
		problems on high-latency networks (such as broadband or long-haul fibre.)
		Non-3D portions of the application's GUI will load and render much
		faster (perhaps even orders of magnitude faster) with TurboVNC than with
		the VGL Transport on such connections.

	* For 3D applications whose rendered images do not contain very many unique
		colors (for instance, CAD applications in wireframe mode), the hybrid
		encoding methods used by TurboVNC will generally use less network bandwidth
		than the pure JPEG encoding method used by the VGL Transport.

	* TurboVNC provides two lossless compression modes, one of which is designed
		to reduce server CPU usage on gigabit networks and the other of which is
		designed to provide reasonable performance on wide-area networks (at the
		expense of higher server CPU usage.)  The VGL Transport's only
		lossless option is uncompressed RGB.

	* TurboVNC includes a lossless refresh feature that will, on demand, send
		a mathematically lossless image of the current VNC desktop to the client.
		A user connecting over a low-bandwidth connection can use low-quality JPEG
		to achieve the best performance when manipulating the 3D model, then they
		can request a lossless refresh when they are ready to study the model in
		detail.

	* The TurboVNC Server can be configured to send a mathematically lossless
		copy of certain regions of the screen during periods of inactivity
		(Automatic Lossless Refresh.)

	* TurboVNC provides rudimentary collaboration capabilities.  Multiple clients
		can simultaneously view the same TurboVNC session and pass around control
		of the keyboard and mouse.

	* The TurboVNC Viewer is stateless.  If the network hiccups or the viewer is
		otherwise disconnected, the session continues to run on the server and can
		be rejoined from any machine on the network.

	* No X server is required on the client machine.  This reduces the deployment
		complexity for Windows clients.

	* Zero-install high-performance Java viewer can be launched from any machine
		that has Java and a web browser installed.

	* Any mobile device can be used as a TurboVNC client (with reduced
		performance.)

*** Disadvantages of TurboVNC (when compared to the VGL transport)
#OPT: noList! plain!

	* No seamless windows.  All application windows are constrained to a "virtual
		desktop", which displays in a single window on the client machine.

	* TurboVNC will generally	require about 20% more server CPU cycles to
		maintain the same frame rate as the VGL Transport, both because it
		has to compress more pixels in each frame	(an entire desktop rather than a
		single window) and because it has to perform 2D (X11) rendering as well as
		3D rendering.

	* TurboVNC does not support quad-buffered stereo or transparent overlays.

** Using TurboVNC and VirtualGL on the Same Server
{anchor: TurboVNC_Usage_Local}

The most common (and optimal) way to use TurboVNC is to set it up on the same
server that is running VirtualGL.  This allows VirtualGL to send its rendered
3D images to TurboVNC through shared memory rather than sending them over a
network.

#IMG: x11transport.png
#OPT fmt=latex: w=4cm

The following procedure describes how to launch a 3D application using this
configuration.

*** Procedure
#OPT: noList! plain!

	#. Follow the procedure described in {ref prefix="Chapter ": TurboVNC_Usage}
		for starting a TurboVNC session and connecting to it.

	#. Open a new terminal inside the TurboVNC desktop.

	#. In the terminal, start a 3D application using VirtualGL:

		#Verb: <<---
		/opt/VirtualGL/bin/vglrun [vglrun options] {application_executable_or_script} {arguments}
		---

		The TurboVNC startup script sets the ''VGL_COMPRESS'' environment variable
		to ''0'', which will automatically enable the X11 Transport within
		VirtualGL.

** Using TurboVNC When VirtualGL Is Running on a Different Machine
{anchor: TurboVNC_Usage_Remote}

#IMG: vgltransportservernetwork.png
#OPT fmt=latex: w=4cm

If TurboVNC and VirtualGL are running on different servers, then it is
desirable to use the VGL Transport to send images from the VirtualGL
server to the TurboVNC server.  It is also desirable to disable image
compression in the VGL Transport.  Otherwise, the images would have to be
compressed by the VirtualGL server, decompressed by the VirtualGL Client, then
recompressed by the TurboVNC Server, which is a waste of CPU resources.
However, sending images uncompressed over a network requires a fast network
(generally, Gigabit Ethernet or faster), so there needs to be a fast link
between the VirtualGL server and the TurboVNC server for this procedure to
perform well.

*** Procedure
#OPT: noList! plain!

	#. Follow the procedure described in {ref prefix="Chapter ": TurboVNC_Usage}
		for starting a TurboVNC session and connecting to it.

	#. Open a new terminal inside the TurboVNC desktop.

	#. In the same terminal window, open a Secure Shell (SSH) session into the
		VirtualGL server:

		#Verb: <<---
		/opt/VirtualGL/bin/vglconnect {user}@{server}
		---

		Replace __''{user}''__ with your username on the VirtualGL server and
		__''{server}''__ with the hostname or IP address of that server.  Refer to
		the VirtualGL User's Guide for additional ''vglconnect'' options.

	#. In the SSH session, set the ''VGL_COMPRESS'' environment variable to
		''rgb''

		!!! Passing an argument of ''-c rgb'' to ''vglrun'' achieves the same
		effect.

	#. In the SSH session, start a 3D application using VirtualGL:

		#Verb: <<---
		/opt/VirtualGL/bin/vglrun [vglrun options] {application_executable_or_script} {arguments}
		---
