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