* Advanced Configuration
{anchor: Advanced_Configuration}

** Server Settings

You can control the operation of the VirtualGL faker in four different ways.
Each method of configuration takes precedence over the previous method:

	#. Setting a configuration environment variable globally (for instance, in
		''/etc/profile'')

	#. Setting a configuration environment variable on a per-user basis (for instance, in
		''~/.bashrc'')

	#. Setting a configuration environment variable only for the current shell
		session (for instance, ''export VGL_XXX={whatever}'')

	#. Passing a configuration option as an argument to ''vglrun''.  This
		effectively overrides any previous environment variable setting
		corresponding to that configuration option.
{:}
	!!! If "Custom (if supported)" is listed as one of the available Image
	Transports, then this means that image transport plugins are free to handle
	or ignore this option as they see fit.

{anchor: VGL_ALLOWINDIRECT}
| Environment Variable | ''VGL_ALLOWINDIRECT = ''__''0 \| 1''__ |
| Summary | Allow applications to request an indirect OpenGL context |
| Image Transports | All |
| Default Value | 0 (all OpenGL contexts use direct rendering, unless \
	rendering to a [[#overlays][transparent overlay]]) |
#OPT: hiCol=first

	Description :: Normally, when VirtualGL maps a Pbuffer to a window and
	establishes an OpenGL rendering context with the Pbuffer, it forces direct
	rendering to be used with this context.  Some 3D applications erroneously try
	to create indirect OpenGL contexts because they detect that the X display is
	remote and assume that the 3D rendering commands will be sent over the
	network.  Thus, VirtualGL normally forces all contexts to be direct in order
	to prevent severe readback performance degradation with such apps (even on
	modern 3D adapters, and even when the connection to the 3D X server is local,
	''glReadPixels()'' can perform very slowly if an indirect OpenGL context is
	used.)
	{nl}{nl}
	However, some applications intentionally try to create indirect contexts so
	that these contexts can be shared, and those apps may not work properly when
	the contexts are forced to be direct.  For such apps, setting
	''VGL_ALLOWINDIRECT'' to ''1'' will cause VirtualGL to honor the
	application's request for an indirect OpenGL context.

| Environment Variable | ''VGL_CLIENT = ''__''{c}''__ |
| ''vglrun'' argument | ''-cl ''__''{c}''__ |
| Summary | __''{c}''__ = the hostname or IP address of the VirtualGL client |
| Image Transports | VGL, Custom (if supported) |
| Default Value | Automatically set by ''vglconnect'' or ''vglrun'' |
#OPT: hiCol=first

	Description :: When using the VGL Transport, ''VGL_CLIENT'' should be set to
	the hostname or IP address of the machine on which ''vglclient'' is running.
	Normally, ''VGL_CLIENT'' is set automatically by the ''vglconnect'' or
	''vglrun'' script, so don't override it unless you know what you're doing.

{anchor: VGL_COMPRESS}
| Environment Variable | ''VGL_COMPRESS = ''__''proxy \| jpeg \| rgb \| xv \| yuv''__ |
| ''vglrun'' argument | ''-c ''__''proxy \| jpeg \| rgb \| xv \| yuv''__ |
| Summary | Set image transport and image compression type |
| Image Transports | All |
| Default Value | (See description) |
#OPT: hiCol=first

	Description :: {:}
	__proxy__ = Send images uncompressed using the X11 Transport.  This is useful
	when displaying to a local 2D X server or X proxy (see
	{ref prefix="Section ": X11_Proxy_Usage_Local}.)
	{nl}{nl}
	__jpeg__ = Compress images using JPEG and send using the VGL Transport.  This
	is useful when displaying to a remote 2D X server (see
	{ref prefix="Chapter ": VGL_Transport_Usage}.)
	{nl}{nl}
	__rgb__ = Encode images as uncompressed RGB and send using the VGL Transport.
	 This is useful when displaying to a remote 2D X server or X proxy across a
	very fast network (see {ref prefix="Section ": X11_Proxy_Usage_Remote}.)
	{nl}{nl}
	__xv__ = Encode images as YUV420P (planar YUV with 4X chrominance
	subsampling) and display them to the 2D X server using the XV Transport.
	This transport is designed for use with X proxies, such as the Sun Ray Server
	Software, that support the X Video extension (see
	{ref prefix="Chapter ":X_Video_Support}.)
	{nl}{nl}
	__yuv__ = Encode images as YUV420P, send using the VGL Transport, and display
	on the client machine using the X Video extension.  This greatly reduces the
	CPU usage on both server and client and uses only about half the network
	bandwidth as RGB, but the use of 4X chrominance subsampling does produce some
	visible artifacts (see {ref prefix="Chapter ":X_Video_Support}.)
	{nl}{nl}
	If this option is not specified, then the default is set as follows:
	{nl}{nl}
	If the ''DISPLAY'' environment variable begins with '':'' or ''unix:'', then
	VirtualGL assumes that the X display connection is local.  If it detects that
	the 2D X server is a Sun Ray X Server instance, then it will default to using
	__xv__ compression.  Otherwise, it will default to __proxy__ compression.
	{nl}{nl}
	If VirtualGL detects that the 2D X server is remote, then it will default to
	using __yuv__ compression if that X server is a Sun Ray X Server instance or
	__jpeg__ compression otherwise.

	!!! If an image transport plugin is being used, then you can set
	''VGL_COMPRESS'' to any numeric value >= 0 (Default value = 0.)  The plugin
	can choose to respond to this value as it sees fit.

{anchor: VGL_DEFAULTFBCONFIG}
| Environment Variable | ''VGL_DEFAULTFBCONFIG = ''__''{attrib_list}''__ |
| Summary | __''{attrib_list}''__ = GLX attributes of the default FB config \
	that VirtualGL uses if a 3D application does not call \
	''glXChooseVisual()'' to specify the 3D rendering attributes it desires |
| Image Transports | All |
| Default Value | None |
#OPT: hiCol=first

	Description :: Normally, VirtualGL monitors the ''glXChooseVisual()''
	function and uses the parameters passed to that function to determine which
	rendering attributes the 3D application desires.  VGL uses those attributes
	to obtain a GLX FB config, and that FB config is mapped internally to the
	visual that is returned to the 3D application.  The FB config is also used
	when creating the Pbuffers that back the application's 3D windows.
	{nl}{nl}
	In rare cases, however, an application may choose to implement its own
	visual selection mechanism rather than calling ''glXChooseVisual()''.  Such
	applications will iterate through the list of X visuals and examine the 3D
	attributes of each using ''glXGetConfig()''.  The problem is that, whereas
	in a "normal" GLX environment there would be a 1:1 correspondence between
	X visuals and GLX FB configs, in VirtualGL's split rendering environment,
	X visuals are on the 2D X server and GLX FB configs are on the 3D X server.
	Thus, if an application calls ''glXGetConfig()'' before calling
	''glXChooseVisual()'', VirtualGL has not yet mapped the X visual in question
	to an FB config, and furthermore, VirtualGL has no idea what type of visual
	the application is looking for.  In such cases, VGL has to map the visual to
	a default FB config.  Since this default FB config is very basic, if
	the application is hunting for a visual with a particular parameter (such as
	an alpha channel or a stencil buffer), then it may fail to find one.
	{nl}{nl}
	This configuration option allows the user to specify the 3D rendering
	attributes of VirtualGL's default FB config, which may be necessary to make
	certain applications work, if those applications do not use
	''glXChooseVisual()'' to obtain a visual.  The attribute list is specified in
	the same way that you would specify arguments to ''glXChooseFBConfig()''.
	Example: ''VGL_DEFAULTFBCONFIG = GLX_ALPHA_SIZE,8,GLX_STENCIL_SIZE,8''.  See
	[[#Application_Recipes][Application Recipes]] for a list of applications that
	are known to require the use of this configuration option.

| Environment Variable | ''VGL_DISPLAY = ''__''{d}''__ |
| ''vglrun'' argument | ''-d ''__''{d}''__ |
| Summary | __''{d}''__ = the X display to use for 3D rendering |
| Image Transports | All |
| Default Value | :0 |
#OPT: hiCol=first

	Description :: If the VirtualGL server has multiple 3D graphics cards and you
	want the OpenGL commands from the 3D application to be redirected to the
	second or subsequent graphics cards in the system, then you can set
	''VGL_DISPLAY'' to (or invoke ''vglrun -d'' with) '':0.1'', '':0.2'', etc.

{anchor: VGL_FORCEALPHA}
| Environment Variable | ''VGL_FORCEALPHA = ''__''0 \| 1''__ |
| Summary | Force the Pbuffers used for 3D rendering to have an 8-bit alpha channel |
| Image Transports | All |
| Default Value | ''VGL_FORCEALPHA=1'' if PBO readback mode is used, ''VGL_FORCEALPHA=0'' otherwise |
#OPT: hiCol=first

	Description :: Normally, VirtualGL will create a Pbuffer whose pixel format
	matches the specifications of the visual requested by the 3D application.
	However, on some 3D hardware, this may produce suboptimal performance when
	reading back the 3D pixels.  Thus, this option can be used to force VirtualGL
	to create a 32-bit-per-pixel Pbuffer when the application requests a
	24-bit-per-pixel visual.
	{nl}{nl}
	On some 3D hardware, it is necessary to use a 32-bit-per-pixel Pbuffer to
	realize any performance improvement from the use of pixel buffer objects
	(PBO's).  Thus, unless this option is explicitly disabled, it will be
	enabled by default whenever PBO readback mode is enabled.  See the
	[[#VGL_READBACK][''VGL_READBACK'']] option for further information.

	!!! ''VGL_FORCEALPHA'' overrides the application's choice of visuals.  It has
	no effect if the application is not explicitly choosing a visual.  In that
	case, use [[#VGL_DEFAULTFBCONFIG][''VGL_DEFAULTFBCONFIG'']] instead.

{anchor: VGL_FPS}
| Environment Variable | ''VGL_FPS = ''__''{f}''__ |
| ''vglrun'' argument | ''-fps ''__''{f}''__ |
| Summary | Limit the client/server frame rate to __''{f}''__ frames/second, \
	where __''{f}''__ is a floating point number > 0.0 |
| Image Transports | VGL, X11, XV, Custom (if supported) |
| Default Value | 0.0 (No limit) |
#OPT: hiCol=first

	Description :: This option prevents VirtualGL from sending frames at a rate
	faster than the specified limit.  It can be used, for instance, as a crude
	way to control network bandwidth or CPU usage in multi-user environments
	where those resources are constrained.
	{nl}{nl}
	If frame spoiling is disabled, then setting ''VGL_FPS'' effectively limits
	the server's 3D rendering frame rate as well.

{anchor: VGL_GAMMA}
| Environment Variable | ''VGL_GAMMA = ''__''{g}''__ |
| ''vglrun'' argument | ''-gamma ''__''{g}''__ |
| Summary | Specify gamma correction factor |
| Image Transports | All |
| Default Value | 1.00 (no gamma correction) |
#OPT: hiCol=first

	Description :: "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 = X{^G}__, where X is between 0 and 1.  G is called the "gamma"
	of the monitor.  PC monitors and TV's usually have a gamma of around 2.2.
	{nl}{nl}
	Some of the math involved in 3D rendering assumes a linear gamma
	(G = 1.0), so technically speaking, 3D applications will not display with
	mathematical correctness unless the pixels are "gamma corrected" to
	counterbalance the non-linear response curve of the monitor.  However,
	some systems do not have any form of built-in gamma correction, so 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 = W{^1/G}__, where G
	is the "gamma correction factor" and should be equal to the gamma of the
	monitor.  So, the final output is __Y = X{^G} = (W{^1/G}){^G} = W__, which
	describes a linear relationship between the intensity of the pixels drawn
	by the application and the intensity of the pixels displayed by the
	monitor.
	{nl}{nl}
	If ''VGL_GAMMA'' is set to an arbitrary floating point value, 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.

{anchor: VGL_GLFLUSHTRIGGER}
| Environment Variable | ''VGL_GLFLUSHTRIGGER = ''__''0 \| 1''__ |
| Summary | Disable/enable reading back and sending the front buffer contents \
	whenever the 3D application calls ''glFlush()'' while rendering to the \
	front buffer |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: ''glFlush()'' is a sort of "asynchronous synchronization"
	command.  It flushes the OpenGL command buffers, which generally has the
	effect of ensuring that the commands have been delivered to the 3D hardware.
	However, unlike ''glFinish()'', ''glFlush()'' does not wait until the
	commands have been rendered before it returns.
	{nl}{nl}
	The use of ''glFlush()'' can vary widely from application to application.
	When doing front buffer rendering, some applications call ''glFlush()'' after
	each object is rendered.  Some call it only at the end of the frame.  Others
	call ''glFlush()'' much more often, even as frequently as every time a few
	lines are drawn.  This creates problems for VirtualGL, since it has to guess
	what the application is intending to do.  Not all applications that use
	front buffer rendering call ''glFinish()'' to signal the end of a frame, so
	VirtualGL can't usually get away with ignoring ''glFlush()''.  However, some
	applications call ''glFlush()'' so often that VirtualGL can't usually get
	away with reading back/sending a frame every time ''glFlush()'' is called,
	either (see [[#VGL_SPOILLAST][VGL_SPOILLAST]] for more information on how
	VirtualGL tries to handle this, under normal circumstances.)
	{nl}{nl}
	Some 3D applications use ''glFlush()'' very liberally and intend for it to be
	an intermediate rather than a final synchronization command.  Such
	applications will call ''glFinish()'' after a sequence of ''glFlush()''
	calls, so for those applications, reading back and sending the rendered 3D
	image in response to ''glFlush()'' calls is a waste of resources and can
	sometimes create visual artifacts (for instance, if the application clears
	the front buffer with a particular color, calls ''glFlush()'', then clears it
	again with another color.  We wouldn't mention it if it hadn't happened
	before.)  For such applications, setting ''VGL_GLFLUSHTRIGGER'' to ''0''
	should allow them to display properly.  See
	[[#Application_Recipes][Application Recipes]] for a list of applications that
	are known to require this.

| Environment Variable | ''VGL_GLLIB = ''__''{l}''__ |
| Summary | __''{l}''__ = the location of an alternate OpenGL library |
| Image Transports | All |
#OPT: hiCol=first

	Description :: Normally, VirtualGL tries to call any "real" GLX and OpenGL
	functions it needs from the OpenGL library against which it is linked
	(usually ''/usr/lib/libGL.so.1'', ''/usr/lib64/libGL.so.1'',  or
	''/usr/lib/64/libGL.so.1'').  Failing this, VirtualGL will then try to call
	these functions from the first compatible library named ''libGL.so.1'' that
	is found in the dynamic loader path.  You can use the ''VGL_GLLIB''
	environment variable to override this behavior and specify a dynamic library
	from which VirtualGL will call the "real" GLX and OpenGL functions.
	{nl}{nl}
	You shouldn't need to muck with this unless something doesn't work.  However,
	setting this environment variable is necessary when using VirtualGL with
	[[chromium.txt#Chromium][Chromium]].  It is also potentially useful if one
	wishes to insert another OpenGL interposer between VirtualGL and the system's
	OpenGL library.

| Environment Variable | ''VGL_GUI = ''__''{k}''__ |
| Summary | __''{k}''__ = the key sequence used to pop up the VirtualGL \
	Configuration dialog, or ''none'' to disable the dialog |
| Image Transports | All |
| Default Value | shift-ctrl-f9 |
#OPT: hiCol=first

	Description :: VirtualGL will normally monitor an application's X event queue
	and pop up the VirtualGL Configuration dialog whenever ''CTRL-SHIFT-F9'' is
	pressed.  In the event that this interferes with a key sequence that a 3D
	application is already using, then you can redefine the key sequence used to
	pop up the VirtualGL Configuration dialog by setting ''VGL_GUI'' to some
	combination of ''shift'', ''ctrl'', ''alt'', and one of ''f1, f2, ..., f12''.
	You can also set ''VGL_GUI'' to ''none'' to disable the configuration dialog
	altogether.  See {ref prefix="Chapter ": Config_Dialog} for more details.

{anchor: VGL_INTERFRAME}
| Environment Variable | ''VGL_INTERFRAME = ''__''0 \| 1''__ |
| Summary | Enable or disable interframe image comparison |
| Image Transports | VGL (JPEG, RGB), Custom (if supported) |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: The VGL Transport will normally compare each frame with the
	previous frame and send only the portions of the image that have changed.
	Setting ''VGL_INTERFRAME'' to ''0'' disables this behavior.
	{nl}{nl}
	This setting was introduced in order to work around a specific application
	interaction issue, but since a proper fix for that issue was introduced in
	VirtualGL 2.1.1, this option isn't really useful anymore.

	!!! When using the VGL Transport, interframe comparison is affected by the
	[[#VGL_TILESIZE][''VGL_TILESIZE'']] option

| Environment Variable | ''VGL_LOG = ''__''{l}''__ |
| Summary | Redirect all messages from VirtualGL to a log file specified by \
	__''{l}''__ |
| Image Transports | All |
| Default Value | Print all messages to stderr |
#OPT: hiCol=first

	Description :: Setting this environment variable to the pathname of a log
	file on the VirtualGL server will cause VirtualGL to redirect all of its
	messages (including profiling and trace output) to the specified log file
	rather than to stderr.

| Environment Variable | ''VGL_LOGO = ''__''0 \| 1''__ |
| Summary | Enable or disable the display of a VGL logo in the 3D window |
| Image Transports | All |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: Setting ''VGL_LOGO'' to ''1'' will cause VirtualGL to display
	a small logo in the bottom right-hand corner of the 3D window.  This is meant
	as a debugging tool to allow users to determine whether or not VirtualGL is
	active.

{anchor: VGL_NPROCS}
| Environment Variable | ''VGL_NPROCS = ''__''{n}''__ |
| ''vglrun'' argument | ''-np ''__''{n}''__ |
| Summary | __''{n}''__ = the number of CPUs to use for multi-threaded \
	compression |
| Image Transports | VGL (JPEG, RGB), Custom (if supported) |
| Default Value | 1 |
#OPT: hiCol=first

	Description :: The VGL Transport can divide the task of compressing each
	frame among multiple server CPUs.  This might speed up the overall throughput
	in rare circumstances where the server CPUs are significantly slower than the
	client CPUs.
	{nl}{nl}
	VirtualGL will not allow more than 4 processors total to be used for
	compression, nor will it allow you to set this parameter to a value greater
	than the number of processors in the system.

	!!! When using the VGL Transport, multi-threaded compression is affected by
	the [[#VGL_TILESIZE][''VGL_TILESIZE'']] option

| Environment Variable | ''VGL_PORT = ''__''{p}''__ |
| ''vglrun'' argument | ''-p ''__''{p}''__ |
| Summary | __''{p}''__ = the TCP port to use when connecting to the \
	VirtualGL Client |
| Image Transports | VGL, Custom (if supported) |
| Default Value | Read from X property stored by VirtualGL Client |
#OPT: hiCol=first

	Description :: The connection port for the VGL Transport is normally
	determined by reading an X property that ''vglclient'' stores on the 2D X
	server, so don't override this unless you know what you're doing.

| Environment Variable | ''VGL_PROFILE = ''__''0 \| 1''__ |
| ''vglrun'' argument | ''-pr'' / ''+pr'' |
| Summary | Disable/enable profiling output |
| Image Transports | VGL, X11, XV, Custom (if supported) |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If profiling output is enabled, then VirtualGL will
	continuously benchmark itself and periodically print out the throughput of
	various stages in its image pipeline.
	{nl}{nl}
	See {ref prefix="Chapter ": Perf_Measurement} for more details.

{anchor: VGL_QUAL}
| Environment Variable | ''VGL_QUAL = ''__''{q}''__ |
| ''vglrun'' argument | ''-q ''__''{q}''__ |
| Summary | __''{q}''__ = the JPEG compression quality, 1 \<\= __''{q}''__ \<\= 100 |
| Image Transports | VGL (JPEG), Custom (if supported) |
| Default Value | 95 |
#OPT: hiCol=first

	Description :: In digital images, "frequency" refers to how quickly the color
	changes between light and dark as you move either horizontally or vertically
	in the image.  Images with very sharp, bright features on a dark background,
	for instance, consist of both low-frequency and high-frequency components,
	whereas images with smooth transitions between neighboring pixels contain
	only low-frequency components.  JPEG compression works by breaking down the
	image into its constituent frequencies and then throwing out the highest of
	these frequencies.  The JPEG image "quality" determines which frequencies are
	thrown out.  A JPEG quality of 1 throws out all but the lowest frequencies
	and thus produces a very impressionistic, but generally not very useful,
	compressed image.  A JPEG quality of 100 retains all frequencies in the
	original image (but, due to roundoff errors, the compressed image is still
	not completely lossless.)
	{nl}{nl}
	Because the human eye usually can't detect the highest frequencies in the
	image, and often because the image lacks those high-frequency elements to
	begin with, a sufficiently high JPEG quality setting can produce a
	"perceptually lossless" image.  A "perceptually lossless" image contains
	a small amount of mathematical error when compared to the original image, but
	this error is so small that, under normal circumstances, the human visual
	system cannot distinguish it.  The threshold quality level at which JPEG
	compression becomes perceptually lossless is different for each image, but
	experiments with various visual difference benchmarks (such as
	[[http://www.mpi-inf.mpg.de/resources/hdr/vdp/][HDR-VDP]]) suggest that	a
	JPEG quality of 95 is sufficient to guarantee perceptual losslessness for the
	types of applications (volume visualization apps, in particular) in which
	image quality is critical.  As with any benchmarks, Your Mileage May Vary.
	If image quality is of paramount concern, consider setting the JPEG quality
	to 100 or using RGB encoding.
	{nl}
	!!! If using an image transport plugin, then this setting need not
	necessarily correspond to JPEG image quality.  The plugin can choose to
	respond to the ''VGL_QUAL'' option as it sees fit.

{anchor: VGL_READBACK}
| Environment Variable | ''VGL_READBACK = ''__''none \| pbo \| sync''__ |
| Summary | Specify the method used by VirtualGL to read back the 3D pixels from the 3D graphics hardware |
| Image Transports | All |
| Default Value | sync |
#OPT: hiCol=first

	Description :: {:}
	* __none__ = Do not read back the 3D pixels at all.  On rare occasions, it
	might be desirable to have VirtualGL redirect OpenGL rendering from an
	application into a Pbuffer but not automatically read back and send the
	rendered pixels.  Some applications have their own mechanisms for reading
	back the rendered pixels, so setting ''VGL_READBACK=none'' disables
	VirtualGL's readback mechanism and prevents duplication of effort.
	{nl}{nl}
	This option was developed initially to support running
	[[http://www.paraview.org/][ParaView]] in parallel using MPI.  ParaView/MPI
	normally uses MPI processes 1 through N as rendering servers, each drawing a
	portion of the geometry into a separate window on a separate X display.
	ParaView reads back these server windows and composites the pixels into the
	main application window, which is controlled by MPI process 0.  By creating a
	script that passes a different value of ''VGL_DISPLAY'' and ''VGL_READBACK''
	to each MPI process, it is possible to make all of the ParaView server
	processes render to off-screen buffers on different graphics cards while
	preventing VirtualGL from displaying any pixels except those generated by
	process 0.
	{nl}{nl}
	This setting can also be used to force Chromium to render into Pbuffers
	instead of windows.  See {ref prefix="Section ": Force_Pbuffer}.
	{nl}{nl}
	* __pbo__ = PBO readback mode.  Attempt to use pixel buffer objects (PBO's)
	to accelerate the readback of the 3D pixels from the 3D graphics card.  A PBO
	is an	opaque memory buffer managed by OpenGL, so it can be locked down for
	direct DMA transfers.  This improves performance as well as makes the pixel
	readback operation non-blocking.  However, the catch is that the pixel format
	requested in the pixel readback operation must match the "native" pixel
	format of the Pbuffer in order for PBO's to realize any performance benefit.
	Otherwise, the 3D driver falls back to using the standard blocking pixel
	readback operation.
	{nl}{nl}
	Because the PBO is a managed buffer, VirtualGL has to introduce an additional
	memory copy to transfer the pixels out of the PBO and into the image
	transport's buffer.  On high-end 3D hardware, PBO readback mode will generally
	perform better than synchronous readback mode, even with this additional
	memory copy, but there are a few platforms on which it performs worse, which
	is why it is not enabled by default.  PBO's will significantly improve
	performance on nVidia hardware when multiple users are sharing the GPU.
	{nl}{nl}
	VirtualGL will automatically fall back to synchronous readback mode if it
	needs to read back pixels in a format other than the native format of the
	Pbuffer.  This will generally be the case if anaglyphic stereo is enabled, if
	RGB encoding is used with the VGL Transport, or if the X11 Transport is used
	with a 2D X server whose pixel format does not match that of the Pbuffer.
	Setting ''VGL_VERBOSE=1'' will print a warning message whenever this occurs.
	Since PBO's are not accelerated on some platforms unless 32-bit pixel formats
	are used, VirtualGL's default behavior is to automatically create Pbuffers
	with 32 bits per pixel when PBO readback mode is enabled (you can use the
	[[#VGL_FORCEALPHA][''VGL_FORCEALPHA'']] option to override this.)
	{nl}{nl}
	* __sync__ = Synchronous readback mode.  This disables the use of PBO's
	altogether, which causes VirtualGL to always use blocking pixel readback
	operations and to let the 3D driver perform any pixel translation that is
	necessary.  This is the default behavior of VirtualGL.
	{nl}{nl}

| Environment Variable | ''VGL_SAMPLES = ''__''{s}''__ |
| ''vglrun'' argument | ''-ms ''__''{s}''__ |
| Summary | Force OpenGL multisampling to be enabled with __''{s}''__ \
	samples.  __''{s}''__ = 0 to force OpenGL multisampling to be disabled. |
| Image Transports | All |
| Default Value | Allow the 3D application to determine the level of \
	multisampling |
#OPT: hiCol=first

	Description :: This option was added primarily because certain
	vendor-specific methods of enabling full-scene antialiasing at a global level
	(such as nVidia's ''__GL_FSAA_MODE'' environment variable) do not work with
	Pbuffers and, subsequently, do not work with VirtualGL.  If ''VGL_SAMPLES''
	is > 0, then VirtualGL will attempt to redirect 3D rendering to
	multisample-enabled Pbuffers with the specified number (or a greater
	number) of samples.  This effectively forces the 3D application to render
	with the specified multisampling level, as if the application had explicitly
	passed parameters of ''GLX_SAMPLES'', __''{s}''__ to ''glXChooseVisual()''.
	If ''VGL_SAMPLES'' is ''0'', then VirtualGL forces multisampling to be
	disabled, even if the 3D application explicitly tries to enable it.

	!!! ''VGL_SAMPLES'' overrides the application's choice of visuals.  It has
	no effect if the application is not explicitly choosing a visual.  In that
	case, use [[#VGL_DEFAULTFBCONFIG][''VGL_DEFAULTFBCONFIG'']] instead.

{anchor: VGL_SPOIL}
| Environment Variable | ''VGL_SPOIL = ''__''0 \| 1''__ |
| ''vglrun'' argument | ''-sp'' / ''+sp'' |
| Summary | Disable/enable frame spoiling |
| Image Transports | VGL, X11, XV, Custom (if supported) |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: In remote display environments, the mouse movement is
	generally sampled at least 40 and sometimes 60 times per second.  Therefore,
	unless VirtualGL is able to deliver at least this number of frames per
	second to the client, the movement of a 3D scene will appear to drag behind
	the mouse motion.  VirtualGL's default behavior is to compensate for this by
	dropping frames.  This ensures that every mouse motion event will result in a
	new frame being rendered on the server, even though not all of these frames
	will actually be delivered to the client.
	{nl}{nl}
	Frame spoiling should produce the best results with interactive applications,
	but it should be turned off when running benchmarks or other non-interactive
	applications.  Turning off frame spoiling will force every frame rendered on
	the server to be sent through VirtualGL, and thus the frame rate reported by
	OpenGL benchmarks will accurately reflect the frame rate of VirtualGL's image
	pipeline (though, in X proxy environments, this may still not accurately
	reflect the frame rate seen by the user.  See
	{ref prefix="Section ": Frame_Spoiling}.)  Disabling frame spoiling also
	prevents non-interactive applications from wasting graphics resources by
	rendering frames that will never be seen.

{anchor: VGL_SPOILLAST}
| Environment Variable | ''VGL_SPOILLAST = ''__''0 \| 1''__ |
| Summary | Disable/enable "spoil last" frame spoiling algorithm for frames triggered by ''glFlush()'' |
| Image Transports | VGL, X11, XV, Custom (if supported) |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: VirtualGL will commonly read back a rendered 3D image if the
	3D application calls ''glXSwapBuffers()'' while rendering to the back
	buffer or if the 3D application calls ''glFinish()'', ''glFlush()'', or
	''glXWaitGL()'' while rendering to the front buffer.  When frame spoiling is
	enabled and the frame queue is busy compressing/sending a frame,
	the newly-rendered frame is normally promoted to the head of the frame
	queue, and the rest of the frames in the queue are "spoiled" (discarded.)
	This algorithm, called "spoil first",	ensures that when a frame is actually
	sent to the client (rather than spoiled), the sent frame will be the most
	recently rendered frame.  However, this algorithm requires that VirtualGL
	read back every frame that the application renders, even if the frame is
	ultimately discarded.
	{nl}{nl}
	Some applications call ''glFlush()'' many thousands of times per frame while
	rendering to the front buffer.  Thus, VirtualGL's default behavior is to use
	a different spoiling algorithm, "spoil last", to process frames triggered by
	''glFlush()'' calls.  "Spoil last" discards the most recently rendered frame
	if the frame queue is busy.  Thus, the only frames that are read back from
	the graphics card are the frames that are actually sent to the client.
	However, there is no guarantee in this case that the frame sent to the client
	will be the most recently rendered frame, so applications that perform
	front buffer rendering and call ''glFlush()'' in response to an
	interactive operation may not display properly.  For such applications,
	setting the ''VGL_SPOILLAST'' environment variable to ''0'' prior to
	launching the application with ''vglrun'' will cause the "spoil first"
	algorithm to be used for all frame triggers, including ''glFlush()''.  This
	should fix the display problem, at the expense of increased load on the
	graphics card (because VirtualGL is now reading back the rendered 3D image
	every time ''glFlush()'' is called.)  See
	[[#Application_Recipes][Application Recipes]] for a list of applications that
	are known to require this.

| Environment Variable | ''VGL_SSL = ''__''0 \| 1''__ |
| ''vglrun'' argument | ''-s'' / ''+s'' |
| Summary | Disable/enable SSL encryption of the image transport |
| Image Transports | VGL, Custom (if supported) |
| Default Value | Disabled |
#OPT: hiCol=first

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

	!!! This option has no effect unless both the VirtualGL server and client
	were built with OpenSSL support.

{anchor: VGL_STEREO}
| Environment Variable | ''VGL_STEREO = ''__''left \| right \| quad \| rc \| gm \| by \| i \| tb \| ss''__ |
| ''vglrun'' argument | ''-st ''__''left \| right \| quad \| rc \| gm \| by \| i \| tb \| ss''__ |
| Summary | Specify the delivery method for stereo images |
| Image Transports | All |
| Default Value | quad |
#OPT: hiCol=first

	Description :: {:}
	__left__ = When an application renders a stereo frame, send only the left
	eye buffer
	{nl}{nl}
	__right__ = When an application renders a stereo frame, send only the right
	eye buffer
	{nl}{nl}
	__quad__ = Attempt to use quad-buffered stereo, which will result in a pair
	of images being sent to the VirtualGL Client for every frame.  If using the
	VGL Transport and quad-buffered stereo is not available on the client, or if
	using the X11 Transport, then fall back to using anaglyphic stereo.
	Using quad-buffered stereo requires the VGL Transport (or a transport plugin
	that can handle stereo image pairs.)  Using quad-buffered stereo with the VGL
	Transport also requires that the 2D X server support OpenGL and be connected
	to a 3D accelerator that supports stereo rendering.  Quad-buffered stereo
	is not supported when using the VGL Transport with YUV encoding.
	{nl}{nl}
	__rc__ = Use Red/Cyan (anaglyphic) stereo, even if quad-buffered is
	available
	{nl}{nl}
	__gm__ = Use Green/Magenta (anaglyphic) stereo, even if quad-buffered is
	available
	{nl}{nl}
	__by__ = Use Blue/Yellow (anaglyphic) stereo, even if quad-buffered is
	available
	{nl}{nl}
	__i__ = Use Interleaved (passive) stereo, even if quad-buffered is
	available
	{nl}{nl}
	__tb__ = Use Top/Bottom (passive) stereo, even if quad-buffered is
	available
	{nl}{nl}
	__ss__ = Use Side-by-Side (passive) stereo, even if quad-buffered is
	available
	{nl}{nl}
	See {ref prefix="Chapter ": Advanced_OpenGL} for more details.

{anchor: VGL_SUBSAMP}
| Environment Variable | ''VGL_SUBSAMP = ''__''gray \| 1x \| 2x \| 4x \| 8x \| 16x''__ |
| ''vglrun'' argument | ''-samp ''__''gray \| 1x \| 2x \| 4x \| 8x \| 16x''__ |
| Summary | Specify the level of chrominance subsampling in the \
	JPEG image compressor |
| Image Transports | VGL (JPEG), Custom (if supported) |
| Default Value | 1x |
#OPT: hiCol=first

	Description :: When an image is encoded using JPEG, each pixel in the image
	is first converted from RGB (Red/Green/Blue) to YUV.  An RGB pixel has three
	values that specify the amounts of red, green, and blue that make up the
	pixel's color.  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".)
	{nl}{nl}
	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.  This technique,
	called "chrominance subsampling", significantly reduces the size of the
	compressed image.
	{nl}{nl}
	__1x__ = no chrominance subsampling
	{nl}{nl}
	__2x__ = discard the chrominance components for every other pixel along the
	image's X direction (this is also known as "4:2:2" or "2:1" subsampling.) All
	else being equal, 2x subsampling generally reduces the image size by about
	20-25% when compared to no subsampling.{nl}
	{nl}
	__4x__ = discard the chrominance components for every other pixel along both
	the X and Y directions of the image (this is also known as "4:2:0" or "2:2"
	subsampling.)   All else being equal, 4x subsampling generally reduces the
	image size by about 35-40% when compared to no subsampling.
	{nl}{nl}
	__8x__ = discard the chrominance components for 3 out of every 4 pixels along
	the image's X direction and half the pixels along the image's Y direction
	(this is also known as "4:1:0" or "4:2" subsampling.)  __This option is
	available only when using an image transport plugin that supports it.__
	{nl}{nl}
	__16x__ = discard the chrominance components for 3 out of every 4 pixels
	along both the X and Y directions of the image (this is also known as "4:4"
	subsampling.)  __This option is available only when using an image transport
	plugin that supports it.__
	{nl}{nl}
	__gray__ = discard all chrominance components.  This is useful when running
	applications (such as medical visualization applications) that are already
	generating grayscale images.
	{nl}{nl}
	Subsampling artifacts are less noticeable with volume data, since it usually
	only contains 256 colors to begin with, but narrow, aliased lines and other
	sharp features on a black background will tend to produce very noticeable
	artifacts when subsampling is enabled.
	{nl}{nl}
	The axis indicator from a popular visualization app displayed with 1x,
	2x, and 4x chrominance subsampling (respectively):{nl}
	{img: 444.gif}{img: 422.gif}{img: 411.gif}
	{nl}
	!!! If using an image transport plugin, then this setting need not
	necessarily correspond to JPEG chrominance subsampling.  How the plugin
	responds to the ''VGL_SUBSAMP'' option is implementation-specific.

{anchor: VGL_SYNC}
| Environment Variable | ''VGL_SYNC = ''__''0 \| 1''__ |
| ''vglrun'' argument | ''-sync'' / ''+sync'' |
| Summary | Disable/enable strict 2D/3D synchronization |
| Image Transports | VGL, X11, XV, Custom (if supported) |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: Normally, VirtualGL's operation is asynchronous from the point
	of view of the application.  The application swaps the buffers or calls
	''glFinish()'' or ''glFlush()'' or ''glXWaitGL()'', and VirtualGL reads	back
	the framebuffer and sends the pixels to the client's display ... eventually.
	This will work fine for the vast majority of applications, but it does not
	strictly conform to the GLX spec.  Technically speaking, when an application
	calls ''glXWaitGL()'' or ''glFinish()'', it is well within its rights to
	expect the 3D image to be immediately available in the X window.
	Fortunately, very few applications actually do expect this, but on rare
	occasions, an application may try to use ''XGetImage()'' or other X11
	functions to obtain a bitmap of the pixels that were rendered by OpenGL.
	Enabling ''VGL_SYNC'' is a somewhat extreme measure that may be needed to
	make such applications work properly.  It was developed initially as a way to
	pass the GLX conformance suite (''conformx'', specifically), but at least one
	commercial application is known to require it as well (see
	[[#Application_Recipes][Application Recipes]].){nl}\
	{nl}\
	When ''VGL_SYNC'' is enabled, every call to ''glFinish()'', ''glXWaitGL()'',
	and ''glXSwapBuffers()'' will cause the contents of the Pbuffer
	to be read back and __synchronously__ drawn into the application's window
	__using the X11 Transport and no frame spoiling__.  The call to
	''glFinish()'', ''glXWaitGL()'', or ''glXSwapBuffers()'' will not return
	until VirtualGL has verified that the pixels have been delivered into the
	application's window.  As such, this mode can have potentially dire effects
	on performance when used with a remote 2D X server.  It is strongly
	recommended that ''VGL_SYNC'' be used only in conjunction with an X proxy
	running on the same server as VirtualGL.

	!!! If an image transport plugin is being used, then VirtualGL does not
	automatically enable the X11 Transport or disable frame spoiling when
	''VGL_SYNC'' is set.  This allows the plugin to handle synchronous image
	delivery as it sees fit (or to simply ignore this option.)

{anchor: VGL_TILESIZE}
| Environment Variable | ''VGL_TILESIZE = ''__''{t}''__ |
| Summary | __''{t}''__ = the image tile size (__''{t}''__ x __''{t}''__ pixels) \
	to use for multi-threaded compression and interframe comparison \
	(8 \<\= __''{t}''__ \<\= 1024) |
| Image Transports | VGL (JPEG, RGB), Custom (if supported) |
| Default Value | 256 |
#OPT: hiCol=first

	Description :: Normally, the VGL Transport will divide an OpenGL window into
	equal-sized square tiles, compare each tile vs. the same tile in the previous
	frame, then compress and send only the tiles that have changed (assuming
	[[#VGL_INTERFRAME][interframe comparison]] is enabled.)  The VGL Transport
	will also divide up the task of compressing these tiles among the available
	CPUs in a round robin fashion, if multi-threaded compression is enabled
	(see [[#VGL_NPROCS][VGL_NPROCS]].)
	{nl}{nl}
	There are several tradeoffs that must be considered when choosing a tile
	size:
	{nl}{nl}
	__Parallel scalability:__
	{list:
		{item: Smaller tiles can more easily be divided up among multiple CPUs.
			If the tile size if too large, then there may not be enough tiles to
			go around.}}
	{nl}
	__Compression efficiency:__
	{list:
		{item: There is a certain amount of fixed CPU overhead required when
			compressing images, so compressing larger tiles makes more efficient use
			of the CPUs and increases the aggregate throughput of the compressor.}}
	{nl}
	__Inter-frame optimization:__
	{list:
		{item: When using smaller tiles, there is more of a chance that a given
			tile will remain unchanged from frame to frame and thus not need to be
			re-transmitted to the client.}}
	{nl}
	__Network efficiency:__
	{list:
		{item: Each tile has a certain amount of fixed overhead required to
			represent it on the network.  Thus, using smaller tiles will increase the
			total number of tiles per frame, which will increase the total network
			usage.}}
	{nl}
	256x256 was chosen as the default because, in experiments, it provided
	the best balance between scalability and efficiency on the platforms that
	VirtualGL supports.

| Environment Variable | ''VGL_TRACE = ''__''0 \| 1''__ |
| ''vglrun'' argument | ''-tr'' / ''+tr'' |
| Summary | Disable/enable tracing |
| Image Transports | All |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: When tracing is enabled, VirtualGL will log all calls to the
	GLX and X11 functions it is intercepting, as well as the arguments, return
	values, and execution times for those functions.  This is useful when
	diagnosing interaction problems between VirtualGL and a particular OpenGL
	application.

| Environment Variable | ''VGL_TRANSPORT = ''__''{t}''__ |
| ''vglrun'' argument | ''-trans ''__''{t}''__ |
| Summary | Use an image transport plugin |
| Default Value | None |
#OPT: hiCol=first

	Description :: If this option is specified, then VirtualGL will attempt to
	load an image transport plugin contained in a dynamic library named
	''libtransvgl_''__''{t}''__''.so'' located in the dynamic linker path.

| Environment Variable | ''VGL_TRAPX11 = ''__''0 \| 1''__ |
| Summary | Disable/enable VirtualGL's X11 error handler |
| Image Transports | All |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If an application does not install its own X11 error handler,
	then the default X11 error handler is used.  The default X11 error handler
	will cause the application to exit if an X11 error occurs.  Enabling the
	''VGL_TRAPX11'' option will cause VirtualGL to install its own X11 error
	handler, which prints a warning message but allows the application to
	continue running.

| Environment Variable | ''VGL_VERBOSE = ''__''0 \| 1''__ |
| ''vglrun'' argument | ''-v'' / ''+v'' |
| Summary | Disable/enable verbose VirtualGL messages |
| Image Transports | All |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: When verbose mode is enabled, VirtualGL will reveal some of
	the decisions it makes behind the scenes, such as which code path it is using
	to compress images, which type of X11 drawing it is using, etc.  This can be
	helpful when diagnosing performance problems.

| Environment Variable | ''VGL_X11LIB = ''__''{l}''__ |
| Summary | __''{l}''__ = the location of an alternate X11 library |
| Image Transports | All |
#OPT: hiCol=first

	Description :: Normally, VirtualGL tries to call any "real" X11 functions it
	needs from the X11 library against which it is linked (usually
	''/usr/lib/libX11.so.6'', ''/usr/lib/64/libX11.so.6'',
	''/usr/X11R6/lib/libX11.so.6'', or ''/usr/X11R6/lib64/libX11.so.6'').
	Failing this, VirtualGL will then try to call these functions from the first
	compatible library named ''libX11.so.6'' that is found in the dynamic loader
	path.  You can use the ''VGL_X11LIB'' environment	variable to override this
	behavior and specify a dynamic library from which VirtualGL will call the
	"real" X11 functions.
	{nl}{nl}
	You shouldn't need to muck with this unless something doesn't work.  However,
	it is potentially useful if one wishes to insert another X11 interposer
	between VirtualGL and the system's X11 library.

| Environment Variable | ''VGL_XVENDOR = ''__''{v}''__ |
| Summary | __''{v}''__ = a fake X11 vendor string to return when the \
	application calls ''XServerVendor()'' or ''ServerVendor()'' |
| Image Transports | All |
#OPT: hiCol=first

	Description :: Some applications expect the X11 vendor string to contain a
	particular value, which the application (sometimes erroneously) uses to
	figure out whether it is being displayed to a local or a remote X server.
	This setting allows you to fool such applications into thinking that they
	are being	displayed to a "local" X server rather than a remote one.

** Client Settings

These settings control the VirtualGL Client, which is used only with the VGL
Transport.  ''vglclient'' is normally launched automatically from
''vglconnect'' and should not require any further configuration except in
exotic circumstances.  These settings are meant only for advanced users or
those wishing to build additional infrastructure around VirtualGL.

| Environment Variable | ''VGLCLIENT_DRAWMODE = ''__''ogl \| x11''__ |
| ''vglclient'' argument | ''-gl'' / ''-x'' |
| Summary | Specify the method used to draw pixels into the application window |
| Default Value | ''x11'' |
#OPT: hiCol=first

	Description :: If the client machine has a 3D accelerator, then it may be
	faster in some rare instances to draw pixels using OpenGL rather than using
	2D (X11) commands.

| Environment Variable | ''VGLCLIENT_LISTEN = ''__''sslonly \| nossl''__ |
| ''vglclient'' argument | ''-sslonly'' / ''-nossl'' |
| Summary | Accept only unencrypted or only SSL connections from the \
	VirtualGL server |
| Default Value | Accept both SSL and unencrypted connections |
#OPT: hiCol=first

	!!! This option is available only if the VirtualGL client was built
	with OpenSSL support.

| Environment Variable | ''VGLCLIENT_PORT = ''__''{p}''__ |
| ''vglclient'' argument | ''-port ''__''{p}''__ |
| Summary | __''{p}''__ = TCP port on which to listen for unencrypted \
	connections from the VirtualGL server |
| Default Value | Automatically select a free port |
#OPT: hiCol=first

	Description :: The default behavior for ''vglclient'' is to first try
	listening for unencrypted connections on port 4242, to maintain backward
	compatibility with VirtualGL v2.0.x.  If port 4242 is not available, then
	''vglclient'' will try to find a free port in the range of 4200-4299.  If
	none of those ports is available, then ''vglclient'' will request a free port
	from the operating system.
	{nl}{nl}
	Setting this option circumvents the automatic behavior described above and
	causes ''vglclient'' to listen only on the specified TCP port.

| Environment Variable | ''VGL_PROFILE = ''__''0 \| 1''__ |
| Summary | Disable/enable profiling output |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If profiling output is enabled, then VirtualGL will
	continuously benchmark itself and periodically print out the throughput of
	various stages in its image pipelines.
	{nl}{nl}
	See {ref prefix="Chapter ": Perf_Measurement} for more details.

| Environment Variable | ''VGLCLIENT_SSLPORT = ''__''{p}''__ |
| ''vglclient'' argument | ''-sslport ''__''{p}''__ |
| Summary | __''{p}''__ = TCP port on which to listen for SSL \
	connections from the VirtualGL server |
| Default Value | Automatically select a free port |
#OPT: hiCol=first

	Description :: The default behavior for ''vglclient'' is to first try
	listening for SSL connections on port 4243, to maintain backward
	compatibility with VirtualGL v2.0.x.  If port 4243 is not available, then
	''vglclient'' will try to find a free port in the range of 4200-4299.  If
	none of those ports is available, then ''vglclient'' will request a free port
	from the operating system.
	{nl}{nl}
	Setting this option circumvents the automatic behavior described above and
	causes ''vglclient'' to listen only on the specified TCP port.

	!!! This option is available only if the VirtualGL client was built
	with OpenSSL support.

| Environment Variable | ''VGL_VERBOSE = ''__''0 \| 1''__ |
| Summary | Disable/enable verbose VirtualGL messages |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: When verbose mode is enabled, VirtualGL will reveal some of
	the decisions it makes behind the scenes, such as which code path it is using
	to decompress images, which type of X11 drawing it is using, etc.  This can
	be helpful when diagnosing performance problems.
