README.OS2
author Ryan C. Gordon <icculus@icculus.org>
Fri, 15 Jun 2007 07:19:05 +0000
branchSDL-1.2
changeset 3965 19d708301fab
parent 1850 d5d3a6fe05a1
child 1895 c121d94672cb
permissions -rw-r--r--
Make sure __inline__ isn't defined before #defining it, since some compilers
(like Sun Studio) have this as a predefined macro.

Fixes Bugzilla #434.
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>