AEAudioBufferListUtilities.h File Reference
#import <Foundation/Foundation.h>
#import <AudioToolbox/AudioToolbox.h>
#import "AETypes.h"

Go to the source code of this file.

Macros

#define AEAudioBufferListCreateOnStack(name)   AEAudioBufferListCreateOnStackWithFormat(name, AEAudioDescription)
 Create an audio buffer list on the stack, using the default audio format.
 
#define AEAudioBufferListCreateOnStackWithFormat(name, audioFormat)
 Create an audio buffer list on the stack, with a custom audio format.
 
#define AEAudioBufferListCopyOnStack(name, sourceBufferList, offsetFrames)   AEAudioBufferListCopyOnStackWithByteOffset(name, sourceBufferList, offsetFrames * AEAudioDescription.mBytesPerFrame)
 Create a stack copy of the given audio buffer list and offset mData pointers.
 
#define AEAudioBufferListCopyOnStackWithByteOffset(name, sourceBufferList, offsetBytes)
 Create a stack copy of the given audio buffer list and offset mData pointers, with offset in bytes.
 
#define AEAudioBufferListCopyOnStackWithChannelSubset(name, sourceBufferList, channelSet)
 Create a stack copy of an audio buffer list that points to a subset of its channels.
 

Functions

AudioBufferList * AEAudioBufferListCreate (int frameCount)
 Allocate an audio buffer list and the associated mData pointers, using the default audio format.
 
AudioBufferList * AEAudioBufferListCreateWithFormat (AudioStreamBasicDescription audioFormat, int frameCount)
 Allocate an audio buffer list and the associated mData pointers, with a custom audio format.
 
AudioBufferList * AEAudioBufferListCopy (const AudioBufferList *original)
 Create a copy of an audio buffer list.
 
void AEAudioBufferListFree (AudioBufferList *bufferList)
 Free a buffer list and associated mData buffers.
 
UInt32 AEAudioBufferListGetLength (const AudioBufferList *bufferList, int *oNumberOfChannels)
 Get the number of frames in a buffer list, with the default audio format.
 
UInt32 AEAudioBufferListGetLengthWithFormat (const AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, int *oNumberOfChannels)
 Get the number of frames in a buffer list, with a custom audio format.
 
void AEAudioBufferListSetLength (AudioBufferList *bufferList, UInt32 frames)
 Set the number of frames in a buffer list, with the default audio format.
 
void AEAudioBufferListSetLengthWithFormat (AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 frames)
 Set the number of frames in a buffer list, with a custom audio format.
 
void AEAudioBufferListOffset (AudioBufferList *bufferList, UInt32 frames)
 Offset the pointers in a buffer list, with the default audio format.
 
void AEAudioBufferListOffsetWithFormat (AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 frames)
 Offset the pointers in a buffer list, with a custom audio format.
 
void AEAudioBufferListAssign (AudioBufferList *target, const AudioBufferList *source, UInt32 offset, UInt32 length)
 Assign values of one buffer list to another, with the default audio format.
 
void AEAudioBufferListAssignWithFormat (AudioBufferList *target, const AudioBufferList *source, AudioStreamBasicDescription audioFormat, UInt32 offset, UInt32 length)
 Assign values of one buffer list to another, with the default audio format.
 
void AEAudioBufferListSilence (const AudioBufferList *bufferList, UInt32 offset, UInt32 length)
 Silence an audio buffer list (zero out frames), with the default audio format.
 
void AEAudioBufferListSilenceWithFormat (const AudioBufferList *bufferList, AudioStreamBasicDescription audioFormat, UInt32 offset, UInt32 length)
 Silence an audio buffer list (zero out frames), with a custom audio format.
 
void AEAudioBufferListCopyContents (const AudioBufferList *target, const AudioBufferList *source, UInt32 targetOffset, UInt32 sourceOffset, UInt32 length)
 Copy the contents of one AudioBufferList to another, with the default audio format.
 
void AEAudioBufferListCopyContentsWithFormat (const AudioBufferList *target, const AudioBufferList *source, AudioStreamBasicDescription audioFormat, UInt32 targetOffset, UInt32 sourceOffset, UInt32 length)
 Copy the contents of one AudioBufferList to another, with a custom audio format.
 

Macro Definition Documentation

#define AEAudioBufferListCreateOnStack (   name)    AEAudioBufferListCreateOnStackWithFormat(name, AEAudioDescription)

Create an audio buffer list on the stack, using the default audio format.

This is useful for creating buffers for temporary use, without needing to perform any memory allocations. It will create a local AudioBufferList* variable on the stack, with a name given by the first argument, and initialise the buffer according to the given audio format.

The created buffer will have NULL mData pointers and 0 mDataByteSize: you will need to assign these to point to a memory buffer.

Parameters
nameName of the variable to create on the stack
#define AEAudioBufferListCreateOnStackWithFormat (   name,
  audioFormat 
)
Value:
int name ## _numberBuffers = audioFormat.mFormatFlags & kAudioFormatFlagIsNonInterleaved \
? audioFormat.mChannelsPerFrame : 1; \
char name ## _bytes[sizeof(AudioBufferList)+(sizeof(AudioBuffer)*(name ## _numberBuffers-1))]; \
memset(&name ## _bytes, 0, sizeof(name ## _bytes)); \
AudioBufferList * name = (AudioBufferList*)name ## _bytes; \
name->mNumberBuffers = name ## _numberBuffers; \
for ( int i=0; i<name->mNumberBuffers; i++ ) { \
name->mBuffers[i].mNumberChannels \
= audioFormat.mFormatFlags & kAudioFormatFlagIsNonInterleaved ? 1 : audioFormat.mChannelsPerFrame; \
}

Create an audio buffer list on the stack, with a custom audio format.

This is useful for creating buffers for temporary use, without needing to perform any memory allocations. It will create a local AudioBufferList* variable on the stack, with a name given by the first argument, and initialise the buffer according to the given audio format.

The created buffer will have NULL mData pointers and 0 mDataByteSize: you will need to assign these to point to a memory buffer.

Parameters
nameName of the variable to create on the stack
audioFormatThe audio format to use
#define AEAudioBufferListCopyOnStack (   name,
  sourceBufferList,
  offsetFrames 
)    AEAudioBufferListCopyOnStackWithByteOffset(name, sourceBufferList, offsetFrames * AEAudioDescription.mBytesPerFrame)

Create a stack copy of the given audio buffer list and offset mData pointers.

This is useful for creating buffers that point to an offset into the original buffer, to fill later regions of the buffer. It will create a local AudioBufferList* variable on the stack, with a name given by the first argument, copy the original AudioBufferList structure values, and offset the mData and mDataByteSize variables.

Note that only the AudioBufferList structure itself will be copied, not the data to which it points.

Parameters
nameName of the variable to create on the stack
sourceBufferListThe original buffer list to copy
offsetFramesNumber of frames of noninterleaved float to offset mData/mDataByteSize members
#define AEAudioBufferListCopyOnStackWithByteOffset (   name,
  sourceBufferList,
  offsetBytes 
)
Value:
char name ## _bytes[sizeof(AudioBufferList)+(sizeof(AudioBuffer)*(sourceBufferList->mNumberBuffers-1))]; \
memcpy(name ## _bytes, sourceBufferList, sizeof(name ## _bytes)); \
AudioBufferList * name = (AudioBufferList*)name ## _bytes; \
for ( int i=0; i<name->mNumberBuffers; i++ ) { \
name->mBuffers[i].mData = (char*)name->mBuffers[i].mData + offsetBytes; \
name->mBuffers[i].mDataByteSize -= offsetBytes; \
}

Create a stack copy of the given audio buffer list and offset mData pointers, with offset in bytes.

This is useful for creating buffers that point to an offset into the original buffer, to fill later regions of the buffer. It will create a local AudioBufferList* variable on the stack, with a name given by the first argument, copy the original AudioBufferList structure values, and offset the mData and mDataByteSize variables.

Note that only the AudioBufferList structure itself will be copied, not the data to which it points.

Parameters
nameName of the variable to create on the stack
sourceBufferListThe original buffer list to copy
offsetBytesNumber of bytes to offset mData/mDataByteSize members
#define AEAudioBufferListCopyOnStackWithChannelSubset (   name,
  sourceBufferList,
  channelSet 
)
Value:
int name ## _bufferCount = MIN(sourceBufferList->mNumberBuffers-1, channelSet.lastChannel) - \
MIN(sourceBufferList->mNumberBuffers-1, channelSet.firstChannel) + 1; \
char name ## _bytes[sizeof(AudioBufferList)+(sizeof(AudioBuffer)*(name ## _bufferCount-1))]; \
AudioBufferList * name = (AudioBufferList*)name ## _bytes; \
name->mNumberBuffers = name ## _bufferCount; \
memcpy(name->mBuffers, &sourceBufferList->mBuffers[MIN(sourceBufferList->mNumberBuffers-1, channelSet.firstChannel)], \
sizeof(AudioBuffer) * name ## _bufferCount);

Create a stack copy of an audio buffer list that points to a subset of its channels.

Parameters
nameName of the variable to create on the stack
sourceBufferListThe original buffer list to copy
channelSetThe subset of channels

Function Documentation

AudioBufferList* AEAudioBufferListCreate ( int  frameCount)

Allocate an audio buffer list and the associated mData pointers, using the default audio format.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

Parameters
frameCountThe number of frames to allocate space for (or 0 to just allocate the list structure itself)
Returns
The allocated and initialised audio buffer list
AudioBufferList* AEAudioBufferListCreateWithFormat ( AudioStreamBasicDescription  audioFormat,
int  frameCount 
)

Allocate an audio buffer list and the associated mData pointers, with a custom audio format.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

Parameters
audioFormatAudio format describing audio to be stored in buffer list
frameCountThe number of frames to allocate space for (or 0 to just allocate the list structure itself)
Returns
The allocated and initialised audio buffer list
AudioBufferList* AEAudioBufferListCopy ( const AudioBufferList *  original)

Create a copy of an audio buffer list.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

Parameters
originalThe original AudioBufferList to copy
Returns
The new, copied audio buffer list
void AEAudioBufferListFree ( AudioBufferList *  bufferList)

Free a buffer list and associated mData buffers.

Note: Do not use this utility from within the Core Audio thread (such as inside a render callback). It may cause the thread to block, inducing audio stutters.

UInt32 AEAudioBufferListGetLength ( const AudioBufferList *  bufferList,
int *  oNumberOfChannels 
)

Get the number of frames in a buffer list, with the default audio format.

Calculates the frame count in the buffer list based on the given audio format. Optionally also provides the channel count.

Parameters
bufferListPointer to an AudioBufferList containing audio
oNumberOfChannelsIf not NULL, will be set to the number of channels of audio in 'list'
Returns
Number of frames in the buffer list
UInt32 AEAudioBufferListGetLengthWithFormat ( const AudioBufferList *  bufferList,
AudioStreamBasicDescription  audioFormat,
int *  oNumberOfChannels 
)

Get the number of frames in a buffer list, with a custom audio format.

Calculates the frame count in the buffer list based on the given audio format. Optionally also provides the channel count.

Parameters
bufferListPointer to an AudioBufferList containing audio
audioFormatAudio format describing the audio in the buffer list
oNumberOfChannelsIf not NULL, will be set to the number of channels of audio in 'list'
Returns
Number of frames in the buffer list
void AEAudioBufferListSetLength ( AudioBufferList *  bufferList,
UInt32  frames 
)

Set the number of frames in a buffer list, with the default audio format.

Calculates the frame count in the buffer list based on the given audio format, and assigns it to the buffer list members.

Parameters
bufferListPointer to an AudioBufferList containing audio
framesThe number of frames to set
void AEAudioBufferListSetLengthWithFormat ( AudioBufferList *  bufferList,
AudioStreamBasicDescription  audioFormat,
UInt32  frames 
)

Set the number of frames in a buffer list, with a custom audio format.

Calculates the frame count in the buffer list based on the given audio format, and assigns it to the buffer list members.

Parameters
bufferListPointer to an AudioBufferList containing audio
audioFormatAudio format describing the audio in the buffer list
framesThe number of frames to set
void AEAudioBufferListOffset ( AudioBufferList *  bufferList,
UInt32  frames 
)

Offset the pointers in a buffer list, with the default audio format.

Increments the mData pointers in the buffer list by the given number of frames. This is useful for filling a buffer in incremental stages.

Parameters
bufferListPointer to an AudioBufferList containing audio
framesThe number of frames to offset the mData pointers by
void AEAudioBufferListOffsetWithFormat ( AudioBufferList *  bufferList,
AudioStreamBasicDescription  audioFormat,
UInt32  frames 
)

Offset the pointers in a buffer list, with a custom audio format.

Increments the mData pointers in the buffer list by the given number of frames. This is useful for filling a buffer in incremental stages.

Parameters
bufferListPointer to an AudioBufferList containing audio
audioFormatAudio format describing the audio in the buffer list
framesThe number of frames to offset the mData pointers by
void AEAudioBufferListAssign ( AudioBufferList *  target,
const AudioBufferList *  source,
UInt32  offset,
UInt32  length 
)

Assign values of one buffer list to another, with the default audio format.

Note that this simply assigns the buffer list values; if you wish to copy the contents, use AEAudioBufferListCopy or AEAudioBufferListCopyContents

Parameters
targetTarget buffer list, to assign values to
sourceSource buffer list, to assign values from
offsetOffset into target buffer
lengthLength to assign, in frames
void AEAudioBufferListAssignWithFormat ( AudioBufferList *  target,
const AudioBufferList *  source,
AudioStreamBasicDescription  audioFormat,
UInt32  offset,
UInt32  length 
)

Assign values of one buffer list to another, with the default audio format.

Note that this simply assigns the buffer list values; if you wish to copy the contents, use AEAudioBufferListCopy or AEAudioBufferListCopyContents

Parameters
targetTarget buffer list, to assign values to
sourceSource buffer list, to assign values from
audioFormatAudio format describing the audio in the buffer list
offsetOffset into target buffer
lengthLength to assign, in frames
void AEAudioBufferListSilence ( const AudioBufferList *  bufferList,
UInt32  offset,
UInt32  length 
)

Silence an audio buffer list (zero out frames), with the default audio format.

Parameters
bufferListPointer to an AudioBufferList containing audio
offsetOffset into buffer
lengthNumber of frames to silence
void AEAudioBufferListSilenceWithFormat ( const AudioBufferList *  bufferList,
AudioStreamBasicDescription  audioFormat,
UInt32  offset,
UInt32  length 
)

Silence an audio buffer list (zero out frames), with a custom audio format.

Parameters
bufferListPointer to an AudioBufferList containing audio
audioFormatAudio format describing the audio in the buffer list
offsetOffset into buffer
lengthNumber of frames to silence
void AEAudioBufferListCopyContents ( const AudioBufferList *  target,
const AudioBufferList *  source,
UInt32  targetOffset,
UInt32  sourceOffset,
UInt32  length 
)

Copy the contents of one AudioBufferList to another, with the default audio format.

Parameters
targetTarget buffer list, to copy to
sourceSource buffer list, to copy from
targetOffsetOffset into target buffer
sourceOffsetOffset into source buffer
lengthNumber of frames to copy
void AEAudioBufferListCopyContentsWithFormat ( const AudioBufferList *  target,
const AudioBufferList *  source,
AudioStreamBasicDescription  audioFormat,
UInt32  targetOffset,
UInt32  sourceOffset,
UInt32  length 
)

Copy the contents of one AudioBufferList to another, with a custom audio format.

Parameters
targetTarget buffer list, to copy to
sourceSource buffer list, to copy from
audioFormatAudio format describing the audio in the buffer list
targetOffsetOffset into target buffer
sourceOffsetOffset into source buffer
lengthNumber of frames to copy