* Advanced Configuration

** Server Settings

| Environment Variable | ''TVNC_ALRALL = ''__''0 \| 1''__ |
| Summary | Disable/Enable automatic lossless refresh for regions that were \
drawn using X11 functions other than ''X[Shm]PutImage()'' |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": ALR}

| Environment Variable | ''TVNC_ALRCOPYRECT = ''__''0 \| 1''__ |
| Summary | Disable/Enable automatic lossless refresh for regions that were \
drawn using CopyRect |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": ALR}

| Environment Variable | ''TVNC_COMBINERECT = ''__''{c}''__ |
| Summary | Combine framebuffer updates with more than __''{c}''__ rectangles \
into a single rectangle spanning the bounding box of all of the constituent \
rectangles |
| Default Value | 100 |
#OPT: hiCol=first

	Description :: Applications can sometimes draw many thousands of points or
	tiny lines using individual X11 calls, and this can cause the VNC server to
	send many	thousands of tiny rectangles to the VNC viewer.  The overhead
	associated with this can bog down the viewer, and in extreme cases, the
	number of rectangles may even exceed the maximum number that is allowed in a
	single framebuffer update (65534.)  Thus, if a framebuffer update contains
	more than __''{c}''__ rectangles, TurboVNC will coalesce it into a single
	rectangle that covers all of the rectangles in the update.  For applications
	that generate many tiny rectangles, increasing ''TVNC_COMBINERECT'' may
	significantly increase the number of pixels sent to the viewer, which will
	increase network usage.  However, for those same applications, lowering
	''TVNC_COMBINERECT'' will increase the number of rectangles sent to the
	viewer, which will increase the CPU usage of both the server and the viewer.

| Environment Variable | ''TVNC_ICEBLOCKSIZE = ''__''{s}''__ |
| Summary | Set the block size for the interframe comparison engine (ICE) to \
__''{s}''__ x __''{s}''__ pixels.  Setting __''{s}''__ to 0 causes the ICE to \
compare full rectangles, as TurboVNC 1.2.x did. |
| Default Value | 256 |
#OPT: hiCol=first

	Description :: If interframe comparison is enabled (see
	{ref prefix="Section ": InterframeComparison}), then TurboVNC will compare
	each rectangle of each framebuffer update on a block-by-block basis and send
	only the blocks that have changed.  This prevents large rectangles from being
	re-transmitted if only a few pixels in the rectangle have changed.  Using
	smaller block sizes can decrease network usage if only a few pixels are
	changing between updates, but using smaller block sizes can also interfere
	with the Tight encoder's ability to efficiently split rectangles into
	subrectangles, thus increasing server CPU usage (and sometimes increasing
	network usage as well, which runs counter to the purpose of interframe
	comparison.)  Setting the block size to 0 causes the ICE to compare full
	framebuffer update rectangles, as TurboVNC 1.2.x did.
	{nl}{nl}
	The default block size of 256x256 was chosen based on extensive low-level
	experiments using the same set of RFB session captures that were used when
	designing the TurboVNC encoder.  For most of those datasets, 256x256 blocks
	produced the lowest network and CPU usage, but actual mileage may vary.
	There were rare cases in which using 64x64 blocks or full-rectangle
	comparison produced better network and CPU usage.

| Environment Variable | ''TVNC_ICEDEBUG = ''__''0 \| 1''__ |
| Summary | Disable/Enable the ICE debugger |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If interframe comparison is enabled (see
	{ref prefix="Section ": InterframeComparison}), then setting this environment
	variable to 1 will cause the interframe comparison engine (ICE) to change the
	color of duplicate screen regions without culling them from the update stream.  This
	allows you to easily see which applications are generating duplicate updates.

| Environment Variable | ''TVNC_MT = ''__''0 \| 1''__ |
| Summary | Disable/Enable multithreaded image encoding |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": Multithreading}

| Environment Variable | ''VGL_NTHREADS = ''__''{n}''__ |
| Summary | Use __''{n}''__ threads to perform image encoding |
| Default Value | __''{n}''__ = the number of CPU cores in the system |
#OPT: hiCol=first

	Description :: See {ref prefix="Section ": Multithreading}

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

	Description :: If profiling output is enabled, then the TurboVNC Server will
	continuously benchmark itself and periodically print the throughput of
	various stages in its image pipeline to the Xvnc log file.

** Viewer Settings

| Environment Variable | ''TVNC_PROFILE = ''__''0 \| 1''__ |
| Summary | Disable/enable profiling output |
| Platforms | Un*x, Mac (Java) |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: If profiling output is enabled, then the TurboVNC Viewer will
	continuously benchmark itself and periodically print the throughput of
	various stages in its image pipeline to the console.

{anchor: VNC_VIA_CMD}
| Environment Variable | ''VNC_VIA_CMD'', ''VNC_TUNNEL_CMD'' |
| Summary | SSH command-line templates for use with the ''via'' and \
	''tunnel'' options (respectively) |
| Platforms | All |
| Default Value | See below |
#OPT: hiCol=first

When the ''-via'' option (or the ''via'' parameter in the Java viewer, along
with the ''extssh'' parameter) is used, the TurboVNC Viewer reads the
''VNC_VIA_CMD'' environment variable (the Java viewer can also read this
information from the ''turbovnc.via'' system property), expands patterns
beginning with the "%" character, and uses the resulting command line to
establish the secure tunnel to the VNC gateway.  If ''VNC_VIA_CMD'' is not set,
then this command line defaults to ''/usr/bin/ssh -f -L %L:%H:%R %G sleep 20''
(or ''c:\\cygwin\\bin\\ssh.exe -f -L %L:%H:%R %G sleep 20'' if using the
Windows native viewer.)

When the ''-tunnel'' option (or the ''tunnel'' parameter in the Java viewer,
along with the ''extssh'' parameter) is used, the TurboVNC Viewer reads the
''VNC_TUNNEL_CMD'' environment variable (the Java viewer can also read this
information from the ''turbovnc.tunnel'' system property), expands patterns
beginning with the "%" character, and uses the resulting command line to
establish the secure tunnel to the VNC server.  If ''VNC_TUNNEL_CMD'' is not
set, then this command line defaults to
''/usr/bin/ssh -f -L %L:localhost:%R %H sleep 20'' (or
''c:\\cygwin\\bin\\ssh.exe -f -L %L:localhost:%R %H sleep 20'' if using the
Windows native viewer.)

The following patterns are recognized in the ''VNC_VIA_CMD'' and
''VNC_TUNNEL_CMD'' environment variables (note that ''%H'', ''%L'' and ''%R''
must be present in the command template, and ''%G'' must also be present if
using the ''-via'' option):

| ''%%'' | A literal "%" |
| ''%G'' | gateway machine name |
| ''%H'' | remote VNC machine name (if using the ''-via'' option, then this \
	is specified from the point of view of the gateway) |
| ''%L'' | local TCP port number |
| ''%R'' | remote TCP port number |

** Java Viewer Settings

Java system properties are normally specified as command-line arguments to the
Java executable.  For example:

	#Verb: <<---
	java -Dmy.system.property={value} -jar MyClass.jar
	---

However, since TurboVNC hides the Java command line inside of its startup
scripts (or inside of an application bundle on OS X), the easiest way to
set these properties is by using the ''JAVA_TOOL_OPTIONS'' environment
variable, which allows you to specify Java command-line arguments even if
you don't have access to the command line.  For instance, on Linux you could
execute:

	#Verb: <<---
	JAVA_TOOL_OPTIONS=-Dturbovnc.turbojpeg=0 /opt/TurboVNC/bin/vncviewer
	---

to start the TurboVNC Viewer without JPEG acceleration.

Refer to the default ''index.vnc'' and ''TurboVNC.jnlp'' files installed with
the TurboVNC Server for an example of how to specify Java command-line
arguments in an applet or Java Web Start environment.

{anchor: turbovnc.forcealpha}
| Java System Property | ''turbovnc.forcealpha = ''__''0 \| 1''__ |
| Summary | Disable/enable back buffer alpha channel |
| Default Value | Enabled if using OpenGL Java 2D blitting, disabled otherwise |
#OPT: hiCol=first

	Description :: If this property is enabled, then the Java TurboVNC Viewer
	will use a TYPE_INT_ARGB_PRE (BGRA with pre-computed alpha channel)
	BufferedImage as its back buffer instead of a TYPE_INT_RGB (BGRX)
	BufferedImage.  When using OpenGL blitting in Java 2D (normally accomplished
	by passing an argument of ''-Dsun.java2d.opengl=true'' to ''java''), it is
	generally faster to draw an alpha-enabled BufferedImage to the screen,
	because otherwise glDrawPixels() has to set all of the alpha values itself
	(which can cause it to revert to an unaccelerated code path in some cases.)

	!!! NOTE: this property is enabled by default when using Java 7 or later on
	Mac platforms, because OpenGL Java 2D blitting is the only option available.

| Java System Property | ''turbovnc.lionfs = ''__''0 \| 1''__ |
| Summary | Disable/enable the use of the OS X full-screen application feature |
| Default Value | Enabled if running on OS X 10.7 or later |
#OPT: hiCol=first

	Description :: When running in full-screen mode, the Java TurboVNC Viewer
	will normally try to take advantage of the full-screen application feature
	provided by OS X 10.7 and later, if available.  Disabling this property will
	force the viewer to use its own built-in cross-platform "pseudo-full-screen"
	feature instead.  This is useful mainly for testing.

| Java System Property | ''turbovnc.primary = ''__''0 \| 1''__ |
| Summary | Disable/enable the use of the X11 PRIMARY clipboard selection |
| Default Value | Enabled |
#OPT: hiCol=first

	Description :: X11 has two ways of copying/pasting text.  When text is
	selected in most X11 applications, it is copied to the PRIMARY selection,
	and it can be pasted by pressing the middle mouse button.  When text is
	explicitly copied using a "Copy" menu option or a hotkey (such as CTRL-C), it
	is copied to the CLIPBOARD selection, and it can only be pasted by explicitly
	selecting a "Paste" menu option or pressing a hotkey (such as CTRL-V.)
	Normally, on X11 platforms, the TurboVNC Viewer transfers the PRIMARY
	selection from client to server and, when receiving a clipboard update from
	the server, it sets both the PRIMARY and CLIPBOARD selections with the
	server's clipboard contents.  Disabling this property will cause only the
	the CLIPBOARD selection to be transferred from client to server (in other
	words, the clipboard will not be transferred unless you explicitly copy
	something by using a menu option or hotkey), and clipboard changes from the
	server will only affect the client's CLIPBOARD selection (in other words, you
	will have to explicitly paste the server's clipboard contents by using a menu
	option or hotkey on the client.)

| Java System Property | ''turbovnc.swingdb = ''__''0 \| 1''__ |
| Summary | Disable/enable Swing double buffering |
| Default Value | Disabled |
#OPT: hiCol=first

	Description :: The Java TurboVNC Viewer has its own double buffering
	mechanism, so it normally disables the double buffering mechanism in Swing
	and Java 2D in order to increase performance.  This also allows the viewer to
	achieve optimal performance under X11 without requiring MIT-SHM pixmap
	support.  Although the viewer has been thoroughly tested, the
	''turbovnc.swingdb'' system property is provided as a fallback in case issues
	are discovered when running it under a specific version of Java.

| Java System Property | ''turbovnc.tunnel'' |
| Summary | SSH command-line template for use with the ''Tunnel'' and \
	''ExtSSH'' parameters |
#OPT: hiCol=first

	Description :: A more Java-friendly way of specifying the command line to use
	when establishing a secure tunnel with the ''Tunnel'' and ''ExtSSH''
	parameters.  See the ''VNC_TUNNEL_CMD'' environment variable above for more
	details.

| Java System Property | ''turbovnc.turbojpeg = ''__''0 \| 1''__ |
| Summary | Disable/enable JPEG acceleration |
| Default Value | Enabled if the libjpeg-turbo JNI library is available |
#OPT: hiCol=first

	Description :: Normally, the Java TurboVNC Viewer will try to load the
	libjpeg-turbo JNI library and use it to accelerate the decompression of
	JPEG subrectangles.  If this property is disabled, then the viewer will
	revert to using unaccelerated JPEG decompression.  This is useful mainly for
	testing and benchmarking purposes.

| Java System Property | ''turbovnc.via'' |
| Summary | SSH command-line template for use with the ''Via'' and \
	''ExtSSH'' parameters |
#OPT: hiCol=first

	Description :: A more Java-friendly way of specifying the command line to use
	when establishing a secure tunnel with the ''Via'' and ''ExtSSH''
	parameters.  See the ''VNC_VIA_CMD'' environment variable above for more
	details.
