x11vnc: support for video4linux webcams & tv-tuners, -24to32 bpp option, -rawfb console.

1 files changed, 214 insertions, 25 deletions

diff --git a/x11vnc/help.c b/x11vnc/help.c
index 1986e7e..c070323 100644
--- a/x11vnc/help.c
+++ b/x11vnc/help.c
@@ -228,9 +228,22 @@ void print_help(int mode) {
 "                       this machine -overlay is supported and gives better\n"
 "                       response.\n"
 "\n"
-"                       Debugging for this mode can be enabled by setting \n"
+"                       Debugging for this mode can be enabled by setting\n"
 "                       \"dbg=1\", \"dbg=2\", or \"dbg=3\".\n"
 "\n"
+"-24to32                Very rare problem: if the framebuffer (X display\n"
+"                       or -rawfb) is 24bpp instead of the usual 32bpp, then\n"
+"                       dynamically transform the pixels to 32bpp.  This will be\n"
+"                       slower, but can be used to work around problems where\n"
+"                       VNC viewers cannot handle 24bpp (e.g. \"main: setPF:\n"
+"                       not 8, 16 or 32 bpp?\").  See the FAQ for more info.\n"
+"\n"
+"                       In the case of -rawfb mode, the pixels are directly\n"
+"                       modified by inserting a 0 byte to pad them out to 32bpp.\n"
+"                       For X displays, a kludge is done that is equivalent to\n"
+"                       \"-noshm -visual TrueColor:32\".  (If better performance\n"
+"                       is needed for the latter, feel free to ask).\n"
+"\n"
 "-scale fraction        Scale the framebuffer by factor \"fraction\".  Values\n"
 "                       less than 1 shrink the fb, larger ones expand it.  Note:\n"
 "                       image may not be sharp and response may be slower.\n"
@@ -2154,13 +2167,17 @@ void print_help(int mode) {
 "                       or where window tearing is a problem.\n"
 "\n"
 "-rawfb string          Experimental option, instead of polling X, poll the\n"
-"                       memory object specified in \"string\".  For shared\n"
-"                       memory segments it is of the form: \"shm:N@WxHxB\"\n"
-"                       which specifies a shmid N and framebuffer Width, Height,\n"
-"                       and Bits per pixel.  To memory map mmap(2) a file use:\n"
+"                       memory object specified in \"string\".\n"
+"\n"
+"                       For shared memory segments string is of the\n"
+"                       form: \"shm:N@WxHxB\" which specifies a shmid\n"
+"                       N and framebuffer Width, Height, and Bits\n"
+"                       per pixel.  To memory map mmap(2) a file use:\n"
 "                       \"map:/path/to/a/file@WxHxB\".  If there is trouble\n"
-"                       with mmap, use  \"file:/...\" for slower lseek(2)\n"
-"                       based reading.  If you do not supply a type \"map\"\n"
+"                       with mmap, use  \"file:/...\" for slower lseek(2) based\n"
+"                       reading. Use \"snap:...\" to imply -snapfb mode and the\n"
+"                       \"file:\" access (this is for devices that only provide\n"
+"                       the fb all at once). If you do not supply a type \"map\"\n"
 "                       is assumed if the file exists.\n"
 "\n"
 "                       If string is \"setup:cmd\", then the command \"cmd\"\n"
@@ -2169,6 +2186,14 @@ void print_help(int mode) {
 "                       determining WxHxB, etc. These are often done as root\n"
 "                       so take care.\n"
 "\n"
+"                       If the string begins with \"video\", see the video4linux\n"
+"                       discusion below where the device may be queried for\n"
+"                       (and possibly set) the framebuffer parameters.\n"
+"\n"
+"                       If the strings begins with \"cons\", see the linux\n"
+"                       console discussion below where the framebuffer device\n"
+"                       is opened and keystrokes are inserted into the console.\n"
+"\n"
 "                       Optional suffixes are \":R/G/B\" and \"+O\" to specify\n"
 "                       red, green, and blue masks and an offset into the\n"
 "                       memory object.  If the masks are not provided x11vnc\n"
@@ -2179,6 +2204,11 @@ void print_help(int mode) {
 "                           -rawfb map:/dev/fb0@1024x768x32\n"
 "                           -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232\n"
 "                           -rawfb file:/tmp/my.pnm@250x200x24+37\n"
+"                           -rawfb file:/dev/urandom@128x128x8\n"
+"                           -rawfb snap:/dev/video0@320x240x24 -24to32\n"
+"                           -rawfb video0\n"
+"                           -rawfb video -pipeinput VID\n"
+"                           -rawfb console\n"
 "\n"
 "                       (see ipcs(1) and fbset(1) for the first two examples)\n"
 "\n"
@@ -2186,16 +2216,157 @@ void print_help(int mode) {
 "                       -pipeinput option).  Most of the X11 (screen, keyboard,\n"
 "                       mouse) options do not make sense and many will cause\n"
 "                       this mode to crash, so please think twice before\n"
-"                       setting/changing them.\n"
+"                       setting or changing them in a running x11vnc.\n"
+"\n"
+"                       If you DO NOT want x11vnc to close the X DISPLAY in\n"
+"                       rawfb mode, prepend a \"+\" e.g. +file:/dev/fb0...\n"
+"                       Keeping the display open enables the default\n"
+"                       remote-control channel, which could be useful.\n"
+"                       Alternatively, if you specify -noviewonly, then the\n"
+"                       mouse and keyboard input are STILL sent to the X\n"
+"                       display, this usage should be very rare, i.e. doing\n"
+"                       something strange with /dev/fb0.\n"
+"\n"
+"                       If the device is not \"seekable\" try reading it all\n"
+"                       at once in full snaps via the \"snap:\" mode (note:\n"
+"                       this is a resource hog).  If you are using file: or\n"
+"                       map: and the device needs to be reopened for *every*\n"
+"                       snapfb snapshot, set the environment variable:\n"
+"                       SNAPFB_RAWFB_RESET=1 as well.\n"
+"\n"
+"                       If you want x11vnc to dynamically transform a 24bpp\n"
+"                       rawfb to 32bpp (note that this will be slower) use\n"
+"                       the -24to32 option.  This would be useful for, say,\n"
+"                       for a video camera that delivers the pixel data as\n"
+"                       24bpp packed RGB.  This is the default under \"video\"\n"
+"                       mode if the bpp is 24.\n"
+"\n"
+"                       video4linux: on Linux some attempt is made to handle\n"
+"                       video devices (webcams or tv tuners) automatically.\n"
+"                       The idea is the WxHxB will be extracted from the\n"
+"                       device itself.  So if you do not supply \"@WxHxB...\n"
+"                       parameters x11vnc will try to determine them.  It first\n"
+"                       tries the v4l API if that support has been compiled in.\n"
+"                       Otherwise it will run the v4l-info(1) external program\n"
+"                       if it is available.\n"
+"\n"
+"                       The simplest examples are \"-rawfb video\" and \"-rawfb\n"
+"                       video1\" which imply the device file /dev/video and\n"
+"                       /dev/video1, respectively.  You can also supply the\n"
+"                       /dev if you like, e.g. \"-rawfb /dev/video0\"\n"
+"\n"
+"                       Since the video capture device framebuffer usually\n"
+"                       changes continuously (e.g. brightness fluctuations),\n"
+"                       you may want to use the -wait, -slow_fb, or -defer\n"
+"                       options to lower the \"framerate\" to cut down on\n"
+"                       network VNC traffic.\n"
+"\n"
+"                       A more sophisticated video device scheme allows\n"
+"                       initializing the device's settings using:\n"
+"\n"
+"                           -rawfb video:<settings>\n"
+"\n"
+"                       The prefix could also be, as above, e.g. \"video1:\" to\n"
+"                       specify the device file.  The v4l API must be available\n"
+"                       for this to work.  Otherwise, you will need to try\n"
+"                       to initialize the device with an external program,\n"
+"                       e.g. xawtv, spcaview, and hope they persist when x11vnc\n"
+"                       re-opens the device.\n"
+"\n"
+"                       <settings> is a comma separated list of key=value pairs.\n"
+"                       The device's brightness, color, contrast, and hue can\n"
+"                       be set to percentages, e.g. br=80,co=50,cn=44,hu=60.\n"
+"\n"
+"                       The device filename can be set too if needed (if it\n"
+"                       does not start with \"video\"), e.g. fn=/dev/qcam.\n"
+"\n"
+"                       The width, height and bpp of the framebuffer can be\n"
+"                       set via, e.g., w=160,h=120,bpp=16.\n"
+"\n"
+"                       Related to the bpp above, the pixel format can be set\n"
+"                       via the fmt=XXX, where XXX can be one of: GREY, HI240,\n"
+"                       RGB555, RGB565, RGB24, and RGB32 (with bpp 8, 8, 16, 16,\n"
+"                       24, and 32 respectively).  See http://www.linuxtv.org\n"
+"                       for more info (V4L api).\n"
+"\n"
+"                       For tv/rf tuner cards one can set the tuning mode\n"
+"                       via tun=XXX where XXX can be one of PAL, NTSC, SECAM,\n"
+"                       or AUTO.\n"
+"\n"
+"                       One can switch the input channel by the inp=XXX setting,\n"
+"                       where XXX is the name of the input channel (Television,\n"
+"                       Composite1, S-Video, etc).  Use the name that is in the\n"
+"                       information about the device that is printed at startup.\n"
+"\n"
+"                       For input channels with tuners (e.g. Television) one\n"
+"                       can change which station is selected by the sta=XXX\n"
+"                       setting.  XXX is the station number.  Currently only\n"
+"                       the ntsc-cable-us (US cable) channels are built into\n"
+"                       x11vnc.  See the -freqtab option below to supply one\n"
+"                       from xawtv. If XXX is greater than 500, then it is\n"
+"                       interpreted as a raw frequency in KHz.\n"
+"\n"
+"                       Example:\n"
+"\n"
+"                       -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47\n"
+"\n"
+"                       one might need to add inp=Television too for the input\n"
+"                       channel to be TV if the card doesn't come up by default\n"
+"                       in that one.\n"
+"\n"
+"                       Note that not all video capture devices will support\n"
+"                       all of the above settings.\n"
+"\n"
+"                       See the -pipeinput VID option below for a way to control\n"
+"                       the settings through the VNC Viewer via keystrokes.\n"
+"\n"
+"                       As above, if you specify a \"@WxHxB...\" after the\n"
+"                       <settings> string they are used verbatim: the device\n"
+"                       is not queried for the current values.  Otherwise the\n"
+"                       device will be queried.\n"
+"\n"
+"                       Linux console:  If the libvncserver LinuxVNC command is\n"
+"                       on your system use that instead of the following method\n"
+"                       because it will be faster and more accurate for Linux\n"
+"                       text console.\n"
+"\n"
+"                       If the rawfb string begins with \"cons\" the framebuffer\n"
+"                       device /dev/fb0 is opened (this requires the appropriate\n"
+"                       kernel modules) and so is /dev/tty0.  The latter is\n"
+"                       used to inject keystrokes (not all are supported,\n"
+"                       but the basic ones are).  You will need to be root to\n"
+"                       inject keystrokes.  /dev/tty0 refers to the active VT,\n"
+"                       to indicate one explicitly, use \"cons2\", etc. using\n"
+"                       the VT number.  Note you can change VT remotely using\n"
+"                       the chvt(1) command.  Sometimes switching out and back\n"
+"                       corrects the framebuffer.  To skip injecting entirely\n"
+"                       use \"consx\".\n"
+"\n"
+"                       The strings \"console\", or \"/dev/fb0\" can be used\n"
+"                       instead of \"cons\".  The latter can be used to specify\n"
+"                       a different framebuffer device, e.g. /dev/fb1.  If the\n"
+"                       name is something nonstandard, use \"cons:/dev/foofb\"\n"
+"\n"
+"                       If you do not want x11vnc to guess the framebuffer's\n"
+"                       WxHxB and masks automatically, specify them with a\n"
+"                       @WxHxB at the end of the string.\n"
 "\n"
-"                       If you don't want x11vnc to close the X DISPLAY in\n"
-"                       rawfb mode, then capitalize the prefix, SHM:, MAP:,\n"
-"                       FILE:   Keeping the display open enables the default\n"
-"                       remote-control channel, which could be useful.  Also,\n"
-"                       if you also specify -noviewonly, then the mouse and\n"
-"                       keyboard input are STILL sent to the X display, this\n"
-"                       usage should be very rare, i.e. doing something strange\n"
-"                       with /dev/fb0.\n"
+"                       Examples:\n"
+"                           -rawfb cons               (same as -rawfb console)\n"
+"                           -rawfb /dev/fb0           (same)\n"
+"                           -rawfb cons3              (force /dev/tty3)\n"
+"                           -rawfb consx              (no keystrokes)\n"
+"                           -rawfb console:/dev/nonstd\n"
+"\n"
+"-freqtab file          For use with \"-rawfb video\" for TV tuner devices to\n"
+"                       specify station frequencies.  Instead of using the built\n"
+"                       in ntsc-cable-us mapping of station number to frequency,\n"
+"                       use the data in file.  For stations that are not\n"
+"                       numeric, e.g. SE20, they are placed above the highest\n"
+"                       numbered station in the order they are found.  Example:\n"
+"                       \"-freqtab /usr/X11R6/share/xawtv/europe-west.list\"\n"
+"                       You can make your own freqtab by copying the xawtv\n"
+"                       format.\n"
 "\n"
 "-pipeinput cmd         Another experimental option: it lets you supply an\n"
 "                       external command in \"cmd\" that x11vnc will pipe\n"
@@ -2214,6 +2385,22 @@ void print_help(int mode) {
 "                       value is stored in X11VNC_RAWFB_STR for the pipe command\n"
 "                       to use if it wants. Do 'env | grep X11VNC' for more.\n"
 "\n"
+"                       If cmd is \"VID\" and you are using the -rawfb for a\n"
+"                       video capture device, then an internal list of keyboard\n"
+"                       mappings is used to set parameters of the video.\n"
+"                       The mappings are:\n"
+"\n"
+"                         \"B\" and \"b\" adjust the brightness up and down.\n"
+"                         \"H\" and \"h\" adjust the hue.\n"
+"                         \"C\" and \"c\" adjust the colour.\n"
+"                         \"N\" and \"n\" adjust the contrast.\n"
+"                         \"S\" and \"s\" adjust the size of the capture screen.\n"
+"                         \"I\" and \"i\" cycle through input channels.\n"
+"                         Up and Down arrows adjust the station (if a tuner)\n"
+"                         F1, F2, ..., F6 will switch the video capture pixel\n"
+"                         format to HI240, RGB565, RGB24, RGB32, RGB555, and\n"
+"                         GREY respectively.  See -rawfb video for details.\n"
+"\n"
 "-gui [gui-opts]        Start up a simple tcl/tk gui based on the the remote\n"
 "                       control options -remote/-query described below.\n"
 "                       Requires the \"wish\" program to be installed on the\n"
@@ -2365,6 +2552,8 @@ void print_help(int mode) {
 "                       8to24           enable  -8to24 mode (if applicable).\n"
 "                       no8to24         disable -8to24 mode.\n"
 "                       8to24_opts:str  set the -8to24 opts to \"str\".\n"
+"                       24to32          enable  -24to32 mode (if applicable).\n"
+"                       no24to32        disable -24to32 mode.\n"
 "                       visual:vis      set -visual to \"vis\"\n"
 "                       scale:frac      set -scale to \"frac\"\n"
 "                       scale_cursor:f  set -scale_cursor to \"f\"\n"
@@ -2639,15 +2828,15 @@ void print_help(int mode) {
 "                       truecolor notruecolor overlay nooverlay overlay_cursor\n"
 "                       overlay_yescursor nooverlay_nocursor nooverlay_cursor\n"
 "                       nooverlay_yescursor overlay_nocursor 8to24 no8to24\n"
-"                       8to24_opts visual scale scale_cursor viewonly noviewonly\n"
-"                       shared noshared forever noforever once timeout filexfer\n"
-"                       nofilexfer deny lock nodeny unlock connect allowonce\n"
-"                       allow localhost nolocalhost listen lookup nolookup\n"
-"                       accept afteraccept gone shm noshm flipbyteorder\n"
-"                       noflipbyteorder onetile noonetile solid_color\n"
-"                       solid nosolid blackout xinerama noxinerama xtrap\n"
-"                       noxtrap xrandr noxrandr xrandr_mode padgeom quiet q\n"
-"                       noquiet modtweak nomodtweak xkb noxkb skip_keycodes\n"
+"                       8to24_opts 24to32 no24to32 visual scale scale_cursor\n"
+"                       viewonly noviewonly shared noshared forever noforever\n"
+"                       once timeout filexfer nofilexfer deny lock nodeny\n"
+"                       unlock connect allowonce allow localhost nolocalhost\n"
+"                       listen lookup nolookup accept afteraccept gone shm\n"
+"                       noshm flipbyteorder noflipbyteorder onetile noonetile\n"
+"                       solid_color solid nosolid blackout xinerama noxinerama\n"
+"                       xtrap noxtrap xrandr noxrandr xrandr_mode padgeom quiet\n"
+"                       q noquiet modtweak nomodtweak xkb noxkb skip_keycodes\n"
 "                       sloppy_keys nosloppy_keys skip_dups noskip_dups\n"
 "                       add_keysyms noadd_keysyms clear_mods noclear_mods\n"
 "                       clear_keys noclear_keys remap repeat norepeat fb nofb\n"