-buttonmap string

String to remap mouse buttons. Format: IJK-LMN, this maps buttons I -> L, etc., e.g. -buttonmap 13-31

Button presses can also be mapped to keystrokes: replace a button digit on the right of the dash with :<sym>: or :<sym1>+<sym2>: etc. for multiple keys. For example, if the viewing machine has a mouse-wheel (buttons 4 5) but the x11vnc side does not, these will do scrolls:

-buttonmap 12345-123:Prior::Next:

-buttonmap 12345-123:Up+Up+Up::Down+Down+Down:

See <X11/keysymdef.h> header file for a list of Keysyms, or use the xev(1) program. Note: mapping of button clicks to Keysyms may not work if -modtweak or -xkb is needed for the Keysym.

If you include a modifier like "Shift_L" the modifier's up/down state is toggled, e.g. to send "The" use :Shift_L+t+Shift_L+h+e: (the 1st one is shift down and the 2nd one is shift up). (note: the initial state of the modifier is ignored and not reset) To include button events use "Button1", ... etc.

-nodragging

Do not update the display during mouse dragging events (mouse button held down). Greatly improves response on slow setups, but you lose all visual feedback for drags, text selection, and some menu traversals. It overrides any -pointer_mode setting.

-ncache n

Client-side caching scheme. Framebuffer memory n (an integer) times that of the full display is allocated below the actual framebuffer to cache screen contents for rapid retrieval. So a W x H frambuffer is expanded to a W x (n+1)*H one. Use 0 to disable. Default: XXX.

The n is actually optional, the default is 10.

For this and the other -ncache* options below you can abbreviate "-ncache" with "-nc". Also, "-nonc" is the same as "-ncache 0"

This is an experimental option, currently implemented in an awkward way in that in the VNC Viewer you can see the cache contents if you scroll down, etc. So you will have to set things up so you can't see that region. If this method is successful, the changes required for clients to do this less awkwardly will be investigated.

Note that this mode consumes a huge amount of memory, both on the x11vnc server side and on the VNC Viewer side. If n=2 then the amount of RAM used is roughly tripled for both x11vnc and the VNC Viewer. As a rule of thumb, note that 1280x1024 at depth 24 is about 5MB of pixel data.

For reasonable response when cycling through 4 to 6 large (e.g. web browser) windows a value n of 6 to 12 is recommended. (that's right: ~10X more memory...)

Because of the way window backingstore and saveunders are implemented, n must be even. It will be incremented by 1 if it is not.

This mode also works for native MacOS X, but may not be as effective as the X version. This is due to a number of things, one is the drop-shadow compositing that leaves extra areas that need to be repaired (see -ncache_pad). Another is the window iconification animations need to be avoided (see -macicontime). It appears the that the 'Scale' animation mode gives better results than the 'Genie' one. Also, window event detection not as accurate as the X version.

-ncache_cr

In -ncache mode, try to do copyrect opaque window moves/drags instead of wireframes (this can induce painting errors). The wireframe will still be used when moving a window whose save-unders has not yet been set or has been invalidated.

Some VNC Viewers provide better response than others with this option. On Unix, realvnc viewer gives smoother drags than tightvnc viewer. Response may also be choppy if the server side machine is too slow.

Sometimes on very slow modem connections, this actually gives an improvement because no pixel data at all (not even the box animation) is sent during the drag.

-ncache_no_moveraise

In -ncache mode, do not assume that moving a window will cause the window manager to raise it to the top of the stack. The default is to assume it does, and so at the beginning of any wireframe, etc, window moves the window will be pushed to top in the VNC viewer.

-ncache_no_dtchange

In -ncache mode, do not try to guess when the desktop (viewport) changes to another one (i.e. another workarea). The default is to try to guess and when detected try to make the transistion more smoothly.

-ncache_no_rootpixmap

In -ncache mode, do not try to snapshot the desktop background to use in guessing or reconstructing window save-unders.

-ncache_keep_anims

In -ncache mode, do not try to disable window manager animations and other effects (that usually degrade ncache performance or cause painting errors). The default is to try to disable them on KDE (but not GNOME) when VNC clients are connected.

For other window managers or desktops that provide animations, effects, compositing, translucency, etc. that interfere with the -ncache method you will have to disable them manually.

-ncache_old_wm

In -ncache mode, enable some heuristics for old style window managers such as fvwm and twm.

-ncache_pad n

In -ncache mode, pad each window with n pixels for the caching rectangles. This can be used to try to improve the situation with dropshadows or other compositing (e.g. MacOS X window manager), although it could make things worse. The default is 0 on Unix and 24 on MacOS X.

-wireframe [str], -nowireframe

Try to detect window moves or resizes when a mouse button is held down and show a wireframe instead of the full opaque window. This is based completely on heuristics and may not always work: it depends on your window manager and even how you move things around. See -pointer_mode below for discussion of the "bogging down" problem this tries to avoid. Default: -wireframe

Shorter aliases: -wf [str] and -nowf

The value "str" is optional and, of course, is packed with many tunable parameters for this scheme:

Format: shade,linewidth,percent,T+B+L+R,mod,t1+t2+t3+t4 Default: 0xff,2,0,32+8+8+8,all,0.15+0.30+5.0+0.125

If you leave nothing between commas: ",," the default value is used. If you don't specify enough commas, the trailing parameters are set to their defaults.

"shade" indicate the "color" for the wireframe, usually a greyscale: 0-255, however for 16 and 32bpp you can specify an rgb.txt X color (e.g. "dodgerblue") or a value > 255 is treated as RGB (e.g. red is 0xff0000). "linewidth" sets the width of the wireframe in pixels. "percent" indicates to not apply the wireframe scheme to windows with area less than this percent of the full screen.

"T+B+L+R" indicates four integers for how close in pixels the pointer has to be from the Top, Bottom, Left, or Right edges of the window to consider wireframing. This is a speedup to quickly exclude a window from being wireframed: set them all to zero to not try the speedup (scrolling and selecting text will likely be slower).

"mod" specifies if a button down event in the interior of the window with a modifier key (Alt, Shift, etc.) down should indicate a wireframe opportunity. It can be "0" or "none" to skip it, "1" or "all" to apply it to any modifier, or "Shift", "Alt", "Control", "Meta", "Super", or "Hyper" to only apply for that type of modifier key.

"t1+t2+t3+t4" specify four floating point times in seconds: t1 is how long to wait for the pointer to move, t2 is how long to wait for the window to start moving or being resized (for some window managers this can be rather long), t3 is how long to keep a wireframe moving before repainting the window. t4 is the minimum time between sending wireframe "animations". If a slow link is detected, these values may be automatically changed to something better for a slow link.

-nowireframelocal

By default, mouse motion and button presses of a user sitting at the LOCAL display are monitored for wireframing opportunities (so that the changes will be sent efficiently to the VNC clients). Use this option to disable this behavior.

-wirecopyrect mode, -nowirecopyrect

Since the -wireframe mechanism evidently tracks moving windows accurately, a speedup can be obtained by telling the VNC viewers to locally copy the translated window region. This is the VNC CopyRect encoding: the framebuffer update doesn't need to send the actual new image data.

Shorter aliases: -wcr [mode] and -nowcr

"mode" can be "never" (same as -nowirecopyrect) to never try the copyrect, "top" means only do it if the window was not covered by any other windows, and "always" means to translate the orginally unobscured region (this may look odd as the remaining pieces come in, but helps on a slow link). Default: "always"

Note: there can be painting errors or slow response when using -scale so you may want to disable CopyRect in this case "-wirecopyrect never" on the command line or by remote-control. Or you can also use the "-scale xxx:nocr" scale option.

-debug_wireframe

Turn on debugging info printout for the wireframe heuristics. "-dwf" is an alias. Specify multiple times for more output.

-scrollcopyrect mode, -noscrollcopyrect

Like -wirecopyrect, but use heuristics to try to guess if a window has scrolled its contents (either vertically or horizontally). This requires the RECORD X extension to "snoop" on X applications (currently for certain XCopyArea and XConfigureWindow X protocol requests). Examples: Hitting <Return> in a terminal window when the cursor was at the bottom, the text scrolls up one line. Hitting <Down> arrow in a web browser window, the web page scrolls up a small amount. Or scrolling with a scrollbar or mouse wheel.

Shorter aliases: -scr [mode] and -noscr

This scheme will not always detect scrolls, but when it does there is a nice speedup from using the VNC CopyRect encoding (see -wirecopyrect). The speedup is both in reduced network traffic and reduced X framebuffer polling/copying. On the other hand, it may induce undesired transients (e.g. a terminal cursor being scrolled up when it should not be) or other painting errors (window tearing, bunching-up, etc). These are automatically repaired in a short period of time. If this is unacceptable disable the feature with -noscrollcopyrect.

Screen clearing kludges: for testing at least, there are some "magic key sequences" (must be done in less than 1 second) to aid repairing painting errors that may be seen when using this mode:

3 Alt_L's in a row: resend whole screen, 4 Alt_L's in a row: reread and resend whole screen, 3 Super_L's in a row: mark whole screen for polling, 4 Super_L's in a row: reset RECORD context, 5 Super_L's in a row: try to push a black screen

note: Alt_L is the Left "Alt" key (a single key) Super_L is the Left "Super" key (Windows flag). Both of these are modifier keys, and so should not generate characters when pressed by themselves. Also, your VNC viewer may have its own refresh hot-key or button.

"mode" can be "never" (same as -noscrollcopyrect) to never try the copyrect, "keys" means to try it in response to keystrokes only, "mouse" means to try it in response to mouse events only, "always" means to do both. Default: "always"

Note: there can be painting errors or slow response when using -scale so you may want to disable CopyRect in this case "-scrollcopyrect never" on the command line or by remote-control. Or you can also use the "-scale xxx:nocr" scale option.

-scr_area n

Set the minimum area in pixels for a rectangle to be considered for the -scrollcopyrect detection scheme. This is to avoid wasting the effort on small rectangles that would be quickly updated the normal way. E.g. suppose an app updated the position of its skinny scrollbar first and then shifted the large panel it controlled. We want to be sure to skip the small scrollbar and get the large panel. Default: 60000

-scr_skip list

Skip scroll detection for applications matching the comma separated list of strings in list. Some applications implement their scrolling in strange ways where the XCopyArea, etc, also applies to invisible portions of the window: if we CopyRect those areas it looks awful during the scroll and there may be painting errors left after the scroll. Soffice.bin is the worst known offender.

Use "##" to denote the start of the application class (e.g. "##XTerm") and "++" to denote the start of the application instance name (e.g. "++xterm"). The string your list is matched against is of the form "^^WM_NAME##Class++Instance<same-for-any-subwindows>" The "xlsclients -la" command will provide this info.

If a pattern is prefixed with "KEY:" it only applies to Keystroke generated scrolls (e.g. Up arrow). If it is prefixed with "MOUSE:" it only applies to Mouse induced scrolls (e.g. dragging on a scrollbar). Default: ##Soffice.bin,##StarOffice

-scr_inc list

Opposite of -scr_skip: this list is consulted first and if there is a match the window will be monitored via RECORD for scrolls irrespective of -scr_skip. Use -scr_skip '*' to skip anything that does not match your -scr_inc. Use -scr_inc '*' to include everything.

-scr_keys list

For keystroke scroll detection, only apply the RECORD heuristics to the comma separated list of keysyms in list. You may find the RECORD overhead for every one of your keystrokes disrupts typing too much, but you don't want to turn it off completely with "-scr mouse" and -scr_parms does not work or is too confusing.

The listed keysyms can be numeric or the keysym names in the <X11/keysymdef.h> header file or from the xev(1) program. Example: "-scr_keys Up,Down,Return". One probably wants to have application specific lists (e.g. for terminals, etc) but that is too icky to think about for now...

If list begins with the "-" character the list is taken as an exclude list: all keysyms except those list will be considered. The special string "builtin" expands to an internal list of keysyms that are likely to cause scrolls. BTW, by default modifier keys, Shift_L, Control_R, etc, are skipped since they almost never induce scrolling by themselves.

-scr_term list

Yet another cosmetic kludge. Apply shell/terminal heuristics to applications matching comma separated list (same as for -scr_skip/-scr_inc). For example an annoying transient under scroll detection is if you hit Enter in a terminal shell with full text window, the solid text cursor block will be scrolled up. So for a short time there are two (or more) block cursors on the screen. There are similar scenarios, (e.g. an output line is duplicated).

These transients are induced by the approximation of scroll detection (e.g. it detects the scroll, but not the fact that the block cursor was cleared just before the scroll). In nearly all cases these transient errors are repaired when the true X framebuffer is consulted by the normal polling. But they are distracting, so what this option provides is extra "padding" near the bottom of the terminal window: a few extra lines near the bottom will not be scrolled, but rather updated from the actual X framebuffer. This usually reduces the annoying artifacts. Use "none" to disable. Default: "term"

-scr_keyrepeat lo-hi

If a key is held down (or otherwise repeats rapidly) and this induces a rapid sequence of scrolls (e.g. holding down an Arrow key) the "scrollcopyrect" detection and overhead may not be able to keep up. A time per single scroll estimate is performed and if that estimate predicts a sustainable scrollrate of keys per second between "lo" and "hi" then repeated keys will be DISCARDED to maintain the scrollrate. For example your key autorepeat may be 25 keys/sec, but for a large window or slow link only 8 scrolls per second can be sustained, then roughly 2 out of every 3 repeated keys will be discarded during this period. Default: "4-20"

-scr_parms string

Set various parameters for the scrollcopyrect mode. The format is similar to that for -wireframe and packed with lots of parameters:

Format: T+B+L+R,t1+t2+t3,s1+s2+s3+s4+s5 Default: 0+64+32+32,0.02+0.10+0.9,0.03+0.06+0.5+0.1+5.0

If you leave nothing between commas: ",," the default value is used. If you don't specify enough commas, the trailing parameters are set to their defaults.

"T+B+L+R" indicates four integers for how close in pixels the pointer has to be from the Top, Bottom, Left, or Right edges of the window to consider scrollcopyrect. If -wireframe overlaps it takes precedence. This is a speedup to quickly exclude a window from being watched for scrollcopyrect: set them all to zero to not try the speedup (things like selecting text will likely be slower).

"t1+t2+t3" specify three floating point times in seconds that apply to scrollcopyrect detection with *Keystroke* input: t1 is how long to wait after a key is pressed for the first scroll, t2 is how long to keep looking after a Keystroke scroll for more scrolls. t3 is how frequently to try to update surrounding scrollbars outside of the scrolling area (0.0 to disable)

"s1+s2+s3+s4+s5" specify five floating point times in seconds that apply to scrollcopyrect detection with *Mouse* input: s1 is how long to wait after a mouse button is pressed for the first scroll, s2 is how long to keep waiting for additional scrolls after the first Mouse scroll was detected. s3 is how frequently to try to update surrounding scrollbars outside of the scrolling area (0.0 to disable). s4 is how long to buffer pointer motion (to try to get fewer, bigger mouse scrolls). s5 is the maximum time to spend just updating the scroll window without updating the rest of the screen.

-fixscreen string

Periodically "repair" the screen based on settings in string. Hopefully you won't need this option, it is intended for cases when the -scrollcopyrect or -wirecopyrect features leave too many painting errors, but it can be used for any scenario. This option periodically performs costly operations and so interactive response may be reduced when it is on. You can use 3 Alt_L's (the Left "Alt" key) taps in a row (as described under -scrollcopyrect) instead to manually request a screen repaint when it is needed.

string is a comma separated list of one or more of the following: "V=t", "C=t", "X=t", and "8=t". In these "t" stands for a time in seconds (it is a floating point even though one should usually use values > 2 to avoid wasting resources). V sets how frequently the entire screen should be sent to viewers (it is like the 3 Alt_L's). C sets how long to wait after a CopyRect to repaint the full screen. X sets how frequently to reread the full X11 framebuffer from the X server and push it out to connected viewers. Use of X should be rare, please report a bug if you find you need it. 8= applies only for -8to24 mode: it sets how often the non-default visual regions of the screen (e.g. 8bpp windows) are refreshed. Examples: -fixscreen V=10 -fixscreen C=10

-debug_scroll

Turn on debugging info printout for the scroll heuristics. "-ds" is an alias. Specify it multiple times for more output.

-noxrecord

Disable any use of the RECORD extension. This is currently used by the -scrollcopyrect scheme and to monitor X server grabs.

-grab_buster, -nograb_buster

Some of the use of the RECORD extension can leave a tiny window for XGrabServer deadlock. This is only if the whole-server grabbing application expects mouse or keyboard input before releasing the grab. It is usually a window manager that does this. x11vnc takes care to avoid the the problem, but if caught x11vnc will freeze. Without -grab_buster, the only solution is to go the physical display and give it some input to satisfy the grabbing app. Or manually kill and restart the window manager if that is feasible. With -grab_buster, x11vnc will fork a helper thread and if x11vnc appears to be stuck in a grab after a period of time (20-30 sec) then it will inject some user input: button clicks, Escape, mouse motion, etc to try to break the grab. If you experience a lot of grab deadlock, please report a bug.

-debug_grabs

Turn on debugging info printout with respect to XGrabServer() deadlock for -scrollcopyrect__mode_.

-debug_sel

Turn on debugging info printout with respect to PRIMARY, CLIPBOARD, and CUTBUFFER0 selections.

-pointer_mode n

Various pointer motion update schemes. "-pm" is an alias. The problem is pointer motion can cause rapid changes on the screen: consider the rapid changes when you drag a large window around opaquely. Neither x11vnc's screen polling and vnc compression routines nor the bandwidth to the vncviewers can keep up these rapid screen changes: everything will bog down when dragging or scrolling. So a scheme has to be used to "eat" much of that pointer input before re-polling the screen and sending out framebuffer updates. The mode number n can be 0 to 4 and selects one of the schemes desribed below.

Note that the -wireframe and -scrollcopyrect__mode_s complement -pointer_mode by detecting (and improving) certain periods of "rapid screen change".

n=0: does the same as -nodragging. (all screen polling is suspended if a mouse button is pressed.)

n=1: was the original scheme used to about Jan 2004: it basically just skips -input_skip keyboard or pointer events before repolling the screen.

n=2 is an improved scheme: by watching the current rate of input events it tries to detect if it should try to "eat" additional pointer events before continuing.

n=3 is basically a dynamic -nodragging mode: it detects when the mouse motion has paused and then refreshes the display.

n=4 attempts to measures network rates and latency, the video card read rate, and how many tiles have been changed on the screen. From this, it aggressively tries to push screen "frames" when it decides it has enough resources to do so. NOT FINISHED.

The default n is 2. Note that modes 2, 3, 4 will skip -input_skip keyboard events (but it will not count pointer events). Also note that these modes are not available in -threads mode which has its own pointer event handling mechanism.

To try out the different pointer modes to see which one gives the best response for your usage, it is convenient to use the remote control function, for example "x11vnc -R pm:4" or the tcl/tk gui (Tuning -> pointer_mode -> n).

-input_skip n

For the pointer handling when non-threaded: try to read n user input events before scanning display. n < 0 means to act as though there is always user input. Default: 10

-allinput

Have x11vnc read and process all available client input before proceeding.

-speeds rd,bw,lat

x11vnc tries to estimate some speed parameters that are used to optimize scheduling (e.g. -pointer_mode 4, -wireframe, -scrollcopyrect) and other things. Use the -speeds option to set these manually. The triple rd,bw,lat corresponds to video h/w read rate in MB/sec, network bandwidth to clients in KB/sec, and network latency to clients in milliseconds, respectively. If a value is left blank, e.g. "-speeds ,100,15", then the internal scheme is used to estimate the empty value(s).

Typical PC video cards have read rates of 5-10 MB/sec. If the framebuffer is in main memory instead of video h/w (e.g. SunRay, shadowfb, dummy driver, Xvfb), the read rate may be much faster. "x11perf -getimage500" can be used to get a lower bound (remember to factor in the bytes per pixel). It is up to you to estimate the network bandwith and latency to clients. For the latency the ping(1) command can be used.

For convenience there are some aliases provided, e.g. "-speeds modem". The aliases are: "modem" for 6,4,200; "dsl" for 6,100,50; and "lan" for 6,5000,1

-wmdt string

For some features, e.g. -wireframe and -scrollcopyrect, x11vnc has to work around issues for certain window managers or desktops (currently kde and xfce). By default it tries to guess which one, but it can guess incorrectly. Use this option to indicate which wm/dt. string can be "gnome", "kde", "cde", "xfce", or "root" (classic X wm). Anything else is interpreted as "root".

-debug_pointer

Print debugging output for every pointer event.

-debug_keyboard

Print debugging output for every keyboard event.

Same as -dp and -dk, respectively. Use multiple times for more output.

-defer time

Time in ms to wait for updates before sending to client (deferUpdateTime) Default: 20

-wait time

Time in ms to pause between screen polls. Used to cut down on load. Default: 20

-wait_ui factor

Factor by which to cut the -wait time if there has been recent user input (pointer or keyboard). Improves response, but increases the load whenever you are moving the mouse or typing. Default: 2.00

-nowait_bog

Do not detect if the screen polling is "bogging down" and sleep more. Some activities with no user input can slow things down a lot: consider a large terminal window with a long build running in it continously streaming text output. By default x11vnc will try to detect this (3 screen polls in a row each longer than 0.25 sec with no user input), and sleep up to 1.5 secs to let things "catch up". Use this option to disable that detection.

-slow_fb time

Floating point time in seconds delay all screen polling. For special purpose usage where a low frame rate is acceptable and desirable, but you want the user input processed at the normal rate so you cannot use -wait.

-readtimeout n

Set libvncserver rfbMaxClientWait to n seconds. On slow links that take a long time to paint the first screen libvncserver may hit the timeout and drop the connection. Default: 20 seconds.

-nap, -nonap

Monitor activity and if it is low take longer naps between screen polls to really cut down load when idle. Default: take naps

-sb time

Time in seconds after NO activity (e.g. screen blank) to really throttle down the screen polls (i.e. sleep for about 1.5 secs). Use 0 to disable. Default: 60

-nofbpm, -fbpm

If the system supports the FBPM (Frame Buffer Power Management) extension (i.e. some Sun systems), then prevent the video h/w from going into a reduced power state when VNC clients are connected.

FBPM capable video h/w save energy when the workstation is idle by going into low power states (similar to DPMS for monitors). This interferes with x11vnc's polling of the framebuffer data.

"-nofbpm" means prevent FBPM low power states whenever VNC clients are connected, while "-fbpm" means to not monitor the FBPM state at all. See the xset(1) manpage for details. -nofbpm is basically the same as running "xset fbpm force on" periodically. Default: -fbpm

-nodpms, -dpms

If the system supports the DPMS (Display Power Management Signaling) extension, then prevent the monitor from going into a reduced power state when VNC clients are connected.

DPMS reduced power monitor states are a good thing and you normally want the power down to take place (usually x11vnc has no problem exporting the display in this state). You probably only want to use "-nodpms" to work around problems with Screen Savers kicking on in DPMS low power states. There is known problem with kdesktop_lock on KDE where the screen saver keeps kicking in every time user input stops for a second or two. Specifying "-nodpms" works around it.

"-nodpms" means prevent DPMS low power states whenever VNC clients are connected, while "-dpms" means to not monitor the DPMS state at all. See the xset(1) manpage for details. -nodpms is basically the same as running "xset dpms force on" periodically. Default: -dpms

-forcedpms

If the system supports the DPMS (Display Power Management Signaling) extension, then try to keep the monitor in a powered off state. This is to prevent nosey people at the physical display from viewing what is on the screen. Be sure lock the screen before disconnecting.

This method is far from bullet proof, e.g. suppose someone attaches a non-DPMS monitor, or loads the machine so that there is a gap of time before x11vnc restores the powered off state? On many machines if he floods it with keyboard and mouse input he can see flashes of what is on the screen before the DPMS off state is reestablished. For this to work securely there would need to be support in the X server to do this exactly rather than approximately with DPMS.

-clientdpms

As -forcedpms but only when VNC clients are connected.

-noserverdpms

The UltraVNC ServerInput extension is supported. This allows the VNC viewer to click a button that will cause the server (x11vnc) to try to disable keyboard and mouse input at the physical display and put the monitor in dpms powered off state. Use this option to skip powering off the monitor.

-noultraext

Disable the following UltraVNC extensions: SingleWindow and ServerInput. The others managed by libvncserver (textchat, 1/n scaling, rfbEncodingUltra) are not.

-noxdamage

Do not use the X DAMAGE extension to detect framebuffer changes even if it is available. Use -xdamage if your default is to have it off.

x11vnc's use of the DAMAGE extension: 1) significantly reduces the load when the screen is not changing much, and 2) detects changed areas (small ones by default) more quickly.

Currently the DAMAGE extension is overly conservative and often reports large areas (e.g. a whole terminal or browser window) as damaged even though the actual changed region is much smaller (sometimes just a few pixels). So heuristics were introduced to skip large areas and use the damage rectangles only as "hints" for the traditional scanline polling. The following tuning parameters are introduced to adjust this behavior:

-xd_area A

Set the largest DAMAGE rectangle area A (in pixels: width * height) to trust as truly damaged: the rectangle will be copied from the framebuffer (slow) no matter what. Set to zero to trust *all* rectangles. Default: 20000

-xd_mem f

Set how long DAMAGE rectangles should be "remembered", f is a floating point number and is in units of the scanline repeat cycle time (32 iterations). The default (1.0) should give no painting problems. Increase it if there are problems or decrease it to live on the edge (perhaps useful on a slow machine).

-sigpipe string

Broken pipe (SIGPIPE) handling. string can be "ignore" or "exit". For "ignore" libvncserver will handle the abrupt loss of a client and continue, for "exit" x11vnc will cleanup and exit at the 1st broken connection.

This option is not really needed since libvncserver is doing the correct thing now for quite some time. However, for convenience you can use it to ignore other signals, e.g. "-sigpipe ignore:HUP,INT,TERM" in case that would be useful for some sort of application. You can also put "exit:.." in the list to have x11vnc cleanup on the listed signals. "-sig" is an alias for this option if you don't like the 'pipe'. Example: -sig ignore:INT,TERM,exit:USR1

-threads, -nothreads

Whether or not to use the threaded libvncserver algorithm [rfbRunEventLoop] if libpthread is available Default: -nothreads

-fs f

If the fraction of changed tiles in a poll is greater than f, the whole screen is updated. Default: 0.75

-gaps n

Heuristic to fill in gaps in rows or cols of n or less tiles. Used to improve text paging. Default: 4

-grow n

Heuristic to grow islands of changed tiles n or wider by checking the tile near the boundary. Default: 3

-fuzz n

Tolerance in pixels to mark a tiles edges as changed. Default: 2

-debug_tiles

Print debugging output for tiles, fb updates, etc.

-snapfb

Instead of polling the X display framebuffer (fb) for changes, periodically copy all of X display fb into main memory and examine that copy for changes. (This setting also applies for non-X -rawfb modes). Under some circumstances this will improve interactive response, or at least make things look smoother, but in others (most!) it will make the response worse. If the video h/w fb is such that reading small tiles is very slow this mode could help. To keep the "framerate" up the screen size x bpp cannot be too large. Note that this mode is very wasteful of memory I/O resources (it makes full screen copies even if nothing changes). It may be of use in video capture-like applications, webcams, or where window tearing is a problem.

-rawfb string

Instead of polling X, poll the memory object specified in string.

For file polling to memory map (2) a file use: "map:/path/to/a/file@WxHxB", with framebuffer Width, Height, and Bits per pixel. "mmap:..." is the same.

If there is trouble with mmap, use "file:/..." for slower (2) based reading. Use "snap:..." to imply -snapfb mode and the "file:" access (this is for devices that only provide the fb all at once).

For shared memory segments string is of the form: "shm:N@WxHxB" which specifies a shmid N and with WxHxB as above. See shmat(1) and ipcs(1)

If you do not supply a type "map" is assumed if the file exists (see the next paragraphs for some exceptions to this.)

If string is "setup:cmd", then the command "cmd" is run and the first line from it is read and used as string. This allows initializing the device, determining WxHxB, etc. These are often done as root so take care.

If the string begins with "video", see the VIDEO4LINUX discusion below where the device may be queried for (and possibly set) the framebuffer parameters.

If the string begins with "console", "/dev/fb", or "fb", see the LINUX CONSOLE discussion below where the framebuffer device is opened and keystrokes (and possibly mouse events) are inserted into the console.

If the string begins with "vnc", see the VNC HOST discussion below where the framebuffer is taken as that of another remote VNC server.

Optional suffixes are ":R/G/B" and "+O" to specify red, green, and blue masks and an offset into the memory object. If the masks are not provided x11vnc guesses them based on the bpp.

Another optional suffix is the Bytes Per Line which in some cases is not WxB/4. Specify it as WxHxB-BPL e.g. 800x600x16-2048. This could be a normal width 1024 at 16bpp fb, but only width 800 shows up.

Examples:

-rawfb shm:210337933@800x600x32:ff/ff00/ff0000

-rawfb map:/dev/fb0@1024x768x32

-rawfb map:/tmp/Xvfb_screen0@640x480x8+3232

-rawfb file:/tmp/my.pnm@250x200x24+37

-rawfb file:/dev/urandom@128x128x8 -rawfb snap:/dev/video0@320x240x24 -24to32 -rawfb video0 -rawfb video -pipeinput VID -rawfb console -rawfb vnc:somehost:0

(see ipcs(1) and fbset(1) for the first two examples)

In general all user input is discarded by default (see the -pipeinput option for how to use a helper program to insert). Most of the X11 (screen, keyboard, mouse) options do not make sense and many will cause this mode to crash, so please think twice before setting or changing them in a running x11vnc.

If you DO NOT want x11vnc to close the X DISPLAY in rawfb mode, prepend a "+" e.g. +file:/dev/fb0... Keeping the display open enables the default remote-control channel, which could be useful. Alternatively, if you specify -noviewonly, then the mouse and keyboard input are STILL sent to the X display, this usage should be very rare, i.e. doing something strange with /dev/fb0.

If the device is not "seekable" (e.g. webcam) try reading it all at once in full snaps via the "snap:" mode (note: this is a resource hog). If you are using file: or map: and the device needs to be reopened for *every* snapfb snapshot, set the environment variable: SNAPFB_RAWFB_RESET=1 as well.

If you want x11vnc to dynamically transform a 24bpp rawfb to 32bpp (note that this will be slower) also supply the -24to32 option. This would be useful for, say, a video camera that delivers the pixel data as 24bpp packed RGB. This is the default under "video" mode if the bpp is 24.

VIDEO4LINUX: on Linux some attempt is made to handle video devices (webcams or TV tuners) automatically. The idea is the WxHxB will be extracted from the device itself. So if you do not supply "@WxHxB... parameters x11vnc will try to determine them. It first tries the v4l API if that support has been compiled in. Otherwise it will run the v4l- info(1) external program if it is available.

The simplest examples are "-rawfb video" and "-rawfb video1" which imply the device file /dev/video and /dev/video1, respectively. You can also supply the /dev if you like, e.g. "-rawfb /dev/video0"

Since the video capture device framebuffer usually changes continuously (e.g. brightness fluctuations), you may want to use the -wait, -slow_fb, or -defer options to lower the "framerate" to cut down on network VNC traffic.

A more sophisticated video device scheme allows initializing the device's settings using:

-rawfb video:<settings>

The prefix could also be, as above, e.g. "video1:" to specify the device file. The v4l API must be available for this to work. Otherwise, you will need to try to initialize the device with an external program, e.g. xawtv, spcaview, and hope they persist when x11vnc re-opens the device.

<settings> is a comma separated list of key=value pairs. The device's brightness, color, contrast, and hue can be set to percentages, e.g. br=80,co=50,cn=44,hu=60.

The device filename can be set too if needed (if it does not start with "video"), e.g. fn=/dev/qcam.

The width, height and bpp of the framebuffer can be set via, e.g., w=160,h=120,bpp=16.

Related to the bpp above, the pixel format can be set via the fmt=XXX, where XXX can be one of: GREY, HI240, RGB555, RGB565, RGB24, and RGB32 (with bpp 8, 8, 16, 16, 24, and 32 respectively). See http://www.linuxtv.org for more info (V4L api).

For TV/rf tuner cards one can set the tuning mode via tun=XXX where XXX can be one of PAL, NTSC, SECAM, or AUTO.

One can switch the input channel by the inp=XXX setting, where XXX is the name of the input channel (Television, Composite1, S-Video, etc). Use the name that is in the information about the device that is printed at startup.

For input channels with tuners (e.g. Television) one can change which station is selected by the sta=XXX setting. XXX is the station number. Currently only the ntsc-cable-us (US cable) channels are built into x11vnc. See the -freqtab option below to supply one from xawtv. If XXX is greater than 500, then it is interpreted as a raw frequency in KHz.

Example:

-rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47

one might need to add inp=Television too for the input channel to be TV if the card doesn't come up by default in that one.

Note that not all video capture devices will support all of the above settings.

See the -pipeinput VID option below for a way to control the settings through the VNC Viewer via keystrokes. As a shortcut, if the string begins "Video.." instead of "video.." then -pipeinput VID is implied.

As above, if you specify a "@WxHxB..." after the <settings> string they are used verbatim: the device is not queried for the current values. Otherwise the device will be queried.

LINUX CONSOLE: If the libvncserver LinuxVNC program is on your system you may want to use that instead of the following method because it will be faster and more accurate for Linux text console.

If the rawfb string begins with "console" the framebuffer device /dev/fb0 is opened (this requires the appropriate kernel modules to be installed) and so is /dev/tty0. The latter is used to inject keystrokes (not all are supported, but the basic ones are). You will need to be root to inject keystrokes. /dev/tty0 refers to the active VT, to indicate one explicitly, use "console2", etc. using the VT number.

If the Linux version seems to be 2.6 or later and the "uinput" module appears to be present, then the uinput method will be used instead of /dev/ttyN. uinput allows insertion of BOTH keystrokes and mouse input and so it preferred when accessing graphical (e.g. QT-embedded) linux console apps. See -pipeinput UINPUT below for more information on this mode; you will have to use -pipeinput if you want to tweak any UINPUT parameters. You may also want to also use the -nodragging and -cursor none options. Use "console0", etc or -pipeinput CONSOLE to force the /dev/ttyN method.

Note you can change VT remotely using the chvt(1) command. Sometimes switching out and back corrects the framebuffer state.

To skip input injecting entirely use "consolex".

The string "/dev/fb0" (1, etc.) can be used instead of "console". This can be used to specify a different framebuffer device, e.g. /dev/fb1. As a shortcut the "/dev/" can be dropped. If the name is something nonstandard, use "console:/dev/foofb"

If you do not want x11vnc to guess the framebuffer's WxHxB and masks automatically (sometimes the kernel gives inaccurate information), specify them with a @WxHxB at the end of the string.

Examples: -rawfb console -rawfb /dev/fb0 (same) -rawfb console3 (force /dev/tty3) -rawfb consolex (no keystrokes or mouse) -rawfb console:/dev/nonstd -rawfb console -pipeinput UINPUT:accel=4.0

VNC HOST: if the -rawfb string is of the form "vnc:host:N" then the VNC display "N" on the remote VNC server "host" is connected to (i.e. x11vnc acts as a VNC client itself) and that framebuffer is exported.

This mode is really only of use if you are trying to improve performance in the case of many (e.g. > 10) simultaneous VNC viewers, and you try a divide and conquer scheme to reduce bandwidth and improve responsiveness.

For example, if there will be 64 simultaneous VNC viewers this can lead to a lot of redundant VNC traffic to and from the server host:N, extra CPU usage, and all viewers response can be reduced by having to wait for writes to the slowest client to finish. However, if you set up 8 reflectors/repeaters started with option -rawfb vnc:host:N, then there are only 8 connections to host:N. Each repeater then handles 8 vnc viewer connections thereby spreading the load around. In classroom broadcast usage, try to put the repeaters on different switches. This mode is the same as -reflect host:N. Replace "host:N" by "listen" or "listen:port" for a reverse connection.

Overall performance will not be as good as a single direct connection because, among other things, there is an additional level of framebuffer polling and pointer motion can still induce many changes per second that must be propagated. Tip: if the remote VNC is x11vnc doing wireframing, or an X display that does wireframing that gives much better response than opaque window dragging. Consider the -nodragging option if the problem is severe.

The VNC HOST mode implies -shared. Use -noshared as a subsequent cmdline option to disable sharing.