PortAudio 2.0

pa_win_waveformat.h

Go to the documentation of this file.
00001 #ifndef PA_WIN_WAVEFORMAT_H
00002 #define PA_WIN_WAVEFORMAT_H
00003 
00004 /*
00005  * PortAudio Portable Real-Time Audio Library
00006  * Windows WAVEFORMAT* data structure utilities
00007  * portaudio.h should be included before this file.
00008  *
00009  * Copyright (c) 2007 Ross Bencina
00010  *
00011  * Permission is hereby granted, free of charge, to any person obtaining
00012  * a copy of this software and associated documentation files
00013  * (the "Software"), to deal in the Software without restriction,
00014  * including without limitation the rights to use, copy, modify, merge,
00015  * publish, distribute, sublicense, and/or sell copies of the Software,
00016  * and to permit persons to whom the Software is furnished to do so,
00017  * subject to the following conditions:
00018  *
00019  * The above copyright notice and this permission notice shall be
00020  * included in all copies or substantial portions of the Software.
00021  *
00022  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
00023  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00024  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00025  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
00026  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
00027  * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
00028  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00029  */
00030 
00031 /*
00032  * The text above constitutes the entire PortAudio license; however, 
00033  * the PortAudio community also makes the following non-binding requests:
00034  *
00035  * Any person wishing to distribute modifications to the Software is
00036  * requested to send the modifications to the original developer so that
00037  * they can be incorporated into the canonical version. It is also 
00038  * requested that these non-binding requests be included along with the 
00039  * license above.
00040  */
00041 
00047 #ifdef __cplusplus
00048 extern "C" {
00049 #endif
00050 
00051 /*
00052         The following #defines for speaker channel masks are the same
00053         as those in ksmedia.h, except with PAWIN_ prepended, KSAUDIO_ removed
00054         in some cases, and casts to PaWinWaveFormatChannelMask added.
00055 */
00056 
00057 typedef unsigned long PaWinWaveFormatChannelMask;
00058 
00059 /* Speaker Positions: */
00060 #define PAWIN_SPEAKER_FRONT_LEFT                                ((PaWinWaveFormatChannelMask)0x1)
00061 #define PAWIN_SPEAKER_FRONT_RIGHT                               ((PaWinWaveFormatChannelMask)0x2)
00062 #define PAWIN_SPEAKER_FRONT_CENTER                              ((PaWinWaveFormatChannelMask)0x4)
00063 #define PAWIN_SPEAKER_LOW_FREQUENCY                             ((PaWinWaveFormatChannelMask)0x8)
00064 #define PAWIN_SPEAKER_BACK_LEFT                                 ((PaWinWaveFormatChannelMask)0x10)
00065 #define PAWIN_SPEAKER_BACK_RIGHT                                ((PaWinWaveFormatChannelMask)0x20)
00066 #define PAWIN_SPEAKER_FRONT_LEFT_OF_CENTER              ((PaWinWaveFormatChannelMask)0x40)
00067 #define PAWIN_SPEAKER_FRONT_RIGHT_OF_CENTER             ((PaWinWaveFormatChannelMask)0x80)
00068 #define PAWIN_SPEAKER_BACK_CENTER                               ((PaWinWaveFormatChannelMask)0x100)
00069 #define PAWIN_SPEAKER_SIDE_LEFT                                 ((PaWinWaveFormatChannelMask)0x200)
00070 #define PAWIN_SPEAKER_SIDE_RIGHT                                ((PaWinWaveFormatChannelMask)0x400)
00071 #define PAWIN_SPEAKER_TOP_CENTER                                ((PaWinWaveFormatChannelMask)0x800)
00072 #define PAWIN_SPEAKER_TOP_FRONT_LEFT                    ((PaWinWaveFormatChannelMask)0x1000)
00073 #define PAWIN_SPEAKER_TOP_FRONT_CENTER                  ((PaWinWaveFormatChannelMask)0x2000)
00074 #define PAWIN_SPEAKER_TOP_FRONT_RIGHT                   ((PaWinWaveFormatChannelMask)0x4000)
00075 #define PAWIN_SPEAKER_TOP_BACK_LEFT                             ((PaWinWaveFormatChannelMask)0x8000)
00076 #define PAWIN_SPEAKER_TOP_BACK_CENTER                   ((PaWinWaveFormatChannelMask)0x10000)
00077 #define PAWIN_SPEAKER_TOP_BACK_RIGHT                    ((PaWinWaveFormatChannelMask)0x20000)
00078 
00079 /* Bit mask locations reserved for future use */
00080 #define PAWIN_SPEAKER_RESERVED                                  ((PaWinWaveFormatChannelMask)0x7FFC0000)
00081 
00082 /* Used to specify that any possible permutation of speaker configurations */
00083 #define PAWIN_SPEAKER_ALL                                               ((PaWinWaveFormatChannelMask)0x80000000)
00084 
00085 /* DirectSound Speaker Config */
00086 #define PAWIN_SPEAKER_DIRECTOUT                                 0
00087 #define PAWIN_SPEAKER_MONO                                              (PAWIN_SPEAKER_FRONT_CENTER)
00088 #define PAWIN_SPEAKER_STEREO                                    (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT)
00089 #define PAWIN_SPEAKER_QUAD                                              (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT | \
00090                                                                                                 PAWIN_SPEAKER_BACK_LEFT  | PAWIN_SPEAKER_BACK_RIGHT)
00091 #define PAWIN_SPEAKER_SURROUND                                  (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT | \
00092                                                                                                 PAWIN_SPEAKER_FRONT_CENTER | PAWIN_SPEAKER_BACK_CENTER)
00093 #define PAWIN_SPEAKER_5POINT1                                   (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT | \
00094                                                                                                 PAWIN_SPEAKER_FRONT_CENTER | PAWIN_SPEAKER_LOW_FREQUENCY | \
00095                                                                                                 PAWIN_SPEAKER_BACK_LEFT  | PAWIN_SPEAKER_BACK_RIGHT)
00096 #define PAWIN_SPEAKER_7POINT1                                   (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT | \
00097                                                                                                 PAWIN_SPEAKER_FRONT_CENTER | PAWIN_SPEAKER_LOW_FREQUENCY | \
00098                                                                                                 PAWIN_SPEAKER_BACK_LEFT | PAWIN_SPEAKER_BACK_RIGHT | \
00099                                                                                                 PAWIN_SPEAKER_FRONT_LEFT_OF_CENTER | PAWIN_SPEAKER_FRONT_RIGHT_OF_CENTER)
00100 #define PAWIN_SPEAKER_5POINT1_SURROUND                  (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT | \
00101                                                                                                 PAWIN_SPEAKER_FRONT_CENTER | PAWIN_SPEAKER_LOW_FREQUENCY | \
00102                                                                                                 PAWIN_SPEAKER_SIDE_LEFT  | PAWIN_SPEAKER_SIDE_RIGHT)
00103 #define PAWIN_SPEAKER_7POINT1_SURROUND                  (PAWIN_SPEAKER_FRONT_LEFT | PAWIN_SPEAKER_FRONT_RIGHT | \
00104                                                                                                 PAWIN_SPEAKER_FRONT_CENTER | PAWIN_SPEAKER_LOW_FREQUENCY | \
00105                                                                                                 PAWIN_SPEAKER_BACK_LEFT | PAWIN_SPEAKER_BACK_RIGHT | \
00106                                                                                                 PAWIN_SPEAKER_SIDE_LEFT | PAWIN_SPEAKER_SIDE_RIGHT)
00107 /*
00108  According to the Microsoft documentation:
00109  The following are obsolete 5.1 and 7.1 settings (they lack side speakers).  Note this means
00110  that the default 5.1 and 7.1 settings (KSAUDIO_SPEAKER_5POINT1 and KSAUDIO_SPEAKER_7POINT1 are
00111  similarly obsolete but are unchanged for compatibility reasons).
00112 */
00113 #define PAWIN_SPEAKER_5POINT1_BACK                              PAWIN_SPEAKER_5POINT1
00114 #define PAWIN_SPEAKER_7POINT1_WIDE                              PAWIN_SPEAKER_7POINT1
00115 
00116 /* DVD Speaker Positions */
00117 #define PAWIN_SPEAKER_GROUND_FRONT_LEFT                 PAWIN_SPEAKER_FRONT_LEFT
00118 #define PAWIN_SPEAKER_GROUND_FRONT_CENTER               PAWIN_SPEAKER_FRONT_CENTER
00119 #define PAWIN_SPEAKER_GROUND_FRONT_RIGHT                PAWIN_SPEAKER_FRONT_RIGHT
00120 #define PAWIN_SPEAKER_GROUND_REAR_LEFT                  PAWIN_SPEAKER_BACK_LEFT
00121 #define PAWIN_SPEAKER_GROUND_REAR_RIGHT                 PAWIN_SPEAKER_BACK_RIGHT
00122 #define PAWIN_SPEAKER_TOP_MIDDLE                                PAWIN_SPEAKER_TOP_CENTER
00123 #define PAWIN_SPEAKER_SUPER_WOOFER                              PAWIN_SPEAKER_LOW_FREQUENCY
00124 
00125 
00126 /*
00127         PaWinWaveFormat is defined here to provide compatibility with
00128         compilation environments which don't have headers defining 
00129         WAVEFORMATEXTENSIBLE (e.g. older versions of MSVC, Borland C++ etc.
00130 
00131         The fields for WAVEFORMATEX and WAVEFORMATEXTENSIBLE are declared as an
00132     unsigned char array here to avoid clients who include this file having 
00133     a dependency on windows.h and mmsystem.h, and also to to avoid having
00134     to write separate packing pragmas for each compiler.
00135 */
00136 #define PAWIN_SIZEOF_WAVEFORMATEX   18
00137 #define PAWIN_SIZEOF_WAVEFORMATEXTENSIBLE (PAWIN_SIZEOF_WAVEFORMATEX + 22)
00138 
00139 typedef struct{
00140     unsigned char fields[ PAWIN_SIZEOF_WAVEFORMATEXTENSIBLE ];
00141     unsigned long extraLongForAlignment; /* ensure that compiler aligns struct to DWORD */ 
00142 } PaWinWaveFormat;
00143 
00144 /*
00145     WAVEFORMATEXTENSIBLE fields:
00146     
00147     union  {
00148             WORD  wValidBitsPerSample;    
00149             WORD  wSamplesPerBlock;    
00150             WORD  wReserved;  
00151     } Samples;
00152     DWORD  dwChannelMask;  
00153     GUID  SubFormat;
00154 */
00155 
00156 #define PAWIN_INDEXOF_WVALIDBITSPERSAMPLE       (PAWIN_SIZEOF_WAVEFORMATEX+0)
00157 #define PAWIN_INDEXOF_DWCHANNELMASK                     (PAWIN_SIZEOF_WAVEFORMATEX+2)
00158 #define PAWIN_INDEXOF_SUBFORMAT                         (PAWIN_SIZEOF_WAVEFORMATEX+6)
00159 
00160 
00161 /*
00162     Valid values to pass for the waveFormatTag PaWin_InitializeWaveFormatEx and
00163     PaWin_InitializeWaveFormatExtensible functions below. These must match
00164     the standard Windows WAVE_FORMAT_* values.
00165 */
00166 #define PAWIN_WAVE_FORMAT_PCM               (1)
00167 #define PAWIN_WAVE_FORMAT_IEEE_FLOAT        (3)
00168 #define PAWIN_WAVE_FORMAT_DOLBY_AC3_SPDIF   (0x0092)
00169 #define PAWIN_WAVE_FORMAT_WMA_SPDIF         (0x0164)
00170 
00171 
00172 /*
00173     returns PAWIN_WAVE_FORMAT_PCM or PAWIN_WAVE_FORMAT_IEEE_FLOAT
00174     depending on the sampleFormat parameter.
00175 */
00176 int PaWin_SampleFormatToLinearWaveFormatTag( PaSampleFormat sampleFormat );
00177 
00178 /*
00179         Use the following two functions to initialize the waveformat structure.
00180 */
00181 
00182 void PaWin_InitializeWaveFormatEx( PaWinWaveFormat *waveFormat, 
00183                 int numChannels, PaSampleFormat sampleFormat, int waveFormatTag, double sampleRate );
00184 
00185 
00186 void PaWin_InitializeWaveFormatExtensible( PaWinWaveFormat *waveFormat, 
00187                 int numChannels, PaSampleFormat sampleFormat, int waveFormatTag, double sampleRate,
00188             PaWinWaveFormatChannelMask channelMask );
00189 
00190 
00191 /* Map a channel count to a speaker channel mask */
00192 PaWinWaveFormatChannelMask PaWin_DefaultChannelMask( int numChannels );
00193 
00194 
00195 #ifdef __cplusplus
00196 }
00197 #endif /* __cplusplus */
00198 
00199 #endif /* PA_WIN_WAVEFORMAT_H */