X VIRTUAL FRAMEBUFFER ********************* INTRODUCTION ============ The X Virtual Framebuffer (Xvfb) is an X server that renders to virtual memory rather than to a graphics display device. While the traditional (video) X server requires a graphics display device to be present, the Xvfb server performs all its rendering in software and thus can run on a computer with or without a graphics display device. Both a video X server and an Xvfb server can run simultaneously on a system but they must have different display numbers (the video X server will usually have display number :0). The Xvfb server recognizes the same standard X protocol as the video X server. Common X Window system tools can be used to to capture, and view, the contents of the virtual frame buffer (see Appendix B). Although an Xvfb server does not accept input from physical input devices, such as a keyboard or mouse, synthetic events for these devices can be generated by use of the X protocol. Xvfb was first introduced in X11R6 in 1994. While it was originally intended to be used to test the X server, the X community has discovered and deployed some novel uses for Xvfb such as: - testing X client programs against unusual screen sizes or visual depths, - porting the X server to new platforms, - running X client programs in "batch" mode, - running programs that require a DISPLAY, but do not need to render to a graphics device (e.g. some image format converters) X VIRTUAL FRAME BUFFER ON HP-UX =============================== Xvfb is typically delivered in some implementations as a separate program in the same directory as the normal X server, e.g. /usr/bin/X11/Xvfb. HP's implementation differs, however, as the functionality of both the video and Xvfb servers are delivered in the single program /usr/bin/X11/X. There are 4 steps required to get Xvfb up and running on HP-UX: 1) install the appropriate X server patches, if necessary, 2) configure the Xvfb server, 3) run the Xvfb server, 4) run X client programs connected to the Xvfb server. Installing the X server patches ------------------------------- Xvfb server functionality was first delivered on HP-UX in the June 2001 Xserver patches: 10.20 PHSS_23535 11.0 PHSS_23546 11i PHSS_21816 If your X server was installed and/or patched prior to June 2001 you will need to apply the appropriate patch from the above list (or any superceding patches). You can confirm whether your X server supports the Xvfb functionality by doing: man Xserver and searching for the section titled "XVFB OPTIONS". Configure Xvfb -------------- All HP X servers (video or Xvfb) use a configuration file. The configuration files are found in the directory /etc/X11, and are named X#screens, where the # is a number that identifies the display number of the X server (typically, the video X server runs as display :0, so it uses X0screens as its configuration file). You need to choose the display number for your Xvfb server; in these examples we will use 5. The only restriction is that it be different from your video X server display number. Create X5screens with the following 2 lines as its contents: ServerOptions serverMode XVfb This tells the X server that when it runs as display :5 it is to run as an Xvfb server. When the Xvfb server is run from the command-line it is possible to configure how it will run. There are 7 new command-line switches recognized only by an Xvfb server: -screen -pixdepths -fbdir -shmem -linebias -blackpixel -whitepixel See Appendix A for details on these command-line switches. Run Xvfb -------- After creating the X5screens configuration file, you run Xvfb simply by: % /usr/bin/X11/X :5 (usually you would put the process in the background with &) You can also specify command-line switches when you run Xvfb: % /usr/bin/X11/X :5 -fbdir /tmp -screen 0 1280x1024x24 -screen 1 640x480x8 Run X clients ------------- If you have an X client program, say my_x_program, that you wish to connect to an Xvfb server there are 3 ways to do it: 1) most X client programs will connect to the display specified by the DISPLAY shell environment variable: % DISPLAY=:5 % my_x_program 2) many X client programs, particularly those that use Motif and Xt, accept the -display command-line switch: % my_x_program -display :5 3) a very few X client programs hard-code in a display name and number. For those, the source program will need to be editted and changed. This method is strongly discouraged. APPENDIX A - Xvfb Command-line Switches ======================================= The Xvfb server accepts the following in addition to the usual X server command-line switches: -screen screennum WxHxD This option creates screen screennum and sets its width, height, and depth to W, H, and D respectively. By default, only screen 0 exists and has the dimensions 1280x1024x8. This option can be repeated to add more screens (each of which have a different size). -pixdepths list-of-depths This option specifies a list of pixmap depths that the server should support in addition to the depths implied by the supported screens. list-of-depths is a space-separated list of integers that can have values from 1 to 32. -fbdir framebuffer-directory This option specifies the directory in which the memory mapped files containing the framebuffer memory should be created. The file created in that directory will be Xvfb_screen#, where # is the display number of the Xvfb server. This option only exists on machines that have the mmap and msync system calls. -shmem This option specifies that the framebuffer should be put in shared memory. The shared memory ID for each screen will be printed by the server. The shared memory is in xwd format. This option only exists on machines that support the System V shared memory interface. If neither -shmem nor -fbdir is specified, the framebuffer memory will be allocated with malloc(). -linebias n This option specifies how to adjust the pixelization of thin lines. The value n is a bitmask of octants in which to prefer an axial step when the Bresenham error term is exactly zero. See the file Xserver/mi/miline.h for more information. This option is probably only useful to server developers to experiment with the range of line pixelization possible with the cfb and mfb code. -blackpixel pixel-value, -whitepixel pixel-value These options specify the black and white pixel values the server should use. APPENDIX B: Viewing the Xvfb Server Framebuffer Contents ======================================================== Since the Xvfb server accepts normal X protocol, the programs 'xwd' and 'xwud' can be used to display the contents of the Xvfb server framebuffer contents to a video X server: xwd -display :5 -root | xwud -display :0 If the Xvfb server was run with the -fbdir switch, then you don't even need the 'xwd' step (assuming /tmp was the directory specified with -fbdir): xwud -in /tmp/Xvfb_screen5 -display :0