Framework | /System/Library/Frameworks/AudioToolbox.framework |
Declared in | AUGraph.h |
Audio Unit Processing Graph Services provide interfaces for representing a set of audio units, connections between their inputs and outputs, and callbacks used to provide inputs. It also enables the embedding of sub (or child) processing graphs within parent graphs to allow for a logical organization of parts of an overall signal chain.
An audio processing graph object (of type AUGraph
) is a complete description of an audio signal processing network. Audio Unit Processing Graph Services may manage the instantiated audio units if the AUGraphOpen
function is called.
An audio processing graph object may be introspected to get complete information about all of the audio units in the graph. The various node objects (each of type AUNode
) in the graph, each representing an audio unit or a sub graph, may be added or removed, and the interactions between them modified.
A graph object’s state can be manipulated in both the rendering thread and in other threads. Consequently, any activities that affect the state of the graph are guarded with locks and a messaging model between any calling thread and the thread upon which the graph object’s output unit is called (the render thread).
A graph object will have a single head node––an output unit. The output unit is used to both start and stop the rendering operations of a graph, and is the dispatch point for the safe manipulation of the state of the graph while it is running.
Adds a node to an audio processing graph.
OSStatus AUGraphAddNode ( AUGraph inGraph, const AudioComponentDescription *inDescription, AUNode *outNode );
The AUGraph
object that you are adding a node to.
The AudioComponentDescription
object used to find and open the audio unit that you are adding as a new node.
The newly added node.
A result code.
Creates a node in an audio processing graph, using the supplied AudioComponentDescription
object to find and open the audio unit for the node.
AUGraph.h
Adds a render notification callback to an audio processing graph.
OSStatus AUGraphAddRenderNotify ( AUGraph inGraph, AURenderCallback inCallback, void *inRefCon );
Adds a callback that the graph will call every time the graph renders. The callback will be called once before the graph’s render operation, and once after the render operation is complete.
AUGraph.h
Clears all of the interactions in an audio unit processing graph.
OSStatus AUGraphClearConnections ( AUGraph inGraph );
This will clear all connections and callback interactions of the nodes of a graph.
AUGraph.h
Closes an audio unit processing graph.
OSStatus AUGraphClose ( AUGraph inGraph );
All AudioUnits are closed - leaving only its nodal representation.
AUGraph.h
Connects one node’s output to another node’s input.
OSStatus AUGraphConnectNodeInput ( AUGraph inGraph, AUNode inSourceNode, UInt32 inSourceOutputNumber, AUNode inDestNode, UInt32 inDestInputNumber );
A result code.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphCountNodeInteractions
.
OSStatus AUGraphCountNodeConnections( AUGraph inGraph, AUNode inNode, UInt32 *outNumConnections );
A result code.
AUGraph.h
Retrieves the number of interactions of an audio processing graph’s node.
OSStatus AUGraphCountNodeInteractions ( AUGraph inGraph, AUNode inNode, UInt32 *outNumInteractions );
A result code.
The number of node interactions currently being managed by the graph for the specified node.
AUGraph.h
Disconnects a node’s input.
OSStatus AUGraphDisconnectNodeInput ( AUGraph inGraph, AUNode inDestNode, UInt32 inDestInputNumber );
A result code.
Use this function to disconnect a connection or a callback interaction.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphGetInteractionInfo
.
OSStatus AUGraphGetConnectionInfo( AUGraph inGraph, UInt32 inConnectionIndex, AUNode *outSourceNode, UInt32 *outSourceOutputNumber, AUNode *outDestNode, UInt32 *outDestInputNumber );
A result code.
AUGraph.h
Obtains the short-term running average of the current CPU load of the audio processing graph.
OSStatus AUGraphGetCPULoad ( AUGraph inGraph, Float32 *outAverageCPULoad );
AUGraph.h
Gets the audio processing graph node at a given index.
OSStatus AUGraphGetIndNode ( AUGraph inGraph, UInt32 inIndex, AUNode *outNode );
The AUGraph
object to get the node from.
The index of the node to get.
On output, the node at the specified index.
A result code.
By using AUGraphGetNodeCount in conjunction with this call, you can iterate through the nodes of an audio processing graph.
AUGraph.h
Retrieves information about a particular interaction in an audio processing graph.
OSStatus AUGraphGetInteractionInfo ( AUGraph inGraph, UInt32 inInteractionIndex, AUNodeInteraction *outInteraction );
The interaction information at the specified index.
A result code.
An application can iterate through the interactions (as with the nodes) of a graph by retrieving the number of interactions, and then iterating an index starting from 0. The inInteractionIndex parameter is based on the outNumInteractions value and is only valid if no edits to the graph’s state have been made.
AUGraph.h
Obtains the maximum CPU load of an audio processing graph since this call was last made or since the graph was last started.
OSStatus AUGraphGetMaxCPULoad ( AUGraph inGraph, Float32 *outMaxLoad );
A result code.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphGetNodeInteractions
.
OSStatus AUGraphGetNodeConnections( AUGraph inGraph, AUNode inNode, AudioUnitNodeConnection *outConnections, UInt32 *ioNumConnections );
A result code.
AUGraph.h
The number of nodes in an audio processing graph.
OSStatus AUGraphGetNodeCount ( AUGraph inGraph, UInt32 *outNumberOfNodes );
the AUGraph object
the number of nodes
A result code.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphNodeInfo
.
OSStatus AUGraphGetNodeInfo( AUGraph inGraph, AUNode inNode, struct ComponentDescription *outDescription, UInt32 *outClassDataSize, void **outClassData, AudioUnit *outAudioUnit );
A result code.
ClassInfo data should not be used with new nodes.
AUGraph.h
Gets the audio processing subgraph object represented by a node.
OSStatus AUGraphGetNodeInfoSubGraph( const AUGraph inGraph, AUNode inNode, AUGraph *outSubGraph);
The AUGraph
object to get the subgraph from.
The node that represents the subgraph.
The subgraph.
A result code.
AUGraph.h
Retrieves information about the interactions in an audio processing graph for a given node.
OSStatus AUGraphGetNodeInteractions ( AUGraph inGraph, AUNode inNode, UInt32 *ioNumInteractions, AUNodeInteraction *outInteractions );
On input, specifies the number of interactions that can be returned. On output, the number of interactions returned.
The interactions that the specified node is involved in.
A result code.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphGetNumberOfInteractions
.
OSStatus AUGraphGetNumberOfConnections( AUGraph inGraph, UInt32 *outNumConnections );
A result code.
AUGraph.h
Retrieves the number of interactions for an audio processing graph.
OSStatus AUGraphGetNumberOfInteractions ( AUGraph inGraph, UInt32 *outNumInteractions );
A result code.
The number of node interactions currently being managed by the graph.
AUGraph.h
Initializes an audio processing graph.
OSStatus AUGraphInitialize ( AUGraph inGraph );
A result code.
Calling this function calls the AudioUnitInitialize
function on each opened node or audio unit that is involved in a interaction. If a node is not involved, it is initialized after it becomes involved in an interaction.
A graph must be opened before it can be initialized.
AUGraph.h
Determines whether an audio processing graph is initialized.
OSStatus AUGraphIsInitialized ( AUGraph inGraph, Boolean *outIsInitialized );
A result code.
AUGraph.h
Determines whether a node object represent an audio processing graph or an audio unit.
OSStatus AUGraphIsNodeSubGraph( const AUGraph inGraph, AUNode inNode, Boolean *outFlag);
The AUGraph
object containing the node you want to query.
The node to query.
On output, true if the node is a subgraph, false if not.
A result code.
AUGraph.h
Determines whether an audio processing graph is open.
OSStatus AUGraphIsOpen ( AUGraph inGraph, Boolean *outIsOpen );
A result code.
AUGraph.h
Determines whether an audio processing graph running.
OSStatus AUGraphIsRunning ( AUGraph inGraph, Boolean *outIsRunning );
A result code.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphAddNode
.
OSStatus AUGraphNewNode( AUGraph inGraph, const AudioComponentDescription *inDescription, UInt32 inClassDataSize,// reserved: must be zero const void *inClassData, AUNode *outNode );
A result code.
ClassInfo data should not be used with new nodes.
AUGraph.h
Creates a node object to represent a subgraph.
OSStatus AUGraphNewNodeSubGraph( AUGraph inGraph, AUNode *outNode);
The AUGraph object that you want to add a subgraph to.
The node that represents the subgraph.
A result code.
This function creates a node that represents a subgraph. The subgraph can be retrieved with the AUGraphGetNodeInfoSubGraph
function. The subgraph is owned by the parent graph and will be disposed when the parent graph is disposed or when the node is removed from the parent graph.
AUGraph.h
Returns information about a node object.
OSStatus AUGraphNodeInfo ( AUGraph inGraph, AUNode inNode, AudioComponentDescription *outDescription, AudioUnit *outAudioUnit );
The AUGraph object.
The node to query.
The component description that would describe the AudioUnit of this node.
the AudioUnit of this node
A result code.
You can pass NULL
for any output parameter whose value you don’t care about.
AUGraph.h
Opens an audio processing graph.
OSStatus AUGraphOpen ( AUGraph inGraph );
A result code.
Upon return from this function call, the audio units belonging to the graph are open but not initialized. Specifically, no resource allocation occurs.
AUGraph.h
Removes a node from an audio processing graph.
OSStatus AUGraphRemoveNode ( AUGraph inGraph, AUNode inNode );
The AUGraph
object that you are removing a node from.
The node you want to remove.
A result code.
Nodes can be removed in any thread context. The output node of the graph cannot be removed while the graph is running.
AUGraph.h
Deprecated in Mac OS X v10.5. Instead, use AUGraphRemoveRenderNotify
.
OSStatus AUGraphRemoveRenderNotification( AUGraph inGraph, AudioUnitRenderCallback inCallback, void *inRefCon );
A result code.
AUGraph.h
Removes a notification callback from an audio processing graph.
OSStatus AUGraphRemoveRenderNotify ( AUGraph inGraph, AURenderCallback inCallback, void *inRefCon );
A result code.
Removes a previously added render notification callback. You must provide both the callback and the context (in the inRefCon parameter) that was used previously to add the callback.
AUGraph.h
Sets an input callback function for a node.
OSStatus AUGraphSetNodeInputCallback ( AUGraph inGraph, AUNode inDestNode, UInt32 inDestInputNumber, const AURenderCallbackStruct *inInputCallback );
The callback that will provide input data to the node.
A result code.
AUGraph.h
Deprecated in Mac OS X v10.3. Instead, use AUGraphAddRenderNotify
.
OSStatus AUGraphSetRenderNotification( AUGraph inGraph, AudioUnitRenderCallback inCallback, void *inRefCon );
A result code.
AUGraph.h
Starts an audio processing graph.
OSStatus AUGraphStart ( AUGraph inGraph );
A result code.
This function starts rendering by starting the head node of an audio processing graph. The graph must be initialized before it can be started.
AUGraph.h
Stops an audio processing graph.
OSStatus AUGraphStop ( AUGraph inGraph );
A result code.
This function stops rendering by stopping the head node of an audio processing graph.
AUGraph.h
Uninitializes an audio processing graph.
OSStatus AUGraphUninitialize ( AUGraph inGraph );
A result code.
This function uninitializes the audio units that compose the audio processing graph.
AUGraph.h
Updates the state of a running audio processing graph.
OSStatus AUGraphUpdate ( AUGraph inGraph, Boolean *outIsUpdated );
In input, pass NULL
for synchronous (blocking) behavior, or non-NULL
to have this function return immediately. On output, true
if all of the edits were applied to the audio processing graph at the time of function return.
A result code.
Call this function to finalize changes to an audio processing graph’s state after making calls such as AUGraphConnectNodeInput
.
Node connections and disconnections can be completely processed in the render notification callback of a graph, finalized by calling this function from within the callback. You can also remove nodes (apart from the head node) from within the render notification callback.
If this function returns the kAUGraphErr_CannotDoInCurrentContext
result code, another thread was calling a function dependent on the graph’s existing state. When the competing thread completes its call, call this function again.
Audio processing graph updates are all or none. If this function encounters any errors while attempting to finalize graph events, then no pending changes are finalized.
AUGraph.h
Disposes of an audio processing graph.
OSStatus DisposeAUGraph ( AUGraph inGraph );
the AUGraph object to be disposed
A result code.
Creates an AUGraph.
AUGraph.h
Creates a new audio processing graph.
OSStatus NewAUGraph ( AUGraph *outGraph );
The new AUGraph object
A result code.
AUGraph.h
A connection between two node objects in an audio processing graph.
struct AudioUnitNodeConnection { AUNode sourceNode; UInt32 sourceOutputNumber; AUNode destNode; UInt32 destInputNumber; }; typedef struct AudioUnitNodeConnection AudioUnitNodeConnection; typedef struct AudioUnitNodeConnection AUNodeConnection;
sourceNode
sourceOutputNumber
destNode
destInputNumber
AUGraph.h
An opaque type representing an audio processing graph.
typedef struct OpaqueAUGraph *AUGraph;
AUGraph.h
A member of an audio processing graph, associated with an audio unit.
typedef SInt32 AUNode;
AUGraph.h
Describes the interaction between two node objects.
struct AUNodeInteraction { UInt32 nodeInteractionType; union { AUNodeConnection connection; AUNodeRenderCallback inputCallback; } nodeInteraction; }; typedef struct AUNodeInteraction AUNodeInteraction;
nodeInteractionType
The interaction type.
nodeInteraction
A union providing information about a node interaction.
This structure contains information about the interaction between two nodes (in the case of a connection), or the input to a node (in the case of a callback).
The type of the interaction is used to determine how to interpret the contents of the following union.
There may be other nodal interactions in the future, so NO ASSUMPTIONS should be made that these are the only two nodal interaction types; you must always check the nodeInteractionType and only act on those types you understand.
Arrays of these structs can be returned, the addition of new members to the nodeInteraction union will NOT change the size of this structure.
AUGraph.h
A callback used to provide input to an audio unit.
struct AUNodeRenderCallback { AUNode destNode; AudioUnitElement destInputNumber; AURenderCallbackStruct cback; }; typedef struct AUNodeRenderCallback AUNodeRenderCallback;
destNode
destInputNumber
cback
Used to contain information when a callback is used to provide input to the specific node's specified input.
AUGraph.h
The different types of node interactions.
enum { kAUNodeInteraction_Connection = 1, kAUNodeInteraction_InputCallback = 2 };
kAUNodeInteraction_Connection
connections between 2 audio units,
Available in Mac OS X v10.5 and later.
Declared in AUGraph.h
.
kAUNodeInteraction_InputCallback
input callbacks being registered to a single audio unit’s input bus.
Available in Mac OS X v10.5 and later.
Declared in AUGraph.h
.
The term interaction is used as a general term to describe some interaction of a node. Currently, the interactions of a node that the graph manages are described below.
This table lists the result codes defined for Audio Unit Processing Graph Services.
Last updated: 2009-06-05