README.OS2
author Sam Lantinga <slouken@libsdl.org>
Thu, 17 Apr 2014 22:36:14 -0700
branchSDL-1.2
changeset 8716 0aade9c0203f
parent 1850 d5d3a6fe05a1
child 1895 c121d94672cb
permissions -rw-r--r--
Fixed bug 2325 - SDL_EnableUNICODE sometimes drops keyboard events completely

Rafał Mużyło

The most annoying part of this bug is that though I've found it in two separate apps, I don't have a trivial testcase for it.

The problem seems to be a condition race, as it's triggered quite randomly (therefore it will be hard to tell whether it really gets fixed, if a probable fix is found).

While it's specific to SDL 1.2, it seems quite similar to the problem described and fixed in http://forums.libsdl.org/viewtopic.php?p=40503.

Now, I should start describing the problem.

A game uses Escape to open menu (the exact key might not be important). Upon opening, it calls SDL_EnableUNICODE(1). Upon closing it calls SDL_EnableUNICODE(0).

I have an IME running.

Game uses SDL_PollEvent to get the events.

If Escape is pressed repeatedly, menu is opened and closed, till it eventually freezes in open state.
"freezes" in this context means "app itself still runs, but no keyboard events are getting delivered (though - for example - mouse events still are)". "getting delivered" should mean "SDL_PollEvent is not receiving any".
If it matters, the last delivered keyboard event is a keypress, the release never arrives.

It seems (no guarantees, due to random nature of the freeze) that unsetting XMODIFIERS (which - AFAIU - will disable IME as far as SDL is concerned) prevents the freeze, therefore the reference to that SDL2 thread.
icculus@1190
     1
icculus@1190
     2
===========
icculus@1190
     3
SDL on OS/2
icculus@1190
     4
===========
icculus@1190
     5
slouken@1850
     6
Last updated on May. 17, 2006.
icculus@1190
     7
icculus@1190
     8
icculus@1190
     9
1. How to compile?
icculus@1190
    10
------------------
icculus@1190
    11
icculus@1190
    12
To compile this, you'll need the followings installed:
icculus@1190
    13
- The OS/2 Developer's Toolkit
icculus@1190
    14
- The OpenWatcom compiler 
icculus@1190
    15
  (http://www.openwatcom.org)
icculus@1190
    16
slouken@1758
    17
First of all, you have to unzip the Watcom-OS2.zip file. This will result in a 
slouken@1758
    18
file called "makefile" and a file called "setvars.cmd" in this folder (and some
slouken@1758
    19
more files...).
slouken@1442
    20
icculus@1190
    21
Please edit the second, fourth and fifth lines of setvars.cmd file
icculus@1190
    22
to set the folders where the toolkit, the OW compiler and the FSLib are. 
icculus@1190
    23
You won't need NASM yet (The Netwide Assembler), you can leave that line.
icculus@1190
    24
Run setvars.cmd, and you should get a shell in which you can
icculus@1190
    25
compile SDL.
icculus@1190
    26
slouken@1758
    27
Check the "makefile" file. There is a line in there which determines if the 
slouken@1758
    28
resulting SDL.DLL will be a 'debug' or a 'release' build. The 'debug' version 
slouken@1758
    29
is full of printf()'s, so if something goes wrong, its output can help a lot
slouken@1758
    30
for debugging.
icculus@1190
    31
slouken@1758
    32
Then run "wmake".
slouken@1850
    33
This should create the SDL12.DLL and the corresponding SDL12.LIB file here.
icculus@1190
    34
icculus@1190
    35
To test applications, it's a good idea to use the 'debug' build of SDL, and
icculus@1190
    36
redirect the standard output and standard error output to files, to see what
icculus@1190
    37
happens internally in SDL.
icculus@1190
    38
(like: testsprite >stdout.txt 2>stderr.txt)
icculus@1190
    39
slouken@1758
    40
To rebuild SDL, use the following commands in this folder:
slouken@1758
    41
wmake clean
slouken@1758
    42
wmake
icculus@1190
    43
icculus@1190
    44
icculus@1190
    45
icculus@1190
    46
2. How to compile the testapps?
icculus@1190
    47
-------------------------------
icculus@1190
    48
slouken@1850
    49
Once you have SDL12.DLL compiled, navigate into the 'test' folder, copy in 
slouken@1850
    50
there the newly built SDL12.DLL, and copy in there FSLib.DLL.
icculus@1190
    51
slouken@1758
    52
Then run "wmake" in there to compile some of the testapps.
icculus@1190
    53
icculus@1190
    54
icculus@1190
    55
icculus@1190
    56
3. What is missing?
icculus@1190
    57
-------------------
icculus@1190
    58
icculus@1190
    59
The following things are missing from this SDL implementation:
icculus@1190
    60
- MMX, SSE and 3DNOW! optimized video blitters?
icculus@1190
    61
- HW Video surfaces
icculus@1190
    62
- OpenGL support
icculus@1190
    63
icculus@1190
    64
icculus@1190
    65
icculus@1190
    66
4. Special Keys / Full-Screen support
icculus@1190
    67
-------------------------------------
icculus@1190
    68
icculus@1190
    69
There are two special hot-keys implemented:
icculus@1190
    70
- Alt+Home switches between fullscreen and windowed mode
icculus@1190
    71
- Alt+End simulates closing the window (can be used as a Panic key)
icculus@1190
    72
Only the LEFT Alt key will work.
icculus@1190
    73
icculus@1190
    74
icculus@1190
    75
icculus@1190
    76
5. Joysticks on SDL/2
icculus@1190
    77
---------------------
icculus@1190
    78
icculus@1190
    79
The Joystick detection only works for standard joysticks (2 buttons, 2 axes
icculus@1190
    80
and the like). Therefore, if you use a non-standard joystick, you should
icculus@1190
    81
specify its features in the SDL_OS2_JOYSTICK environment variable in a batch
icculus@1190
    82
file or CONFIG.SYS, so SDL applications can provide full capability to your
icculus@1190
    83
device. The syntax is:
icculus@1190
    84
icculus@1190
    85
SET SDL_OS2_JOYSTICK=[JOYSTICK_NAME] [AXES] [BUTTONS] [HATS] [BALLS]
icculus@1190
    86
icculus@1190
    87
So, it you have a Gravis GamePad with 4 axes, 2 buttons, 2 hats and 0 balls,
icculus@1190
    88
the line should be:
icculus@1190
    89
icculus@1190
    90
SET SDL_OS2_JOYSTICK=Gravis_GamePad 4 2 2 0
icculus@1190
    91
icculus@1190
    92
If you want to add spaces in your joystick name, just surround it with
icculus@1190
    93
quotes or double-quotes:
icculus@1190
    94
icculus@1190
    95
SET SDL_OS2_JOYSTICK='Gravis GamePad' 4 2 2 0
icculus@1190
    96
icculus@1190
    97
or
icculus@1190
    98
icculus@1190
    99
SET SDL_OS2_JOYSTICK="Gravis GamePad" 4 2 2 0
icculus@1190
   100
icculus@1190
   101
   Notive However that Balls and Hats are not supported under OS/2, and the
icculus@1190
   102
value will be ignored... but it is wise to define these correctly because 
icculus@1190
   103
in the future those can be supported.
icculus@1190
   104
   Also the number of buttons is limited to 2 when using two joysticks,
icculus@1190
   105
4 when using one joystick with 4 axes, 6 when using a joystick with 3 axes
icculus@1190
   106
and 8 when using a joystick with 2 axes. Notice however these are limitations 
icculus@1190
   107
of the Joystick Port hardware, not OS/2.
icculus@1190
   108
icculus@1190
   109
icculus@1190
   110
slouken@1442
   111
6. Proportional windows
slouken@1442
   112
-----------------------
slouken@1442
   113
slouken@1442
   114
For some SDL applications it can be handy to have proportional windows, so
slouken@1442
   115
the windows will keep their aspect ratio when resized.
slouken@1442
   116
This can be achieved in two ways:
slouken@1442
   117
slouken@1442
   118
- Before starting the given SDL application, set the
slouken@1442
   119
  SDL_USE_PROPORTIONAL_WINDOW environment variable to something, e.g.:
slouken@1442
   120
slouken@1442
   121
  SET SDL_USE_PROPORTIONAL_WINDOW=1
slouken@1442
   122
  dosbox.exe
slouken@1442
   123
slouken@1442
   124
- If you have a HOME environment variable set, then SDL will look for a file
slouken@1442
   125
  in there called ".sdl.proportionals". If that file contains the name of the
slouken@1442
   126
  currently running SDL executable, then that process will have proportional
slouken@1442
   127
  windows automatically.
slouken@1442
   128
slouken@1442
   129
  Please note that this file is created automatically with default values
slouken@1442
   130
  at the first run.
slouken@1442
   131
slouken@1442
   132
slouken@1442
   133
slouken@1442
   134
7. Audio in SDL applications
slouken@1442
   135
----------------------------
slouken@1442
   136
slouken@1442
   137
Audio effects are one of the most important features in games. Creating audio
slouken@1442
   138
effects in sync with the game and without hickups and pauses in the audio are
slouken@1442
   139
very important things.
slouken@1442
   140
slouken@1442
   141
However there are multithreaded SDL applications that have tight loops as their
slouken@1442
   142
main logic loop. This kills performance in OS/2, and takes too much CPU from
slouken@1442
   143
other threads in the same process, for example from the thread to create the 
slouken@1442
   144
sound effects.
slouken@1442
   145
slouken@1442
   146
For this reason, the OS/2 port of SDL can be instructed to run the audio thread
slouken@1442
   147
in high priority, which makes sure that there will be enough time for the 
slouken@1442
   148
processing of the audio data.
slouken@1442
   149
slouken@1442
   150
At default, SDL/2 runs the audio thread at ForegroundServer+0 priority. Well 
slouken@1442
   151
written and well behaving SDL applications should work well in this mode.
slouken@1442
   152
For other applications, you can tell SDL/2 to run the audio thread at 
slouken@1442
   153
TimeCritical priority by setting an env.variable before starting the SDL app:
slouken@1442
   154
slouken@1442
   155
    SET SDL_USE_TIMECRITICAL_AUDIO=1
slouken@1442
   156
slouken@1442
   157
Please note that this is a bit risky, because if the SDL application runs a
slouken@1442
   158
tight infinite loop in this thread, this will make the whole system 
slouken@1442
   159
unresponsive, so use it with care, and only for applications that need it!
slouken@1442
   160
slouken@1442
   161
slouken@1442
   162
slouken@1442
   163
8. Next steps...
icculus@1190
   164
----------------
icculus@1190
   165
icculus@1190
   166
Things to do:
icculus@1190
   167
- Implement missing stuffs (look for 'TODO' string in source code!)
icculus@1190
   168
- Finish video driver (the 'wincommon' can be a good example for missing
icculus@1190
   169
  things like application icon and so on...)
icculus@1190
   170
- Enable MMX/SSE/SSE2 acceleration functions
icculus@1190
   171
- Rewrite CDROM support using DOS Ioctl for better support.
icculus@1190
   172
icculus@1190
   173
icculus@1190
   174
slouken@1442
   175
9. Contacts
icculus@1190
   176
-----------
icculus@1190
   177
icculus@1190
   178
   You can contact the developers for bugs:
icculus@1190
   179
icculus@1190
   180
   Area					Developer		email
icculus@1190
   181
   General (Audio/Video/System)		Doodle			doodle@scenergy.dfmk.hu
icculus@1190
   182
   CDROM and Joystick			Caetano			daniel@caetano.eng.br
icculus@1190
   183
icculus@1190
   184
   Notice however that SDL/2 is 'in development' stage so ... if you want to help,
icculus@1190
   185
please, be our guest and contact us!
icculus@1190
   186
slouken@1442
   187
slouken@1442
   188
slouken@1442
   189
10. Changelog of the OS/2 port
slouken@1442
   190
------------------------------
slouken@1442
   191
slouken@1850
   192
Version 1.2.10 - 2006-05-17  - Doodle
slouken@1850
   193
 - Small modifications for v1.2.10 release
slouken@1850
   194
 - Changed DLL name to include version info (currently SDL12.dll)
slouken@1850
   195
slouken@1758
   196
Version 1.2 - 2006-05-01  - Doodle
slouken@1758
   197
 - Modified makefile system to have only one makefile
slouken@1758
   198
 - Included FSLib headers, DLL and LIB file
slouken@1758
   199
slouken@1442
   200
Version 1.2 - 2006-02-26  - Doodle
slouken@1442
   201
 - Updated the official SDL version with the OS/2 specific changes.
slouken@1442
   202
 - Added support for real unicode keycode conversion.
slouken@1442
   203
slouken@1442
   204
Version 1.2.7 - 2006-01-20  - Doodle
slouken@1442
   205
 - Added support for selectively using timecritical priority for
slouken@1442
   206
   audio threads by SDL_USE_TIMECRITICAL_AUDIO environment variable.
slouken@1442
   207
   (e.g.: 
slouken@1442
   208
    SET SDL_USE_TIMECRITICAL_AUDIO=1
slouken@1442
   209
    dosbox.exe
slouken@1442
   210
   )
slouken@1442
   211
slouken@1442
   212
Version 1.2.7 - 2005-12-22  - Doodle
slouken@1442
   213
 - Added support for proportional SDL windows.
slouken@1442
   214
   There are two ways to have proportional (aspect-keeping) windows for
slouken@1442
   215
   a given SDL application: Either set the SDL_USE_PROPORTIONAL_WINDOW
slouken@1442
   216
   environment variable to something before starting the application
slouken@1442
   217
   (e.g.: 
slouken@1442
   218
    SET SDL_USE_PROPORTIONAL_WINDOW=1
slouken@1442
   219
    dosbox.exe
slouken@1442
   220
   )
slouken@1850
   221
   or, if you have the HOME environment variable set, then SDL12.DLL will
slouken@1442
   222
   create a file in that directory called .sdl.proportionals, and you can
slouken@1442
   223
   put there the name of executable files that will be automatically made
slouken@1442
   224
   proportional.
slouken@1442
   225
slouken@1442
   226
Version 1.2.7 - 2005-10-14  - Doodle
slouken@1442
   227
 - Enabled Exception handler code in FSLib to be able to restore original
slouken@1442
   228
   desktop video mode in case the application crashes.
slouken@1442
   229
 - Added the missing FSLib_Uninitialize() call into SDL.
slouken@1442
   230
   (The lack of it did not cause problems, but it's cleaner this way.)
slouken@1442
   231
 - Fixed a mouse problem in Fullscreen mode where any mouse click
slouken@1442
   232
   re-centered the mouse.
slouken@1442
   233
slouken@1442
   234
Version 1.2.7 - 2005-10-09  - Doodle
slouken@1442
   235
 - Implemented window icon support
slouken@1442
   236
slouken@1442
   237
Version 1.2.7 - 2005-10-03  - Doodle
slouken@1442
   238
 - Reworked semaphore support again
slouken@1442
   239
 - Tuned thread priorities
slouken@1442
   240
slouken@1442
   241
Version 1.2.7 - 2005-10-02  - Doodle
slouken@1442
   242
 - Added support for custom mouse pointers
slouken@1442
   243
 - Fixed WM_CLOSE processing: give a chance to SDL app to ask user...
slouken@1442
   244
 - Added support for MMX-accelerated audio mixers
slouken@1442
   245
 - Other small fixes
slouken@1442
   246
slouken@1442
   247
Version 1.2.7 - 2005-09-12  - Doodle
slouken@1442
   248
 - Small fixes for DosBox incorporated into public release
slouken@1442
   249
 - Fixed semaphore support (SDL_syssem.c)
slouken@1442
   250
 - Fixed FSLib to have good clipping in scaled window mode,
slouken@1442
   251
   and to prevent occasional desktop freezes.
slouken@1442
   252
slouken@1442
   253
Version 1.2.7 - 2004-09-08a - Caetano
slouken@1442
   254
	- Improved joystick support (general verifications about hardware).
slouken@1442
   255
	- Added support up to 8 buttons in 2 axes joysticks and 6 buttons in 3 axes joysticks.
slouken@1442
   256
	- Added support to environment variable SDL_OS2_JOYSTICK to specify a joystick.
slouken@1442
   257
	- Improved Joystick test to handle every type of joystick and display only relevant information.
slouken@1442
   258
	- Merged with Doodle 2004-09-08
slouken@1442
   259
	- Little tid up in README.OS2
slouken@1442
   260
	- Added explanation about SDL_OS2_JOYSTICK environment variable on README.OS2
slouken@1442
   261
slouken@1442
   262
Version 1.2.7 - 2004-09-07 - Caetano
slouken@1442
   263
	- Merged with changes in headers for GCC compiling.
slouken@1442
   264
	- Added Joystick support using basic IBM GAME$ support, allowing it to work with all joystick drivers since OS/2 2.1.
slouken@1442
   265
	- Improved joystick detection (hacked!). OS/2 do not allow real joystick detection, so... 
slouken@1442
   266
	- Modified makefile in test to compile "testjoystick". Anyway, it's useless, since it seems to cause a lot of trouble in OS/2 (because os video routines, not Joystick support).
slouken@1442
   267
	- Created separated Joystick test program to test only joystick functions.
slouken@1442
   268
	- Improved joystick auto-centering.
slouken@1442
   269
	- Improved the coordinate correction routine to use two scale factors for each axis.
slouken@1442
   270
slouken@1442
   271
Version 1.2.7 - 2004-07-05 - Caetano
slouken@1442
   272
	- Corrected the time returned by status in CDROM support (it was incorrect)
slouken@1442
   273
	- Added the testcdrom.c and corrected the linking directive (it was causing an error)
slouken@1442
   274
slouken@1442
   275
Version 1.2.7 - 2004-07-02a - Caetano
slouken@1442
   276
	- Corrected a little problem in a comment at SDL-1.2.7\test\torturethread.c, line 18 (missing */, nested comment)
slouken@1442
   277
	- Added CDROM support to tree (SDL-1.2.7\src\cdrom\os2\SDL_syscdrom.c)
slouken@1442
   278
	- Modified makefile (SDL-1.2.7\src\makefiles.wat and SDL-1.2.7\watcom.mif) to build with CDROM support
slouken@1442
   279
	- Added the "extra" SDL_types.h forgotten in 2004-07-02 version.
slouken@1442
   280
slouken@1442
   281
<End-Of-File>