-
Notifications
You must be signed in to change notification settings - Fork 45
AudioBuffer
For the use case of an AudioBuffer, please read "Understanding MWEngine's core actors" first.
AudioBuffer( int amountOfChannels, int aBufferSize )
Where amountOfChannels describes the amount of channels the AudioBuffer instance will hold. E.g. 1 for mono audio, 2 for stereo, etc., each of these channels will have their own buffer inside this instance. aBufferSize describes the total length in samples of each buffer. This length is equal for all the channel buffers. Upon construction, the AudioBuffer instance will have reserved memory for the required amount of buffers at the requested size. The buffers are lists of floating point values, either as 32-bit float or 64-bit double (see SAMPLE_TYPE in global.h-configuration).
~AudioBuffer()
Will delete the contents of this instances buffers. As such, make sure this AudioBuffer isn't currently being read from by the Sequencer / Processors / render loop, etc. !
SAMPLE_TYPE* getBufferForChannel( int aChannelNum )
Returns a pointer to the buffer (list of floating point sample values) for the given channel number aChannelNum. When working with mono, aChannelNum can only be 0, in stereo the allowed values are 0 (left channel) and 1 (right channel), and so on for multi channel AudioBuffer instances.
This buffer can be retrieved to perform specific operations on solely this channel (for instance when applying a Processor that performs multi channel actions, such as a ping pong delay, etc.)
int mergeBuffers( AudioBuffer* aBuffer, int aReadOffset, int aWriteOffset, float aMixVolume )
Merge (mix in) the contents of a given AudioBuffer aBuffer into the contents of the current AudioBuffer instance, note that both buffers must contain an equal amount of channels. aReadOffset describes the offset of the read pointer of the given aBuffer, while aWriteOffset describes the offset of the write pointer to write into the current AudioBuffer instance. If you wish to mix in the contents of the given aBuffer at the start of the current instance, use value 0 for read offset and 0 for write offset.
Example exercise regarding read / write offsets : let's assume the current AudioBuffer instance is 1024 samples in length, and the given aBuffer-instance is 512 samples in length. We would like to mix in the contents of the given aBuffer halfway through the current instance's buffer (1024 / 2 == 512 samples in). The write offset should then be 512. Additionally, we'd only like to mix in the latter half of the given aBuffer (512 / 2 == 256 samples in). The read offset should then be 256.
The result is that (aBuffer length 512 - read offset 256 == 256 samples) of given _aBuffer_s channels are mixed in at offset 512 of the current AudioBuffer instances channels.
Note that if given aBuffer is of a different length than the current instance, no errors are thrown, but mixing merely stops when either given aBuffer has reached its end during reading, or when the current instance has reached its end during writing. If the current instance is loopeable (e.g. the AudioBuffer should play from the beginning when it has reached its end during playback), given aBuffer will continually be appended until the length of the current instance has been written.
Furthermore, if you wish to mix in the audio at a lower volume level, you can supply a floating point value in the 0 to 1 range for aMixVolume. If mix volume is 1, given aBuffer will be mixed in at its full volume, if lower than 1, it will be attenuated prior to mixing in.
This method returns an integer value of the amount of samples that have been written (per buffer).
silenceBuffers()
Erases the existing audible contents of the AudioBuffer instance. This does NOT delete the buffers, but merely replace all samples with silent (0.0-value) samples. As such, this operation can safely occur during reading by the Sequencer / Processors, etc.
adjustBufferVolumes( SAMPLE_TYPE amp )
Attenuate the volume of the existing buffers contents. amp is a floating point value in the 0 - 1 range.
applyMonoSource()
Convenience method to clone the contents of the left (0 index) buffer into the remaining buffers. Can be used after writing a mono source to spread its contents over the multi-channel instance.
AudioBuffer* clone()
Returns a new AudioBuffer instance with identical contents and properties to the current instance.
int amountOfChannels
Returns the amount of channels the AudioBuffer holds.
int bufferSize
Return the length in samples of each of the AudioBuffers channels.
bool loopeable
Whether the contents of this AudioBuffer can be looped (false upon construction). If true, when the Sequencer has reached the end when reading the AudioBuffer, it will continue to read from the beginning for the remaining amount of samples it has been allotted to read.