src/audio/SDL_sysaudio.h
author Ryan C. Gordon
Mon, 16 Mar 2015 02:11:39 -0400
changeset 9393 ed79a66e57e5
parent 9391 3a54985e999e
child 9394 bb28e5281770
permissions -rw-r--r--
Initial work on audio device hotplug support.

This fills in the core pieces and fully implements it for Mac OS X.

Most other platforms, at the moment, will report a disconnected device if
it fails to write audio, but don't notice if the system's device list changed
at all.
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@8149
     3
  Copyright (C) 1997-2014 Sam Lantinga <slouken@libsdl.org>
slouken@0
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@0
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@0
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@0
    20
*/
icculus@8093
    21
#include "../SDL_internal.h"
slouken@0
    22
slouken@0
    23
#ifndef _SDL_sysaudio_h
slouken@0
    24
#define _SDL_sysaudio_h
slouken@0
    25
slouken@0
    26
#include "SDL_mutex.h"
slouken@0
    27
#include "SDL_thread.h"
slouken@0
    28
slouken@0
    29
/* The SDL audio driver */
slouken@0
    30
typedef struct SDL_AudioDevice SDL_AudioDevice;
slouken@7191
    31
#define _THIS   SDL_AudioDevice *_this
slouken@0
    32
icculus@5593
    33
/* Used by audio targets during DetectDevices() */
icculus@9393
    34
typedef int (*SDL_AddAudioDevice)(const char *name);
icculus@9393
    35
icculus@9393
    36
/* Audio targets should call this as devices are hotplugged. Don't call
icculus@9393
    37
   during DetectDevices(), this is for hotplugging a device later. */
icculus@9393
    38
extern void SDL_AudioDeviceConnected(const int iscapture, const char *name);
icculus@9393
    39
icculus@9393
    40
/* Audio targets should call this as devices are unplugged.
icculus@9393
    41
  (device) can be NULL if an unopened device is lost. */
icculus@9393
    42
extern void SDL_AudioDeviceDisconnected(const int iscapture, SDL_AudioDevice *device);
icculus@9393
    43
icculus@5593
    44
icculus@9012
    45
/* This is the size of a packet when using SDL_QueueAudio(). We allocate
icculus@9012
    46
   these as necessary and pool them, under the assumption that we'll
icculus@9012
    47
   eventually end up with a handful that keep recycling, meeting whatever
icculus@9012
    48
   the app needs. We keep packing data tightly as more arrives to avoid
icculus@9012
    49
   wasting space, and if we get a giant block of data, we'll split them
icculus@9012
    50
   into multiple packets behind the scenes. My expectation is that most
icculus@9012
    51
   apps will have 2-3 of these in the pool. 8k should cover most needs, but
icculus@9012
    52
   if this is crippling for some embedded system, we can #ifdef this.
icculus@9012
    53
   The system preallocates enough packets for 2 callbacks' worth of data. */
icculus@9012
    54
#define SDL_AUDIOBUFFERQUEUE_PACKETLEN (8 * 1024)
icculus@9012
    55
icculus@9012
    56
/* Used by apps that queue audio instead of using the callback. */
icculus@9012
    57
typedef struct SDL_AudioBufferQueue
icculus@9012
    58
{
icculus@9012
    59
    Uint8 data[SDL_AUDIOBUFFERQUEUE_PACKETLEN];  /* packet data. */
icculus@9012
    60
    Uint32 datalen;  /* bytes currently in use in this packet. */
icculus@9012
    61
    Uint32 startpos;  /* bytes currently consumed in this packet. */
icculus@9012
    62
    struct SDL_AudioBufferQueue *next;  /* next item in linked list. */
icculus@9012
    63
} SDL_AudioBufferQueue;
icculus@9012
    64
icculus@2049
    65
typedef struct SDL_AudioDriverImpl
icculus@2049
    66
{
icculus@5593
    67
    void (*DetectDevices) (int iscapture, SDL_AddAudioDevice addfn);
icculus@2049
    68
    int (*OpenDevice) (_THIS, const char *devname, int iscapture);
icculus@2049
    69
    void (*ThreadInit) (_THIS); /* Called by audio thread at start */
icculus@2049
    70
    void (*WaitDevice) (_THIS);
icculus@2049
    71
    void (*PlayDevice) (_THIS);
icculus@9031
    72
    int (*GetPendingBytes) (_THIS);
icculus@2049
    73
    Uint8 *(*GetDeviceBuf) (_THIS);
icculus@2049
    74
    void (*WaitDone) (_THIS);
icculus@2049
    75
    void (*CloseDevice) (_THIS);
icculus@2049
    76
    void (*LockDevice) (_THIS);
icculus@2049
    77
    void (*UnlockDevice) (_THIS);
icculus@2049
    78
    void (*Deinitialize) (void);
icculus@2049
    79
icculus@5590
    80
    /* !!! FIXME: add pause(), so we can optimize instead of mixing silence. */
icculus@5590
    81
icculus@2049
    82
    /* Some flags to push duplicate code into the core and reduce #ifdefs. */
icculus@9391
    83
    /* !!! FIXME: these should be SDL_bool */
icculus@5589
    84
    int ProvidesOwnCallbackThread;
icculus@5590
    85
    int SkipMixerLock;  /* !!! FIXME: do we need this anymore? */
icculus@5589
    86
    int HasCaptureSupport;
icculus@5589
    87
    int OnlyHasDefaultOutputDevice;
icculus@5589
    88
    int OnlyHasDefaultInputDevice;
icculus@2049
    89
} SDL_AudioDriverImpl;
icculus@2049
    90
icculus@2049
    91
icculus@2049
    92
typedef struct SDL_AudioDriver
slouken@1895
    93
{
slouken@1895
    94
    /* * * */
slouken@1895
    95
    /* The name of this audio driver */
slouken@1895
    96
    const char *name;
slouken@0
    97
slouken@1895
    98
    /* * * */
slouken@1895
    99
    /* The description of this audio driver */
slouken@1895
   100
    const char *desc;
slouken@0
   101
icculus@2049
   102
    SDL_AudioDriverImpl impl;
icculus@5593
   103
icculus@9393
   104
    /* A mutex for device detection */
icculus@9393
   105
    SDL_mutex *detection_lock;
icculus@9393
   106
icculus@9393
   107
    SDL_bool need_capture_device_redetect;
icculus@9393
   108
    SDL_bool need_output_device_redetect;
icculus@9393
   109
icculus@5593
   110
    char **outputDevices;
icculus@5593
   111
    int outputDeviceCount;
icculus@5593
   112
icculus@5593
   113
    char **inputDevices;
icculus@5593
   114
    int inputDeviceCount;
icculus@2049
   115
} SDL_AudioDriver;
icculus@2049
   116
slouken@0
   117
slouken@2716
   118
/* Streamer */
slouken@2716
   119
typedef struct
slouken@2716
   120
{
slouken@2716
   121
    Uint8 *buffer;
slouken@2716
   122
    int max_len;                /* the maximum length in bytes */
slouken@2716
   123
    int read_pos, write_pos;    /* the position of the write and read heads in bytes */
slouken@2716
   124
} SDL_AudioStreamer;
slouken@2716
   125
slouken@2716
   126
icculus@2049
   127
/* Define the SDL audio driver structure */
icculus@2049
   128
struct SDL_AudioDevice
icculus@2049
   129
{
slouken@1895
   130
    /* * * */
slouken@1895
   131
    /* Data common to all devices */
icculus@9393
   132
    SDL_AudioDeviceID id;
slouken@0
   133
slouken@1895
   134
    /* The current audio specification (shared with audio thread) */
slouken@1895
   135
    SDL_AudioSpec spec;
slouken@0
   136
slouken@1895
   137
    /* An audio conversion block for audio format emulation */
slouken@1895
   138
    SDL_AudioCVT convert;
slouken@0
   139
slouken@2716
   140
    /* The streamer, if sample rate conversion necessitates it */
slouken@2716
   141
    int use_streamer;
slouken@2716
   142
    SDL_AudioStreamer streamer;
slouken@2716
   143
slouken@1895
   144
    /* Current state flags */
icculus@9391
   145
    /* !!! FIXME: should be SDL_bool */
icculus@2049
   146
    int iscapture;
slouken@1895
   147
    int enabled;
slouken@1895
   148
    int paused;
slouken@1895
   149
    int opened;
slouken@0
   150
slouken@1895
   151
    /* Fake audio buffer for when the audio hardware is busy */
slouken@1895
   152
    Uint8 *fake_stream;
slouken@0
   153
icculus@9391
   154
    /* A mutex for locking the mixing buffers */
slouken@1895
   155
    SDL_mutex *mixer_lock;
slouken@0
   156
slouken@1895
   157
    /* A thread to feed the audio device */
slouken@1895
   158
    SDL_Thread *thread;
slouken@3578
   159
    SDL_threadID threadid;
slouken@0
   160
icculus@9012
   161
    /* Queued buffers (if app not using callback). */
icculus@9012
   162
    SDL_AudioBufferQueue *buffer_queue_head; /* device fed from here. */
icculus@9012
   163
    SDL_AudioBufferQueue *buffer_queue_tail; /* queue fills to here. */
icculus@9012
   164
    SDL_AudioBufferQueue *buffer_queue_pool; /* these are unused packets. */
icculus@9012
   165
    Uint32 queued_bytes;  /* number of bytes of audio data in the queue. */
icculus@9012
   166
slouken@1895
   167
    /* * * */
slouken@1895
   168
    /* Data private to this driver */
slouken@1895
   169
    struct SDL_PrivateAudioData *hidden;
slouken@0
   170
};
slouken@0
   171
#undef _THIS
slouken@0
   172
slouken@1895
   173
typedef struct AudioBootStrap
slouken@1895
   174
{
slouken@1895
   175
    const char *name;
slouken@1895
   176
    const char *desc;
slouken@2060
   177
    int (*init) (SDL_AudioDriverImpl * impl);
icculus@5578
   178
    int demand_only;  /* 1==request explicitly, or it won't be available. */
slouken@0
   179
} AudioBootStrap;
slouken@0
   180
icculus@2049
   181
#endif /* _SDL_sysaudio_h */
slouken@0
   182
slouken@1895
   183
/* vi: set ts=4 sw=4 expandtab: */