annotate docs/man3/SDL_OpenAudio.3 @ 563:04dcaf3da918

Massive Quartz input enhancements from Darrell Walisser. His email: Enclosed is a patch that addresses the following: --Various minor cleanups. Removed dead/obsolete code, made some style cleanups --Mouse Events Now keep track of what button(s) were pressed so we know when to send the mouse up event. This fixes the case where the mouse is dragged outside of the game window and released (in which case we want to send the mouse up event even though the mouse is outside the game window). --Input Grabbing Here is my take on the grabbing situation, which is the basis for the new implementation. There are 3 grab states, ungrabbed (UG), visible (VG), and invisible (IG). Both VG and IG keep the mouse constrained to the window and produce relative motion events. In VG the cursor is visible (duh), in IG it is not. In VG, absolute motion events also work. There are 6 actions that can affect grabbing: 1. Set Fullscreen/Window (F/W). In fullscreen, a visible grab should do nothing. However, a fullscreen visible grab can be treated just like a windowed visible grab, which is what I have done to help simplify things. 2. Cursor hide/show (H/S). If the cursor is hidden when grabbing, the grab is an invisible grab. If the cursor is visible, the grab should just constrain the mouse to the window. 3. Input grab/ungrab(G/U). If grabbed, the cursor should be confined to the window as should the keyboard input. On Mac OS X, the keyboard input is implicitly grabbed by confining the cursor, except for command-tab which can switch away from the application. Should the window come to the foreground if the application is deactivated and grab input is called? This isn't necessary in this implementation because the grab state will be asserted upon activation. Using my notation, these are all the cases that need to be handled (state + action = new state). UG+U = UG UG+G = VG or IG, if cursor is visible or not UG+H = UG UG+S = UG VG+U = UG VG+G = VG VG+H = IG VG+S = VG IG+U = UG IG+G = IG IG+H = IG IG+S = VG The cases that result in the same state can be ignored in the code, which cuts it down to just 5 cases. Another issue is what happens when the app loses/gains input focus from deactivate/activate or iconify/deiconify. I think that if input focus is ever lost (outside of SDL's control), the grab state should be suspended and the cursor should become visible and active again. When regained, the cursor should reappear in its original location and/or grab state. This way, when reactivating the cursor is still in the same position as before so apps shouldn't get confused when the next motion event comes in. This is what I've done in this patch.
author Ryan C. Gordon <icculus@icculus.org>
date Fri, 27 Dec 2002 20:52:41 +0000
parents e5bc29de3f0a
children 546f7c1eb755
rev   line source
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
1 .TH "SDL_OpenAudio" "3" "Tue 11 Sep 2001, 22:58" "SDL" "SDL API Reference"
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
2 .SH "NAME"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
3 SDL_OpenAudio\- Opens the audio device with the desired parameters\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
4 .SH "SYNOPSIS"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
5 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
6 \fB#include "SDL\&.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
7 .sp
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
8 \fBint \fBSDL_OpenAudio\fP\fR(\fBSDL_AudioSpec *desired, SDL_AudioSpec *obtained\fR);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
9 .SH "DESCRIPTION"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
10 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
11 This function opens the audio device with the \fBdesired\fR parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by \fBobtained\fR\&. If \fBobtained\fR is NULL, the audio data passed to the callback function will be guaranteed to be in the requested format, and will be automatically converted to the hardware audio format if necessary\&. This function returns -1 if it failed to open the audio device, or couldn\&'t set up the audio thread\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
12 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
13 To open the audio device a \fBdesired\fR \fI\fBSDL_AudioSpec\fR\fR must be created\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
14 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
15 .nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
16 \f(CWSDL_AudioSpec *desired;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
17 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
18 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
19 desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
20 .fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
21 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
22 You must then fill this structure with your desired audio specifications\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
23 .IP "\fBdesired\fR->\fBfreq\fR" 10The desired audio frequency in samples-per-second\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
24 .IP "\fBdesired\fR->\fBformat\fR" 10The desired audio format (see \fI\fBSDL_AudioSpec\fR\fR)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
25 .IP "\fBdesired\fR->\fBsamples\fR" 10The desired size of the audio buffer in samples\&. This number should be a power of two, and may be adjusted by the audio driver to a value more suitable for the hardware\&. Good values seem to range between 512 and 8192 inclusive, depending on the application and CPU speed\&. Smaller values yield faster response time, but can lead to underflow if the application is doing heavy processing and cannot fill the audio buffer in time\&. A stereo sample consists of both right and left channels in LR ordering\&. Note that the number of samples is directly related to time by the following formula: ms = (samples*1000)/freq
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
26 .IP "\fBdesired\fR->\fBcallback\fR" 10This should be set to a function that will be called when the audio device is ready for more data\&. It is passed a pointer to the audio buffer, and the length in bytes of the audio buffer\&. This function usually runs in a separate thread, and so you should protect data structures that it accesses by calling \fI\fBSDL_LockAudio\fP\fR and \fI\fBSDL_UnlockAudio\fP\fR in your code\&. The callback prototype is:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
27 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
28 .nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
29 \f(CWvoid callback(void *userdata, Uint8 *stream, int len);\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
30 .fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
31 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
32 \fBuserdata\fR is the pointer stored in \fBuserdata\fR field of the \fBSDL_AudioSpec\fR\&. \fBstream\fR is a pointer to the audio buffer you want to fill with information and \fBlen\fR is the length of the audio buffer in bytes\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
33 .IP "\fBdesired\fR->\fBuserdata\fR" 10This pointer is passed as the first parameter to the \fBcallback\fP function\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
34 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
35 \fBSDL_OpenAudio\fP reads these fields from the \fBdesired\fR \fBSDL_AudioSpec\fR structure pass to the function and attempts to find an audio configuration matching your \fBdesired\fR\&. As mentioned above, if the \fBobtained\fR parameter is \fBNULL\fP then SDL with convert from your \fBdesired\fR audio settings to the hardware settings as it plays\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
36 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
37 If \fBobtained\fR is \fBNULL\fP then the \fBdesired\fR \fBSDL_AudioSpec\fR is your working specification, otherwise the \fBobtained\fR \fBSDL_AudioSpec\fR becomes the working specification and the \fBdesirec\fR specification can be deleted\&. The data in the working specification is used when building \fBSDL_AudioCVT\fR\&'s for converting loaded data to the hardware format\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
38 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
39 \fBSDL_OpenAudio\fP calculates the \fBsize\fR and \fBsilence\fR fields for both the \fBdesired\fR and \fBobtained\fR specifications\&. The \fBsize\fR field stores the total size of the audio buffer in bytes, while the \fBsilence\fR stores the value used to represent silence in the audio buffer
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
40 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
41 The audio device starts out playing \fBsilence\fR when it\&'s opened, and should be enabled for playing by calling \fI\fBSDL_PauseAudio\fP(\fB0\fR)\fR when you are ready for your audio \fBcallback\fR function to be called\&. Since the audio driver may modify the requested \fBsize\fR of the audio buffer, you should allocate any local mixing buffers after you open the audio device\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
42 .SH "EXAMPLES"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
43 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
44 .nf
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
45 \f(CW/* Prototype of our callback function */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
46 void my_audio_callback(void *userdata, Uint8 *stream, int len);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
47
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
48 /* Open the audio device */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
49 SDL_AudioSpec *desired, *obtained;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
50 SDL_AudioSpec *hardware_spec;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
51
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
52 /* Allocate a desired SDL_AudioSpec */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
53 desired=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
54
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
55 /* Allocate space for the obtained SDL_AudioSpec */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
56 obtained=(SDL_AudioSpec *)malloc(sizeof(SDL_AudioSpec));
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
57
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
58 /* 22050Hz - FM Radio quality */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
59 desired->freq=22050;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
60
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
61 /* 16-bit signed audio */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
62 desired->format=AUDIO_S16LSB;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
63
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
64 /* Mono */
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
65 desired->channels=0;
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
66
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
67 /* Large audio buffer reduces risk of dropouts but increases response time */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
68 desired->samples=8192;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
69
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
70 /* Our callback function */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
71 desired->callback=my_audio_callback;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
72
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
73 desired->userdata=NULL;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
74
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
75 /* Open the audio device */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
76 if ( SDL_OpenAudio(desired, obtained) < 0 ){
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
77 fprintf(stderr, "Couldn\&'t open audio: %s
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
78 ", SDL_GetError());
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
79 exit(-1);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
80 }
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
81 /* desired spec is no longer needed */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
82 free(desired);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
83 hardware_spec=obtained;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
84 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
85 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
86 /* Prepare callback for playing */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
87 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
88 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
89 \&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
90 /* Start playing */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
91 SDL_PauseAudio(0);\fR
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
92 .fi
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
93 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
94 .SH "SEE ALSO"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
95 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
96 \fI\fBSDL_AudioSpec\fP\fR, \fI\fBSDL_LockAudio\fP\fR, \fI\fBSDL_UnlockAudio\fP\fR, \fI\fBSDL_PauseAudio\fP\fR
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
97 ...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 22:58