IDataExchangeHandler Class Reference

Host Data Exchange handler interface: Vst::IDataExchangeHandler. More...

#include <ivstdataexchange.h>

Inheritance diagram for IDataExchangeHandler:

Public Member Functions
virtual tresult	openQueue (IAudioProcessor *processor, uint32 blockSize, uint32 numBlocks, uint32 alignment, DataExchangeUserContextID userContextID, DataExchangeQueueID *outID)=0
	open a new queue More...
virtual tresult	closeQueue (DataExchangeQueueID queueID)=0
	close a queue More...
virtual tresult	lockBlock (DataExchangeQueueID queueId, DataExchangeBlock *block)=0
	lock a block if available More...
virtual tresult	freeBlock (DataExchangeQueueID queueId, DataExchangeBlockID blockID, TBool sendToController)=0
	free a previously locked block More...
Public Member Functions inherited from FUnknown
virtual tresult	queryInterface (const TUID _iid, void **obj)=0
virtual uint32	addRef ()=0
virtual uint32	release ()=0

Static Public Attributes
static const FUID	iid
Static Public Attributes inherited from FUnknown
static const FUID	iid

Detailed Description

Host Data Exchange handler interface: Vst::IDataExchangeHandler.

• [host imp]
• [context interface]
• [released: 3.7.9]
• [optional]

The IDataExchangeHandler implements a direct and thread-safe connection from the realtime audio context of the audio processor to the non-realtime audio context of the edit controller. This should be used when the edit controller needs continuous data from the audio process for visualization or other use-cases. To circumvent the bottleneck on the main thread it is possible to configure the connection in a way that the calls to the edit controller will happen on a background thread.

Opening a queue: The main operation for a plug-in is to open a queue via the handler before the plug-in is activated (but it must be connected to the edit controller via the IConnectionPoint when the plug-in is using the recommended separation of edit controller and audio processor). The best place to do this is in the IAudioProcessor::setupProcessing method as this is also the place where the plug-in knows the sample rate and maximum block size which the plug-in may need to calculate the queue block size. When a queue is opened the edit controller gets a notification about it and the controller can decide if it wishes to receive the data on the main thread or the background thread.

Sending data: In the IAudioProcessor::process call the plug-in can now lock a block from the handler, fill it and when done free the block via the handler which then sends the block to the edit controller. The edit controller then receives the block either on the main thread or on a background thread depending on the setup of the queue. The host guarantees that all blocks are send before the plug-in is deactivated.

Closing a queue: The audio processor must close an opened queue and this has to be done after the processor was deactivated and before it is disconnected from the edit controller (see IConnectionPoint).

What to do when the queue is full and no block can be locked? The plug-in needs to be prepared for this situation as constraints in the overall system may cause the queue to get full. If you need to get this information to the controller you can declare a hidden parameter which you set to a special value and send this parameter change in your audio process method.

Member Function Documentation

openQueue()

virtual tresult openQueue ( IAudioProcessor *  processor, uint32  blockSize, uint32  numBlocks, uint32  alignment, DataExchangeUserContextID  userContextID, DataExchangeQueueID *  outID  )

pure virtual

open a new queue

only allowed to be called from the main thread when the component is not active but initialized and connected (see IConnectionPoint)

Parameters

processor	the processor who wants to open the queue
blockSize	size of one block
numBlocks	number of blocks in the queue
alignment	data alignment, if zero will use the platform default alignment if any
userContextID	an identifier internal to the processor
outID	on return the ID of the queue

Returns

kResultTrue on success

closeQueue()

virtual tresult closeQueue ( DataExchangeQueueID  queueID )

pure virtual

close a queue

closes and frees all memory of a previously opened queue if there are locked blocks in the queue, they are freed and made invalid

only allowed to be called from the main thread when the component is not active but initialized and connected

Parameters

queueID

the ID of the queue to close

Returns

kResultTrue on success

lockBlock()

virtual tresult lockBlock ( DataExchangeQueueID  queueId, DataExchangeBlock *  block  )

pure virtual

lock a block if available

only allowed to be called from within the IAudioProcessor::process call

Parameters

queueID	the ID of the queue
block	on return will contain the data pointer and size of the block

Returns

kResultTrue if a free block was found and kOutOfMemory if all blocks are locked

freeBlock()

virtual tresult freeBlock ( DataExchangeQueueID  queueId, DataExchangeBlockID  blockID, TBool  sendToController  )

pure virtual

free a previously locked block

only allowed to be called from within the IAudioProcessor::process call

Parameters

queueID	the ID of the queue
blockID	the ID of the block
sendToController	if true the block data will be send to the IEditController otherwise it will be discarded

Returns

kResultTrue on success

Member Data Documentation

iid

const FUID iid

static