Penguin
Recent Changes
Blame: SDL_OpenAudio(3)
EditPageHistoryDiffInfoLikePages
Annotated edit history of SDL_OpenAudio(3) version 3, including all changes. View license author blame.
Rev Author # Line
2 perry 1 SDL_!OpenAudio
2 !!!SDL_!OpenAudio
1 perry 3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 EXAMPLES
7 SEE ALSO
8 ----
9 !!NAME
10
11
2 perry 12 SDL_!OpenAudio- Opens the audio device with the desired parameters.
1 perry 13 !!SYNOPSIS
14
15
16 __#include __
17
18
2 perry 19 __int SDL_!OpenAudio__(__SDL_!AudioSpec *desired,
20 SDL_!AudioSpec *obtained__);
1 perry 21 !!DESCRIPTION
22
23
24 This function opens the audio device with the __desired__
25 parameters, and returns 0 if successful, placing the actual
26 hardware parameters in the structure pointed to by
27 __obtained__. If __obtained__ is NULL, the audio data
28 passed to the callback function will be guaranteed to be in
29 the requested format, and will be automatically converted to
30 the hardware audio format if necessary. This function
31 returns -1 if it failed to open the audio device, or
32 couldn't set up the audio thread.
33
34
2 perry 35 To open the audio device a __desired SDL_!AudioSpec__ must
1 perry 36 be created.
37
38
2 perry 39 SDL_!AudioSpec *desired;
1 perry 40 .
41 .
2 perry 42 desired=(SDL_!AudioSpec *)malloc(sizeof(SDL_!AudioSpec));
1 perry 43 You must then fill this structure with your desired audio specifications.
44
45
46 __desired__-__freq__
47
48
49 __desired__-__format__
50
51
52 __desired__-__samples__
53
54
55 __desired__-__callback__
56
57
58 void callback(void *userdata, Uint8 *stream, int len);
2 perry 59 __userdata__ is the pointer stored in __userdata__ field of the __SDL_!AudioSpec__. __stream__ is a pointer to the audio buffer you want to fill with information and __len__ is the length of the audio buffer in bytes.
1 perry 60
61
62 __desired__-__userdata__
63
64
2 perry 65 __SDL_!OpenAudio__ reads these fields from the __desired
66 SDL_!AudioSpec__ structure pass to the function and
1 perry 67 attempts to find an audio configuration matching your
68 __desired__. As mentioned above, if the __obtained__
69 parameter is __NULL__ then SDL with convert from your
70 __desired__ audio settings to the hardware settings as it
71 plays.
72
73
74 If __obtained__ is __NULL__ then the __desired
2 perry 75 SDL_!AudioSpec__ is your working specification, otherwise
76 the __obtained SDL_!AudioSpec__ becomes the working
1 perry 77 specification and the __desirec__ specification can be
78 deleted. The data in the working specification is used when
79 building __SDL_AudioCVT__'s for converting loaded data to
80 the hardware format.
81
82
2 perry 83 __SDL_!OpenAudio__ calculates the __size__ and
1 perry 84 __silence__ fields for both the __desired__ and
85 __obtained__ specifications. The __size__ field stores
86 the total size of the audio buffer in bytes, while the
87 __silence__ stores the value used to represent silence in
88 the audio buffer
89
90
91 The audio device starts out playing __silence__ when it's
92 opened, and should be enabled for playing by calling
2 perry 93 __SDL_!PauseAudio__''(''__0__) when you are ready
1 perry 94 for your audio __callback__ function to be called. Since
95 the audio driver may modify the requested __size__ of the
96 audio buffer, you should allocate any local mixing buffers
97 after you open the audio device.
98 !!EXAMPLES
99
100
3 OneTimeUser 101 /* Prototype of our callback function */
102 void my_audio_callback(void *userdata, Uint8 *stream, int len);
103 /* Open the audio device */
104 SDL_!AudioSpec *desired, *obtained;
105 SDL_!AudioSpec *hardware_spec;
106 /* Allocate a desired SDL_!AudioSpec */
107 desired=(SDL_!AudioSpec *)malloc(sizeof(SDL_!AudioSpec));
108 /* Allocate space for the obtained SDL_!AudioSpec */
109 obtained=(SDL_!AudioSpec *)malloc(sizeof(SDL_!AudioSpec));
110 /* 22050Hz - FM Radio quality */
111 desired-
1 perry 112 !!SEE ALSO
113
114
2 perry 115 __SDL_!AudioSpec__, __SDL_!LockAudio__,
116 __SDL_!UnlockAudio__, __SDL_!PauseAudio__
1 perry 117 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.