annotate README.OS2 @ 1629:ef4a796e7f24

Fixed bug #55 From Christian Walther: When writing my patch for #12, I ended up doing all sorts of changes to the way application/window activating/deactivating is handled in the Quartz backend, resulting in the attached patch. It does make the code a bit cleaner IMHO, but as it might be regarded as a case of "if it ain't broken, don't fix it" I'd like to hear other people's opinion about it. Please shout if some change strikes you as unnecessary or wrong, and I'll explain the reasons behind it. As far as I tested it, it does not introduce any new bugs, but I may well have missed some. - The most fundamental change (that triggered most of the others) is irrelevant for the usual single-window SDL applications, it only affects the people who are crazy enough to display other Cocoa windows alongside the SDL window (I'm actually doing this currently, although the additional window only displays debugging info and won't be present in the final product): Before, some things were done on the application becoming active, some on the window becoming key, and some on the window becoming main. Conceptually, all these actions belong to the window becoming key, so that's what I implemented. However, since in a single-window application these three events always happen together, the previous implementation "ain't broken". - This slightly changed the meaning of the SDL_APPMOUSEFOCUS flag from SDL_GetAppState(): Before, it meant "window is main and mouse is inside window (or mode is fullscreen)". Now, it means "window is key and mouse is inside window (or mode is fullscreen)". It makes more sense to me that way. (See http://developer.apple.com/documentation/Cocoa/Conceptual/WinPanel/Concepts/ChangingMainKeyWindow.html for a discussion of what key and main windows are.) The other two flags are unchanged: SDL_APPACTIVE = application is not hidden and window is not minimized, SDL_APPINPUTFOCUS = window is key (or mode is fullscreen). - As a side effect, the reorganization fixes the following two issues (and maybe others) (but they could also be fixed in less invasive ways): * A regression that was introduced in revision 1.42 of SDL_QuartzVideo.m (http://libsdl.org/cgi/cvsweb.cgi/SDL12/src/video/quartz/SDL_QuartzVideo.m.diff?r1=1.41&r2=1.42) (from half-desirable to undesirable behavior): Situation: While in windowed mode, hide the cursor using SDL_ShowCursor(SDL_DISABLE), move the mouse outside of the window so that the cursor becomes visible again, and SDL_SetVideoMode() to a fullscreen mode. What happened before revision 1.42: The cursor is visible, but becomes invisible as soon as the mouse is moved (half-desirable). What happens in revision 1.42 and after (including current CVS): The cursor is visible and stays visible (undesirable). What happens after my patch: The cursor is invisible from the beginning (desirable). * When the cursor is hidden and grabbed, switch away from the application using cmd-tab (which ungrabs and makes the cursor visible), move the cursor outside of the SDL window, then cmd-tab back to the application. In 1.2.8 and in the current CVS, the cursor is re-grabbed, but it stays visible (immovable in the middle of the window). With my patch, the cursor is correctly re-grabbed and hidden. (For some reason, it still doesn't work correctly if you switch back to the application using the dock instead of cmd-tab. I haven't been able to figure out why. I can step over [NSCursor hide] being called in the debugger, but it seems to have no effect.) - The patch includes my patch for #12 (it was easier to obtain using cvs diff that way). If you apply both of them, you will end up with 6 duplicate lines in SDL_QuartzEvents.m.
author Sam Lantinga <slouken@libsdl.org>
date Thu, 13 Apr 2006 14:17:48 +0000
parents e3242177fe4a
children 14717b52abc0
rev   line source
1190
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
1
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
2 ===========
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
3 SDL on OS/2
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
4 ===========
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
5
1442
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
6 Last updated on Feb. 26, 2006.
1190
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
7
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
8
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
9 1. How to compile?
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
10 ------------------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
11
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
12 To compile this, you'll need the followings installed:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
13 - The OS/2 Developer's Toolkit
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
14 - The OpenWatcom compiler
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
15 (http://www.openwatcom.org)
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
16 - The FSLib library
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
17 (ftp://ftp.netlabs.org/pub/SDL)
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
18
1442
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
19 First of all, you have to put the OS/2-specific Watcom makefiles into the
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
20 source code tree by unzipping the file Watcom-OS2.zip here. This will
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
21 result in a Watcom.mif and a setvars.cmd file in this folder, and several
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
22 Makefile.wat files in the src\ folder and in some of its subfolders.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
23
1190
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
24 Please edit the second, fourth and fifth lines of setvars.cmd file
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
25 to set the folders where the toolkit, the OW compiler and the FSLib are.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
26 You won't need NASM yet (The Netwide Assembler), you can leave that line.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
27 Run setvars.cmd, and you should get a shell in which you can
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
28 compile SDL.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
29
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
30 Check the "Watcom.mif" file. This is the file which is included by all the
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
31 Watcom makefiles, so changes here will affect the whole build process.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
32 There is a line in there which determines if the resulting SDL.DLL will be
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
33 a 'debug' or a 'release' build. The 'debug' version is full of printf()'s,
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
34 so if something goes wrong, its output can help a lot for debugging.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
35
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
36 Then go to the 'src' folder, and run "wmake -f makefile.wat".
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
37 This should create the SDL.DLL and the corresponding SDL.LIB file there.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
38
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
39 To test applications, it's a good idea to use the 'debug' build of SDL, and
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
40 redirect the standard output and standard error output to files, to see what
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
41 happens internally in SDL.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
42 (like: testsprite >stdout.txt 2>stderr.txt)
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
43
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
44 To rebuild SDL, use the following commands in 'src' folder:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
45 wmake -f makefile.wat clean
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
46 wmake -f makefile.wat
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
47
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
48
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
49
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
50 2. How to compile the testapps?
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
51 -------------------------------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
52
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
53 Once you have SDL.DLL compiled, navigate into the 'test' folder, copy in there
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
54 the newly built SDL.DLL, and copy in there FSLib.DLL.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
55
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
56 Then run "wmake -f makefile.wat" in there to compile some of the testapps.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
57
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
58
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
59
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
60 3. What is missing?
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
61 -------------------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
62
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
63 The following things are missing from this SDL implementation:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
64 - MMX, SSE and 3DNOW! optimized video blitters?
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
65 - HW Video surfaces
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
66 - OpenGL support
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
67
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
68
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
69
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
70 4. Special Keys / Full-Screen support
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
71 -------------------------------------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
72
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
73 There are two special hot-keys implemented:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
74 - Alt+Home switches between fullscreen and windowed mode
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
75 - Alt+End simulates closing the window (can be used as a Panic key)
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
76 Only the LEFT Alt key will work.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
77
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
78
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
79
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
80 5. Joysticks on SDL/2
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
81 ---------------------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
82
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
83 The Joystick detection only works for standard joysticks (2 buttons, 2 axes
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
84 and the like). Therefore, if you use a non-standard joystick, you should
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
85 specify its features in the SDL_OS2_JOYSTICK environment variable in a batch
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
86 file or CONFIG.SYS, so SDL applications can provide full capability to your
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
87 device. The syntax is:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
88
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
89 SET SDL_OS2_JOYSTICK=[JOYSTICK_NAME] [AXES] [BUTTONS] [HATS] [BALLS]
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
90
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
91 So, it you have a Gravis GamePad with 4 axes, 2 buttons, 2 hats and 0 balls,
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
92 the line should be:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
93
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
94 SET SDL_OS2_JOYSTICK=Gravis_GamePad 4 2 2 0
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
95
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
96 If you want to add spaces in your joystick name, just surround it with
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
97 quotes or double-quotes:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
98
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
99 SET SDL_OS2_JOYSTICK='Gravis GamePad' 4 2 2 0
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
100
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
101 or
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
102
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
103 SET SDL_OS2_JOYSTICK="Gravis GamePad" 4 2 2 0
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
104
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
105 Notive However that Balls and Hats are not supported under OS/2, and the
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
106 value will be ignored... but it is wise to define these correctly because
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
107 in the future those can be supported.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
108 Also the number of buttons is limited to 2 when using two joysticks,
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
109 4 when using one joystick with 4 axes, 6 when using a joystick with 3 axes
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
110 and 8 when using a joystick with 2 axes. Notice however these are limitations
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
111 of the Joystick Port hardware, not OS/2.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
112
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
113
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
114
1442
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
115 6. Proportional windows
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
116 -----------------------
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
117
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
118 For some SDL applications it can be handy to have proportional windows, so
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
119 the windows will keep their aspect ratio when resized.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
120 This can be achieved in two ways:
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
121
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
122 - Before starting the given SDL application, set the
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
123 SDL_USE_PROPORTIONAL_WINDOW environment variable to something, e.g.:
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
124
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
125 SET SDL_USE_PROPORTIONAL_WINDOW=1
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
126 dosbox.exe
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
127
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
128 - If you have a HOME environment variable set, then SDL will look for a file
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
129 in there called ".sdl.proportionals". If that file contains the name of the
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
130 currently running SDL executable, then that process will have proportional
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
131 windows automatically.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
132
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
133 Please note that this file is created automatically with default values
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
134 at the first run.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
135
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
136
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
137
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
138 7. Audio in SDL applications
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
139 ----------------------------
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
140
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
141 Audio effects are one of the most important features in games. Creating audio
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
142 effects in sync with the game and without hickups and pauses in the audio are
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
143 very important things.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
144
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
145 However there are multithreaded SDL applications that have tight loops as their
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
146 main logic loop. This kills performance in OS/2, and takes too much CPU from
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
147 other threads in the same process, for example from the thread to create the
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
148 sound effects.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
149
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
150 For this reason, the OS/2 port of SDL can be instructed to run the audio thread
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
151 in high priority, which makes sure that there will be enough time for the
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
152 processing of the audio data.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
153
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
154 At default, SDL/2 runs the audio thread at ForegroundServer+0 priority. Well
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
155 written and well behaving SDL applications should work well in this mode.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
156 For other applications, you can tell SDL/2 to run the audio thread at
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
157 TimeCritical priority by setting an env.variable before starting the SDL app:
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
158
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
159 SET SDL_USE_TIMECRITICAL_AUDIO=1
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
160
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
161 Please note that this is a bit risky, because if the SDL application runs a
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
162 tight infinite loop in this thread, this will make the whole system
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
163 unresponsive, so use it with care, and only for applications that need it!
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
164
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
165
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
166
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
167 8. Next steps...
1190
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
168 ----------------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
169
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
170 Things to do:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
171 - Implement missing stuffs (look for 'TODO' string in source code!)
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
172 - Finish video driver (the 'wincommon' can be a good example for missing
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
173 things like application icon and so on...)
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
174 - Enable MMX/SSE/SSE2 acceleration functions
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
175 - Rewrite CDROM support using DOS Ioctl for better support.
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
176
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
177
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
178
1442
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
179 9. Contacts
1190
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
180 -----------
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
181
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
182 You can contact the developers for bugs:
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
183
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
184 Area Developer email
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
185 General (Audio/Video/System) Doodle doodle@scenergy.dfmk.hu
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
186 CDROM and Joystick Caetano daniel@caetano.eng.br
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
187
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
188 Notice however that SDL/2 is 'in development' stage so ... if you want to help,
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
189 please, be our guest and contact us!
173c063d4f55 OS/2 port!
Ryan C. Gordon <icculus@icculus.org>
parents:
diff changeset
190
1442
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
191
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
192
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
193 10. Changelog of the OS/2 port
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
194 ------------------------------
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
195
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
196 Version 1.2 - 2006-02-26 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
197 - Updated the official SDL version with the OS/2 specific changes.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
198 - Added support for real unicode keycode conversion.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
199
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
200 Version 1.2.7 - 2006-01-20 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
201 - Added support for selectively using timecritical priority for
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
202 audio threads by SDL_USE_TIMECRITICAL_AUDIO environment variable.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
203 (e.g.:
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
204 SET SDL_USE_TIMECRITICAL_AUDIO=1
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
205 dosbox.exe
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
206 )
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
207
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
208 Version 1.2.7 - 2005-12-22 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
209 - Added support for proportional SDL windows.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
210 There are two ways to have proportional (aspect-keeping) windows for
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
211 a given SDL application: Either set the SDL_USE_PROPORTIONAL_WINDOW
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
212 environment variable to something before starting the application
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
213 (e.g.:
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
214 SET SDL_USE_PROPORTIONAL_WINDOW=1
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
215 dosbox.exe
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
216 )
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
217 or, if you have the HOME environment variable set, then SDL.DLL will
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
218 create a file in that directory called .sdl.proportionals, and you can
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
219 put there the name of executable files that will be automatically made
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
220 proportional.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
221
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
222 Version 1.2.7 - 2005-10-14 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
223 - Enabled Exception handler code in FSLib to be able to restore original
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
224 desktop video mode in case the application crashes.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
225 - Added the missing FSLib_Uninitialize() call into SDL.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
226 (The lack of it did not cause problems, but it's cleaner this way.)
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
227 - Fixed a mouse problem in Fullscreen mode where any mouse click
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
228 re-centered the mouse.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
229
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
230 Version 1.2.7 - 2005-10-09 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
231 - Implemented window icon support
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
232
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
233 Version 1.2.7 - 2005-10-03 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
234 - Reworked semaphore support again
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
235 - Tuned thread priorities
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
236
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
237 Version 1.2.7 - 2005-10-02 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
238 - Added support for custom mouse pointers
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
239 - Fixed WM_CLOSE processing: give a chance to SDL app to ask user...
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
240 - Added support for MMX-accelerated audio mixers
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
241 - Other small fixes
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
242
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
243 Version 1.2.7 - 2005-09-12 - Doodle
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
244 - Small fixes for DosBox incorporated into public release
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
245 - Fixed semaphore support (SDL_syssem.c)
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
246 - Fixed FSLib to have good clipping in scaled window mode,
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
247 and to prevent occasional desktop freezes.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
248
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
249 Version 1.2.7 - 2004-09-08a - Caetano
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
250 - Improved joystick support (general verifications about hardware).
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
251 - Added support up to 8 buttons in 2 axes joysticks and 6 buttons in 3 axes joysticks.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
252 - Added support to environment variable SDL_OS2_JOYSTICK to specify a joystick.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
253 - Improved Joystick test to handle every type of joystick and display only relevant information.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
254 - Merged with Doodle 2004-09-08
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
255 - Little tid up in README.OS2
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
256 - Added explanation about SDL_OS2_JOYSTICK environment variable on README.OS2
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
257
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
258 Version 1.2.7 - 2004-09-07 - Caetano
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
259 - Merged with changes in headers for GCC compiling.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
260 - Added Joystick support using basic IBM GAME$ support, allowing it to work with all joystick drivers since OS/2 2.1.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
261 - Improved joystick detection (hacked!). OS/2 do not allow real joystick detection, so...
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
262 - 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).
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
263 - Created separated Joystick test program to test only joystick functions.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
264 - Improved joystick auto-centering.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
265 - Improved the coordinate correction routine to use two scale factors for each axis.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
266
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
267 Version 1.2.7 - 2004-07-05 - Caetano
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
268 - Corrected the time returned by status in CDROM support (it was incorrect)
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
269 - Added the testcdrom.c and corrected the linking directive (it was causing an error)
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
270
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
271 Version 1.2.7 - 2004-07-02a - Caetano
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
272 - Corrected a little problem in a comment at SDL-1.2.7\test\torturethread.c, line 18 (missing */, nested comment)
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
273 - Added CDROM support to tree (SDL-1.2.7\src\cdrom\os2\SDL_syscdrom.c)
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
274 - Modified makefile (SDL-1.2.7\src\makefiles.wat and SDL-1.2.7\watcom.mif) to build with CDROM support
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
275 - Added the "extra" SDL_types.h forgotten in 2004-07-02 version.
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
276
e3242177fe4a Updated OS/2 build, yay!
Sam Lantinga <slouken@libsdl.org>
parents: 1190
diff changeset
277 <End-Of-File>