| 1 | ============================================================================== |
| 2 | Using the Simple DirectMedia Layer with OpenBSD/wscons |
| 3 | ============================================================================== |
| 4 | |
| 5 | The wscons SDL driver can be used to run SDL programs on OpenBSD |
| 6 | without running X. So far, the driver only runs on the Sharp Zaurus, |
| 7 | but the driver is written to be easily extended for other machines. |
| 8 | The main missing pieces are blitting routines for anything but 16 bit |
| 9 | displays, and keycode maps for other keyboards. Also, there is no |
| 10 | support for hardware palettes. |
| 11 | |
| 12 | There is currently no mouse support. |
| 13 | |
| 14 | To compile SDL with support for wscons, use the |
| 15 | "--enable-video-wscons" option when running configure. I used the |
| 16 | following command line: |
| 17 | |
| 18 | ./configure --disable-oss --disable-ltdl --enable-pthread-sem \ |
| 19 | --disable-esd --disable-arts --disable-video-aalib \ |
| 20 | --enable-openbsdaudio --enable-video-wscons \ |
| 21 | --prefix=/usr/local --sysconfdir=/etc |
| 22 | |
| 23 | |
| 24 | Setting the console device to use |
| 25 | ================================= |
| 26 | |
| 27 | When starting an SDL program on a wscons console, the driver uses the |
| 28 | current virtual terminal (usually /dev/ttyC0). To force the driver to |
| 29 | use a specific terminal device, set the environment variable |
| 30 | SDL_WSCONSDEV: |
| 31 | |
| 32 | bash$ SDL_WSCONSDEV=/dev/ttyC1 ./some-sdl-program |
| 33 | |
| 34 | This is especially useful when starting an SDL program from a remote |
| 35 | login prompt (which is great for development). If you do this, and |
| 36 | want to use keyboard input, you should avoid having some other program |
| 37 | reading from the used virtual console (i.e., do not have a getty |
| 38 | running). |
| 39 | |
| 40 | |
| 41 | Rotating the display |
| 42 | ==================== |
| 43 | |
| 44 | The display can be rotated by the wscons SDL driver. This is useful |
| 45 | for the Sharp Zaurus, since the display hardware is wired so that it |
| 46 | is correctly rotated only when the display is folded into "PDA mode." |
| 47 | When using the Zaurus in "normal," or "keyboard" mode, the hardware |
| 48 | screen is rotated 90 degrees anti-clockwise. |
| 49 | |
| 50 | To let the wscons SDL driver rotate the screen, set the environment |
| 51 | variable SDL_VIDEO_WSCONS_ROTATION to "CW", "CCW", or "UD", for |
| 52 | clockwise, counter clockwise, and upside-down rotation respectively. |
| 53 | "CW" makes the screen appear correct on a Sharp Zaurus SL-C3100. |
| 54 | |
| 55 | When using rotation in the driver, a "shadow" frame buffer is used to |
| 56 | hold the intermediary display, before blitting it to the actual |
| 57 | hardware frame buffer. This slows down performance a bit. |
| 58 | |
| 59 | For completeness, the rotation "NONE" can be specified to use a shadow |
| 60 | frame buffer without actually rotating. Unsetting |
| 61 | SDL_VIDEO_WSCONS_ROTATION, or setting it to '' turns off the shadow |
| 62 | frame buffer for maximum performance. |
| 63 | |
| 64 | |
| 65 | Running MAME |
| 66 | ============ |
| 67 | |
| 68 | Since my main motivation for writing the driver was playing MAME on |
| 69 | the Zaurus, I'll give a few hints: |
| 70 | |
| 71 | XMame compiles just fine under OpenBSD. |
| 72 | |
| 73 | I'm not sure this is strictly necessary, but set |
| 74 | |
| 75 | MY_CPU = arm |
| 76 | |
| 77 | in makefile.unix, and |
| 78 | |
| 79 | CFLAGS.arm = -DLSB_FIRST -DALIGN_INTS -DALIGN_SHORTS |
| 80 | |
| 81 | in src/unix/unix.max |
| 82 | |
| 83 | to be sure. |
| 84 | |
| 85 | The latest XMame (0.101 at this writing) is a very large program. |
| 86 | Either tinker with the make files to compile a version without support |
| 87 | for all drivers, or, get an older version of XMame. My recommendation |
| 88 | would be 0.37b16. |
| 89 | |
| 90 | When running MAME, DO NOT SET SDL_VIDEO_WSCONS_ROTATION! Performace |
| 91 | is MUCH better without this, and it is COMPLETELY UNNECESSARY, since |
| 92 | MAME can rotate the picture itself while drawing, and does so MUCH |
| 93 | FASTER. |
| 94 | |
| 95 | Use the Xmame command line option "-ror" to rotate the picture to the |
| 96 | right. |
| 97 | |
| 98 | |
| 99 | Acknowledgments |
| 100 | =============== |
| 101 | |
| 102 | I studied the wsfb driver for XFree86/Xorg quite a bit before writing |
| 103 | this, so there ought to be some similarities. |
| 104 | |
| 105 | |
| 106 | -- |
| 107 | Staffan Ulfberg <staffan@ulfberg.se> |