diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/libsdl-trunk/README.OS2 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/libsdl-trunk/README.OS2 Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,281 @@ + +=========== +SDL on OS/2 +=========== + +Last updated on May. 17, 2006. + + +1. How to compile? +------------------ + +To compile this, you'll need the followings installed: +- The OS/2 Developer's Toolkit +- The OpenWatcom compiler + (http://www.openwatcom.org) + +First of all, you have to unzip the Watcom-OS2.zip file. This will result in a +file called "makefile" and a file called "setvars.cmd" in this folder (and some +more files...). + +Please edit the second, fourth and fifth lines of setvars.cmd file +to set the folders where the toolkit, the OW compiler and the FSLib are. +You won't need NASM yet (The Netwide Assembler), you can leave that line. +Run setvars.cmd, and you should get a shell in which you can +compile SDL. + +Check the "makefile" file. There is a line in there which determines if the +resulting SDL.DLL will be a 'debug' or a 'release' build. The 'debug' version +is full of printf()'s, so if something goes wrong, its output can help a lot +for debugging. + +Then run "wmake". +This should create the SDL12.DLL and the corresponding SDL12.LIB file here. + +To test applications, it's a good idea to use the 'debug' build of SDL, and +redirect the standard output and standard error output to files, to see what +happens internally in SDL. +(like: testsprite >stdout.txt 2>stderr.txt) + +To rebuild SDL, use the following commands in this folder: +wmake clean +wmake + + + +2. How to compile the testapps? +------------------------------- + +Once you have SDL12.DLL compiled, navigate into the 'test' folder, copy in +there the newly built SDL12.DLL, and copy in there FSLib.DLL. + +Then run "wmake" in there to compile some of the testapps. + + + +3. What is missing? +------------------- + +The following things are missing from this SDL implementation: +- MMX, SSE and 3DNOW! optimized video blitters? +- HW Video surfaces +- OpenGL support + + + +4. Special Keys / Full-Screen support +------------------------------------- + +There are two special hot-keys implemented: +- Alt+Home switches between fullscreen and windowed mode +- Alt+End simulates closing the window (can be used as a Panic key) +Only the LEFT Alt key will work. + + + +5. Joysticks on SDL/2 +--------------------- + +The Joystick detection only works for standard joysticks (2 buttons, 2 axes +and the like). Therefore, if you use a non-standard joystick, you should +specify its features in the SDL_OS2_JOYSTICK environment variable in a batch +file or CONFIG.SYS, so SDL applications can provide full capability to your +device. The syntax is: + +SET SDL_OS2_JOYSTICK=[JOYSTICK_NAME] [AXES] [BUTTONS] [HATS] [BALLS] + +So, it you have a Gravis GamePad with 4 axes, 2 buttons, 2 hats and 0 balls, +the line should be: + +SET SDL_OS2_JOYSTICK=Gravis_GamePad 4 2 2 0 + +If you want to add spaces in your joystick name, just surround it with +quotes or double-quotes: + +SET SDL_OS2_JOYSTICK='Gravis GamePad' 4 2 2 0 + +or + +SET SDL_OS2_JOYSTICK="Gravis GamePad" 4 2 2 0 + + Notive However that Balls and Hats are not supported under OS/2, and the +value will be ignored... but it is wise to define these correctly because +in the future those can be supported. + Also the number of buttons is limited to 2 when using two joysticks, +4 when using one joystick with 4 axes, 6 when using a joystick with 3 axes +and 8 when using a joystick with 2 axes. Notice however these are limitations +of the Joystick Port hardware, not OS/2. + + + +6. Proportional windows +----------------------- + +For some SDL applications it can be handy to have proportional windows, so +the windows will keep their aspect ratio when resized. +This can be achieved in two ways: + +- Before starting the given SDL application, set the + SDL_USE_PROPORTIONAL_WINDOW environment variable to something, e.g.: + + SET SDL_USE_PROPORTIONAL_WINDOW=1 + dosbox.exe + +- If you have a HOME environment variable set, then SDL will look for a file + in there called ".sdl.proportionals". If that file contains the name of the + currently running SDL executable, then that process will have proportional + windows automatically. + + Please note that this file is created automatically with default values + at the first run. + + + +7. Audio in SDL applications +---------------------------- + +Audio effects are one of the most important features in games. Creating audio +effects in sync with the game and without hickups and pauses in the audio are +very important things. + +However there are multithreaded SDL applications that have tight loops as their +main logic loop. This kills performance in OS/2, and takes too much CPU from +other threads in the same process, for example from the thread to create the +sound effects. + +For this reason, the OS/2 port of SDL can be instructed to run the audio thread +in high priority, which makes sure that there will be enough time for the +processing of the audio data. + +At default, SDL/2 runs the audio thread at ForegroundServer+0 priority. Well +written and well behaving SDL applications should work well in this mode. +For other applications, you can tell SDL/2 to run the audio thread at +TimeCritical priority by setting an env.variable before starting the SDL app: + + SET SDL_USE_TIMECRITICAL_AUDIO=1 + +Please note that this is a bit risky, because if the SDL application runs a +tight infinite loop in this thread, this will make the whole system +unresponsive, so use it with care, and only for applications that need it! + + + +8. Next steps... +---------------- + +Things to do: +- Implement missing stuffs (look for 'TODO' string in source code!) +- Finish video driver (the 'wincommon' can be a good example for missing + things like application icon and so on...) +- Enable MMX/SSE/SSE2 acceleration functions +- Rewrite CDROM support using DOS Ioctl for better support. + + + +9. Contacts +----------- + + You can contact the developers for bugs: + + Area Developer email + General (Audio/Video/System) Doodle doodle@scenergy.dfmk.hu + CDROM and Joystick Caetano daniel@caetano.eng.br + + Notice however that SDL/2 is 'in development' stage so ... if you want to help, +please, be our guest and contact us! + + + +10. Changelog of the OS/2 port +------------------------------ + +Version 1.2.10 - 2006-05-17 - Doodle + - Small modifications for v1.2.10 release + - Changed DLL name to include version info (currently SDL12.dll) + +Version 1.2 - 2006-05-01 - Doodle + - Modified makefile system to have only one makefile + - Included FSLib headers, DLL and LIB file + +Version 1.2 - 2006-02-26 - Doodle + - Updated the official SDL version with the OS/2 specific changes. + - Added support for real unicode keycode conversion. + +Version 1.2.7 - 2006-01-20 - Doodle + - Added support for selectively using timecritical priority for + audio threads by SDL_USE_TIMECRITICAL_AUDIO environment variable. + (e.g.: + SET SDL_USE_TIMECRITICAL_AUDIO=1 + dosbox.exe + ) + +Version 1.2.7 - 2005-12-22 - Doodle + - Added support for proportional SDL windows. + There are two ways to have proportional (aspect-keeping) windows for + a given SDL application: Either set the SDL_USE_PROPORTIONAL_WINDOW + environment variable to something before starting the application + (e.g.: + SET SDL_USE_PROPORTIONAL_WINDOW=1 + dosbox.exe + ) + or, if you have the HOME environment variable set, then SDL12.DLL will + create a file in that directory called .sdl.proportionals, and you can + put there the name of executable files that will be automatically made + proportional. + +Version 1.2.7 - 2005-10-14 - Doodle + - Enabled Exception handler code in FSLib to be able to restore original + desktop video mode in case the application crashes. + - Added the missing FSLib_Uninitialize() call into SDL. + (The lack of it did not cause problems, but it's cleaner this way.) + - Fixed a mouse problem in Fullscreen mode where any mouse click + re-centered the mouse. + +Version 1.2.7 - 2005-10-09 - Doodle + - Implemented window icon support + +Version 1.2.7 - 2005-10-03 - Doodle + - Reworked semaphore support again + - Tuned thread priorities + +Version 1.2.7 - 2005-10-02 - Doodle + - Added support for custom mouse pointers + - Fixed WM_CLOSE processing: give a chance to SDL app to ask user... + - Added support for MMX-accelerated audio mixers + - Other small fixes + +Version 1.2.7 - 2005-09-12 - Doodle + - Small fixes for DosBox incorporated into public release + - Fixed semaphore support (SDL_syssem.c) + - Fixed FSLib to have good clipping in scaled window mode, + and to prevent occasional desktop freezes. + +Version 1.2.7 - 2004-09-08a - Caetano + - Improved joystick support (general verifications about hardware). + - Added support up to 8 buttons in 2 axes joysticks and 6 buttons in 3 axes joysticks. + - Added support to environment variable SDL_OS2_JOYSTICK to specify a joystick. + - Improved Joystick test to handle every type of joystick and display only relevant information. + - Merged with Doodle 2004-09-08 + - Little tid up in README.OS2 + - Added explanation about SDL_OS2_JOYSTICK environment variable on README.OS2 + +Version 1.2.7 - 2004-09-07 - Caetano + - Merged with changes in headers for GCC compiling. + - Added Joystick support using basic IBM GAME$ support, allowing it to work with all joystick drivers since OS/2 2.1. + - Improved joystick detection (hacked!). OS/2 do not allow real joystick detection, so... + - 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). + - Created separated Joystick test program to test only joystick functions. + - Improved joystick auto-centering. + - Improved the coordinate correction routine to use two scale factors for each axis. + +Version 1.2.7 - 2004-07-05 - Caetano + - Corrected the time returned by status in CDROM support (it was incorrect) + - Added the testcdrom.c and corrected the linking directive (it was causing an error) + +Version 1.2.7 - 2004-07-02a - Caetano + - Corrected a little problem in a comment at SDL-1.2.7\test\torturethread.c, line 18 (missing */, nested comment) + - Added CDROM support to tree (SDL-1.2.7\src\cdrom\os2\SDL_syscdrom.c) + - Modified makefile (SDL-1.2.7\src\makefiles.wat and SDL-1.2.7\watcom.mif) to build with CDROM support + - Added the "extra" SDL_types.h forgotten in 2004-07-02 version. + +