AEBufferStack.h File Reference

#import <Foundation/Foundation.h>
#import <AudioToolbox/AudioToolbox.h>
#import "AETypes.h"

Go to the source code of this file.

Typedefs
typedef struct AEBufferStack	AEBufferStack

Functions
AEBufferStack *	AEBufferStackNew (int poolSize)
	Initialize a new buffer stack.
AEBufferStack *	AEBufferStackNewWithOptions (int poolSize, int maxChannelsPerBuffer, int numberOfSingleChannelBuffers)
	Initialize a new buffer stack, supplying additional options.
void	AEBufferStackFree (AEBufferStack *stack)
	Clean up a buffer stack.
void	AEBufferStackSetFrameCount (AEBufferStack *stack, UInt32 frameCount)
	Set current frame count per buffer.
UInt32	AEBufferStackGetFrameCount (const AEBufferStack *stack)
	Get the current frame count per buffer.
void	AEBufferStackSetTimeStamp (AEBufferStack *stack, const AudioTimeStamp *timestamp)
	Set timestamp for the current interval.
const AudioTimeStamp *	AEBufferStackGetTimeStamp (const AEBufferStack *stack)
	Get the timestamp for the current interval.
int	AEBufferStackGetPoolSize (const AEBufferStack *stack)
	Get the pool size.
int	AEBufferStackGetMaximumChannelsPerBuffer (const AEBufferStack *stack)
	Get the maximum number of channels per buffer.
int	AEBufferStackCount (const AEBufferStack *stack)
	Get the current stack count.
const AudioBufferList *	AEBufferStackGet (const AEBufferStack *stack, int index)
	Get a buffer.
const AudioBufferList *	AEBufferStackPush (AEBufferStack *stack, int count)
	Push one or more new buffers onto the stack.
const AudioBufferList *	AEBufferStackPushWithChannels (AEBufferStack *stack, int count, int channelCount)
	Push one or more new buffers onto the stack.
const AudioBufferList *	AEBufferStackPushExternal (AEBufferStack *stack, const AudioBufferList *buffer)
	Push an external audio buffer.
const AudioBufferList *	AEBufferStackDuplicate (AEBufferStack *stack)
	Duplicate the top buffer on the stack.
void	AEBufferStackSwap (AEBufferStack *stack)
	Swap the top two stack items.
void	AEBufferStackPop (AEBufferStack *stack, int count)
	Pop one or more buffers from the stack.
void	AEBufferStackRemove (AEBufferStack *stack, int index)
	Remove a buffer from the stack.
const AudioBufferList *	AEBufferStackMix (AEBufferStack *stack, int count)
	Mix two or more buffers together.
const AudioBufferList *	AEBufferStackMixWithGain (AEBufferStack *stack, int count, const float *gains)
	Mix two or more buffers together, with individual mix factors by which to scale each buffer.
void	AEBufferStackApplyFaders (AEBufferStack *stack, float targetVolume, float *currentVolume, float targetBalance, float *currentBalance)
	Apply volume and balance controls to the top buffer.
void	AEBufferStackSilence (AEBufferStack *stack)
	Silence the top buffer.
void	AEBufferStackMixToBufferList (AEBufferStack *stack, int bufferCount, const AudioBufferList *output)
	Mix stack items onto an AudioBufferList.
void	AEBufferStackMixToBufferListChannels (AEBufferStack *stack, int bufferCount, AEChannelSet channels, const AudioBufferList *output)
	Mix stack items onto an AudioBufferList, with specific channel configuration.
AudioTimeStamp *	AEBufferStackGetTimeStampForBuffer (AEBufferStack *stack, int index)
	Get the timestamp for the given buffer index.
void	AEBufferStackReset (AEBufferStack *stack)
	Reset the stack.

Variables
const UInt32	AEBufferStackMaxFramesPerSlice

Typedef Documentation

typedef struct AEBufferStack AEBufferStack

Function Documentation

AEBufferStack* AEBufferStackNew

(

int

poolSize

)

Initialize a new buffer stack.

Parameters

poolSize

The number of audio buffer lists to make room for in the buffer pool, or 0 for default value

Returns

The new buffer stack

AEBufferStack* AEBufferStackNewWithOptions	(	int	poolSize,
		int	maxChannelsPerBuffer,
		int	numberOfSingleChannelBuffers
	)

Initialize a new buffer stack, supplying additional options.

Parameters

poolSize	The number of audio buffer lists to make room for in the buffer pool, or 0 for default value
maxChannelsPerBuffer	The maximum number of audio channels for each buffer (default 2)
numberOfSingleChannelBuffers	Number of mono float buffers to allocate (or 0 for default: poolSize*maxChannelsPerBuffer)

Returns

The new buffer stack

void AEBufferStackFree

(

AEBufferStack *

stack

)

Clean up a buffer stack.

Parameters

stack

The stack

void AEBufferStackSetFrameCount	(	AEBufferStack *	stack,
		UInt32	frameCount
	)

Set current frame count per buffer.

Parameters

stack	The stack
frameCount	The number of frames for newly-pushed buffers

UInt32 AEBufferStackGetFrameCount

(

const AEBufferStack *

stack

)

Get the current frame count per buffer.

Parameters

stack

The stack

Returns

The current frame count for newly-pushed buffers

void AEBufferStackSetTimeStamp	(	AEBufferStack *	stack,
		const AudioTimeStamp *	timestamp
	)

Set timestamp for the current interval.

Parameters

stack	The stack
timestamp	The current timestamp

const AudioTimeStamp* AEBufferStackGetTimeStamp

(

const AEBufferStack *

stack

)

Get the timestamp for the current interval.

Parameters

stack

The stack

Returns

The current timestamp

int AEBufferStackGetPoolSize

(

const AEBufferStack *

stack

)

Get the pool size.

Parameters

stack

The stack

Returns

The current pool size

int AEBufferStackGetMaximumChannelsPerBuffer

(

const AEBufferStack *

stack

)

Get the maximum number of channels per buffer.

Parameters

stack

The stack

Returns

The maximum number of channels per buffer

int AEBufferStackCount

(

const AEBufferStack *

stack

)

Get the current stack count.

Parameters

stack

The stack

Returns

Number of buffers currently on stack

const AudioBufferList* AEBufferStackGet	(	const AEBufferStack *	stack,
		int	index
	)

Get a buffer.

Parameters

stack	The stack
index	The buffer index

Returns

The buffer at the given index (0 is the top of the stack: the most recently pushed buffer)

const AudioBufferList* AEBufferStackPush	(	AEBufferStack *	stack,
		int	count
	)

Push one or more new buffers onto the stack.

Note that a buffer that has been pushed immediately after a pop points to the same data - essentially, this is a no-op. If a buffer is pushed immediately after a pop with more channels, then the first channels up to the prior channel count point to the same data, and later channels point to new buffers.

Parameters

stack	The stack
count	Number of buffers to push

Returns

The first new buffer

const AudioBufferList* AEBufferStackPushWithChannels	(	AEBufferStack *	stack,
		int	count,
		int	channelCount
	)

Push one or more new buffers onto the stack.

Note that a buffer that has been pushed immediately after a pop points to the same data - essentially, this is a no-op. If a buffer is pushed immediately after a pop with more channels, then the first channels up to the prior channel count point to the same data, and later channels point to new buffers.

Parameters

stack	The stack
count	Number of buffers to push
channelCount	Number of channels of audio for each buffer

Returns

The first new buffer

const AudioBufferList* AEBufferStackPushExternal	(	AEBufferStack *	stack,
		const AudioBufferList *	buffer
	)

Push an external audio buffer.

This function allows you to push a buffer that was allocated elsewhere. Note while the mData pointers within the pushed buffer will remain the same, and thus will point to the same audio data memory, the AudioBufferList structure itself will be copied; later changes to the original structure will not be reflected in the copy on the stack.

It is the responsibility of the caller to ensure that it does not modify the audio data until the end of the current render cycle. Note that successive audio modules may modify the contents.

Parameters

stack	The stack
buffer	The buffer list to copy onto the stack

Returns

The new buffer

const AudioBufferList* AEBufferStackDuplicate

(

AEBufferStack *

stack

)

Duplicate the top buffer on the stack.

Pushes a new buffer onto the stack which is a copy of the prior buffer.

Parameters

stack

The stack

Returns

The duplicated buffer

void AEBufferStackSwap

(

AEBufferStack *

stack

)

Swap the top two stack items.

Parameters

stack

The stack

void AEBufferStackPop	(	AEBufferStack *	stack,
		int	count
	)

Pop one or more buffers from the stack.

The popped buffer remains valid until another buffer is pushed. A newly pushed buffer will use the same memory regions as the old one, and thus a pop followed by a push is essentially a no-op, given the same number of channels in each.

Parameters

stack	The stack
count	Number of buffers to pop, or 0 for all

void AEBufferStackRemove	(	AEBufferStack *	stack,
		int	index
	)

Remove a buffer from the stack.

Remove an indexed buffer from within the stack. This has the same behaviour as AEBufferStackPop, in that a removal followed by a push results in a buffer pointing to the same memory.

Parameters

stack	The stack
index	The buffer index

const AudioBufferList* AEBufferStackMix	(	AEBufferStack *	stack,
		int	count
	)

Mix two or more buffers together.

Pops the given number of buffers from the stack, and pushes a buffer with these mixed together.

When mixing a mono buffer and a stereo buffer, the mono buffer's channels will be duplicated.

Parameters

stack	The stack
count	Number of buffers to mix

Returns

The resulting buffer

const AudioBufferList* AEBufferStackMixWithGain	(	AEBufferStack *	stack,
		int	count,
		const float *	gains
	)

Mix two or more buffers together, with individual mix factors by which to scale each buffer.

Parameters

stack	The stack
count	Number of buffers to mix
gains	The gain factors (power ratio) for each buffer. You must provide 'count' values

Returns

The resulting buffer

void AEBufferStackApplyFaders	(	AEBufferStack *	stack,
		float	targetVolume,
		float *	currentVolume,
		float	targetBalance,
		float *	currentBalance
	)

Apply volume and balance controls to the top buffer.

This function applies gains to the given buffer to affect volume and balance, with a smoothing ramp applied to avoid discontinuities. If the buffer is mono, and the balance is non-zero, the buffer will be made stereo instead.

Parameters

stack	The stack
targetVolume	The target volume (power ratio)
currentVolume	On input, the current volume; on output, the new volume. Store this and pass it back to this function on successive calls for a smooth ramp. If NULL, no smoothing will be applied.
targetBalance	The target balance
currentBalance	On input, the current balance; on output, the new balance. Store this and pass it back to this function on successive calls for a smooth ramp. If NULL, no smoothing will be applied.

void AEBufferStackSilence

(

AEBufferStack *

stack

)

Silence the top buffer.

This function zereos out all samples in the topmost buffer.

Parameters

stack

The stack

void AEBufferStackMixToBufferList	(	AEBufferStack *	stack,
		int	bufferCount,
		const AudioBufferList *	output
	)

Mix stack items onto an AudioBufferList.

The given number of stack items will mixed into the buffer list.

Parameters

stack	The stack
bufferCount	Number of buffers to process, or 0 for all
output	The output buffer list

void AEBufferStackMixToBufferListChannels	(	AEBufferStack *	stack,
		int	bufferCount,
		AEChannelSet	channels,
		const AudioBufferList *	output
	)

Mix stack items onto an AudioBufferList, with specific channel configuration.

The given number of stack items will mixed into the buffer list.

Parameters

stack	The stack
bufferCount	Number of buffers to process, or 0 for all
channels	The set of channels to output to. If stereo, any mono inputs will be doubled to stereo. If mono, any stereo inputs will be mixed down.
output	The output buffer list

AudioTimeStamp* AEBufferStackGetTimeStampForBuffer	(	AEBufferStack *	stack,
		int	index
	)

Get the timestamp for the given buffer index.

Modules can use this method to access and manipulate the timestamp that corresponds to a piece of audio. For example, AEAudioUnitInputModule replaces the timestamp with one that corresponds to the input audio.

Parameters

stack	The stack
index	The buffer index

Returns

The timestamp that corresponds to the buffer at the given index

void AEBufferStackReset

(

AEBufferStack *

stack

)

Reset the stack.

This pops all items until the stack is empty

Parameters

stack

The stack

Variable Documentation

const UInt32 AEBufferStackMaxFramesPerSlice