PSound Class Reference

A class representing a sound. More...

`#include <sound.h>`

Inheritance 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
| 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...
Public Member Functions inherited from PBaseArray< T >
| PBaseArray (PINDEX initialSize=0)
| Construct a new dynamic array of elements of the specified type. More...
| PBaseArray (T const *buffer, PINDEX length, PBoolean dynamic=true)
| Construct a new dynamic array of elements of the specified type. More...
virtual PObject * | Clone () const
| Clone the object. More...
PBoolean | SetAt (PINDEX index, T val)
| Set the specific element in the array. More...
T | GetAt (PINDEX index) const
| Get a value from the array. More...
void | Attach (const T *buffer, PINDEX bufferSize)
| Attach a pointer to a static block to the base array type. More...
T * | GetPointer (PINDEX minSize=0)
| Get a pointer to the internal array and assure that it is of at least the specified size. More...
T | operator[] (PINDEX index) const
| Get a value from the array. More...
T & | operator[] (PINDEX index)
| Get a reference to value from the array. More...
| operator T const * () 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 void | PrintOn (ostream &strm) const
| Output the contents of the object to the stream. More...
virtual void | ReadFrom (istream &strm)
| Input the contents of the object from the stream. 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...
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...
PBoolean | SetMinSize (PINDEX minSize)
| Set the minimum size of container. More...
virtual PBoolean | IsEmpty () const
| Determine if the container is empty. More...
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
virtual | ~PObject ()
virtual PINDEX | HashFunction () const
| This function yields a hash value required by the `PDictionary` class. More...
virtual const char * | GetClass (unsigned ancestor=0) const
| Get the current dynamic type of the object instance. More...
PBoolean | IsClass (const char *cls) const
virtual PBoolean | InternalIsDescendant (const char *clsName) const
| Determine if the dynamic type of the current instance is a descendent of the specified 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 PBoolean | PlayFile (const PFilePath &file, PBoolean wait=true)
| Play a sound file to the default device. More...
static void | Beep ()
| Play the "standard" warning beep for the platform. More...
Static Public Member Functions inherited from PObject
static const char * | Class ()
| Get the name of the class as a C string. 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

## 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< T >
virtual void | PrintElementOn (ostream &stream, PINDEX index) const
| PBaseArray (PContainerReference &reference)
Protected Member Functions inherited from PAbstractArray
PBoolean | InternalSetSize (PINDEX newSize, PBoolean force)
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() [1/2]

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() [2/2]

PSound::PSound | ( | const PFilePath & | filename | ) |

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

Parameters

  filename | Sound file to load.

## Member Function Documentation

## Beep()

static void PSound::Beep | ( |  | ) |

static

Play the "standard" warning beep for the platform.

Referenced by GetFormatInfoData().

## GetChannels()

unsigned PSound::GetChannels | ( |  | ) | const

inline

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

References numChannels.

Referenced by PSoundChannel::GetDirectionText().

## GetEncoding()

unsigned PSound::GetEncoding | ( |  | ) | const

inline

Get the current encoding.

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

References encoding.

## GetErrorCode()

DWORD PSound::GetErrorCode | ( |  | ) | const

inline

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

References dwLastError.

## GetFormatInfoData()

const void* PSound::GetFormatInfoData | ( |  | ) | const

inline

Get pointer to the platform dependent format info.

References Beep(), formatInfo, and PlayFile().

## GetFormatInfoSize()

PINDEX PSound::GetFormatInfoSize | ( |  | ) | const

inline

Get the size of the platform dependent format info.

References formatInfo, and PContainer::GetSize().

## GetSampleRate()

unsigned PSound::GetSampleRate | ( |  | ) | const

inline

Get the sample rate in samples per second.

References sampleRate.

Referenced by PSoundChannel::GetDirectionText().

## GetSampleSize()

unsigned PSound::GetSampleSize | ( |  | ) | const

inline

Get the sample size in bits per sample.

References sampleSize.

Referenced by PSoundChannel::GetDirectionText().

## Load()

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.

## operator=()

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

Set new data bytes for the sound.

Parameters

  data | New data for sound

## Play() [1/2]

PBoolean PSound::Play | ( |  | ) |

Play the sound on the default sound device.

## Play() [2/2]

PBoolean PSound::Play | ( | const PString & | device | ) |

Play the sound to the specified sound device.

## PlayFile()

static PBoolean PSound::PlayFile | ( | const PFilePath & | file,
|  | PBoolean | wait = `true`
| ) |  |

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.

Referenced by GetFormatInfoData().

## Save()

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.

## SetFormat()

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

Referenced by PSoundChannel::GetDirectionText().

## Member Data Documentation

## dwLastError

DWORD PSound::dwLastError

protected

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

Referenced by GetErrorCode().

## encoding

unsigned PSound::encoding

protected

Format code.

Referenced by GetEncoding().

## formatInfo

PBYTEArray PSound::formatInfo

protected

Full info on the format (platform dependent)

Referenced by GetFormatInfoData(), and GetFormatInfoSize().

## numChannels

unsigned PSound::numChannels

protected

Number of channels eg mono/stereo.

Referenced by GetChannels(), PSoundChannel::GetDeviceNames(), and PSoundChannel::GetDirectionText().

## sampleRate

unsigned PSound::sampleRate

protected

Samples per second.

Referenced by PSoundChannel::GetDeviceNames(), PSoundChannel::GetDirectionText(), and GetSampleRate().

## sampleSize

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