Difference between revisions of "User:Henke37/HSound"

From WiiBrew
Jump to navigation Jump to search
(New page: HSound is an unfinished sound library for the Wii by {{u|henke37}}. It is written in c++. It uses the pull design, the sound samples are specifically requested from the sound sources, comp...)
 
 
Line 7: Line 7:
 
Warning: The different classes that take a SoundSource pointer as a parameter has no way of telling when the pointer becomes invalid, do not forget to change the pointer to a valid value before the object it points to is destroyed. This is especially important for the SoundCard, since that one is a global object that runs even after main returns. Think of it as not changing the cabling while the equipment is powered on and to turn off the amplifier before the sound source.
 
Warning: The different classes that take a SoundSource pointer as a parameter has no way of telling when the pointer becomes invalid, do not forget to change the pointer to a valid value before the object it points to is destroyed. This is especially important for the SoundCard, since that one is a global object that runs even after main returns. Think of it as not changing the cabling while the equipment is powered on and to turn off the amplifier before the sound source.
  
=Basic consepts=
+
=The SoundCard class=
==The SoundCard class==
 
 
The SoundCard class abstracts away the low level sound hardware as an easy to use class.
 
The SoundCard class abstracts away the low level sound hardware as an easy to use class.
===Usage===
+
==Usage==
 
Just call the setSource member function with a pointer to either a valid SoundSource object or null. Do not let the SoundSource object become invalid without calling the function to set the source to a valid source! The set source must fully fill the buffer when called. The sound format is 48 KHz stereo. Setting the sound level to zero does not stop the source usage.
 
Just call the setSource member function with a pointer to either a valid SoundSource object or null. Do not let the SoundSource object become invalid without calling the function to set the source to a valid source! The set source must fully fill the buffer when called. The sound format is 48 KHz stereo. Setting the sound level to zero does not stop the source usage.
===Low level implementation===
+
==Low level implementation==
 
It runs a thread with priority 80 to keep the buffer filled, the thread is blocked while the buffer is consumed and asleep while the source is a null pointer.
 
It runs a thread with priority 80 to keep the buffer filled, the thread is blocked while the buffer is consumed and asleep while the source is a null pointer.
===Other notes===
+
==Other notes==
 
The SoundCard class is a singleton and is a global object named "soundCard".
 
The SoundCard class is a singleton and is a global object named "soundCard".
  
==The SoundSource class==
+
=The SoundSource class=
The SoundSource class is the interface used by the library to manage the sample flow. All sound outputting classes extends this class. The loadNextBuffer pure virtual member function is used to fill in a caller provided buffer with SoundSample objects. The length parameter is measured in sample pairs. The return value is the number of actually written sample pairs.
+
The SoundSource class is the interface used by the library to manage the sample flow. All sound outputting classes extends this class. The loadNextBuffer pure virtual member function is used to fill in a caller provided buffer with SoundSample objects. The length parameter is measured in sample pairs, that is, one stereo sample. The return value is the number of actually written sample pairs.
  
==The SilenceGenerator class==
+
=The SilenceGenerator class=
 
A SoundSource that provides silence, it has no functions or properties of interest.
 
A SoundSource that provides silence, it has no functions or properties of interest.
  
==The SineGenerator class==
+
=The SineGenerator class=
 
The stock Sinewave generator that all soundlibraries need. It is due for cleanup.
 
The stock Sinewave generator that all soundlibraries need. It is due for cleanup.
  
==The SoundMixer class and family==
+
=The SoundMixer class and family=
The SoundMixer class is a software soundmixer and provides the normal sound API mixing features. Use the channels property to manage  the channel std::list. Watch out for threading issues and don't add and remove channels while the mixer output is used. The soundmixer will fully fill the provided buffer in loadNextBuffer.
+
The SoundMixer class is a software sound mixer and provides the normal sound API mixing features. Use the channels property to manage  the channel std::list. Watch out for threading issues and don't add and remove channels while the mixer output is used. The soundmixer will fully fill the provided buffer in loadNextBuffer. The mixing does NOT clip the signal, possible overflow corruption may occur. This means that you can not generate the popular distortion effect with the mixer.
===The SoundChannel class===
+
==The SoundChannel class==
 
A very basic class, used in the mixer. Remember to not let the source member variable become invalid and that the channel starts out with both the left and right sub channels with 0 volume. Even at zero value the sound channel is considered used and will have the loadNextBuffer member function called.
 
A very basic class, used in the mixer. Remember to not let the source member variable become invalid and that the channel starts out with both the left and right sub channels with 0 volume. Even at zero value the sound channel is considered used and will have the loadNextBuffer member function called.
  
==The OnePlayBackup class==
+
=The OnePlayBackup class=
 
A quick way to cover for SoundSources that may run out of samples. It will always call loadNextBuffer on the set source, but will cover for it by substituting silence if the buffer is not fully filled.
 
A quick way to cover for SoundSources that may run out of samples. It will always call loadNextBuffer on the set source, but will cover for it by substituting silence if the buffer is not fully filled.
  
==The SoundPlayer class==
+
=The SoundPlayer class=
 
Basic interface class, just has the property "soundDone".
 
Basic interface class, just has the property "soundDone".
  
==The MP3Player class==
+
=The MP3Player class=
 
Base class for the MP3 playback classes and provides the decoding loop. Not possible to use directly. Does not provide ID3 support.
 
Base class for the MP3 playback classes and provides the decoding loop. Not possible to use directly. Does not provide ID3 support.
  
==The MemmoryMP3Player class==
+
=The MemmoryMP3Player class=
 
Concrete class for playing back a char * as MP3 data. Useful for stuff embedded with bin2o.
 
Concrete class for playing back a char * as MP3 data. Useful for stuff embedded with bin2o.

Latest revision as of 10:26, 25 August 2008

HSound is an unfinished sound library for the Wii by henke37. It is written in c++. It uses the pull design, the sound samples are specifically requested from the sound sources, compared to letting the sound sources create samples as they feel like.

The library is currently not publicly released, but if you want to alpha test it, contact the author.

All sound is done with 48KHz stereo 16 bit samples.

Warning: The different classes that take a SoundSource pointer as a parameter has no way of telling when the pointer becomes invalid, do not forget to change the pointer to a valid value before the object it points to is destroyed. This is especially important for the SoundCard, since that one is a global object that runs even after main returns. Think of it as not changing the cabling while the equipment is powered on and to turn off the amplifier before the sound source.

The SoundCard class

The SoundCard class abstracts away the low level sound hardware as an easy to use class.

Usage

Just call the setSource member function with a pointer to either a valid SoundSource object or null. Do not let the SoundSource object become invalid without calling the function to set the source to a valid source! The set source must fully fill the buffer when called. The sound format is 48 KHz stereo. Setting the sound level to zero does not stop the source usage.

Low level implementation

It runs a thread with priority 80 to keep the buffer filled, the thread is blocked while the buffer is consumed and asleep while the source is a null pointer.

Other notes

The SoundCard class is a singleton and is a global object named "soundCard".

The SoundSource class

The SoundSource class is the interface used by the library to manage the sample flow. All sound outputting classes extends this class. The loadNextBuffer pure virtual member function is used to fill in a caller provided buffer with SoundSample objects. The length parameter is measured in sample pairs, that is, one stereo sample. The return value is the number of actually written sample pairs.

The SilenceGenerator class

A SoundSource that provides silence, it has no functions or properties of interest.

The SineGenerator class

The stock Sinewave generator that all soundlibraries need. It is due for cleanup.

The SoundMixer class and family

The SoundMixer class is a software sound mixer and provides the normal sound API mixing features. Use the channels property to manage the channel std::list. Watch out for threading issues and don't add and remove channels while the mixer output is used. The soundmixer will fully fill the provided buffer in loadNextBuffer. The mixing does NOT clip the signal, possible overflow corruption may occur. This means that you can not generate the popular distortion effect with the mixer.

The SoundChannel class

A very basic class, used in the mixer. Remember to not let the source member variable become invalid and that the channel starts out with both the left and right sub channels with 0 volume. Even at zero value the sound channel is considered used and will have the loadNextBuffer member function called.

The OnePlayBackup class

A quick way to cover for SoundSources that may run out of samples. It will always call loadNextBuffer on the set source, but will cover for it by substituting silence if the buffer is not fully filled.

The SoundPlayer class

Basic interface class, just has the property "soundDone".

The MP3Player class

Base class for the MP3 playback classes and provides the decoding loop. Not possible to use directly. Does not provide ID3 support.

The MemmoryMP3Player class

Concrete class for playing back a char * as MP3 data. Useful for stuff embedded with bin2o.