VST 3 Interfaces VST 3.7
SDK for developing VST plug-in
IDataExchangeHandler Class Referenceabstract

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
processorthe processor who wants to open the queue
blockSizesize of one block
numBlocksnumber of blocks in the queue
alignmentdata alignment, if zero will use the platform default alignment if any
userContextIDan identifier internal to the processor
outIDon 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
queueIDthe 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
queueIDthe ID of the queue
blockon 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
queueIDthe ID of the queue
blockIDthe ID of the block
sendToControllerif 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
Empty

Copyright © Steinberg Media Technologies GmbH. All Rights Reserved. This documentation is under this license.