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.38  2006/10/19 12:05:32  rjongbloed
00031  * Added missing Close() function apss thru on PSoundChannel wrapper class.
00032  *
00033  * Revision 1.37  2006/06/21 03:28:41  csoutheren
00034  * Various cleanups thanks for Frederic Heem
00035  *
00036  * Revision 1.36  2005/11/25 03:43:47  csoutheren
00037  * Fixed function argument comments to be compatible with Doxygen
00038  *
00039  * Revision 1.35  2005/08/09 09:08:09  rjongbloed
00040  * Merged new video code from branch back to the trunk.
00041  *
00042  * Revision 1.34.2.2  2005/07/17 11:47:45  rjongbloed
00043  * Fixed backward compatibility
00044  *
00045  * Revision 1.34.2.1  2005/07/17 09:27:04  rjongbloed
00046  * Major revisions of the PWLib video subsystem including:
00047  *   removal of F suffix on colour formats for vertical flipping, all done with existing bool
00048  *   working through use of RGB and BGR formats so now consistent
00049  *   cleaning up the plug in system to use virtuals instead of pointers to functions.
00050  *   rewrite of SDL to be a plug in compatible video output device.
00051  *   extensive enhancement of video test program
00052  *
00053  * Revision 1.34  2005/07/13 13:02:35  csoutheren
00054  * Unified interface across Windows and Unix
00055  *
00056  * Revision 1.33  2005/07/04 11:35:03  shorne
00057  * Added ability to play sound to specfied device (Win32).
00058  *
00059  * Revision 1.32  2005/01/04 07:44:03  csoutheren
00060  * More changes to implement the new configuration methodology, and also to
00061  * attack the global static problem
00062  *
00063  * Revision 1.31  2004/11/01 23:16:59  ykiryanov
00064  * Added macro declaring sound plugin to be static for BeOS
00065  *
00066  * Revision 1.30  2003/12/28 02:03:18  csoutheren
00067  * Fixed problem with GetLastReadCount/GetLastWriteCount  on Windows sound devices
00068  *
00069  * Revision 1.29  2003/11/18 10:50:26  csoutheren
00070  * Changed name of Windows sound device
00071  *
00072  * Revision 1.28  2003/11/14 05:59:09  csoutheren
00073  * Added Read function, thanks to Derek Smithies
00074  *
00075  * Revision 1.27  2003/11/12 10:25:41  csoutheren
00076  * Changes to allow operation of static plugins under Windows
00077  *
00078  * Revision 1.26  2003/11/12 05:18:04  csoutheren
00079  * Added more backwards compatibility functions for PSoundChannel
00080  *
00081  * Revision 1.25  2003/11/12 04:33:32  csoutheren
00082  * Fixed problem with static linking of sound plugins
00083  * Fixed problem with Windows sound driver
00084  *
00085  * Revision 1.24  2003/11/12 03:29:51  csoutheren
00086  * Initial version of plugin code from Snark of GnomeMeeting with changes
00087  *    by Craig Southeren of Post Increment
00088  *
00089  * Revision 1.23.2.2  2003/10/13 02:42:39  dereksmithies
00090  * Add additional functions, so plugins work better.
00091  *
00092  * Revision 1.23.2.1  2003/10/07 03:02:28  csoutheren
00093  * Initial checkin of pwlib code to do plugins.
00094  * Modified from original code and concept provided by Snark of Gnomemeeting
00095  *
00096  * Revision 1.23  2003/09/17 05:41:59  csoutheren
00097  * Removed recursive includes
00098  *
00099  * Revision 1.22  2003/09/17 01:18:02  csoutheren
00100  * Removed recursive include file system and removed all references
00101  * to deprecated coooperative threading support
00102  *
00103  * Revision 1.21  2002/09/16 01:08:59  robertj
00104  * Added #define so can select if #pragma interface/implementation is used on
00105  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
00106  *
00107  * Revision 1.20  2002/02/08 09:58:44  robertj
00108  * Slight adjustment to API and documentation for volume functions.
00109  *
00110  * Revision 1.19  2002/02/07 20:57:21  dereks
00111  * add SetVolume and GetVolume methods to PSoundChannel
00112  *
00113  * Revision 1.18  2001/05/22 12:49:32  robertj
00114  * Did some seriously wierd rewrite of platform headers to eliminate the
00115  *   stupid GNU compiler warning about braces not matching.
00116  *
00117  * Revision 1.17  2001/02/07 03:33:43  craigs
00118  * Added functions to get sound channel parameters
00119  *
00120  * Revision 1.16  2000/03/04 10:15:32  robertj
00121  * Added simple play functions for sound files.
00122  *
00123  * Revision 1.15  1999/05/28 14:04:10  robertj
00124  * Added function to get default audio device.
00125  *
00126  * Revision 1.14  1999/03/09 02:59:51  robertj
00127  * Changed comments to doc++ compatible documentation.
00128  *
00129  * Revision 1.13  1999/02/22 10:15:14  robertj
00130  * Sound driver interface implementation to Linux OSS specification.
00131  *
00132  * Revision 1.12  1999/02/16 06:02:27  robertj
00133  * Major implementation to Linux OSS model
00134  *
00135  * Revision 1.11  1998/09/23 06:21:27  robertj
00136  * Added open source copyright license.
00137  *
00138  * Revision 1.10  1995/06/17 11:13:26  robertj
00139  * Documentation update.
00140  *
00141  * Revision 1.9  1995/03/14 12:42:40  robertj
00142  * Updated documentation to use HTML codes.
00143  *
00144  * Revision 1.8  1995/01/16  09:42:05  robertj
00145  * Documentation.
00146  *
00147  * Revision 1.7  1994/08/23  11:32:52  robertj
00148  * Oops
00149  *
00150  * Revision 1.6  1994/08/22  00:46:48  robertj
00151  * Added pragma fro GNU C++ compiler.
00152  *
00153  * Revision 1.5  1994/06/25  11:55:15  robertj
00154  * Unix version synchronisation.
00155  *
00156  * Revision 1.4  1994/01/03  04:42:23  robertj
00157  * Mass changes to common container classes and interactors etc etc etc.
00158  *
00159  * Revision 1.3  1993/09/29  03:06:30  robertj
00160  * Added unix compatibility to Beep()
00161  *
00162  * Revision 1.2  1993/07/14  12:49:16  robertj
00163  * Fixed RCS keywords.
00164  *
00165  */
00166 
00167 
00168 #ifndef _PSOUND
00169 #define _PSOUND
00170 
00171 #ifdef P_USE_PRAGMA
00172 #pragma interface
00173 #endif
00174 
00175 #include <ptlib/plugin.h>
00176 #include <ptlib/pluginmgr.h>
00177 
00185 class PSound : public PBYTEArray
00186 {
00187   PCLASSINFO(PSound, PBYTEArray);
00188 
00189   public:
00198     PSound(
00199       unsigned numChannels = 1,    
00200       unsigned sampleRate = 8000,  
00201       unsigned bitsPerSample = 16, 
00202       PINDEX   bufferSize = 0,     
00203       const BYTE * data = NULL     
00204     );
00205 
00208     PSound(
00209       const PFilePath & filename   
00210     );
00211 
00214     PSound & operator=(
00215       const PBYTEArray & data  
00216     );
00218 
00230     BOOL Load(
00231       const PFilePath & filename   
00232     );
00233 
00240     BOOL Save(
00241       const PFilePath & filename   
00242     );
00244 
00247 
00248     BOOL Play();
00249 
00251     BOOL Play(const PString & device);
00252 
00256     void SetFormat(
00257       unsigned numChannels,   
00258       unsigned sampleRate,    
00259       unsigned bitsPerSample  
00260     );
00261 
00265     unsigned GetEncoding()   const { return encoding; }
00266 
00268     unsigned GetChannels()   const { return numChannels; }
00269 
00271     unsigned GetSampleRate() const { return sampleRate; }
00272 
00274     unsigned GetSampleSize() const { return sampleSize; }
00275 
00277     DWORD    GetErrorCode()  const { return dwLastError; }
00278 
00280     PINDEX   GetFormatInfoSize()  const { return formatInfo.GetSize(); }
00281 
00283     const void * GetFormatInfoData() const { return (const BYTE *)formatInfo; }
00285 
00296     static BOOL PlayFile(
00297       const PFilePath & file, 
00298       BOOL wait = TRUE        
00299     );
00300 
00302     static void Beep();
00304 
00305   protected:
00307     unsigned   encoding;      
00309     unsigned   numChannels;   
00311     unsigned   sampleRate;    
00313     unsigned   sampleSize;    
00315     DWORD      dwLastError;   
00317     PBYTEArray formatInfo;    
00318 };
00319 
00320 
00351 class PSoundChannel : public PChannel
00352 {
00353   PCLASSINFO(PSoundChannel, PChannel);
00354 
00355   public:
00358     enum Directions {
00359       Recorder,
00360       Player
00361     };
00362 
00364     PSoundChannel();
00365 
00369     PSoundChannel(
00370       const PString & device,       
00371       Directions dir,               
00372       unsigned numChannels = 1,     
00373       unsigned sampleRate = 8000,   
00374       unsigned bitsPerSample = 16   
00375     );
00376     // 
00377 
00378     virtual ~PSoundChannel();
00379     // Destroy and close the sound driver
00381 
00386     static PStringList GetDriverNames(
00387       PPluginManager * pluginMgr = NULL   
00388     );
00389 
00394     static PStringList GetDriversDeviceNames(
00395       const PString & driverName,         
00396       Directions direction,               
00397       PPluginManager * pluginMgr = NULL   
00398     );
00399 
00400     // For backward compatibility
00401     static inline PStringList GetDeviceNames(
00402       const PString & driverName,
00403       Directions direction,
00404       PPluginManager * pluginMgr = NULL
00405     ) { return GetDriversDeviceNames(driverName, direction, pluginMgr); }
00406 
00409     static PSoundChannel * CreateChannel (
00410       const PString & driverName,         
00411       PPluginManager * pluginMgr = NULL   
00412     );
00413 
00414     /* Create the matching sound channel that corresponds to the device name.
00415        So, for "fake" return a device that will generate fake video.
00416        For "Phillips 680 webcam" (eg) will return appropriate grabber.
00417        Note that Phillips will return the appropriate grabber also.
00418 
00419        This is typically used with the return values from GetDeviceNames().
00420      */
00421     static PSoundChannel * CreateChannelByName(
00422       const PString & deviceName,         
00423       Directions direction,               
00424       PPluginManager * pluginMgr = NULL   
00425     );
00426 
00432     static PSoundChannel * CreateOpenedChannel(
00433       const PString & driverName,         
00434       const PString & deviceName,         
00435       Directions direction,               
00436       unsigned numChannels = 1,           
00437       unsigned sampleRate = 8000,         
00438       unsigned bitsPerSample = 16,        
00439       PPluginManager * pluginMgr = NULL   
00440     );
00441 
00454     static PString GetDefaultDevice(
00455       Directions dir    // Sound I/O direction
00456     );
00457 
00466     static PStringList GetDeviceNames(
00467       Directions direction,               
00468       PPluginManager * pluginMgr = NULL   
00469     );
00470 
00477     virtual BOOL Open(
00478       const PString & device,       
00479       Directions dir,               
00480       unsigned numChannels = 1,     
00481       unsigned sampleRate = 8000,   
00482       unsigned bitsPerSample = 16   
00483     );
00484 
00490     virtual BOOL IsOpen() const
00491       { return (baseChannel == NULL) ? FALSE : baseChannel->PChannel::IsOpen(); }
00492 
00497     virtual BOOL Close()
00498       { return (baseChannel == NULL) ? -1 : baseChannel->Close(); }
00499 
00505     virtual int GetHandle() const
00506       { return (baseChannel == NULL) ? -1 : baseChannel->PChannel::GetHandle(); }
00507 
00513     virtual BOOL Abort()
00514     { return (baseChannel == NULL) ? FALSE : baseChannel->Abort(); }
00516 
00528     virtual BOOL SetFormat(
00529       unsigned numChannels = 1,     
00530       unsigned sampleRate = 8000,   
00531       unsigned bitsPerSample = 16   
00532     )
00533     { return (baseChannel == NULL) ? FALSE : baseChannel->SetFormat(numChannels, sampleRate, bitsPerSample); }
00534 
00536     virtual unsigned GetChannels()   const
00537     { return (baseChannel == NULL) ? 0 : baseChannel->GetChannels(); }
00538 
00540     virtual unsigned GetSampleRate() const
00541     { return (baseChannel == NULL) ? 0 : baseChannel->GetSampleRate(); }
00542 
00544     virtual unsigned GetSampleSize() const 
00545     { return (baseChannel == NULL) ? 0 : baseChannel->GetSampleSize(); }
00546 
00555     virtual BOOL SetBuffers(
00556       PINDEX size,      
00557       PINDEX count = 2  
00558     )
00559     { return (baseChannel == NULL) ? FALSE : baseChannel->SetBuffers(size, count); }
00560 
00566     virtual BOOL GetBuffers(
00567       PINDEX & size,    // Size of each buffer
00568       PINDEX & count    // Number of buffers
00569     )
00570     { return (baseChannel == NULL) ? FALSE : baseChannel->GetBuffers(size, count); }
00571 
00572     enum {
00573       MaxVolume = 100
00574     };
00575 
00582     virtual BOOL SetVolume(
00583       unsigned volume   
00584     )
00585     { return (baseChannel == NULL) ? FALSE : baseChannel->SetVolume(volume); }
00586 
00593     virtual BOOL GetVolume(
00594       unsigned & volume   
00595     )
00596     { return (baseChannel == NULL) ? FALSE : baseChannel->GetVolume(volume); }
00598 
00601 
00613      virtual BOOL Write(const void * buf, PINDEX len)
00614       { return (baseChannel == NULL) ? FALSE : baseChannel->Write(buf, len); }
00615 
00616     PINDEX GetLastWriteCount() const
00617     { return (baseChannel == NULL) ? lastWriteCount : baseChannel->GetLastWriteCount(); }
00618 
00635     virtual BOOL PlaySound(
00636       const PSound & sound,   
00637       BOOL wait = TRUE        
00638     )
00639     { return (baseChannel == NULL) ? FALSE : baseChannel->PlaySound(sound, wait); }
00655     virtual BOOL PlayFile(
00656       const PFilePath & file, 
00657       BOOL wait = TRUE        
00658     )
00659     { return (baseChannel == NULL) ? FALSE : baseChannel->PlayFile(file, wait); }
00660 
00667     virtual BOOL HasPlayCompleted()
00668     { return (baseChannel == NULL) ? FALSE : baseChannel->HasPlayCompleted(); }
00669 
00676     virtual BOOL WaitForPlayCompletion() 
00677     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForPlayCompletion(); }
00678 
00680 
00695     virtual BOOL Read(
00696       void * buf,   
00697       PINDEX len    
00698     )
00699     { return (baseChannel == NULL) ? FALSE : baseChannel->Read(buf, len); }
00700 
00701     PINDEX GetLastReadCount() const
00702     { return (baseChannel == NULL) ? lastReadCount : baseChannel->GetLastReadCount(); }
00703 
00721     virtual BOOL RecordSound(
00722       PSound & sound 
00723     )
00724     { return (baseChannel == NULL) ? FALSE : baseChannel->RecordSound(sound); }
00725 
00738     virtual BOOL RecordFile(
00739       const PFilePath & file 
00740     )
00741     { return (baseChannel == NULL) ? FALSE : baseChannel->RecordFile(file); }
00742 
00749     virtual BOOL StartRecording()
00750     { return (baseChannel == NULL) ? FALSE : baseChannel->StartRecording(); }
00751 
00759     virtual BOOL IsRecordBufferFull() 
00760     { return (baseChannel == NULL) ? FALSE : baseChannel->IsRecordBufferFull(); }
00761 
00770     virtual BOOL AreAllRecordBuffersFull() 
00771     { return (baseChannel == NULL) ? FALSE : baseChannel->AreAllRecordBuffersFull(); }
00772 
00780     virtual BOOL WaitForRecordBufferFull() 
00781     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForRecordBufferFull() ; }
00782 
00791     virtual BOOL WaitForAllRecordBuffersFull() 
00792     { return (baseChannel == NULL) ? FALSE : baseChannel->WaitForAllRecordBuffersFull() ; }
00794 
00795   protected:
00796     PSoundChannel * baseChannel;
00797 };
00798 
00799 
00801 
00802 // define the sound plugin service descriptor
00803 
00804 template <class className> class PSoundChannelPluginServiceDescriptor : public PDevicePluginServiceDescriptor
00805 {
00806   public:
00807     virtual PObject *   CreateInstance(int /*userData*/) const { return new className; }
00808     virtual PStringList GetDeviceNames(int userData) const { return className::GetDeviceNames((PSoundChannel::Directions)userData); }
00809 };
00810 
00811 #define PCREATE_SOUND_PLUGIN(name, className) \
00812   static PSoundChannelPluginServiceDescriptor<className> className##_descriptor; \
00813   PCREATE_PLUGIN(name, PSoundChannel, &className##_descriptor)
00814 
00815 #endif
00816 
00817 // End Of File ///////////////////////////////////////////////////////////////

Generated on Fri Feb 29 13:37:10 2008 for PWLib by  doxygen 1.5.5