README.OS2
author Holmes Futrell <hfutrell@umail.ucsb.edu>
Fri, 18 Jul 2008 20:46:02 +0000
branchgsoc2008_iphone
changeset 2378 d76ecec0c3f7
parent 1895 c121d94672cb
child 3244 7c73d5b5a0d6
permissions -rw-r--r--
iPhone SDL 1.3 demos go here. All these demos are written using pure SDL 1.3 code. No compatibility calls! Perhaps if they are any good they could be use as tests for the SDL 1.3 release.
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>