include/SDL_audio.h
author Ryan C. Gordon <icculus@icculus.org>
Wed, 13 Jan 2010 07:00:20 +0000
changeset 3648 a9d830c05998
parent 3554 cf815007e443
child 3697 f7b03b6838cb
permissions -rw-r--r--
Fixed build problems with gcc __attribute__.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     1
/*
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     2
    SDL - Simple DirectMedia Layer
2859
99210400e8b9 Updated copyright date
Sam Lantinga <slouken@libsdl.org>
parents: 2720
diff changeset
     3
    Copyright (C) 1997-2009 Sam Lantinga
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     4
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     5
    This library is free software; you can redistribute it and/or
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 930
diff changeset
     6
    modify it under the terms of the GNU Lesser General Public
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     7
    License as published by the Free Software Foundation; either
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 930
diff changeset
     8
    version 2.1 of the License, or (at your option) any later version.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
     9
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    10
    This library is distributed in the hope that it will be useful,
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 930
diff changeset
    13
    Lesser General Public License for more details.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    14
1312
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 930
diff changeset
    15
    You should have received a copy of the GNU Lesser General Public
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 930
diff changeset
    16
    License along with this library; if not, write to the Free Software
c9b51268668f Updated copyright information and removed rcs id lines (problematic in branch merges)
Sam Lantinga <slouken@libsdl.org>
parents: 930
diff changeset
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    18
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    19
    Sam Lantinga
251
b8688cfdc232 Updated the headers with the correct e-mail address
Sam Lantinga <slouken@libsdl.org>
parents: 188
diff changeset
    20
    slouken@libsdl.org
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    21
*/
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    22
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
    23
/**
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    24
 *  \file SDL_audio.h
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    25
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    26
 *  Access to the raw audio mixing buffer for the SDL library.
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
    27
 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    28
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    29
#ifndef _SDL_audio_h
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    30
#define _SDL_audio_h
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    31
1353
7ba544e2888d Started the process of improving configure support, and merging C types
Sam Lantinga <slouken@libsdl.org>
parents: 1330
diff changeset
    32
#include "SDL_stdinc.h"
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    33
#include "SDL_error.h"
1358
c71e05b4dc2e More header massaging... works great on Windows. ;-)
Sam Lantinga <slouken@libsdl.org>
parents: 1356
diff changeset
    34
#include "SDL_endian.h"
c71e05b4dc2e More header massaging... works great on Windows. ;-)
Sam Lantinga <slouken@libsdl.org>
parents: 1356
diff changeset
    35
#include "SDL_mutex.h"
c71e05b4dc2e More header massaging... works great on Windows. ;-)
Sam Lantinga <slouken@libsdl.org>
parents: 1356
diff changeset
    36
#include "SDL_thread.h"
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    37
#include "SDL_rwops.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    38
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    39
#include "begin_code.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    40
/* Set up for C function definitions, even when using C++ */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    41
#ifdef __cplusplus
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
    42
/* *INDENT-OFF* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    43
extern "C" {
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
    44
/* *INDENT-ON* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    45
#endif
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    46
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    47
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    48
 *  \brief Audio format flags.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    49
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    50
 *  These are what the 16 bits in SDL_AudioFormat currently mean...
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    51
 *  (Unspecified bits are always zero).
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    52
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    53
 *  \verbatim
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    54
    ++-----------------------sample is signed if set
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    55
    ||
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    56
    ||       ++-----------sample is bigendian if set
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    57
    ||       ||
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    58
    ||       ||          ++---sample is float if set
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    59
    ||       ||          ||
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    60
    ||       ||          || +---sample bit size---+
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    61
    ||       ||          || |                     |
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    62
    15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    63
    \endverbatim
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    64
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    65
 *  There are macros in SDL 1.3 and later to query these bits.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    66
 */
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    67
typedef Uint16 SDL_AudioFormat;
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    68
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    69
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    70
 *  \name Audio flags
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    71
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    72
/*@{*/
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    73
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    74
#define SDL_AUDIO_MASK_BITSIZE       (0xFF)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    75
#define SDL_AUDIO_MASK_DATATYPE      (1<<8)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    76
#define SDL_AUDIO_MASK_ENDIAN        (1<<12)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    77
#define SDL_AUDIO_MASK_SIGNED        (1<<15)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    78
#define SDL_AUDIO_BITSIZE(x)         (x & SDL_AUDIO_MASK_BITSIZE)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    79
#define SDL_AUDIO_ISFLOAT(x)         (x & SDL_AUDIO_MASK_DATATYPE)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    80
#define SDL_AUDIO_ISBIGENDIAN(x)     (x & SDL_AUDIO_MASK_ENDIAN)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    81
#define SDL_AUDIO_ISSIGNED(x)        (x & SDL_AUDIO_MASK_SIGNED)
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    82
#define SDL_AUDIO_ISINT(x)           (!SDL_AUDIO_ISFLOAT(x))
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    83
#define SDL_AUDIO_ISLITTLEENDIAN(x)  (!SDL_AUDIO_ISBIGENDIAN(x))
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    84
#define SDL_AUDIO_ISUNSIGNED(x)      (!SDL_AUDIO_ISSIGNED(x))
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
    85
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    86
/** 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    87
 *  \name Audio format flags
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    88
 *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    89
 *  Defaults to LSB byte order.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    90
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    91
/*@{*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    92
#define AUDIO_U8	0x0008  /**< Unsigned 8-bit samples */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    93
#define AUDIO_S8	0x8008  /**< Signed 8-bit samples */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    94
#define AUDIO_U16LSB	0x0010  /**< Unsigned 16-bit samples */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    95
#define AUDIO_S16LSB	0x8010  /**< Signed 16-bit samples */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    96
#define AUDIO_U16MSB	0x1010  /**< As above, but big-endian byte order */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
    97
#define AUDIO_S16MSB	0x9010  /**< As above, but big-endian byte order */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    98
#define AUDIO_U16	AUDIO_U16LSB
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
    99
#define AUDIO_S16	AUDIO_S16LSB
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   100
/*@}*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   101
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   102
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   103
 *  \name int32 support
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   104
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   105
 *  New to SDL 1.3.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   106
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   107
/*@{*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   108
#define AUDIO_S32LSB	0x8020  /**< 32-bit integer samples */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   109
#define AUDIO_S32MSB	0x9020  /**< As above, but big-endian byte order */
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   110
#define AUDIO_S32	AUDIO_S32LSB
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   111
/*@}*/
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   112
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   113
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   114
 *  \name float32 support
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   115
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   116
 *  New to SDL 1.3.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   117
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   118
/*@{*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   119
#define AUDIO_F32LSB	0x8120  /**< 32-bit floating point samples */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   120
#define AUDIO_F32MSB	0x9120  /**< As above, but big-endian byte order */
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   121
#define AUDIO_F32	AUDIO_F32LSB
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   122
/*@}*/
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   123
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   124
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   125
 *  \name Native audio byte ordering
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   126
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   127
/*@{*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   128
#if SDL_BYTEORDER == SDL_LIL_ENDIAN
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   129
#define AUDIO_U16SYS	AUDIO_U16LSB
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   130
#define AUDIO_S16SYS	AUDIO_S16LSB
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   131
#define AUDIO_S32SYS	AUDIO_S32LSB
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   132
#define AUDIO_F32SYS	AUDIO_F32LSB
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   133
#else
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   134
#define AUDIO_U16SYS	AUDIO_U16MSB
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   135
#define AUDIO_S16SYS	AUDIO_S16MSB
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   136
#define AUDIO_S32SYS	AUDIO_S32MSB
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   137
#define AUDIO_F32SYS	AUDIO_F32MSB
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   138
#endif
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   139
/*@}*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   140
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   141
/** 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   142
 *  \name Allow change flags
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   143
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   144
 *  Which audio format changes are allowed when opening a device.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   145
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   146
/*@{*/
2866
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   147
#define SDL_AUDIO_ALLOW_FREQUENCY_CHANGE    0x00000001
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   148
#define SDL_AUDIO_ALLOW_FORMAT_CHANGE       0x00000002
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   149
#define SDL_AUDIO_ALLOW_CHANNELS_CHANGE     0x00000004
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   150
#define SDL_AUDIO_ALLOW_ANY_CHANGE          (SDL_AUDIO_ALLOW_FREQUENCY_CHANGE|SDL_AUDIO_ALLOW_FORMAT_CHANGE|SDL_AUDIO_ALLOW_CHANNELS_CHANGE)
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   151
/*@}*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   152
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   153
/*@}*//*Audio flags*/
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   154
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   155
/**
3554
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   156
 *  This function is called when the audio device needs more data.
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   157
 *
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   158
 *  \param userdata An application-specific parameter saved in
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   159
 *                  the SDL_AudioSpec structure
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   160
 *  \param stream A pointer to the audio data buffer.
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   161
 *  \param len    The length of that buffer in bytes.
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   162
 *
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   163
 *  Once the callback returns, the buffer will no longer be valid.
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   164
 *  Stereo samples are stored in a LRLRLR ordering.
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   165
 */
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   166
typedef void (SDLCALL * SDL_AudioCallback) (void *userdata, Uint8 * stream,
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   167
                                            int len);
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   168
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   169
/**
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   170
 *  The calculated values in this structure are calculated by SDL_OpenAudio().
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   171
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   172
typedef struct SDL_AudioSpec
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   173
{
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   174
    int freq;                   /**< DSP frequency -- samples per second */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   175
    SDL_AudioFormat format;     /**< Audio data format */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   176
    Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   177
    Uint8 silence;              /**< Audio buffer silence value (calculated) */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   178
    Uint16 samples;             /**< Audio buffer size in samples (power of 2) */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   179
    Uint16 padding;             /**< Necessary for some compile environments */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   180
    Uint32 size;                /**< Audio buffer size in bytes (calculated) */
3554
cf815007e443 Name the audio callback for documentation clarity.
Sam Lantinga <slouken@libsdl.org>
parents: 3537
diff changeset
   181
    SDL_AudioCallback callback;
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   182
    void *userdata;
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   183
} SDL_AudioSpec;
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   184
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   185
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   186
struct SDL_AudioCVT;
1985
8055185ae4ed Added source color and alpha modulation support.
Sam Lantinga <slouken@libsdl.org>
parents: 1983
diff changeset
   187
typedef void (SDLCALL * SDL_AudioFilter) (struct SDL_AudioCVT * cvt,
8055185ae4ed Added source color and alpha modulation support.
Sam Lantinga <slouken@libsdl.org>
parents: 1983
diff changeset
   188
                                          SDL_AudioFormat format);
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   189
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   190
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   191
 *  A structure to hold a set of audio conversion filters and buffers.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   192
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   193
typedef struct SDL_AudioCVT
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   194
{
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   195
    int needed;                 /**< Set to 1 if conversion possible */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   196
    SDL_AudioFormat src_format; /**< Source audio format */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   197
    SDL_AudioFormat dst_format; /**< Target audio format */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   198
    double rate_incr;           /**< Rate conversion increment */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   199
    Uint8 *buf;                 /**< Buffer to hold entire audio data */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   200
    int len;                    /**< Length of original audio buffer */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   201
    int len_cvt;                /**< Length of converted audio buffer */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   202
    int len_mult;               /**< buffer must be len*len_mult big */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   203
    double len_ratio;           /**< Given len, final size is len*len_ratio */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   204
    SDL_AudioFilter filters[10];        /**< Filter list */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   205
    int filter_index;           /**< Current audio conversion function */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   206
} SDL_AudioCVT;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   207
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   208
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   209
/* Function prototypes */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   210
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   211
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   212
 *  \name Driver discovery functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   213
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   214
 *  These functions return the list of built in audio drivers, in the
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   215
 *  order that they are normally initialized by default.
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   216
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   217
/*@{*/
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   218
extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   219
extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   220
/*@}*/
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   221
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   222
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   223
 *  \name Initialization and cleanup
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   224
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   225
 *  \internal These functions are used internally, and should not be used unless
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   226
 *            you have a specific need to specify the audio driver you want to 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   227
 *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   228
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   229
/*@{*/
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   230
extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   231
extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   232
/*@}*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   233
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   234
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   235
 *  This function returns the name of the current audio driver, or NULL
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   236
 *  if no driver has been initialized.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   237
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   238
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   239
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   240
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   241
 *  This function opens the audio device with the desired parameters, and
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   242
 *  returns 0 if successful, placing the actual hardware parameters in the
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   243
 *  structure pointed to by \c obtained.  If \c obtained is NULL, the audio
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   244
 *  data passed to the callback function will be guaranteed to be in the
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   245
 *  requested format, and will be automatically converted to the hardware
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   246
 *  audio format if necessary.  This function returns -1 if it failed 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   247
 *  to open the audio device, or couldn't set up the audio thread.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   248
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   249
 *  When filling in the desired audio spec structure,
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   250
 *    - \c desired->freq should be the desired audio frequency in samples-per-
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   251
 *      second.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   252
 *    - \c desired->format should be the desired audio format.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   253
 *    - \c desired->samples is the desired size of the audio buffer, in 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   254
 *      samples.  This number should be a power of two, and may be adjusted by 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   255
 *      the audio driver to a value more suitable for the hardware.  Good values
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   256
 *      seem to range between 512 and 8096 inclusive, depending on the 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   257
 *      application and CPU speed.  Smaller values yield faster response time, 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   258
 *      but can lead to underflow if the application is doing heavy processing 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   259
 *      and cannot fill the audio buffer in time.  A stereo sample consists of 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   260
 *      both right and left channels in LR ordering.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   261
 *      Note that the number of samples is directly related to time by the
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   262
 *      following formula:  \code ms = (samples*1000)/freq \endcode
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   263
 *    - \c desired->size is the size in bytes of the audio buffer, and is
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   264
 *      calculated by SDL_OpenAudio().
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   265
 *    - \c desired->silence is the value used to set the buffer to silence,
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   266
 *      and is calculated by SDL_OpenAudio().
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   267
 *    - \c desired->callback should be set to a function that will be called
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   268
 *      when the audio device is ready for more data.  It is passed a pointer
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   269
 *      to the audio buffer, and the length in bytes of the audio buffer.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   270
 *      This function usually runs in a separate thread, and so you should
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   271
 *      protect data structures that it accesses by calling SDL_LockAudio()
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   272
 *      and SDL_UnlockAudio() in your code.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   273
 *    - \c desired->userdata is passed as the first parameter to your callback
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   274
 *      function.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   275
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   276
 *  The audio device starts out playing silence when it's opened, and should
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   277
 *  be enabled for playing by calling \c SDL_PauseAudio(0) when you are ready
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   278
 *  for your audio callback function to be called.  Since the audio driver
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   279
 *  may modify the requested size of the audio buffer, you should allocate
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   280
 *  any local mixing buffers after you open the audio device.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   281
 */
2866
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   282
extern DECLSPEC int SDLCALL SDL_OpenAudio(SDL_AudioSpec * desired,
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   283
                                          SDL_AudioSpec * obtained);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   284
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   285
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   286
 *  SDL Audio Device IDs.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   287
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   288
 *  A successful call to SDL_OpenAudio() is always device id 1, and legacy
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   289
 *  SDL audio APIs assume you want this device ID. SDL_OpenAudioDevice() calls
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   290
 *  always returns devices >= 2 on success. The legacy calls are good both
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   291
 *  for backwards compatibility and when you don't care about multiple,
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   292
 *  specific, or capture devices.
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   293
 */
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   294
typedef Uint32 SDL_AudioDeviceID;
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   295
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   296
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   297
 *  Get the number of available devices exposed by the current driver.
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   298
 *  Only valid after a successfully initializing the audio subsystem.
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   299
 *  Returns -1 if an explicit list of devices can't be determined; this is
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   300
 *  not an error. For example, if SDL is set up to talk to a remote audio
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   301
 *  server, it can't list every one available on the Internet, but it will
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   302
 *  still allow a specific host to be specified to SDL_OpenAudioDevice().
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   303
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   304
 *  In many common cases, when this function returns a value <= 0, it can still
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   305
 *  successfully open the default device (NULL for first argument of
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   306
 *  SDL_OpenAudioDevice()).
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   307
 */
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   308
extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   309
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   310
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   311
 *  Get the human-readable name of a specific audio device.
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   312
 *  Must be a value between 0 and (number of audio devices-1).
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   313
 *  Only valid after a successfully initializing the audio subsystem.
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   314
 *  The values returned by this function reflect the latest call to
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   315
 *  SDL_GetNumAudioDevices(); recall that function to redetect available
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   316
 *  hardware.
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   317
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   318
 *  The string returned by this function is UTF-8 encoded, read-only, and
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   319
 *  managed internally. You are not to free it. If you need to keep the
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   320
 *  string for any length of time, you should make your own copy of it, as it
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   321
 *  will be invalid next time any of several other SDL functions is called.
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   322
 */
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   323
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   324
                                                           int iscapture);
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   325
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   326
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   327
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   328
 *  Open a specific audio device. Passing in a device name of NULL requests
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   329
 *  the most reasonable default (and is equivalent to calling SDL_OpenAudio()).
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   330
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   331
 *  The device name is a UTF-8 string reported by SDL_GetAudioDeviceName(), but
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   332
 *  some drivers allow arbitrary and driver-specific strings, such as a
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   333
 *  hostname/IP address for a remote audio server, or a filename in the
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   334
 *  diskaudio driver.
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   335
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   336
 *  \return 0 on error, a valid device ID that is >= 2 on success.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   337
 *  
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   338
 *  SDL_OpenAudio(), unlike this function, always acts on device ID 1.
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   339
 */
1967
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   340
extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(const char
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   341
                                                              *device,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   342
                                                              int iscapture,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   343
                                                              const
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   344
                                                              SDL_AudioSpec *
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   345
                                                              desired,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   346
                                                              SDL_AudioSpec *
2866
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   347
                                                              obtained,
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   348
                                                              int
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   349
                                                              allowed_changes);
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   350
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   351
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   352
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   353
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   354
 *  \name Audio state
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   355
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   356
 *  Get the current audio state.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   357
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   358
/*@{*/
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   359
typedef enum
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   360
{
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   361
    SDL_AUDIO_STOPPED = 0,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   362
    SDL_AUDIO_PLAYING,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   363
    SDL_AUDIO_PAUSED
3537
e897a4a9f578 Switch to mixed case for consistency with other enumerations
Sam Lantinga <slouken@libsdl.org>
parents: 3407
diff changeset
   364
} SDL_AudioStatus;
e897a4a9f578 Switch to mixed case for consistency with other enumerations
Sam Lantinga <slouken@libsdl.org>
parents: 3407
diff changeset
   365
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   366
3537
e897a4a9f578 Switch to mixed case for consistency with other enumerations
Sam Lantinga <slouken@libsdl.org>
parents: 3407
diff changeset
   367
extern DECLSPEC SDL_AudioStatus SDLCALL
1967
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   368
SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   369
/*@}*//*Audio State*/
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   370
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   371
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   372
 *  \name Pause audio functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   373
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   374
 *  These functions pause and unpause the audio callback processing.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   375
 *  They should be called with a parameter of 0 after opening the audio
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   376
 *  device to start playing sound.  This is so you can safely initialize
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   377
 *  data for your callback function after opening the audio device.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   378
 *  Silence will be written to the audio device during the pause.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   379
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   380
/*@{*/
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   381
extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   382
extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   383
                                                  int pause_on);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   384
/*@}*//*Pause audio functions*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   385
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   386
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   387
 *  This function loads a WAVE from the data source, automatically freeing
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   388
 *  that source if \c freesrc is non-zero.  For example, to load a WAVE file,
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   389
 *  you could do:
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   390
 *  \code
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   391
 *  	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   392
 *  \endcode
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   393
 *
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   394
 *  If this function succeeds, it returns the given SDL_AudioSpec,
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   395
 *  filled with the audio data format of the wave data, and sets
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   396
 *  \c *audio_buf to a malloc()'d buffer containing the audio data,
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   397
 *  and sets \c *audio_len to the length of that audio buffer, in bytes.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   398
 *  You need to free the audio buffer with SDL_FreeWAV() when you are 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   399
 *  done with it.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   400
 *
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   401
 *  This function returns NULL and sets the SDL error message if the 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   402
 *  wave file cannot be opened, uses an unknown data format, or is 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   403
 *  corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   404
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   405
extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   406
                                                      int freesrc,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   407
                                                      SDL_AudioSpec * spec,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   408
                                                      Uint8 ** audio_buf,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   409
                                                      Uint32 * audio_len);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   410
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   411
/** 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   412
 *  Loads a WAV from a file.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   413
 *  Compatibility convenience function.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   414
 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   415
#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   416
	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   417
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   418
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   419
 *  This function frees data previously allocated with SDL_LoadWAV_RW()
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   420
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   421
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   422
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   423
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   424
 *  This function takes a source format and rate and a destination format
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   425
 *  and rate, and initializes the \c cvt structure with information needed
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   426
 *  by SDL_ConvertAudio() to convert a buffer of audio data from one format
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   427
 *  to the other.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   428
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   429
 *  \return -1 if the format conversion is not supported, 0 if there's
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   430
 *  no conversion needed, or 1 if the audio filter is set up.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   431
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   432
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   433
                                              SDL_AudioFormat src_format,
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   434
                                              Uint8 src_channels,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   435
                                              int src_rate,
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   436
                                              SDL_AudioFormat dst_format,
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   437
                                              Uint8 dst_channels,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   438
                                              int dst_rate);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   439
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   440
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   441
 *  Once you have initialized the \c cvt structure using SDL_BuildAudioCVT(),
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   442
 *  created an audio buffer \c cvt->buf, and filled it with \c cvt->len bytes of
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   443
 *  audio data in the source format, this function will convert it in-place
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   444
 *  to the desired format.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   445
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   446
 *  The data conversion may expand the size of the audio data, so the buffer
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   447
 *  \c cvt->buf should be allocated after the \c cvt structure is initialized by
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   448
 *  SDL_BuildAudioCVT(), and should be \c cvt->len*cvt->len_mult bytes long.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   449
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   450
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   451
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   452
#define SDL_MIX_MAXVOLUME 128
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   453
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   454
 *  This takes two audio buffers of the playing audio format and mixes
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   455
 *  them, performing addition, volume adjustment, and overflow clipping.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   456
 *  The volume ranges from 0 - 128, and should be set to ::SDL_MIX_MAXVOLUME
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   457
 *  for full audio volume.  Note this does not change hardware volume.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   458
 *  This is provided for convenience -- you can mix your own audio data.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   459
 */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   460
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   461
                                          Uint32 len, int volume);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   462
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   463
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   464
 *  This works like SDL_MixAudio(), but you specify the audio format instead of
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   465
 *  using the format of audio device 1. Thus it can be used when no audio
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   466
 *  device is open at all.
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   467
 */
1967
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   468
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   469
                                                const Uint8 * src,
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   470
                                                SDL_AudioFormat format,
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   471
                                                Uint32 len, int volume);
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   472
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   473
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   474
 *  \name Audio lock functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   475
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   476
 *  The lock manipulated by these functions protects the callback function.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   477
 *  During a SDL_LockAudio()/SDL_UnlockAudio() pair, you can be guaranteed that 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   478
 *  the callback function is not running.  Do not call these from the callback
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   479
 *  function or you will cause deadlock.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   480
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   481
/*@{*/
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   482
extern DECLSPEC void SDLCALL SDL_LockAudio(void);
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   483
extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   484
extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   485
extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   486
/*@}*//*Audio lock functions*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   487
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   488
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   489
 *  This function shuts down audio processing and closes the audio device.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   490
 */
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   491
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   492
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   493
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   494
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   495
 * \return 1 if audio device is still functioning, zero if not, -1 on error.
1964
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   496
 */
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   497
extern DECLSPEC int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   498
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   499
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   500
/* Ends C function definitions when using C++ */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   501
#ifdef __cplusplus
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   502
/* *INDENT-OFF* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   503
}
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   504
/* *INDENT-ON* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   505
#endif
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   506
#include "close_code.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   507
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   508
#endif /* _SDL_audio_h */
1895
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   509
c121d94672cb SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
Sam Lantinga <slouken@libsdl.org>
parents: 1358
diff changeset
   510
/* vi: set ts=4 sw=4 expandtab: */