Namespaces
namespace	detail

namespace	node_player_utils

namespace	test_utilities

Classes
class	AudioBufferPool
	A lock-free pool of audio buffers. More...

class	AudioBufferStack
	A stack of audio buffers. More...

class	AudioFifo

class	BasicSummingNode

struct	ChannelConnection

class	ConnectedNode
	An Node which sums together the multiple inputs adding additional latency to provide a coherent output. More...

class	ForwardingNode
	Takes a non-owning input node and simply forwards its outputs on. More...

class	FunctionNode

class	GainNode

class	LatencyNode

struct	LatencyProcessor

class	LightweightSemaphore
	A counting semaphore that spins on a atomic before waiting so will avoid system calls if wait periods are very short. More...

class	LockFreeMultiThreadedNodePlayer
	Plays back a node with mutiple threads. More...

class	LockFreeObject
	Manages access to an object in a way that means it is lock-free to access from a real-time thread. More...

class	MidiNode
	Plays back a MIDI sequence. More...

class	MultiThreadedNodePlayer
	Plays back a node with mutiple threads. More...

class	Node
	Main graph Node processor class. More...

struct	NodeAndID
	A Node and its ID cached for quick lookup (without having to traverse the graph). More...

struct	NodeBuffer
	Holds a view over some data and optionally some storage for that data. More...

struct	NodeGraph
	Holds a graph in an order ready for processing and a sorted map for quick lookups. More...

struct	NodeOptimisations
	Holds some hints that might be used by the Node or players to improve efficiency. More...

class	NodePlayer
	Simple player for an Node. More...

struct	NodeProperties
	Holds some really basic properties of a node. More...

class	PerformanceMeasurement
	A timer for measuring performance of code. More...

struct	PlaybackInitialisationInfo
	Passed into Nodes when they are being initialised, to give them useful contextual information that they may need. More...

class	PlayHead
	Converts a monotonically increasing reference range in to a timeline range. More...

class	PlayHeadState
	Determines how this block releates to other previous render blocks and if the play head has jumped in time. More...

class	RealTimeSpinLock
	A basic spin lock that uses an atomic_flag to store the locked state so should never result in a system call. More...

class	ReturnNode

class	ScopedPerformanceMeasurement
	RAII wrapper to start and stop a performance measurement. More...

struct	ScopedSignpost
	A macOS specific class to start/stop a signpost for use in Instruments. More...

class	Semaphore
	A basic counting semaphore. More...

class	SendNode

class	SilentNode
	Just a simple audio node that doesn't take any input so can be used as a stub. More...

class	SimpleNodePlayer
	Simple player for a Node. More...

class	SinkNode
	Blocks audio and MIDI input from reaching the outputs. More...

class	SinNode

struct	SplitTimelineRange
	Represents a pair of timeline ranges which could be wraped around the loop end. More...

class	SummingNode
	An Node which sums together the multiple inputs adding additional latency to provide a coherent output. More...

class	TransformCache

Enumerations
enum class	TransformResult { none , connectionsMade , nodesDeleted }
	Enum to signify the result of the transform function. More...

enum class	ClearBuffers : std::uint8_t { no , yes }

enum class	AllocateAudioBuffer : std::uint8_t { no , yes }

enum class	ShareOutputBuffer : std::uint8_t { no , yes }

enum class	VertexOrdering { preordering , postordering , reversePreordering , reversePostordering , bfsPreordering , bfsReversePreordering }
	Specifies the ordering algorithm. More...

enum class	ThreadPoolStrategy { conditionVariable , realTime , hybrid , semaphore , lightweightSemaphore , lightweightSemHybrid }
	Available strategies for thread pools. More...

Functions
template<typename NodeType , typename... Args>
std::unique_ptr< Node >	makeNode (Args &&... args)
	Creates a node of the given type and returns it as the base Node class.

bool	operator< (NodeAndID n1, NodeAndID n2)
	Compares two NodeAndIDs.

bool	operator== (NodeAndID n1, NodeAndID n2)
	Compares two NodeAndIDs.

std::unique_ptr< NodeGraph >	createNodeGraph (std::unique_ptr< Node >, bool disableLatencyCompensation)
	Transforms a Node and then returns a NodeGraph of it ready to be initialised.

template<typename Visitor >
void	visitNodes (Node &, Visitor &&, bool preordering)
	Should call the visitor for any direct inputs to the node exactly once.

template<typename Visitor >
void	visitNodesBFS (Node &node, Visitor &&visitor)

void	addNodesRecursive (std::vector< NodeAndID > &nodeMap, Node &n)

std::vector< NodeAndID >	createNodeMap (const std::vector< Node * > &nodes)

LockFreeMultiThreadedNodePlayer::ThreadPoolCreator	getPoolCreatorFunction (ThreadPoolStrategy)
	Returns a function to create a ThreadPool for the given stategy.

template<typename IntType >
constexpr double	sampleToTime (IntType samplePosition, double sampleRate)
	Converts an integer sample number to a time in seconds.

constexpr int64_t	timeToSample (std::floating_point auto timeInSeconds, double sampleRate)
	Converts a time in seconds to a sample number.

template<typename IntType >
constexpr juce::Range< double >	sampleToTime (juce::Range< IntType > sampleRange, double sampleRate)
	Converts an integer sample range to a time range in seconds.

constexpr juce::Range< int64_t >	timeToSample (juce::Range< double > timeInSeconds, double sampleRate)
	Converts a time range in seconds to a range of sample numbers.

template<typename RangeType >
constexpr juce::Range< int64_t >	timeToSample (RangeType timeInSeconds, double sampleRate)
	Converts a time range in seconds to a range of sample numbers.

template<typename NodeType , typename Predicate >
NodeType *	findNode (NodeGraph &nodeGraph, Predicate pred)
	Attempts to find a Node of a given type with a specified ID.

template<typename NodeType >
NodeType *	findNodeWithID (NodeGraph &nodeGraph, size_t nodeIDToLookFor)
	Attempts to find a Node of a given type with a specified ID.

template<typename NodeType >
NodeType *	findNodeWithIDIfNonZero (NodeGraph *nodeGraph, size_t nodeIDToLookFor)
	Attempts to find a Node of a given type with a specified ID.

juce::AudioBuffer< float >	toAudioBuffer (choc::buffer::ChannelArrayView< float > view)
	Creates a juce::AudioBuffer from a choc::buffer::BufferView.

template<typename SampleType >
choc::buffer::BufferView< SampleType, choc::buffer::SeparateChannelLayout >	toBufferView (juce::AudioBuffer< SampleType > &buffer)
	Converts a juce::AudioBuffer<SampleType> to a choc::buffer::BufferView.

choc::buffer::FrameRange	createFrameRange (std::integral auto start, std::integral auto end)
	Creates a FrameRange from any integral type.

juce::MidiMessage	toMidiMessage (const choc::midi::Sequence::Event &e)
	Converts a choc::midi event to a juce::MidiMessage.

template<typename BufferViewType , typename SampleType , typename SmoothingType >
void	multiplyBy (BufferViewType &view, juce::SmoothedValue< SampleType, SmoothingType > &value) noexcept
	Mutiplies a choc::buffer::BufferView by a juce::SmoothedValue.

template<typename BufferType , typename GainType >
void	applyGainRamp (BufferType &&buffer, GainType startGain, GainType endGain) noexcept
	Applies a gain ram to a choc::buffer::BufferView.

choc::buffer::FrameRange	frameRangeWithStartAndLength (choc::buffer::FrameCount start, choc::buffer::FrameCount length)
	Returns a FrameRange with a start and length.

choc::buffer::ChannelRange	channelRangeWithStartAndLength (choc::buffer::ChannelCount start, choc::buffer::ChannelCount length)
	Returns a ChannelRange with a start and length.

template<typename Buffer >
void	sanitise (Buffer &buffer)

template<typename SampleType , template< typename > typename LayoutType>
void	sanityCheckView (const choc::buffer::BufferView< SampleType, LayoutType > &view)
	Checks that the channels have valid pointers if they have a non-zero number of frames.

bool	setThreadPriority (std::thread &, int priority)
	Changes the thread's priority.

bool	tryToUpgradeCurrentThreadToRealtime (const juce::Thread::RealtimeOptions &)
	Tries to upgrade the current thread to realtime priority.

Detailed Description

Aims:

Separate graph structure from processing and any model
Ensure nodes can be processed multi-threaded which scales independently of graph complexity
Processing can happen in any sized block (up to the maximum prepared for)
Process calls will only ever get the number of channels to fill that they report
Process calls will always provide empty buffers so nodes can simply "add" in to them. (Measure performance here)
Processing in float or double

Notes:

Each node should have pointers to its inputs
When a node is processed, it should check its inputs to see if they have produced outputs
If they have, that node can be processed. If they haven't the processor can try another node
If one node reports latency, every other node being summed with it will need to be delayed up to the same ammount
The reported latency of a node is the max of all its input latencies

Initialisation:

There really needs to be two stages for this:
- Stage 1 is a simple visit of all the base nodes (i.e. no send/return connections). This will get a list of all the nodes in the graph
- Stage 2 will be the initialise call with a flat list of all the nodes. Send/return nodes can use this to add inputs from the graph (e.g. based on busNum) (However, at this stage, return nodes might choose to add latency nodes to balance themselves???) (Maybe this should have to happen when the graph is built? That would mean latency needs to be fixed, and therefore plugins would need to be initialised before graph construction.)
Now we have a fully connected graph we can do a proper DFS:
- This can be used to balance processing buffers between the graph by finding unconnected nodes
- Finding a processing order by building "stacks" of nodes starting with leafs
This might look like the following steps:
- visitAcyclic (Visitor) [only visit nodes that it was constructed with, used to create the flat list]
- initialise (const PlaybackInitialisationInfo&) [used to add extra connections and balance latency etc.]
- visitDFS (Visitor) [used to get list of nodes to process and can be called multiple times to optimise graph etc.]

Avoiding incontinuities when latency changes:

One of the bg problems with this latency balancing approach is when the graph is rebuilt, any stateful buffers will be lost.
The only way I can think of solving this is to either reusue the latency nodes directly or reuse the buffers
The biggest problem here is finding which nodes correspond to the new and old graphs
The only way I can currently think of is:
- Each node to have a UID when it is constructed based on its properties (source material, connections etc.)
- During the initialisation stage, the old nodes can be passed on to the new nodes and if they have the same UID, the take any resources they need
- There will probably need to be some validation to ensure that two nodes don't have the same UID
- For things like clip/plugin nodes the UID is simple (EditItemID)
- For latency nodes etc. it will probably have to be based on the input ID and channel index etc.

Buffer optimisation:

As there will be a lot of nodes, it makes sense to reduce the memory footprint by reusing audio and MIDI buffers
There are two ways I can think of doing this:
1. Analyse the graph and where nodes are sequential but not directly connected, use the same buffer
2. Use a buffer pool and release it when all nodes have read from it.
  - This would probably require all nodes that need the output buffer to call "retain" on the node before the processing stage and then "release" once they're done with it. When the count drops to 0 the buffers can be released back to the pool

Enumeration Type Documentation

◆ TransformResult

enum class graph::TransformResult

strong

Enum to signify the result of the transform function.

Enumerator

none

connectionsMade

No transform has been made.

nodesDeleted

New connections have been made.

Nodes have been deleted.

◆ ClearBuffers

enum class graph::ClearBuffers : std::uint8_t

strong

Enumerator
no	Don't clear buffers before passing them to process, your subclass will take care of that.
yes	Do clear buffers before passing to process so your subclass can simply add in to them.

◆ AllocateAudioBuffer

enum class graph::AllocateAudioBuffer : std::uint8_t

strong

Enumerator
no	Don't allocate an audio buffer, your subclass will ignore the dest buffer passed to process and simply use setAudioOutput to pass the buffer along.
yes	Do allocate an audio buffer so your subclass use the dest buffer passed to process.

◆ ShareOutputBuffer

enum class graph::ShareOutputBuffer : std::uint8_t

strong

Enumerator

no

Don't let downstream Nodes adopt this Node's output buffer as their own process buffer.

Use this if the buffer's contents must persist between blocks, e.g. SilentNode's buffer which is cleared once and never re-written.

yes

Downstream Nodes may adopt this Node's output buffer and process in place, overwriting its contents.

◆ VertexOrdering

enum class graph::VertexOrdering

strong

Specifies the ordering algorithm.

Enumerator
preordering
postordering
reversePreordering
reversePostordering
bfsPreordering
bfsReversePreordering

◆ ThreadPoolStrategy

enum class graph::ThreadPoolStrategy

strong

Available strategies for thread pools.

This will determine how worker threads are handled when no Nodes are available for processing.

Enumerator
conditionVariable	Uses CVs to pause threads.
realTime	Uses pause, yield and sleeps to suspend threads.
hybrid	Uses a combination of the above, avoiding CVs on the audio thread.
semaphore	Uses a semaphore to suspend threads.
lightweightSemaphore	Uses a semaphore/spin mechanism to suspend threads.
lightweightSemHybrid	Uses a combination of semaphores/spin and yields to suspend threads.

Function Documentation

◆ makeNode()

template<typename NodeType , typename... Args>

std::unique_ptr< Node > graph::makeNode ( Args &&... args )

Creates a node of the given type and returns it as the base Node class.

References makeNode().

Referenced by makeNode().

◆ operator<()

bool graph::operator<	(	NodeAndID	n1,
		NodeAndID	n2
	)

Compares two NodeAndIDs.

References graph::NodeAndID::id.

◆ operator==()

bool graph::operator==	(	NodeAndID	n1,
		NodeAndID	n2
	)

Compares two NodeAndIDs.

References graph::NodeAndID::id, and graph::NodeAndID::node.

◆ createNodeGraph()

std::unique_ptr< NodeGraph > graph::createNodeGraph	(	std::unique_ptr< Node >	rootNode,
		bool	disableLatencyCompensation
	)

Transforms a Node and then returns a NodeGraph of it ready to be initialised.

References createNodeGraph(), and createNodeMap().

Referenced by createNodeGraph().

◆ visitNodes()

template<typename Visitor >

void graph::visitNodes	(	Node &	node,
		Visitor &&	visitor,
		bool	preordering
	)

Should call the visitor for any direct inputs to the node exactly once.

If preordering is true, nodes will be visited before their inputs, if false, inputs will be visited first.

Parameters

Visitor

has the signature

void (Node&)

graph::Node

Main graph Node processor class.

Definition tracktion_Node.h:228

References preordering, and visitNodes().

Referenced by graph::ConnectedNode::addAudioConnection(), graph::ConnectedNode::addMidiConnection(), and visitNodes().

◆ visitNodesBFS()

template<typename Visitor >

void graph::visitNodesBFS	(	Node &	node,
		Visitor &&	visitor
	)

References visitNodesBFS().

Referenced by visitNodesBFS().

◆ addNodesRecursive()

void graph::addNodesRecursive	(	std::vector< NodeAndID > &	nodeMap,
		Node &	n
	)

References addNodesRecursive(), graph::Node::getInternalNodes(), and graph::Node::getNodeProperties().

Referenced by addNodesRecursive(), and createNodeMap().

◆ createNodeMap()

std::vector< NodeAndID > graph::createNodeMap ( const std::vector< Node * > & nodes )

References addNodesRecursive(), and createNodeMap().

Referenced by createNodeGraph(), and createNodeMap().

◆ getPoolCreatorFunction()

LockFreeMultiThreadedNodePlayer::ThreadPoolCreator graph::getPoolCreatorFunction ( ThreadPoolStrategy )

Returns a function to create a ThreadPool for the given stategy.

References getPoolCreatorFunction().

Referenced by getPoolCreatorFunction().

◆ sampleToTime() [1/2]

template<typename IntType >

constexpr double graph::sampleToTime	(	IntType	samplePosition,
		double	sampleRate
	)

constexpr

Converts an integer sample number to a time in seconds.

References sampleToTime().

Referenced by graph::LatencyProcessor::clearMIDI(), graph::LatencyProcessor::prepareToPlay(), graph::LatencyProcessor::readMIDI(), sampleToTime(), and sampleToTime().

◆ timeToSample() [1/3]

constexpr int64_t graph::timeToSample	(	std::floating_point auto	timeInSeconds,
		double	sampleRate
	)

constexpr

Converts a time in seconds to a sample number.

References timeToSample().

Referenced by graph::NodePlayer::prepareToPlay(), timeToSample(), timeToSample(), and timeToSample().

◆ sampleToTime() [2/2]

template<typename IntType >

constexpr juce::Range< double > graph::sampleToTime	(	juce::Range< IntType >	sampleRange,
		double	sampleRate
	)

constexpr

Converts an integer sample range to a time range in seconds.

References sampleToTime().

◆ timeToSample() [2/3]

constexpr juce::Range< int64_t > graph::timeToSample	(	juce::Range< double >	timeInSeconds,
		double	sampleRate
	)

constexpr

Converts a time range in seconds to a range of sample numbers.

References timeToSample().

◆ timeToSample() [3/3]

template<typename RangeType >

constexpr juce::Range< int64_t > graph::timeToSample	(	RangeType	timeInSeconds,
		double	sampleRate
	)

constexpr

Converts a time range in seconds to a range of sample numbers.

References timeToSample().

◆ findNode()

template<typename NodeType , typename Predicate >

NodeType * graph::findNode	(	NodeGraph &	nodeGraph,
		Predicate	pred
	)

Attempts to find a Node of a given type with a specified ID.

This uses the sortedNodes vector so should be relatively quick (much quicker than traversing from the root node.

References findNode(), and graph::NodeGraph::sortedNodes.

Referenced by findNode().

◆ findNodeWithID()

template<typename NodeType >

NodeType * graph::findNodeWithID	(	NodeGraph &	nodeGraph,
		size_t	nodeIDToLookFor
	)

Attempts to find a Node of a given type with a specified ID.

This uses the sortedNodes vector so should be relatively quick (much quicker than traversing from the root node.

References findNodeWithID(), and graph::NodeGraph::sortedNodes.

Referenced by findNodeWithID().

◆ findNodeWithIDIfNonZero()

template<typename NodeType >

NodeType * graph::findNodeWithIDIfNonZero	(	NodeGraph *	nodeGraph,
		size_t	nodeIDToLookFor
	)

Attempts to find a Node of a given type with a specified ID.

This uses the sortedNodes vector so should be relatively quick (much quicker than traversing from the root node.

References findNodeWithIDIfNonZero().

Referenced by findNodeWithIDIfNonZero().

◆ toAudioBuffer()

juce::AudioBuffer< float > graph::toAudioBuffer ( choc::buffer::ChannelArrayView< float > view )

Creates a juce::AudioBuffer from a choc::buffer::BufferView.

References toAudioBuffer().

Referenced by graph::test_utilities::buffersAreEqual(), toAudioBuffer(), and graph::test_utilities::writeToFile().

◆ toBufferView()

template<typename SampleType >

choc::buffer::BufferView< SampleType, choc::buffer::SeparateChannelLayout > graph::toBufferView ( juce::AudioBuffer< SampleType > & buffer )

Converts a juce::AudioBuffer<SampleType> to a choc::buffer::BufferView.

◆ createFrameRange()

choc::buffer::FrameRange graph::createFrameRange	(	std::integral auto	start,
		std::integral auto	end
	)

Creates a FrameRange from any integral type.

References createFrameRange().

Referenced by createFrameRange().

◆ toMidiMessage()

juce::MidiMessage graph::toMidiMessage ( const choc::midi::Sequence::Event & e )

Converts a choc::midi event to a juce::MidiMessage.

References toMidiMessage().

Referenced by toMidiMessage().

◆ multiplyBy()

template<typename BufferViewType , typename SampleType , typename SmoothingType >

void graph::multiplyBy	(	BufferViewType &	view,
		juce::SmoothedValue< SampleType, SmoothingType > &	value
	)

noexcept

Mutiplies a choc::buffer::BufferView by a juce::SmoothedValue.

References multiplyBy().

Referenced by multiplyBy().

◆ applyGainRamp()

template<typename BufferType , typename GainType >

void graph::applyGainRamp	(	BufferType &&	buffer,
		GainType	startGain,
		GainType	endGain
	)

noexcept

Applies a gain ram to a choc::buffer::BufferView.

References applyGainRamp().

Referenced by applyGainRamp().

◆ frameRangeWithStartAndLength()

choc::buffer::FrameRange graph::frameRangeWithStartAndLength	(	choc::buffer::FrameCount	start,
		choc::buffer::FrameCount	length
	)

Returns a FrameRange with a start and length.

References frameRangeWithStartAndLength().

Referenced by frameRangeWithStartAndLength().

◆ channelRangeWithStartAndLength()

choc::buffer::ChannelRange graph::channelRangeWithStartAndLength	(	choc::buffer::ChannelCount	start,
		choc::buffer::ChannelCount	length
	)

Returns a ChannelRange with a start and length.

References channelRangeWithStartAndLength().

Referenced by channelRangeWithStartAndLength().

◆ sanitise()

template<typename Buffer >

void graph::sanitise ( Buffer & buffer )

References sanitise().

Referenced by sanitise().

◆ sanityCheckView()

template<typename SampleType , template< typename > typename LayoutType>

void graph::sanityCheckView ( const choc::buffer::BufferView< SampleType, LayoutType > & view )

Checks that the channels have valid pointers if they have a non-zero number of frames.

References sanityCheckView().

Referenced by sanityCheckView().

◆ setThreadPriority()

bool graph::setThreadPriority	(	std::thread &	,
		int	priority
	)

Changes the thread's priority.

May return false if for some reason the priority can't be changed.

Parameters

priority the new priority, in the range 0 (lowest) to 10 (highest). A priority of 5 is normal.

References setThreadPriority().

Referenced by setThreadPriority().

◆ tryToUpgradeCurrentThreadToRealtime()

bool graph::tryToUpgradeCurrentThreadToRealtime ( const juce::Thread::RealtimeOptions & )

Tries to upgrade the current thread to realtime priority.

References tryToUpgradeCurrentThreadToRealtime().

Referenced by tryToUpgradeCurrentThreadToRealtime().

Namespaces

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ TransformResult

◆ ClearBuffers

◆ AllocateAudioBuffer

◆ ShareOutputBuffer

◆ VertexOrdering

◆ ThreadPoolStrategy

Function Documentation

◆ makeNode()

◆ operator<()

◆ operator==()

◆ createNodeGraph()

◆ visitNodes()

◆ visitNodesBFS()

◆ addNodesRecursive()

◆ createNodeMap()

◆ getPoolCreatorFunction()

◆ sampleToTime() [1/2]

◆ timeToSample() [1/3]

◆ sampleToTime() [2/2]

◆ timeToSample() [2/3]

◆ timeToSample() [3/3]

◆ findNode()

◆ findNodeWithID()

◆ findNodeWithIDIfNonZero()

◆ toAudioBuffer()

◆ toBufferView()

◆ createFrameRange()

◆ toMidiMessage()

◆ multiplyBy()

◆ applyGainRamp()

◆ frameRangeWithStartAndLength()

◆ channelRangeWithStartAndLength()

◆ sanitise()

◆ sanityCheckView()

◆ setThreadPriority()

◆ tryToUpgradeCurrentThreadToRealtime()