README.Watcom
author Sam Lantinga <slouken@libsdl.org>
Thu, 02 Apr 2009 04:43:36 +0000
branchSDL-1.2
changeset 4167 a6f635e5eaa6
parent 1888 488eba319a25
child 3568 8c72321542f6
child 12987 ad20a4424a57
permissions -rw-r--r--
Fixed bug #611

From Tim Angus 2008-08-12 11:18:06

I'm one of the maintainers of ioquake3.org, an updated version of the
Quake 3 engine. Relatively recently, we moved ioq3 to use SDL as a
replacement for 95% of the platform specific code that was there. On the
whole it's doing a great job but unfortunately since the move we've been
getting complaints about the quality of the mouse input on the Windows
platform to the point where for many the game is unplayable. Put in
other terms, the current stable SDL 1.2 is basically not fit for purpose
if you need high quality mouse input as you do in a first person shooter.

Over the weekend I decided to pull my finger out and actually figure out
what's going on. There are basically two major problems. Firstly, when
using the "windib" driver, mouse input is gathered via the WM_MOUSEMOVE
message. Googling for this indicates that often this is known to result
in "spurious" and/or "missing" mouse movement events; this is the
primary cause of the poor mouse input. The second problem is that the
"directx" driver does not work at all in combination with OpenGL meaning
that you can't use DirectInput if your application also uses OpenGL. In
other words you're locked into using the "windib" driver and its poor
mouse input.

In order to address these problems I've done the following:

* Remove WM_MOUSEMOVE based motion event generation and replace with
calls to GetCursorPos which seems much more reliable. In order to
achieve this I've moved mouse motion out into a separate function that
is called once per DIB_PumpEvents.

* Remove the restriction on the "directx" driver being inoperable in
combination with OpenGL. There is a bug for this issues that I've
hijacked to a certain extent
(http://bugzilla.libsdl.org/show_bug.cgi?id=265). I'm the first to admit
I don't really understand why this restriction is there in the first
place. The commit message for the bug fix that introduced this
restriction (r581) isn't very elaborate and I couldn't see any other bug
tracking the issue. If anyone has more information on the bug that was
avoided by r581 it would be helpful as I/someone could then look into
addressing the problem without disabling the "directx" driver.

* I've also removed the restriction on not being allowed to use
DirectInput in windowed mode. I couldn't see any reason for this, at
least not from our perspective. I have my suspicions that it'll be
something like matching up the cursor with the mouse coordinates...

* I bumped up the DirectInput API used to version 7 in order to get
access to mouse buttons 4-7. I've had to inject a little bit of the DX7
headers into SDL there as the MinGW ones aren't up to date in this respect.
slouken@1773
     1
slouken@1773
     2
Using SDL under Windows with the OpenWatcom compiler
slouken@1773
     3
====================================================
slouken@1773
     4
slouken@1773
     5
Prerequisites
slouken@1773
     6
-------------
slouken@1773
     7
slouken@1773
     8
I have done the port under Windows XP Home with SP2 installed. Windows
slouken@1773
     9
2000 should also be working. I'm not so sure about ancient Windows NT,
slouken@1773
    10
since only DirectX 3 is available there. Building should be possible,
slouken@1773
    11
but running the compiled applications will probalbly fail with
slouken@1773
    12
SDL_VIDEODRIVER=directx. The windib driver should work, though.
slouken@1773
    13
slouken@1773
    14
To compile and use the SDL with Open Watcom you will need the following:
slouken@1773
    15
- Open Watcom compiler. I used version 1.5. The environment variables
slouken@1773
    16
  PATH, WATCOM and INCLUDE need to be set appropriately - please consult
slouken@1773
    17
  the OpenWatcom documentation and instructions given during the
slouken@1773
    18
  installation of the compiler.
slouken@1773
    19
  My setup looks like this in owvars.bat:
slouken@1773
    20
    set WATCOM=C:\watcom
slouken@1773
    21
    set INCLUDE=%WATCOM%\h;%WATCOM%\h\nt
slouken@1773
    22
    set PATH=%PATH%;%WATCOM%\binnt;%WATCOM%\binw
slouken@1773
    23
- A fairly recent DirectX SDK. The original unmodified DX8 SDK works, as
slouken@1773
    24
  well as the minimal DirectX 7 SDK from the Allegro download site
slouken@1773
    25
  (<http://alleg.sourceforge.net/files/dx70_min.zip>).
slouken@1773
    26
- The SDL sources from Subversion
slouken@1773
    27
- The file Watcom-Win32.zip (now available in Subversion)
slouken@1773
    28
slouken@1773
    29
slouken@1773
    30
Building the Library
slouken@1773
    31
--------------------
slouken@1773
    32
slouken@1773
    33
1) In the SDL base directory extract the archive Watcom-Win32.zip. This
slouken@1773
    34
   creates a subdirectory named 'watcom'.
slouken@1773
    35
2) The makefile expects the environment variable DXDIR to be set to the
slouken@1773
    36
   base directory of a DirectX SDK. I have tried a stock DX8 SDK from
slouken@1773
    37
   Microsoft as well as the minimal DirectX 7 SDK from the Allegro
slouken@1773
    38
   download site.
slouken@1773
    39
   You can also edit the makefile directly and hard code your path to
slouken@1773
    40
   the SDK on your system.
slouken@1773
    41
   I have this in my setup:
slouken@1773
    42
     set DXDIR=D:\devel\DX8_SDK
slouken@1773
    43
3) Enter the watcom directory and run
slouken@1773
    44
     wmake sdl
slouken@1773
    45
4) All tests from the test directory are working and can be built by
slouken@1773
    46
   running
slouken@1773
    47
     wmake tests
slouken@1773
    48
slouken@1773
    49
Notes:
slouken@1773
    50
slouken@1773
    51
 The makefile offers some options to tweak the way the library is built.
slouken@1773
    52
 You have at your disposal the option to build a static (default)
slouken@1773
    53
 library, or a DLL (with tgt=dll). You can also choose whether to build
slouken@1773
    54
 a Release (default) or a Debug version (with build=debug) of the tests
slouken@1773
    55
 and library. Please consult the usage comment at the top of the
slouken@1773
    56
 makefile for usage instructions.
slouken@1773
    57
slouken@1773
    58
 If you specify a test target (i.e. 'wmake tests' for all tests, or
slouken@1773
    59
 selected targets like 'wmake testgl testvidinfo testoverlay2'), the
slouken@1773
    60
 tests are always freshly compiled and linked. This is done to
slouken@1773
    61
 minimise hassle when switching between library versions (static vs.
slouken@1773
    62
 DLL), because they require subtly different options.
slouken@1773
    63
 Also, the test executables are put directly into the test directory,
slouken@1773
    64
 so they can find their data files. The clean target of the makefile
slouken@1773
    65
 removes the test executables and the SDL.dll file from the test
slouken@1773
    66
 directory.
slouken@1773
    67
slouken@1773
    68
 To use the library in your own projects with Open Watcom, you can use
slouken@1773
    69
 the way the tests are built as base of your own build environment.
slouken@1773
    70
slouken@1888
    71
 The library can also be built with the stack calling convention of the
slouken@1888
    72
 compiler (-6s instead of -6r).
slouken@1888
    73
slouken@1773
    74
slouken@1773
    75
Test applications
slouken@1773
    76
-----------------
slouken@1773
    77
slouken@1773
    78
I've tried to make all tests work. The following table gives an overview
slouken@1773
    79
of the current status.
slouken@1773
    80
slouken@1773
    81
 Testname        Status
slouken@1773
    82
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
slouken@1773
    83
checkkeys       +
slouken@1773
    84
graywin         +
slouken@1773
    85
loopwave        +
slouken@1773
    86
testalpha       +
slouken@1773
    87
testbitmap      +
slouken@1773
    88
testdyngl       +
slouken@1773
    89
testerror       +
slouken@1773
    90
testfile        +
slouken@1773
    91
testgamma       +
slouken@1773
    92
testgl          +
slouken@1773
    93
testhread       +
slouken@1773
    94
testiconv       - (all failed)
slouken@1773
    95
testkeys        +
slouken@1773
    96
testlock        +
slouken@1773
    97
testoverlay     + (needs 'set SDL_VIDEODRIVER=directx')
slouken@1773
    98
testoverlay2    + (needs 'set SDL_VIDEODRIVER=directx')
slouken@1773
    99
testpalette     +
slouken@1773
   100
testplatform    +
slouken@1773
   101
testsem         +
slouken@1773
   102
testsprite      +
slouken@1773
   103
testtimer       +
slouken@1773
   104
testver         +
slouken@1773
   105
testvidinfo     +
slouken@1888
   106
testwin         ? (fading doesn't seem right)
slouken@1773
   107
testwm          +
slouken@1773
   108
torturethread   +
slouken@1773
   109
testcdrom       +
slouken@1773
   110
testjoystick    not tested
slouken@1773
   111
threadwin       +
slouken@1888
   112
testcursor      +
slouken@1773
   113
slouken@1773
   114
slouken@1773
   115
TODO
slouken@1773
   116
----
slouken@1773
   117
slouken@1773
   118
There is room for further improvement:
slouken@1773
   119
- Test joystick functionality.
slouken@1773
   120
- Investigate fading issue in 'testwin' test.
slouken@1773
   121
- Fix the UTF-8 support.
slouken@1773
   122
- Adapt the makefile/object file list to support more target systems
slouken@1773
   123
- Use "#pragma aux" syntax for the CPU info functions.
slouken@1773
   124
slouken@1773
   125
slouken@1773
   126
Questions and Comments
slouken@1773
   127
----------------------
slouken@1773
   128
slouken@1773
   129
Please direct any questions or comments to me:  <mailto:macpete@gmx.de>
slouken@1773
   130
slouken@1773
   131
   Happy Coding!
slouken@1773
   132
slouken@1773
   133
   Marc Peter