SDL  2.0
SDL_sysaudio.h
Go to the documentation of this file.
1 /*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2016 Sam Lantinga <slouken@libsdl.org>
4 
5  This software is provided 'as-is', without any express or implied
6  warranty. In no event will the authors be held liable for any damages
7  arising from the use of this software.
8 
9  Permission is granted to anyone to use this software for any purpose,
10  including commercial applications, and to alter it and redistribute it
11  freely, subject to the following restrictions:
12 
13  1. The origin of this software must not be misrepresented; you must not
14  claim that you wrote the original software. If you use this software
15  in a product, an acknowledgment in the product documentation would be
16  appreciated but is not required.
17  2. Altered source versions must be plainly marked as such, and must not be
18  misrepresented as being the original software.
19  3. This notice may not be removed or altered from any source distribution.
20 */
21 #include "../SDL_internal.h"
22 
23 #ifndef _SDL_sysaudio_h
24 #define _SDL_sysaudio_h
25 
26 #include "SDL_mutex.h"
27 #include "SDL_thread.h"
28 
29 /* !!! FIXME: These are wordy and unlocalized... */
30 #define DEFAULT_OUTPUT_DEVNAME "System audio output device"
31 #define DEFAULT_INPUT_DEVNAME "System audio capture device"
32 
33 /* The SDL audio driver */
34 typedef struct SDL_AudioDevice SDL_AudioDevice;
35 #define _THIS SDL_AudioDevice *_this
36 
37 /* Audio targets should call this as devices are added to the system (such as
38  a USB headset being plugged in), and should also be called for
39  for every device found during DetectDevices(). */
40 extern void SDL_AddAudioDevice(const int iscapture, const char *name, void *handle);
41 
42 /* Audio targets should call this as devices are removed, so SDL can update
43  its list of available devices. */
44 extern void SDL_RemoveAudioDevice(const int iscapture, void *handle);
45 
46 /* Audio targets should call this if an opened audio device is lost while
47  being used. This can happen due to i/o errors, or a device being unplugged,
48  etc. If the device is totally gone, please also call SDL_RemoveAudioDevice()
49  as appropriate so SDL's list of devices is accurate. */
51 
52 
53 /* This is the size of a packet when using SDL_QueueAudio(). We allocate
54  these as necessary and pool them, under the assumption that we'll
55  eventually end up with a handful that keep recycling, meeting whatever
56  the app needs. We keep packing data tightly as more arrives to avoid
57  wasting space, and if we get a giant block of data, we'll split them
58  into multiple packets behind the scenes. My expectation is that most
59  apps will have 2-3 of these in the pool. 8k should cover most needs, but
60  if this is crippling for some embedded system, we can #ifdef this.
61  The system preallocates enough packets for 2 callbacks' worth of data. */
62 #define SDL_AUDIOBUFFERQUEUE_PACKETLEN (8 * 1024)
63 
64 /* Used by apps that queue audio instead of using the callback. */
65 typedef struct SDL_AudioBufferQueue
66 {
68  Uint32 datalen; /* bytes currently in use in this packet. */
69  Uint32 startpos; /* bytes currently consumed in this packet. */
70  struct SDL_AudioBufferQueue *next; /* next item in linked list. */
72 
73 typedef struct SDL_AudioDriverImpl
74 {
75  void (*DetectDevices) (void);
76  int (*OpenDevice) (_THIS, void *handle, const char *devname, int iscapture);
77  void (*ThreadInit) (_THIS); /* Called by audio thread at start */
78  void (*WaitDevice) (_THIS);
79  void (*PlayDevice) (_THIS);
80  int (*GetPendingBytes) (_THIS);
81  Uint8 *(*GetDeviceBuf) (_THIS);
82  int (*CaptureFromDevice) (_THIS, void *buffer, int buflen);
83  void (*FlushCapture) (_THIS);
84  void (*PrepareToClose) (_THIS); /**< Called between run and draining wait for playback devices */
85  void (*CloseDevice) (_THIS);
86  void (*LockDevice) (_THIS);
87  void (*UnlockDevice) (_THIS);
88  void (*FreeDeviceHandle) (void *handle); /**< SDL is done with handle from SDL_AddAudioDevice() */
89  void (*Deinitialize) (void);
90 
91  /* !!! FIXME: add pause(), so we can optimize instead of mixing silence. */
92 
93  /* Some flags to push duplicate code into the core and reduce #ifdefs. */
94  /* !!! FIXME: these should be SDL_bool */
102 
103 
104 typedef struct SDL_AudioDeviceItem
105 {
106  void *handle;
108  #if (defined(__GNUC__) && (__GNUC__ <= 2))
109  char name[1]; /* actually variable length. */
110  #else
111  char name[];
112  #endif
114 
115 
116 typedef struct SDL_AudioDriver
117 {
118  /* * * */
119  /* The name of this audio driver */
120  const char *name;
121 
122  /* * * */
123  /* The description of this audio driver */
124  const char *desc;
125 
127 
128  /* A mutex for device detection */
137 
138 
139 /* Streamer */
140 typedef struct
141 {
143  int max_len; /* the maximum length in bytes */
144  int read_pos, write_pos; /* the position of the write and read heads in bytes */
146 
147 
148 /* Define the SDL audio driver structure */
150 {
151  /* * * */
152  /* Data common to all devices */
154 
155  /* The current audio specification (shared with audio thread) */
157 
158  /* An audio conversion block for audio format emulation */
160 
161  /* The streamer, if sample rate conversion necessitates it */
164 
165  /* Current state flags */
166  SDL_atomic_t shutdown; /* true if we are signaling the play thread to end. */
167  SDL_atomic_t enabled; /* true if device is functioning and connected. */
170 
171  /* Fake audio buffer for when the audio hardware is busy */
173 
174  /* A mutex for locking the mixing buffers */
176 
177  /* A thread to feed the audio device */
180 
181  /* Queued buffers (if app not using callback). */
182  SDL_AudioBufferQueue *buffer_queue_head; /* device fed from here. */
183  SDL_AudioBufferQueue *buffer_queue_tail; /* queue fills to here. */
184  SDL_AudioBufferQueue *buffer_queue_pool; /* these are unused packets. */
185  Uint32 queued_bytes; /* number of bytes of audio data in the queue. */
186 
187  /* * * */
188  /* Data private to this driver */
190 
191  void *handle;
192 };
193 #undef _THIS
194 
195 typedef struct AudioBootStrap
196 {
197  const char *name;
198  const char *desc;
199  int (*init) (SDL_AudioDriverImpl * impl);
200  int demand_only; /* 1==request explicitly, or it won't be available. */
202 
203 #endif /* _SDL_sysaudio_h */
204 
205 /* vi: set ts=4 sw=4 expandtab: */
struct SDL_PrivateAudioData * hidden
Definition: SDL_sysaudio.h:189
SDL_AudioDeviceID id
Definition: SDL_sysaudio.h:153
SDL_mutex * mixer_lock
Definition: SDL_sysaudio.h:175
SDL_bool captureDevicesRemoved
Definition: SDL_sysaudio.h:130
SDL_atomic_t enabled
Definition: SDL_sysaudio.h:167
const char * name
Definition: SDL_sysaudio.h:120
const char * name
Definition: SDL_sysaudio.h:197
A type representing an atomic integer value. It is a struct so people don&#39;t accidentally use numeric ...
Definition: SDL_atomic.h:189
struct SDL_AudioDeviceItem * next
Definition: SDL_sysaudio.h:107
SDL_atomic_t paused
Definition: SDL_sysaudio.h:168
SDL_atomic_t shutdown
Definition: SDL_sysaudio.h:166
GLint GLenum GLsizei GLsizei GLsizei GLint GLsizei const GLvoid * data
Definition: SDL_opengl.h:1967
SDL_threadID threadid
Definition: SDL_sysaudio.h:179
SDL_AudioBufferQueue * buffer_queue_pool
Definition: SDL_sysaudio.h:184
SDL_AudioSpec spec
Definition: SDL_sysaudio.h:156
void SDL_AddAudioDevice(const int iscapture, const char *name, void *handle)
Definition: SDL_audio.c:364
GLuint const GLchar * name
uint32_t Uint32
An unsigned 32-bit integer type.
Definition: SDL_stdinc.h:161
SDL_mutex * detectionLock
Definition: SDL_sysaudio.h:129
SDL_AudioBufferQueue * buffer_queue_head
Definition: SDL_sysaudio.h:182
void SDL_RemoveAudioDevice(const int iscapture, void *handle)
Definition: SDL_audio.c:422
SDL_AudioBufferQueue * buffer_queue_tail
Definition: SDL_sysaudio.h:183
struct SDL_AudioBufferQueue * next
Definition: SDL_sysaudio.h:70
uint8_t Uint8
An unsigned 8-bit integer type.
Definition: SDL_stdinc.h:143
const char * desc
Definition: SDL_sysaudio.h:124
SDL_bool iscapture
Definition: SDL_sysaudio.h:169
#define _THIS
Definition: SDL_sysaudio.h:35
Uint8 * fake_stream
Definition: SDL_sysaudio.h:172
SDL_AudioDeviceItem * outputDevices
Definition: SDL_sysaudio.h:134
SDL_bool
Definition: SDL_stdinc.h:130
SDL_AudioStreamer streamer
Definition: SDL_sysaudio.h:163
SDL_bool outputDevicesRemoved
Definition: SDL_sysaudio.h:131
SDL_PRINTF_FORMAT_STRING const char int SDL_PRINTF_FORMAT_STRING const char int SDL_PRINTF_FORMAT_STRING const char int SDL_PRINTF_FORMAT_STRING const char const char SDL_SCANF_FORMAT_STRING const char return SDL_ThreadFunction const char void return Uint32 return Uint32 void
SDL_AudioDriverImpl impl
Definition: SDL_sysaudio.h:126
Uint32 SDL_AudioDeviceID
Definition: SDL_audio.h:304
GLuint buffer
void SDL_OpenedAudioDeviceDisconnected(SDL_AudioDevice *device)
Definition: SDL_audio.c:381
const char * desc
Definition: SDL_sysaudio.h:198
SDL_Thread * thread
Definition: SDL_sysaudio.h:178
#define SDL_AUDIOBUFFERQUEUE_PACKETLEN
Definition: SDL_sysaudio.h:62
SDL_AudioCVT convert
Definition: SDL_sysaudio.h:159
SDL_AudioDeviceItem * inputDevices
Definition: SDL_sysaudio.h:135
unsigned long SDL_threadID
Definition: SDL_thread.h:49