sound.h

Go to the documentation of this file.
00001 /*
00002  * sound.h
00003  *
00004  * Sound interface class.
00005  *
00006  * Portable Windows Library
00007  *
00008  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
00009  *
00010  * The contents of this file are subject to the Mozilla Public License
00011  * Version 1.0 (the "License"); you may not use this file except in
00012  * compliance with the License. You may obtain a copy of the License at
00013  * http://www.mozilla.org/MPL/
00014  *
00015  * Software distributed under the License is distributed on an "AS IS"
00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
00017  * the License for the specific language governing rights and limitations
00018  * under the License.
00019  *
00020  * The Original Code is Portable Windows Library.
00021  *
00022  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
00023  *
00024  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
00025  * All Rights Reserved.
00026  *
00027  * Contributor(s): ______________________________________.
00028  *
00029  * $Log: sound.h,v $
00030  * Revision 1.36  2005/11/25 03:43:47  csoutheren
00031  * Fixed function argument comments to be compatible with Doxygen
00032  *
00033  * Revision 1.35  2005/08/09 09:08:09  rjongbloed
00034  * Merged new video code from branch back to the trunk.
00035  *
00036  * Revision 1.34.2.2  2005/07/17 11:47:45  rjongbloed
00037  * Fixed backward compatibility
00038  *
00039  * Revision 1.34.2.1  2005/07/17 09:27:04  rjongbloed
00040  * Major revisions of the PWLib video subsystem including:
00041  *   removal of F suffix on colour formats for vertical flipping, all done with existing bool
00042  *   working through use of RGB and BGR formats so now consistent
00043  *   cleaning up the plug in system to use virtuals instead of pointers to functions.
00044  *   rewrite of SDL to be a plug in compatible video output device.
00045  *   extensive enhancement of video test program
00046  *
00047  * Revision 1.34  2005/07/13 13:02:35  csoutheren
00048  * Unified interface across Windows and Unix
00049  *
00050  * Revision 1.33  2005/07/04 11:35:03  shorne
00051  * Added ability to play sound to specfied device (Win32).
00052  *
00053  * Revision 1.32  2005/01/04 07:44:03  csoutheren
00054  * More changes to implement the new configuration methodology, and also to
00055  * attack the global static problem
00056  *
00057  * Revision 1.31  2004/11/01 23:16:59  ykiryanov
00058  * Added macro declaring sound plugin to be static for BeOS
00059  *
00060  * Revision 1.30  2003/12/28 02:03:18  csoutheren
00061  * Fixed problem with GetLastReadCount/GetLastWriteCount  on Windows sound devices
00062  *
00063  * Revision 1.29  2003/11/18 10:50:26  csoutheren
00064  * Changed name of Windows sound device
00065  *
00066  * Revision 1.28  2003/11/14 05:59:09  csoutheren
00067  * Added Read function, thanks to Derek Smithies
00068  *
00069  * Revision 1.27  2003/11/12 10:25:41  csoutheren
00070  * Changes to allow operation of static plugins under Windows
00071  *
00072  * Revision 1.26  2003/11/12 05:18:04  csoutheren
00073  * Added more backwards compatibility functions for PSoundChannel
00074  *
00075  * Revision 1.25  2003/11/12 04:33:32  csoutheren
00076  * Fixed problem with static linking of sound plugins
00077  * Fixed problem with Windows sound driver
00078  *
00079  * Revision 1.24  2003/11/12 03:29:51  csoutheren
00080  * Initial version of plugin code from Snark of GnomeMeeting with changes
00081  *    by Craig Southeren of Post Increment
00082  *
00083  * Revision 1.23.2.2  2003/10/13 02:42:39  dereksmithies
00084  * Add additional functions, so plugins work better.
00085  *
00086  * Revision 1.23.2.1  2003/10/07 03:02:28  csoutheren
00087  * Initial checkin of pwlib code to do plugins.
00088  * Modified from original code and concept provided by Snark of Gnomemeeting
00089  *
00090  * Revision 1.23  2003/09/17 05:41:59  csoutheren
00091  * Removed recursive includes
00092  *
00093  * Revision 1.22  2003/09/17 01:18:02  csoutheren
00094  * Removed recursive include file system and removed all references
00095  * to deprecated coooperative threading support
00096  *
00097  * Revision 1.21  2002/09/16 01:08:59  robertj
00098  * Added #define so can select if #pragma interface/implementation is used on
00099  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00100  *
00101  * Revision 1.20  2002/02/08 09:58:44  robertj
00102  * Slight adjustment to API and documentation for volume functions.
00103  *
00104  * Revision 1.19  2002/02/07 20:57:21  dereks
00105  * add SetVolume and GetVolume methods to PSoundChannel
00106  *
00107  * Revision 1.18  2001/05/22 12:49:32  robertj
00108  * Did some seriously wierd rewrite of platform headers to eliminate the
00109  *   stupid GNU compiler warning about braces not matching.
00110  *
00111  * Revision 1.17  2001/02/07 03:33:43  craigs
00112  * Added functions to get sound channel parameters
00113  *
00114  * Revision 1.16  2000/03/04 10:15:32  robertj
00115  * Added simple play functions for sound files.
00116  *
00117  * Revision 1.15  1999/05/28 14:04:10  robertj
00118  * Added function to get default audio device.
00119  *
00120  * Revision 1.14  1999/03/09 02:59:51  robertj
00121  * Changed comments to doc++ compatible documentation.
00122  *
00123  * Revision 1.13  1999/02/22 10:15:14  robertj
00124  * Sound driver interface implementation to Linux OSS specification.
00125  *
00126  * Revision 1.12  1999/02/16 06:02:27  robertj
00127  * Major implementation to Linux OSS model
00128  *
00129  * Revision 1.11  1998/09/23 06:21:27  robertj
00130  * Added open source copyright license.
00131  *
00132  * Revision 1.10  1995/06/17 11:13:26  robertj
00133  * Documentation update.
00134  *
00135  * Revision 1.9  1995/03/14 12:42:40  robertj
00136  * Updated documentation to use HTML codes.
00137  *
00138  * Revision 1.8  1995/01/16  09:42:05  robertj
00139  * Documentation.
00140  *
00141  * Revision 1.7  1994/08/23  11:32:52  robertj
00142  * Oops
00143  *
00144  * Revision 1.6  1994/08/22  00:46:48  robertj
00145  * Added pragma fro GNU C++ compiler.
00146  *
00147  * Revision 1.5  1994/06/25  11:55:15  robertj
00148  * Unix version synchronisation.
00149  *
00150  * Revision 1.4  1994/01/03  04:42:23  robertj
00151  * Mass changes to common container classes and interactors etc etc etc.
00152  *
00153  * Revision 1.3  1993/09/29  03:06:30  robertj
00154  * Added unix compatibility to Beep()
00155  *
00156  * Revision 1.2  1993/07/14  12:49:16  robertj
00157  * Fixed RCS keywords.
00158  *
00159  */
00160 
00161 
00162 #ifndef _PSOUND
00163 #define _PSOUND
00164 
00165 #ifdef P_USE_PRAGMA
00166 #pragma interface
00167 #endif
00168 
00169 #include <ptlib/pluginmgr.h>
00170 
00178 class PSound : public PBYTEArray
00179 {
00180   PCLASSINFO(PSound, PBYTEArray);
00181 
00182   public:
00191     PSound(
00192       unsigned numChannels = 1,    
00193       unsigned sampleRate = 8000,  
00194       unsigned bitsPerSample = 16, 
00195       PINDEX   bufferSize = 0,     
00196       const BYTE * data = NULL     
00197     );
00198 
00201     PSound(
00202       const PFilePath & filename   
00203     );
00204 
00207     PSound & operator=(
00208       const PBYTEArray & data  
00209     );
00211 
00223     BOOL Load(
00224       const PFilePath & filename   
00225     );
00226 
00233     BOOL Save(
00234       const PFilePath & filename   
00235     );
00237 
00240 
00241     BOOL Play();
00242 
00244     BOOL Play(const PString & device);
00245 
00249     void SetFormat(
00250       unsigned numChannels,   
00251       unsigned sampleRate,    
00252       unsigned bitsPerSample  
00253     );
00254 
00258     unsigned GetEncoding()   const { return encoding; }
00259 
00261     unsigned GetChannels()   const { return numChannels; }
00262 
00264     unsigned GetSampleRate() const { return sampleRate; }
00265 
00267     unsigned GetSampleSize() const { return sampleSize; }
00268 
00270     DWORD    GetErrorCode()  const { return dwLastError; }
00271 
00273     PINDEX   GetFormatInfoSize()  const { return formatInfo.GetSize(); }
00274 
00276     const void * GetFormatInfoData() const { return (const BYTE *)formatInfo; }
00278 
00289     static BOOL PlayFile(
00290       const PFilePath & file, 
00291       BOOL wait = TRUE        
00292     );
00293 
00295     static void Beep();
00297 
00298   protected:
00300     unsigned   encoding;      
00302     unsigned   numChannels;   
00304     unsigned   sampleRate;    
00306     unsigned   sampleSize;    
00308     DWORD      dwLastError;   
00310     PBYTEArray formatInfo;    
00311 };
00312 
00313 
00344 class PSoundChannel : public PChannel
00345 {
00346   PCLASSINFO(PSoundChannel, PChannel);
00347 
00348   public:
00351     enum Directions {
00352       Recorder,
00353       Player
00354     };
00355 
00357     PSoundChannel();
00358 
00362     PSoundChannel(
00363       const PString & device,       
00364       Directions dir,               
00365       unsigned numChannels = 1,     
00366       unsigned sampleRate = 8000,   
00367       unsigned bitsPerSample = 16   
00368     );
00369     // 
00370 
00371     virtual ~PSoundChannel();
00372     // Destroy and close the sound driver
00374 
00379     static PStringList GetDriverNames(
00380       PPluginManager * pluginMgr = NULL   
00381     );
00382 
00387     static PStringList GetDriversDeviceNames(
00388       const PString & driverName,         
00389       Directions direction,               
00390       PPluginManager * pluginMgr = NULL   
00391     );
00392 
00393     // For backward compatibility
00394     static inline PStringList GetDeviceNames(
00395       const PString & driverName,
00396       Directions direction,
00397       PPluginManager * pluginMgr = NULL
00398     ) { return GetDriversDeviceNames(driverName, direction, pluginMgr); }
00399 
00402     static PSoundChannel * CreateChannel (
00403       const PString & driverName,         
00404       PPluginManager * pluginMgr = NULL   
00405     );
00406 
00407     /* Create the matching sound channel that corresponds to the device name.
00408        So, for "fake" return a device that will generate fake video.
00409        For "Phillips 680 webcam" (eg) will return appropriate grabber.
00410        Note that Phillips will return the appropriate grabber also.
00411 
00412        This is typically used with the return values from GetDeviceNames().
00413      */
00414     static PSoundChannel * CreateChannelByName(
00415       const PString & deviceName,         
00416       Directions direction,               
00417       PPluginManager * pluginMgr = NULL   
00418     );
00419 
00425     static PSoundChannel * CreateOpenedChannel(
00426       const PString & driverName,         
00427       const PString & deviceName,         
00428       Directions direction,               
00429       unsigned numChannels = 1,           
00430       unsigned sampleRate = 8000,         
00431       unsigned bitsPerSample = 16,        
00432       PPluginManager * pluginMgr = NULL   
00433     );
00434 
00447     static PString GetDefaultDevice(
00448       Directions dir    // Sound I/O direction
00449     );
00450 
00459     static PStringList GetDeviceNames(
00460       Directions direction,               
00461       PPluginManager * pluginMgr = NULL   
00462     );
00463 
00470     virtual BOOL Open(
00471       const PString & device,       
00472       Directions dir,               
00473       unsigned numChannels = 1,     
00474       unsigned sampleRate = 8000,   
00475       unsigned bitsPerSample = 16   
00476     );
00477 
00483     virtual BOOL IsOpen() const
00484       { return (baseChannel == NULL) ? FALSE : baseChannel->PChannel::IsOpen(); }
00485 
00491     virtual int GetHandle() const
00492       { return (baseChannel == NULL) ? -1 : baseChannel->PChannel::GetHandle(); }
00493 
00499     virtual BOOL Abort()
00500     { return (baseChannel == NULL) ? FALSE : baseChannel->Abort(); }
00502 
00514     virtual BOOL SetFormat(
00515       unsigned numChannels = 1,     
00516       unsigned sampleRate = 8000,   
00517       unsigned bitsPerSample = 16   
00518     )
00519     { return (baseChannel == NULL) ? FALSE : baseChannel->SetFormat(numChannels, sampleRate, bitsPerSample); }
00520 
00522     virtual unsigned GetChannels()   const
00523     { return (baseChannel == NULL) ? 0 : baseChannel->GetChannels(); }
00524 
00526     virtual unsigned GetSampleRate() const
00527     { return (baseChannel == NULL) ? 0 : baseChannel->GetSampleRate(); }
00528 
00530     virtual unsigned GetSampleSize() const 
00531     { return (baseChannel == NULL) ? 0 : baseChannel->GetSampleSize(); }
00532 
00541     virtual BOOL SetBuffers(
00542       PINDEX size,      
00543       PINDEX count = 2  
00544     )
00545     { return (baseChannel == NULL) ? FALSE : baseChannel->SetBuffers(size, count); }
00546 
00552     virtual BOOL GetBuffers(
00553       PINDEX & size,    // Size of each buffer
00554       PINDEX & count    // Number of buffers
00555     )
00556     { return (baseChannel == NULL) ? FALSE : baseChannel->GetBuffers(size, count); }
00557 
00558     enum {
00559       MaxVolume = 100
00560     };
00561 
00568     virtual BOOL SetVolume(
00569       unsigned volume   
00570     )
00571     { return (baseChannel == NULL) ? FALSE : baseChannel->SetVolume(volume); }
00572 
00579     virtual BOOL GetVolume(
00580       unsigned & volume   
00581     )
00582     { return (baseChannel == NULL) ? FALSE : baseChannel->GetVolume(volume); }
00584 
00587 
00599      virtual BOOL Write(const void * buf, PINDEX len)
00600       { return (baseChannel == NULL) ? FALSE : baseChannel->Write(buf, len); }
00601 
00602     PINDEX GetLastWriteCount() const
00603     { return (baseChannel == NULL) ? lastWriteCount : baseChannel->GetLastWriteCount(); }
00604 
00621     virtual BOOL PlaySound(
00622       const PSound & sound,   
00623       BOOL wait = TRUE        
00624     )
00625     { return (baseChannel == NULL) ? FALSE : baseChannel->PlaySound(sound, wait); }
00641     virtual BOOL PlayFile(
00642       const PFilePath & file, 
00643       BOOL wait = TRUE        
00644     )
00645     { return (baseChannel == NULL) ? FALSE : baseChannel->PlayFile(file, wait); }
00646 
00653     virtual BOOL HasPlayCompleted()
00654     { return (baseChannel == NULL) ? FALSE : baseChannel->HasPlayCompleted(); }
00655 
00662     virtual BOOL WaitForPlayCompletion() 
00663     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForPlayCompletion(); }
00664 
00666 
00681     virtual BOOL Read(
00682       void * buf,   
00683       PINDEX len    
00684     )
00685     { return (baseChannel == NULL) ? FALSE : baseChannel->Read(buf, len); }
00686 
00687     PINDEX GetLastReadCount() const
00688     { return (baseChannel == NULL) ? lastReadCount : baseChannel->GetLastReadCount(); }
00689 
00707     virtual BOOL RecordSound(
00708       PSound & sound 
00709     )
00710     { return (baseChannel == NULL) ? FALSE : baseChannel->RecordSound(sound); }
00711 
00724     virtual BOOL RecordFile(
00725       const PFilePath & file 
00726     )
00727     { return (baseChannel == NULL) ? FALSE : baseChannel->RecordFile(file); }
00728 
00735     virtual BOOL StartRecording()
00736     { return (baseChannel == NULL) ? FALSE : baseChannel->StartRecording(); }
00737 
00745     virtual BOOL IsRecordBufferFull() 
00746     { return (baseChannel == NULL) ? FALSE : baseChannel->IsRecordBufferFull(); }
00747 
00756     virtual BOOL AreAllRecordBuffersFull() 
00757     { return (baseChannel == NULL) ? FALSE : baseChannel->AreAllRecordBuffersFull(); }
00758 
00766     virtual BOOL WaitForRecordBufferFull() 
00767     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForRecordBufferFull() ; }
00768 
00777     virtual BOOL WaitForAllRecordBuffersFull() 
00778     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForAllRecordBuffersFull() ; }
00780 
00781   protected:
00782     PSoundChannel * baseChannel;
00783 };
00784 
00785 
00787 
00788 // define the sound plugin service descriptor
00789 
00790 template <class className> class PSoundChannelPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00791 {
00792   public:
00793     virtual PObject *   CreateInstance(int /*userData*/) const { return new className; }
00794     virtual PStringList GetDeviceNames(int userData) const { return className::GetDeviceNames((PSoundChannel::Directions)userData); }
00795 };
00796 
00797 #define PCREATE_SOUND_PLUGIN(name, className) \
00798   static PSoundChannelPluginServiceDescriptor<className> className##_descriptor; \
00799   PCREATE_PLUGIN(name, PSoundChannel, &className##_descriptor)
00800 
00801 #endif
00802 
00803 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Sep 21 14:40:11 2007 for PWLib by  doxygen 1.5.3