README.wscons
changeset 1187 19d8949b4584
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/README.wscons	Tue Nov 22 15:19:50 2005 +0000
     1.3 @@ -0,0 +1,107 @@
     1.4 +==============================================================================
     1.5 +Using the Simple DirectMedia Layer with OpenBSD/wscons
     1.6 +==============================================================================
     1.7 +
     1.8 +The wscons SDL driver can be used to run SDL programs on OpenBSD
     1.9 +without running X.  So far, the driver only runs on the Sharp Zaurus,
    1.10 +but the driver is written to be easily extended for other machines.
    1.11 +The main missing pieces are blitting routines for anything but 16 bit
    1.12 +displays, and keycode maps for other keyboards.  Also, there is no
    1.13 +support for hardware palettes.
    1.14 +
    1.15 +There is currently no mouse support.
    1.16 +
    1.17 +To compile SDL with support for wscons, use the
    1.18 +"--enable-video-wscons" option when running configure.  I used the
    1.19 +following command line:
    1.20 +
    1.21 +./configure --disable-oss --disable-ltdl --enable-pthread-sem \
    1.22 +	    --disable-esd --disable-arts --disable-video-aalib  \
    1.23 +	    --enable-openbsdaudio --enable-video-wscons \
    1.24 +	    --prefix=/usr/local --sysconfdir=/etc
    1.25 +
    1.26 +
    1.27 +Setting the console device to use
    1.28 +=================================
    1.29 +
    1.30 +When starting an SDL program on a wscons console, the driver uses the
    1.31 +current virtual terminal (usually /dev/ttyC0).  To force the driver to
    1.32 +use a specific terminal device, set the environment variable
    1.33 +SDL_WSCONSDEV:
    1.34 +
    1.35 +bash$ SDL_WSCONSDEV=/dev/ttyC1 ./some-sdl-program
    1.36 +
    1.37 +This is especially useful when starting an SDL program from a remote
    1.38 +login prompt (which is great for development).  If you do this, and
    1.39 +want to use keyboard input, you should avoid having some other program
    1.40 +reading from the used virtual console (i.e., do not have a getty
    1.41 +running).
    1.42 +
    1.43 +
    1.44 +Rotating the display
    1.45 +====================
    1.46 +
    1.47 +The display can be rotated by the wscons SDL driver.  This is useful
    1.48 +for the Sharp Zaurus, since the display hardware is wired so that it
    1.49 +is correctly rotated only when the display is folded into "PDA mode."
    1.50 +When using the Zaurus in "normal," or "keyboard" mode, the hardware
    1.51 +screen is rotated 90 degrees anti-clockwise.
    1.52 +
    1.53 +To let the wscons SDL driver rotate the screen, set the environment
    1.54 +variable SDL_VIDEO_WSCONS_ROTATION to "CW", "CCW", or "UD", for
    1.55 +clockwise, counter clockwise, and upside-down rotation respectively.
    1.56 +"CW" makes the screen appear correct on a Sharp Zaurus SL-C3100.
    1.57 +
    1.58 +When using rotation in the driver, a "shadow" frame buffer is used to
    1.59 +hold the intermediary display, before blitting it to the actual
    1.60 +hardware frame buffer.  This slows down performance a bit.
    1.61 +
    1.62 +For completeness, the rotation "NONE" can be specified to use a shadow
    1.63 +frame buffer without actually rotating.  Unsetting
    1.64 +SDL_VIDEO_WSCONS_ROTATION, or setting it to '' turns off the shadow
    1.65 +frame buffer for maximum performance.
    1.66 +
    1.67 +
    1.68 +Running MAME
    1.69 +============
    1.70 +
    1.71 +Since my main motivation for writing the driver was playing MAME on
    1.72 +the Zaurus, I'll give a few hints:
    1.73 +
    1.74 +XMame compiles just fine under OpenBSD.
    1.75 +
    1.76 +I'm not sure this is strictly necessary, but set
    1.77 +
    1.78 +MY_CPU = arm
    1.79 +
    1.80 +in makefile.unix, and
    1.81 +
    1.82 +CFLAGS.arm = -DLSB_FIRST -DALIGN_INTS -DALIGN_SHORTS
    1.83 +
    1.84 +in src/unix/unix.max
    1.85 +
    1.86 +to be sure.
    1.87 +
    1.88 +The latest XMame (0.101 at this writing) is a very large program.
    1.89 +Either tinker with the make files to compile a version without support
    1.90 +for all drivers, or, get an older version of XMame.  My recommendation
    1.91 +would be 0.37b16.
    1.92 +
    1.93 +When running MAME, DO NOT SET SDL_VIDEO_WSCONS_ROTATION!  Performace
    1.94 +is MUCH better without this, and it is COMPLETELY UNNECESSARY, since
    1.95 +MAME can rotate the picture itself while drawing, and does so MUCH
    1.96 +FASTER.
    1.97 +
    1.98 +Use the Xmame command line option "-ror" to rotate the picture to the
    1.99 +right.
   1.100 +
   1.101 +
   1.102 +Acknowledgments
   1.103 +===============
   1.104 +
   1.105 +I studied the wsfb driver for XFree86/Xorg quite a bit before writing
   1.106 +this, so there ought to be some similarities.
   1.107 +
   1.108 +
   1.109 +--
   1.110 +Staffan Ulfberg <staffan@ulfberg.se>