/*===================================================================================================
AAX_CommonInterface_Communication.doxygen

Copyright 2016, 2018, 2023 Avid Technology, Inc. 
All rights reserved.

CONFIDENTIAL: this document contains confidential information of Avid. Do
not disclose to any third party. Use of the information contained in this
document is subject to an Avid SDK license.

===================================================================================================*/



/** @defgroup CommonInterface_Communication AAX communication protocols
 	@ingroup MainInterface
 	
 	@brief How to transfer data between different parts of an %AAX plug-in
 	
 	
 	%AAX is a highly modular architecture.  This section describes the various means by which %AAX
 	plug-in modules may communicate with one another and with the host.
 	
 	There are two fundamental categories of communication in AAX:
 		-# \ref CommonInterface_Communication_hostmodules
 		-# \ref CommonInterface_Communication_algorithm
 	
 	\section CommonInterface_Communication_hostmodules Communication with the C++ interface objects
 		
 		\subsection CommonInterface_Communication_hostmodules_controller Direct host communication
 		
 			Most communication between the %AAX host and the plug-in is accomplished via the
 			\ref AAX_IController interface.  This interface contains methods for such things as:
 				- Retrieving environment information such as the current
 				    \ref AAX_IController::GetSampleRate() "sample rate"
 				- Getting and setting Effect parameters such as the Effect's
 				    \ref AAX_IController::GetSignalLatency() "algorithmic delay"
 				- Accessing host-managed information such as
 				    \ref AdditionalFeatures_Meters and MIDI
 				- Accessing other host-managed communications protocols like
 				    \ref CommonInterface_Communication_algorithm_datapackets and MIDI
 			
 			In addition, the GUI uses a separate interface for managing view and event details
 			with the host.  This interface, \ref AAX_IViewContainer, includes methods for:
 				- Retrieving information like the raw view and the currently held modifier keys
 				- Requesting changes to view parameters (e.g. size)
 				- Passing GUI events on to the host.
 					- This is an important function because the host may require its own specific
 					 behavior for certain events.  For example, a command-control-option click
 					 in Pro Tools should bring up the parameter's automation menu.
 		
 		\subsection CommonInterface_Communication_hostmodules_customdata Custom data blocks
 		
 			Often it is necessary to transmit arbitrary blocks of custom plug-in data between
 			different plug-in modules.  In %AAX, this is accomplished by "pushing" data to and
 			"pulling" it from the plug-in's \ref CommonInterface_DataModel "data model".
 			
 			The abstract data model interface includes two custom data methods for this:
 				\li \ref AAX_IEffectParameters::GetCustomData()
 				\li \ref AAX_IEffectParameters::SetCustomData()
 			
 			It is the data model's job to act as a go-between when custom data must be
 			transmitted between a plug-in's other modules.
 			
 			For example, a plug-in may wish to send analysis data from its
 			\ref AuxInterface_DirectData "direct data module" to its \ref CommonInterface_GUI "GUI".  In this situation,
 			the Direct Data object would call
 			\ref AAX_IEffectParameters::SetCustomData() "SetCustomData()" to update the data model
 			whenever new data was available, while the GUI would "pull" the most up-to-date data
 			via \ref AAX_IEffectParameters::GetCustomData() "GetCustomData()" whenever an update was
 			required.
 			
 			Note that the default implementations of these methods are empty and thus all
 			implementation details, including thread safety guards, are left to the plug-in.
 			
 		\subsection CommonInterface_Communication_hostmodules_notifications Notifications
 		
 			The \ref CommonInterface_DataModel "data model" and \ref CommonInterface_GUI "GUI" interfaces include
 			\ref AAX_IEffectParameters::NotificationReceived() "notification hook" methods.
 			These methods used for \ref AAX_ENotificationEvent "host-to-Effect notifications"
 			by default, but may also be called with custom notification IDs in order to create
 			custom notifications within a plug-in.
 		
 		\subsection CommonInterface_Communication_hostmodules_directpointersharing Direct pointer sharing
 		
 			If co-location is guaranteed, plug-in modules may directly share data pointers.  For
 			example, a non-real-time plug-in's \ref AuxInterface_HostProcessor "Host Processor" object may share a
 			\c this pointer with its \ref CommonInterface_DataModel "data model" object.
 			
 			To guarantee co-location between modules that could normally be placed into different
 			memory spaces by the host, use "constraint" properties:
 			
 				\li \ref AAX_eProperty_Constraint_Location
 				\li \ref AAX_eProperty_Constraint_Topology
 			
 			To help avoid forwards-compatibility issues with future devices that support %AAX, these
 			constraints should be set whenever a plug-in requires co-location of its components.
 			Note, however, that using a design that relies on co-location will prevent the plug-in
 			from running in distributed environments and should therefore be avoided when possible.

 	\section CommonInterface_Communication_algorithm Communication with the real-time algorithm
 		
 		An %AAX plug-in's algorithm is essentially a stateless callback and, therefore, all of its
 		state data must at some level be managed by the host.  This model is fundamentally different
 		from the other plug-in modules, which are each objects with their own memory and state.
 		
 		Most algorithmic data management is performed via the algorithm's context structure.  More
 		information about memory management in %AAX real-time algorithms can be found
 		\ref alg_memmgmt "here".
 		
 		\subsection CommonInterface_Communication_algorithm_datapackets Data packets
 		
 			The most common form of communication with a plug-in's real-time algorithm callback is
 			the transmission of read-only data from the data model to the context structure.
 			
 			%AAX includes a dedicated API for this task that provides buffered, optimized delivery of
 			read-only data packets to the algorithm.  For more information, see \ref alg_comm .
 		
  		\subsection CommonInterface_Communication_algorithm_fields Host-managed context fields
 		
 			Algorithms can also send data to the host and receive environment information through
 			dedicated context fields.  For example, the host can provide access to DMA facilities
 			through an object accessed via a DMA field, and a plug-in can report meter values to the
 			host via a dedicated meter field.  For more information, see \ref alg_comm .
 		
 		\subsection CommonInterface_Communication_algorithm_directdata Direct data transfers
 		
 			When other modules in the plug-in must interact directly with the algorithm's state
 			information this is accomplished via the \ref AuxInterface_DirectData "Direct Data" interface.  This interface
 			provides an idle-time context in which the plug-in may read from or write to the
 			algorithm's private data memory.  These transfers are unbuffered and therefore the
 			plug-in must handle any appropriate thread-safety considerations.
 		
 */
