DIVE X Window Server (AKA Xpmfb) Version: 0.1-beta Patchlevel: 3 Table of contents * Table of contents * Important notes * Introduction * Installing * The startx2 script * Command line options * Colors * The window * The keyboard * Closing the server * Uninstalling * Fixed bugs * Known bugs * Bug reports * The author * License and copyrights Note: You can dowload this server from Hobbes or Leo, but not from my site, which is already filled up with other projects. Sorry. Important notes This demo is not for fainthearts. You should be a experienced guy, or at least a fearless one. ++++++++READ EVERY WORD OF THIS FILE++++++++ There are no guarantees, either implicit or explicit, in this product. You use it at your own risk. It's an unfinished product and may lack many features. It is not intended to be used in a production environment, and I will not accept any responsability for any damage or loss due to the use of this program. Introduction Ever since I discovered EMX and XFreeOS/2 I've been always dreaming with the possibility of building up myself a PM native X server. It was a sort of personal challenge that for some time I never dared to face (not even speak about), mainly because of a total lack of knowledge about OS/2 or X windows programming. However, as time passed by, a copy of an unfinished DIVE game fell on my HD drive and I finally saw how easy it was to get good & fast graphics even on top of PM. A few days later Doom's source code was released and I started playing with the code, so that Doom for DIVE saw the light right with the new year!!!. Gee, using DIVE was simple and programming a window loop is rather straightforward. Thus, what was stopping me from hacking an X server? Nothing! The XFree86 server kit (a cut down source tree just with X Windows servers), some manuals (great books available for download, with loads of information) and a few holiday weeks were enough to get the first alpha release. So, what is Xpmfb? The word XPMFB stands for "X Presentation Manager Frame Buffer": * The X: It is an X Windows Server, i.e., a program which is capable of display the graphic output of other programs (the clients). * The PM: Xpmfb is a mixture of standard Unix code and Presentation Manager routines. Xpmfb is coded as an OS/2 text program that starts in a Windowed Session and is capable of opening a window for graphic output. * The FB: Xpmfb has a lot of code from the XFree86 Org. in it. This code is ready to write to video memory, but Xpmfb tweaks it so that the actual destination is a protected area of the computer's memory (The "frame buffer"). Next, just when updates are many or it is time do so, Xpmfb dumps to screen portions of that buffer using the OS/2's DIVE library. Installing There's a set of steps that you should follow. Currently they are a bit messy, but I'm quite sure that configuring XFreeOS/2 is the toughest part: 1. You must have DIVE installed in your system. Warp 4 (aka Merlin) already does this, but when using Warp 3 you will need to install the Multimedia Kit (See "Selective Install"). 2. Install XFreeOS/2 as explained in its docs. Modify CONFIG.SYS accordingly. You don't need to install a server. 3. Configure XFreeOS/2 using xf86config. You should do it the right way (For instance, keyboard settings are important). If XFreeOS/2 does not support your video card, you are free to lie about it: just choose a powerful one. 4. Unpack the Xpmfb.zip package into a single directory. [C:\PMFB] unzip Xpmfb.zip -d C:\PMFB 5. If you are using XFreeOS/2 3.3.2 then copy the file %X11ROOT%/XFree86/lib/X11/XF86Config to %X11ROOT%/XFree86/lib/X11/XConfig 6. Edit the XConfig file and add the following piece of text at the end Section "Screen" Driver "fbdev" Device "My device" Monitor "My Monitor" Subsection "Display" Modes "640x400" ViewPort 0 0 EndSubsection EndSection 7. In the preceding text, replace "My Monitor" with a monitor identifier found in your XConfig file. If you are clueless, look in XConfig for a piece of text looking like Section "Monitor" Identifier "UltraScan-233" VendorName "ACME" ModelName "FastXGA" ... and copy the [Identifier] string ("UltraScan-233" in this case). 8. Next replace "My device" with a device identifier found in your XConfig file. If you are clueless, look in XConfig for a piece of text looking like Section "Device" Identifier "VL-41" VendorName "Unknown" BoardName "Unknown" and copy the [Identifier] string ("VL-41" in the example). 9. Choose also a value for Modes. You can use any one of those defined in the ModeLines sections in XConfig. (Usually, 640x400 or 640x480 work and cause no big overhead). Note: these values are unimportant and will not affect the performance of Xpmfb. They are just here to keep the XFree86 code happy. 10. Have a try (see below for the appropiate options) [C:\PMFB] startx2.cmd -- xpmfb -direct -screen 640x400x8 11. From inside the server you should invoke xmodmap (See below) or you can automate this by fixing `startx2.cmd'. The startx2 script It is a script that is designed to work much like the XFreeOS/2 scripts startx and xinit. However, it starts by default the Xpmfb server and it does not switch to full screen mode because Xpmfb does not need it. The command line parameters of startx2 are more or less as follows startx2 [client options1] -- [server options2] Default values are client %X11ROOT%\XFree86\lib\X11\xinit\xinitrc.cmd options1 server xpmfb.exe options2-direct -screen 640x400x8 The default options should work for a usual setup where 'xpmfb.exe' is accessible (i.e., it is either in the current directory or in any other one which is listed in the PATH environment variable). They just tell startx2 to launch the Xpmfb server in 640x400 size using 256 colors and trying direct access to screen. Once Xpmfb is up and running, startx2 will just invoke xinitrc.cmd to launch the default clients. Command line options for Xpmfb Size and depth of the screen The format for this option is -screen WxHxD W = X windows horizontal resolution H = X windows vertical resolution D = color depth (i.e., bits per color) The color depth is the number of bits that the graphics adapter uses to represent a color. Usual values are 8, 16, 24 and 32. See below for an explanation. Direct access to screen This option has no parameters, it is simply -direct I had reports that DIVE's DiveBlit routine did not work in some systems, while DiveAcquireFrameBuffer did. This made me rewrite most of the graphics ops (not much, 50 lines of code) using direct access to the video memory. It works pretty fast in my 486DX2, but you guys with video accelerators might prefer not using it. The direct video routine automatically deactivates itselve when you specify a color depth of 8 in a 16,24 or 32 environment. This is because the directo access code is not smart enough to perform palette translation (And it'll never be, because DIVE is already fast at doing this). Deactivation of -direct also occurs when the video aperture size is not a multiple of the scan line size. This might or might not be fixed in the future. Placement of video buffer The option -malloc tells Xpmfb to allocate the graphic buffer in normal RAM instead of using the memory of the video adapter. It is only useful on systems where DIVE is faulty and does not allocate the buffer itself (For instance, this happens with some old Trident cards). High resolution timer The last option is -os2HRTTimer It advices Xpmfb to use the TIMER0.SYS device to get a high resolution timer. Not really needed, I think, but kept for compatibility with XFreeOS/2's servers. Colors Xpmfb is a color X Windows Server. It needs a graphic adapter that is capable of showing 256 colors or more, and PM must be using a graphic mode that provides either 256 colors or more. There are a lot of different graphic adapters, together with a plethora of different graphic modes that supports colors. When speaking about colors, we can either mention the maximum number of colors that the graphic mode provides, or the number of bits that the computer uses to store each color in memory. This is a short equivalence table: Number of bits Number of colors 8 bits 256 16 bits 65536 24 bits 16,777,216 32 bits 16,777,216 You can see that the 32 bits mode wastes 8 bits (but it's a bit faster due to word alignment of data). In order to Xpmfb work, Presentation Manager must be using a graphic mode that is capable of showing 256 colors or more. Once we assure this, Xpmfb is able to support two different color configurations. One uses the same type of color mode as Presentation Manager. The other one uses just 8 bit colors (i.e., a total maximum of 256) and lets DIVE to translate them to the native color mode. PM mode/Xpmfb mode 8 bits 16 bits 24 bits 32 bits 8 bits Direct/DIVE DIVE DIVE DIVE 16 bits [NA] Direct/DIVE [NA] [NA] 24 bits [NA] [NA] Direct/DIVE [NA] 32 bits [NA] [NA] [NA] Direct/DIVE As you see, an 8 bit mode is always available wich uses DIVE to translate the palette and to write to screen. This mode is cheap, and eats much less memory than the other ones. Apart from this mode, Xpmfb only accepts the PM native one, that is, the one with the same number of colors as PM. If this is the selected one, direct access to video memory is possible and speeds up graphics. Right now Xpmfb both the color depth and the screen resolution must be specified at launch time. By default, xpmfb is invoked using xpmfb -direct -screen 600x400x8 which means a 600x400 pixels server using a 8 bit color mode (256 colors). The way to select other resolutions is something like startx2 -- xpmfb -direct -screen 640x480x16 which invokes a server with a 640x480 screen in 16 bit color mode. This is to be fixed, but right now, to know the color depth (= number of bits) you must either already know it, or simply grab the output from Xpmfb and watch the lines saying (--) xpmfb: Found DIVE controller (--) xpmfb: depth = 8 (--) xpmfb: fourcc = LUT8 (--) xpmfb: maxWidth = 640 (--) xpmfb: maxHeight = 480 (--) xpmfb: banks = False (--) xpmfb: direct = True (--) xpmfb: aperture = 491520 (--) This example shows that PM is using a 8 bit color mode (second line, "depth = 8"). Please ignore the core dump at the end of the program (when the message "Exiting" has come out), because it is a minor annoyance due to a quick hack to kill a thread. The window The Xpmfb window is where X Windows applications show their output. The window has some important features. The first one is that it lacks a system menu: the one on the top left corner. The reason for this is that it grabs some important keystrokes, such as the ALT key. The second feature is that it is of a limited size: i.e, it cannot grow past the size that is specified on the command line (remember the -screen option?). And the third feature is a funny one: even when Xpmfb does not have the focus it still accepts mouse clicks. This way, you can still operate on X Windows applications even when PM ones are on top of the desktop. The keyboard Hey kids, this is not my fault, but PM seems to translate the PC-keyboard scan codes to a set which is different from standard one. This is a bit annoying because a keyboard mapping that works with XFreeOS/2's servers does not longer work with Xpmfb --at least for some keys (Right Alt, right ctrl, etc)--. I've found a sort of fix: you have to invoke xmodmap with the appropiate translation table for the keys that need to be fixed. For my 101/102 AT keyboard the fix is --keymap---------cut here-------------- ! These are the keys that have to be fixed (i.e., they have wrong ! keycodes in the XFree86 keymap): keycode 102 = Mode_switch Multi_key keycode 99 = Control_R keycode 105 = Up keycode 110 = Down keycode 108 = Right keycode 107 = Left keycode 103 = Pause keycode 101 = Print Execute keycode 112 = Insert keycode 104 = Home keycode 106 = Prior keycode 113 = Delete keycode 109 = End keycode 111 = Next keycode 100 = KP_Divide clear Shift clear Lock clear Control clear Mod1 clear Mod2 clear Mod3 clear Mod4 clear Mod5 add Shift = Shift_L Shift_R add Lock = Caps_Lock add Control = Control_L Control_R add Mod1 = Alt_L add Mod2 = Num_Lock add Mod3 = Mode_switch add Mod5 = Scroll_Lock --keymap---------cut here-------------- The steps are more or less like this: 1. Make sure that XFreeOS/2 uses XKB and that the proper keymap is selected. This is usually achieved with the xf86config program. 2. Cut the preceding text out and save it anywhere. 3. Next, every time you start Xpmfb you should invoke xmodmap. For instance, at home I have the keymap text in c:/usr/etc/xpmfbkeys and I've added a line to `startx2.cmd' saying 'detach xmodmap c:/usr/etc/xpmfbkeys' See `startx2.cmd' for the place where this line or a similar one should go. Closing the server To exit the server, try pressing ALT+F4 or close the window (Either from the Window List or using the "X" icon under Warp 4). If there's no response, move the window (draggin with the mouse pressed on the title). That'll cause a window update and thus the server will be killed. If nothing else worked, you can still use the Holger's `death.exe' program together with my `killname.cmd' script to kill the server whenever previous method didn't work. For example [C:\PMFB] killname xpmfb.exe You should get a message saying `rc = 0'. `death.exe' must be in some directory listed in the PATH or in the current directory. Uninstalling Simply delete the C:\PMFB directory together with the files you got from the package. Fixed bugs 1. The server got too large when using truecolor modes. 2. Doubled images when using DIVE translation to 8 bit color. 3. Distorded colors in >= 16bits color depth 4. Unkillable server process at exit. 5. When using DIVE translation screen is not automatically updated. Known bugs/features 1. Direct video access is not possible for video apertures that are not a multiple of the screen scan line size. The reason? Lazyness of the author :) 2. The window does not get the focus when you click on it. This is good if you want both an X app and a PM one to share the screen. Bug reports If the server crashes or it simply does not start, try launching it by hand: * Open an OS/2 command window. * Launch Xpmfb with the appropiate options and grab the output. For example xpfmb -direct -screen 640x400x8 2>&1 > error.log * Try using any combination of -direct, color depths, and -malloc. * Have a look at 'error.log'. It usually says why the server does not want to work. * If you still don't know what's going on, e-mail me the log file 'error.log' together with an explanation of any other sympthoms. A description of the hardware would be OK, too. But NEVER SEND ME A CORE DUMP!!!! The author This is me: Juan Jose Garcia Ripoll Universidad de Castilla-La Mancha, E.T.S.I. Industriales, Dept. Matematicas And you can reach me here: E-mail: worm@arrakis.es WWW: http://www.arrakis.es/~worm Copyrights I really do not know about laws at all and I most surely never will so please tell me if I am doing anything wrong. For the base X server code Copyright c 1996 X Consortium Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, dis- tribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the fol- lowing conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL- ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABIL- ITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium. X Window System is a trademark of X Consortium, Inc. For some of the OS/2 support routiens /* * (c) Copyright 1996 by Sebastien Marineau * * * (c) Copyright 1996,1997 by Holger Veit * * * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL * HOLGER VEIT BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE * SOFTWARE. * * Except as contained in this notice, the name of Sebastien Marineau shall not be * used in advertising or otherwise to promote the sale, use or other dealings * in this Software without prior written authorization from Sebastien Marineau. * */