A class representing a sound. More...

#include <sound.h>

Inheritance diagram for PSound:

Collaboration diagram for PSound:

Public Member Functions
Construction
	PSound (unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16, PINDEX bufferSize=0, const BYTE *data=NULL)
	Create a new sound, using the parameters provided. More...

	PSound (const PFilePath &filename)
	Create a new sound, reading from a platform dependent file. More...

PSound &	operator= (const PBYTEArray &data)
	Set new data bytes for the sound. More...

File functions
PBoolean	Load (const PFilePath &filename)
	Load a platform dependent sound file (eg .WAV file for Win32) into the object. More...

PBoolean	Save (const PFilePath &filename)
	Save a platform dependent sound file (eg .WAV file for Win32) from the object. More...

Access functions
PBoolean	Play ()
	Play the sound on the default sound device. More...

PBoolean	Play (const PString &device)
	Play the sound to the specified sound device. More...

void	SetFormat (unsigned numChannels, unsigned sampleRate, unsigned bitsPerSample)
	Set the internal sound format to linear PCM at the specification in the parameters. More...

unsigned	GetEncoding () const
	Get the current encoding. More...

unsigned	GetChannels () const
	Get the number of channels (mono/stereo) in the sound. More...

unsigned	GetSampleRate () const
	Get the sample rate in samples per second. More...

unsigned	GetSampleSize () const
	Get the sample size in bits per sample. More...

DWORD	GetErrorCode () const
	Get the platform dependent error code from the last file load. More...

PINDEX	GetFormatInfoSize () const
	Get the size of the platform dependent format info. More...

const void *	GetFormatInfoData () const
	Get pointer to the platform dependent format info. More...

Public Member Functions inherited from PBYTEArray
template<typename T >
const T &	GetAs (PINDEX offset=0)
	Function to cast block of memory in PBYTEArray to another structure. More...

	PBYTEArray (PINDEX initialSize=0)
	Construct a new dynamic array of unsigned chars. More...

	PBYTEArray (BYTE const *buffer, PINDEX length, PBoolean dynamic=true)
	Construct a new dynamic array of unsigned chars. More...

	PBYTEArray (PContainerReference &reference_)

virtual void	PrintOn (ostream &strm) const
	Print the array. More...

virtual void	ReadFrom (istream &strm)
	Read the array. More...

virtual PObject *	Clone () const
	Clone the object. More...

Public Member Functions inherited from PBaseArray< BYTE >
	PBaseArray (PINDEX initialSize=0)
	Construct a new dynamic array of elements of the specified type. More...

	PBaseArray (BYTEconst *buffer, PINDEX length, PBoolean dynamic=true)
	Construct a new dynamic array of elements of the specified type. More...

PBoolean	SetAt (PINDEX index, BYTEval)
	Set the specific element in the array. More...

BYTE	GetAt (PINDEX index) const
	Get a value from the array. More...

void	Attach (const BYTE *buffer, PINDEX bufferSize)
	Attach a pointer to a static block to the base array type. More...

BYTE *	GetPointer (PINDEX minSize=0)
	Get a pointer to the internal array and assure that it is of at least the specified size. More...

BYTE	operator[] (PINDEX index) const
	Get a value from the array. More...

BYTE &	operator[] (PINDEX index)
	Get a reference to value from the array. More...

	operator BYTEconst * () const
	Get a pointer to the internal array. More...

PBoolean	Concatenate (const PBaseArray &array)
	Concatenate one array to the end of this array. More...

Public Member Functions inherited from PAbstractArray
	PAbstractArray (PINDEX elementSizeInBytes, PINDEX initialSize=0)
	Create a new dynamic array of `initalSize` elements of `elementSizeInBytes` bytes each. More...

	PAbstractArray (PINDEX elementSizeInBytes, const void *buffer, PINDEX bufferSizeInElements, PBoolean dynamicAllocation)
	Create a new dynamic array of `bufferSizeInElements` elements of `elementSizeInBytes` bytes each. More...

virtual Comparison	Compare (const PObject &obj) const
	Get the relative rank of the two arrays. More...

virtual PBoolean	SetSize (PINDEX newSize)
	Set the size of the array in elements. More...

void	Attach (const void *buffer, PINDEX bufferSize)
	Attach a pointer to a static block to the base array type. More...

void *	GetPointer (PINDEX minSize=1)
	Get a pointer to the internal array and assure that it is of at least the specified size. More...

const void *	GetPointer () const

virtual PINDEX	GetLength () const
	Retrun the length in bytes for the array. More...

PBoolean	Concatenate (const PAbstractArray &array)
	Concatenate one array to the end of this array. More...

Public Member Functions inherited from PContainer
	PContainer (PINDEX initialSize=0)
	Create a new unique container. More...

	PContainer (const PContainer &cont)
	Create a new refernce to container. More...

PContainer &	operator= (const PContainer &cont)
	Assign one container reference to another. More...

virtual	~PContainer ()
	Destroy the container class. More...

virtual PINDEX	GetSize () const
	Get the current size of the container. More...

__inline size_t	size () const

PBoolean	SetMinSize (PINDEX minSize)
	Set the minimum size of container. More...

virtual PBoolean	IsEmpty () const
	Determine if the container is empty. More...

__inline bool	empty () const

PBoolean	IsUnique () const
	Determine if container is unique reference. More...

virtual PBoolean	MakeUnique ()
	Make this instance to be the one and only reference to the container contents. More...

Public Member Functions inherited from PObject
__inline unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

__inline void	SetTraceContextIdentifier (unsigned id)

__inline void	SetTraceContextIdentifier (const PObject &obj)

__inline void	SetTraceContextIdentifier (const PObject *obj)

__inline void	CopyTraceContextIdentifier (PObject &obj) const

__inline void	CopyTraceContextIdentifier (PObject *obj) const

virtual	~PObject ()

__inline const char *	GetClass () const

__inline bool	IsClass (const char *name) const

__inline const PObject *	PTraceObjectInstance () const

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

Static Public Member Functions
Miscellaneous functions
static bool	PlayFile (const PFilePath &file, bool wait=true, unsigned volume=100)
	Play a sound file to the default device. More...

static void	Beep ()
	Play the "standard" warning beep for the platform. More...

static bool	ConvertPCM (const short srcPtr, PINDEX &srcSize, unsigned srcRate, unsigned srcChannels, short dstPtr, PINDEX &dstSize, unsigned dstRate, unsigned dstChannels)
	Convert PCM data sample rates and channel depth. More...

Static Public Member Functions inherited from PObject
static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject *from)

static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject to, const PObject from)

static __inline const char *	Class ()

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

template<typename T >
static Comparison	Compare2 (T v1, T v2)
	Compare two types, returning Comparison type. More...

static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

Protected Attributes
unsigned	encoding
	Format code. More...

unsigned	numChannels
	Number of channels eg mono/stereo. More...

unsigned	sampleRate
	Samples per second. More...

unsigned	sampleSize
	Number of bits per sample. More...

DWORD	dwLastError
	Last error code for Load()/Save() functions. More...

PBYTEArray	formatInfo
	Full info on the format (platform dependent) More...

Protected Attributes inherited from PAbstractArray
PINDEX	elementSize
	Size of an element in bytes. More...

char *	theArray
	Pointer to the allocated block of memory. More...

PBoolean	allocatedDynamically
	Flag indicating the array was allocated on the heap. More...

Protected Attributes inherited from PContainer
PContainerReference *	reference

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Additional Inherited Members
Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Protected Member Functions inherited from PBaseArray< BYTE >
	PBaseArray (PContainerReference &reference_)

virtual void	PrintElementOn (ostream &stream, PINDEX index) const

Protected Member Functions inherited from PAbstractArray
PBoolean	InternalSetSize (PINDEX newSize, PBoolean force)

virtual void	PrintElementOn (ostream &stream, PINDEX index) const

virtual void	ReadElementFrom (istream &stream, PINDEX index)

	PAbstractArray (PContainerReference &reference, PINDEX elementSizeInBytes)

Protected Member Functions inherited from PContainer
	PContainer (int dummy, const PContainer *cont)
	Constructor used in support of the Clone() function. More...

	PContainer (PContainerReference &reference)
	Construct using static PContainerReference. More...

virtual void	DestroyContents ()=0
	Destroy the container contents. More...

virtual void	AssignContents (const PContainer &c)
	Copy the container contents. More...

void	CopyContents (const PContainer &c)
	Copy the container contents. More...

void	CloneContents (const PContainer *src)
	Create a duplicate of the container contents. More...

void	Destruct ()
	Internal function called from container destructors. More...

virtual void	DestroyReference ()
	Destroy the PContainerReference instance. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Detailed Description

A class representing a sound.

A sound is a highly platform dependent entity that is abstracted for use here. Very little manipulation of the sounds are possible.

The most common sound to use is the static function Beep() which emits the system standard "warning" or "attention" sound.

Constructor & Destructor Documentation

PSound::PSound	(	unsigned	numChannels = `1`,
		unsigned	sampleRate = `8000`,
		unsigned	bitsPerSample = `16`,
		PINDEX	bufferSize = `0`,
		const BYTE *	data = `NULL`
	)

Create a new sound, using the parameters provided.

It is expected that the "lowest common denominator" encoding, linear PCM, is used.

All other values for the encoding are platform dependent.

Parameters

numChannels	Number of channels eg mono/stereo
sampleRate	Samples per second
bitsPerSample	Number of bits per sample
bufferSize	Size of data
data	Pointer to initial data

PSound::PSound ( const PFilePath & filename )

Create a new sound, reading from a platform dependent file.

Parameters

filename Sound file to load.

Member Function Documentation

static void PSound::Beep ( )

static

Play the "standard" warning beep for the platform.

static bool PSound::ConvertPCM	(	const short *	srcPtr,
		PINDEX &	srcSize,
		unsigned	srcRate,
		unsigned	srcChannels,
		short *	dstPtr,
		PINDEX &	dstSize,
		unsigned	dstRate,
		unsigned	dstChannels
	)

static

Convert PCM data sample rates and channel depth.

@ return true if all the input could be converted in the output buffer size.

Parameters

srcPtr	Source PCM data
srcSize	In: number of bytes of source PCM, Out: bytes consumed
srcRate	Sample rate for source PCM
srcChannels	Number of channels for source PCM
dstPtr	Destination PCM data, may be same as srcPtr
dstSize	In: size of destination buffer, Out: bytes written
dstRate	Sample rate for destination PCM
dstChannels	Number of channels for destination PCM

unsigned PSound::GetChannels ( ) const

inline

Get the number of channels (mono/stereo) in the sound.

References numChannels.

unsigned PSound::GetEncoding ( ) const

inline

Get the current encoding.

A value of 0 indicates linear PCM, any other value is platform dependent.

References encoding.

DWORD PSound::GetErrorCode ( ) const

inline

Get the platform dependent error code from the last file load.

References dwLastError.

const void* PSound::GetFormatInfoData ( ) const

inline

Get pointer to the platform dependent format info.

References formatInfo.

PINDEX PSound::GetFormatInfoSize ( ) const

inline

Get the size of the platform dependent format info.

References formatInfo, and PContainer::GetSize().

unsigned PSound::GetSampleRate ( ) const

inline

Get the sample rate in samples per second.

References sampleRate.

unsigned PSound::GetSampleSize ( ) const

inline

Get the sample size in bits per sample.

References sampleSize.

PBoolean PSound::Load ( const PFilePath & filename )

Load a platform dependent sound file (eg .WAV file for Win32) into the object.

Note the whole file must able to be loaded into memory.

Also note that not all possible files are playable by this library. No format conversions between file and driver are performed.

Returns: true if the sound is loaded successfully.

Parameters

filename Sound file to load.

PSound& PSound::operator= ( const PBYTEArray & data )

Set new data bytes for the sound.

Parameters

data	New data for sound

PBoolean PSound::Play ( )

Play the sound on the default sound device.

PBoolean PSound::Play ( const PString & device )

Play the sound to the specified sound device.

static bool PSound::PlayFile	(	const PFilePath &	file,
		bool	wait = `true`,
		unsigned	volume = `100`
	)

static

Play a sound file to the default device.

If the wait parameter is true then the function does not return until the file has been played. If false then the sound play is begun asynchronously and the function returns immediately.

Returns: true if the sound is playing or has played.

Parameters

file	Sound file to play.
wait	Flag to play sound synchronously.
volume	Volume in percent to play the wave file.

PBoolean PSound::Save ( const PFilePath & filename )

Save a platform dependent sound file (eg .WAV file for Win32) from the object.

Returns: true if the sound is saved successfully.

Parameters

filename Sound file to load.

void PSound::SetFormat	(	unsigned	numChannels,
		unsigned	sampleRate,
		unsigned	bitsPerSample
	)

Set the internal sound format to linear PCM at the specification in the parameters.

Parameters

numChannels	Number of channels eg mono/stereo
sampleRate	Samples per second
bitsPerSample	Number of bits per sample

Member Data Documentation

DWORD PSound::dwLastError

protected

Last error code for Load()/Save() functions.

Referenced by GetErrorCode().

unsigned PSound::encoding

protected

Format code.

Referenced by GetEncoding().

PBYTEArray PSound::formatInfo

protected

Full info on the format (platform dependent)

Referenced by GetFormatInfoData(), and GetFormatInfoSize().

unsigned PSound::numChannels

protected

Number of channels eg mono/stereo.

Referenced by GetChannels().

unsigned PSound::sampleRate

protected

Samples per second.

Referenced by GetSampleRate().

unsigned PSound::sampleSize

protected

Number of bits per sample.

Referenced by GetSampleSize().

The documentation for this class was generated from the following file:

sound.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation