include/SDL_audio.h
author Sam Lantinga <slouken@libsdl.org>
Mon, 19 Oct 2009 13:31:58 +0000
changeset 3407 d3baf5ac4e37
parent 3021 f3dcf04412cf
child 3537 e897a4a9f578
permissions -rw-r--r--
Partial fix for bug #859 Header file update from Ken for improved doxygen output
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
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   156
 *  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
   157
 */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   158
typedef struct SDL_AudioSpec
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   159
{
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   160
    int freq;                   /**< DSP frequency -- samples per second */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   161
    SDL_AudioFormat format;     /**< Audio data format */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   162
    Uint8 channels;             /**< Number of channels: 1 mono, 2 stereo */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   163
    Uint8 silence;              /**< Audio buffer silence value (calculated) */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   164
    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
   165
    Uint16 padding;             /**< Necessary for some compile environments */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   166
    Uint32 size;                /**< Audio buffer size in bytes (calculated) */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   167
    /**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   168
     *  This function is called when the audio device needs more data.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   169
     *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   170
     *  \param stream A pointer to the audio data buffer.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   171
     *  \param len    The length of that buffer in bytes.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   172
     *
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   173
     *  Once the callback returns, the buffer will no longer be valid.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   174
     *  Stereo samples are stored in a LRLRLR ordering.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   175
     */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   176
    void (SDLCALL * callback) (void *userdata, Uint8 * stream, int len);
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   177
    void *userdata;
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   178
} SDL_AudioSpec;
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   179
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   180
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   181
struct SDL_AudioCVT;
1985
8055185ae4ed Added source color and alpha modulation support.
Sam Lantinga <slouken@libsdl.org>
parents: 1983
diff changeset
   182
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
   183
                                          SDL_AudioFormat format);
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   184
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   185
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   186
 *  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
   187
 */
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
   188
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
   189
{
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   190
    int needed;                 /**< Set to 1 if conversion possible */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   191
    SDL_AudioFormat src_format; /**< Source audio format */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   192
    SDL_AudioFormat dst_format; /**< Target audio format */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   193
    double rate_incr;           /**< Rate conversion increment */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   194
    Uint8 *buf;                 /**< Buffer to hold entire audio data */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   195
    int len;                    /**< Length of original audio buffer */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   196
    int len_cvt;                /**< Length of converted audio buffer */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   197
    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
   198
    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
   199
    SDL_AudioFilter filters[10];        /**< Filter list */
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   200
    int filter_index;           /**< Current audio conversion function */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   201
} SDL_AudioCVT;
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   202
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   203
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   204
/* Function prototypes */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   205
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   206
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   207
 *  \name Driver discovery functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   208
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   209
 *  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
   210
 *  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
   211
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   212
/*@{*/
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
   213
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
   214
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
   215
/*@}*/
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
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   218
 *  \name Initialization and cleanup
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   219
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   220
 *  \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
   221
 *            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
   222
 *            use.  You should normally use SDL_Init() or SDL_InitSubSystem().
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   223
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   224
/*@{*/
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   225
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
   226
extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   227
/*@}*/
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
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   230
 *  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
   231
 *  if no driver has been initialized.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   232
 */
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
   233
extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   234
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   235
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   236
 *  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
   237
 *  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
   238
 *  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
   239
 *  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
   240
 *  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
   241
 *  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
   242
 *  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
   243
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   244
 *  When filling in the desired audio spec structure,
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   245
 *    - \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
   246
 *      second.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   247
 *    - \c desired->format should be the desired audio format.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   248
 *    - \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
   249
 *      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
   250
 *      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
   251
 *      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
   252
 *      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
   253
 *      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
   254
 *      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
   255
 *      both right and left channels in LR ordering.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   256
 *      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
   257
 *      following formula:  \code ms = (samples*1000)/freq \endcode
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   258
 *    - \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
   259
 *      calculated by SDL_OpenAudio().
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   260
 *    - \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
   261
 *      and is calculated by SDL_OpenAudio().
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   262
 *    - \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
   263
 *      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
   264
 *      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
   265
 *      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
   266
 *      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
   267
 *      and SDL_UnlockAudio() in your code.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   268
 *    - \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
   269
 *      function.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   270
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   271
 *  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
   272
 *  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
   273
 *  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
   274
 *  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
   275
 *  any local mixing buffers after you open the audio device.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   276
 */
2866
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   277
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
   278
                                          SDL_AudioSpec * obtained);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   279
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   280
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   281
 *  SDL Audio Device IDs.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   282
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   283
 *  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
   284
 *  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
   285
 *  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
   286
 *  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
   287
 *  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
   288
 */
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
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
   290
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   291
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   292
 *  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
   293
 *  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
   294
 *  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
   295
 *  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
   296
 *  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
   297
 *  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
   298
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   299
 *  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
   300
 *  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
   301
 *  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
   302
 */
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   303
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
   304
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   305
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   306
 *  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
   307
 *  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
   308
 *  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
   309
 *  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
   310
 *  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
   311
 *  hardware.
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   312
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   313
 *  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
   314
 *  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
   315
 *  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
   316
 *  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
   317
 */
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   318
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
   319
                                                           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
   320
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   321
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   322
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   323
 *  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
   324
 *  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
   325
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   326
 *  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
   327
 *  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
   328
 *  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
   329
 *  diskaudio driver.
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
 *  \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
   332
 *  
2049
5f6550e5184f Merged SDL-ryan-multiple-audio-device branch r2803:2871 into the trunk.
Ryan C. Gordon <icculus@icculus.org>
parents: 1985
diff changeset
   333
 *  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
   334
 */
1967
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   335
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
   336
                                                              *device,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   337
                                                              int iscapture,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   338
                                                              const
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   339
                                                              SDL_AudioSpec *
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   340
                                                              desired,
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   341
                                                              SDL_AudioSpec *
2866
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   342
                                                              obtained,
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   343
                                                              int
e532417a6977 Fixed SDL 1.2 compatibility problem.
Sam Lantinga <slouken@libsdl.org>
parents: 2859
diff changeset
   344
                                                              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
   345
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   346
071b6598d48f 1.3 API proposals for audio subsystem. Nothing in here is guaranteed to
Ryan C. Gordon <icculus@icculus.org>
parents: 1895
diff changeset
   347
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   348
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   349
 *  \name Audio state
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   350
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   351
 *  Get the current audio state.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   352
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   353
/*@{*/
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
   354
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
   355
{
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
   356
    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
   357
    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
   358
    SDL_AUDIO_PAUSED
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   359
} SDL_audiostatus;
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   360
extern DECLSPEC SDL_audiostatus SDLCALL SDL_GetAudioStatus(void);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   361
1967
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   362
extern DECLSPEC SDL_audiostatus SDLCALL
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   363
SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   364
/*@}*//*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
   365
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   366
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   367
 *  \name Pause audio functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   368
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   369
 *  These functions pause and unpause the audio callback processing.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   370
 *  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
   371
 *  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
   372
 *  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
   373
 *  Silence will be written to the audio device during the pause.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   374
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   375
/*@{*/
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   376
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
   377
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
   378
                                                  int pause_on);
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   379
/*@}*//*Pause audio functions*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   380
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   381
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   382
 *  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
   383
 *  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
   384
 *  you could do:
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   385
 *  \code
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   386
 *  	SDL_LoadWAV_RW(SDL_RWFromFile("sample.wav", "rb"), 1, ...);
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   387
 *  \endcode
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   388
 *
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   389
 *  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
   390
 *  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
   391
 *  \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
   392
 *  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
   393
 *  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
   394
 *  done with it.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   395
 *
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   396
 *  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
   397
 *  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
   398
 *  corrupt.  Currently raw and MS-ADPCM WAVE files are supported.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   399
 */
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
   400
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
   401
                                                      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
   402
                                                      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
   403
                                                      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
   404
                                                      Uint32 * audio_len);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   405
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   406
/** 
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   407
 *  Loads a WAV from a file.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   408
 *  Compatibility convenience function.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   409
 */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   410
#define SDL_LoadWAV(file, spec, audio_buf, audio_len) \
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   411
	SDL_LoadWAV_RW(SDL_RWFromFile(file, "rb"),1, spec,audio_buf,audio_len)
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   412
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   413
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   414
 *  This function frees data previously allocated with SDL_LoadWAV_RW()
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   415
 */
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
   416
extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
0
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 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
   420
 *  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
   421
 *  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
   422
 *  to the other.
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
 *  \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
   425
 *  no conversion needed, or 1 if the audio filter is set up.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   426
 */
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
   427
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
   428
                                              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
   429
                                              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
   430
                                              int src_rate,
1983
ee73925ddf14 Forgot to check in updated SDL_audio.h ...
Ryan C. Gordon <icculus@icculus.org>
parents: 1967
diff changeset
   431
                                              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
   432
                                              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
   433
                                              int dst_rate);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   434
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   435
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   436
 *  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
   437
 *  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
   438
 *  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
   439
 *  to the desired format.
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
 *  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
   442
 *  \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
   443
 *  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
   444
 */
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
   445
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   446
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   447
#define SDL_MIX_MAXVOLUME 128
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   448
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   449
 *  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
   450
 *  them, performing addition, volume adjustment, and overflow clipping.
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   451
 *  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
   452
 *  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
   453
 *  This is provided for convenience -- you can mix your own audio data.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   454
 */
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
   455
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
   456
                                          Uint32 len, int volume);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   457
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   458
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   459
 *  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
   460
 *  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
   461
 *  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
   462
 */
1967
01e29c3e9a29 In general, fill in pointers to structures, rather than return them.
Sam Lantinga <slouken@libsdl.org>
parents: 1964
diff changeset
   463
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
   464
                                                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
   465
                                                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
   466
                                                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
   467
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   468
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   469
 *  \name Audio lock functions
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   470
 *  
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   471
 *  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
   472
 *  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
   473
 *  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
   474
 *  function or you will cause deadlock.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   475
 */
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   476
/*@{*/
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   477
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
   478
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
   479
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
   480
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
   481
/*@}*//*Audio lock functions*/
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   482
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   483
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   484
 *  This function shuts down audio processing and closes the audio device.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   485
 */
337
9154ec9ca3d2 Explicitly specify the SDL API calling convention (C by default)
Sam Lantinga <slouken@libsdl.org>
parents: 297
diff changeset
   486
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
   487
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
   488
3407
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   489
/**
d3baf5ac4e37 Partial fix for bug #859
Sam Lantinga <slouken@libsdl.org>
parents: 3021
diff changeset
   490
 * \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
   491
 */
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 int SDLCALL SDL_AudioDeviceConnected(SDL_AudioDeviceID dev);
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   493
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   494
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   495
/* Ends C function definitions when using C++ */
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   496
#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
   497
/* *INDENT-OFF* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   498
}
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
   499
/* *INDENT-ON* */
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   500
#endif
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   501
#include "close_code.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   502
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
   503
#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
   504
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
   505
/* vi: set ts=4 sw=4 expandtab: */