/*===================================================================================================
AAX_AdditionalFeatures_CurveDisplays.doxygen

Copyright 2017, 2019, 2023-2024 Avid Technology, Inc. 
All rights reserved.

This file is part of the Avid AAX SDK.

The AAX SDK is subject to commercial or open-source licensing.

By using the AAX SDK, you agree to the terms of both the Avid AAX SDK License
Agreement and Avid Privacy Policy.

AAX SDK License: https://developer.avid.com/aax
Privacy Policy: https://www.avid.com/legal/privacy-policy-statement

Or: You may also use this code under the terms of the GPL v3 (see
www.gnu.org/licenses).

THE AAX SDK IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
DISCLAIMED.

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

/** @defgroup AdditionalFeatures_CurveDisplays EQ and Dynamics Curve Displays
	@ingroup AdditionalFeatures
	
	@brief Displaying EQ and Dynamics curves in Pro Tools, control surfaces, and other auxiliary graphical interfaces
	
	<!-- NOTE: REFERENCES TO PRO TOOLS CONTROL APP REMOVED UNTIL IT SUPPORTS CURVES -->
	
	<H3>About</H3>
	<DIV CLASS="section">
		Pro Tools, control surfaces, and other auxiliary displays connected to the %AAX host may provide a curve data display to enhance the graphical representation of the plug-in's state.
		
		A "bouncing ball" meter may also be overlaid within the curve data presentation for Dynamics plug-ins.
		
		<!--
		<TABLE CLASS="invis">
			<TR>
				<TD width="30%">
					\nodox Image files must be copied to the /output/html directory \endnodox
		<IMG width="80%" alt="Pro Tools | Control app controlling an EQ plug-in instance" src="pro_tools_control_eq.png" />
		<DIV CLASS="imagecaption">Pro Tools | Control app display controlling an EQ plug-in instance</DIV>
				</TD>
				<TD width="70%">
					\nodox Image files must be copied to the /output/html directory \endnodox
		<IMG width="20%" alt="Pro Tools | S6 MTM display showing a Dynamics plug-in instance with bouncing-ball metering" src="s6_mtm_dyn-filtered-16.png" />
		<DIV CLASS="imagecaption">Pro Tools | S6 MTM display showing a Dynamics plug-in instance with bouncing-ball metering</DIV>
				</TD>
			</TR>
		</TABLE>
		-->
		
		\nodox Image files must be copied to the /output/html directory \endnodox
		<IMG width="35%" alt="Pro Tools display showing an EQ plug-in instance" src="pro_tools_eq_curve.png" />
		<DIV CLASS="imagecaption">Pro Tools Mix Window displaying EQ plug-in instances</DIV>
		
		\nodox Image files must be copied to the /output/html directory \endnodox
		<IMG width="20%" alt="Pro Tools | S6 MTM display showing a Dynamics plug-in instance with bouncing-ball metering" src="s6_mtm_dyn-filtered-16.png" />
		<DIV CLASS="imagecaption">Pro Tools | S6 MTM display showing a Dynamics plug-in instance with bouncing-ball metering</DIV>
		
	</DIV>
	
	<H3>Requirements</H3>
	<DIV CLASS="section">
		\compatibility For S6 control surface displays, see \ref PT-226228 and \ref PT-226227 in the \ref KnownIssues page for more information about the requirements listed in this section.
		
		These are the requirements for supporting the %AAX curve data display features:
		
		- To support EQ curve data displays, a plug-in must support AAX_IEffectParameters::GetCurveData()
		- To support Dynamics curve data displays, a plug-in must also support \ref AAX_IEffectParameters::GetCurveDataDisplayRange() for the Dynamics curve data types.
		
		The %AAX host will only query and display curve data for plug-ins of the applicable \ref AAX_EPlugInCategory "Category", as specified in the \ref AAX_ECurveType documentation.
		
		In order to present a bouncing-ball metering display, Dynamics plug-ins must also support \ref AAX_IEffectParameters::GetCurveDataMeterIds() in addition to the two other curve data methods. This feature is always optional: a Dynamics plug-in may present a curve only without support for a bouncing-ball meter overlay.
	
	</DIV>
	
	<H3>Pro Tools Implementation</H3>
	<DIV CLASS="section">
		There are three different kinds of calls that Pro Tools will make when querying EQ plug-ins for curve data:
		- An initial query with a small set of points. This query is used only to determine whether the plug-in supports the EQ Curve display feature. The result data is not used. If the plug-in does not support the feature it must return an error value from \ref AAX_IEffectParameters::GetCurveData() "GetCurveData()"
		- A normal full-curve query to get the base curve data across the full display range
		- One or more targeted queries around any detected inflection points. These queries are used to increase display resolution for plug-ins with very narrow Q settings.
	
		Pro Tools will call \ref AAX_IEffectParameters::GetCurveData() "GetCurveData()" from a thread in a low-priority thread pool. Most other Pro Tools operations will not be blocked by the execution of this method, though note that if a control surface is also issuing queries then the method may be called concurrently from multiple host threads.
		
		In Pro Tools, curve updates are triggered by incrementing the plug-in's change counter. This is the counter value returned from the \ref AAX_IEffectParameters::GetNumberOfChanges() "GetNumberOfChanges()" method in the plug-in. This counter is updated automatically when any plug-in parameter changes.
	
	</DIV>
		
	<H3>Testing</H3>		
	<DIV CLASS="section">	
		There are several ways to test a plug-in's S6 curve implementation:
		
		<H5>
			View the plug-in using Pro Tools or another client app or control surface with curve display support
		</H5>
		<DIV CLASS="TextInd1">
			The best way to test your plug-in's curve data display support is to use a real application or control surface to test the behavior of your plug-in with real user workflows. For EQ plug-ins you can use the EQ Curve display in the Pro Tools Mix Window.
			
			<!-- If you do not have access to a full \ref subsubsection__avid_s6 "Pro Tools | S6" control surface then the free \ref subsubsection__avid_ptcontrol "Pro Tools | Control" app is a great way to test your plug-in's curve data display in a real-world setting using a shipping client. -->
		</DIV>
		
		<H5>
			View the plug-in using the S6 Surfulator software to emulate an S6 control surface
		</H5>
		<DIV CLASS="TextInd1">
			You can view the plug-in's curve data on the emulated MTM module display. The emulator runs the same software as a true S6 system, so the curve representation in the emulator will be accurate to what would be displayed on S6 hardware.
		</DIV>
		
		<H5>
			Test EQ and Dynamics curves at high resolution within Pro Tools using the "TestGetCurveData" DigiOption
		</H5>
		<DIV CLASS="TextInd1">
			See \ref aax_pro_tools_guide__digioptions for more information about this option.
				
			\nodox Image files must be copied to the /output/html directory \endnodox
			<IMG width="30%" alt="TestGetCurveData EQ graph in plug-in header" src="Pro_Tools_Guide_DigiOption_TestGetCurveData.png" />
			<DIV CLASS="imagecaption">TestGetCurveData EQ graph in plug-in header</DIV>
		</DIV>
		
		<H5>
			Use the aaxh dish which is included in the DSH Test Tools package to check your plug-in's curve data
		</H5>
		<DIV CLASS="TextInd1">
			\verbatim
	dsh> load_dish aaxh
	dsh> loadpi "/path/to/your/plug-in.aaxplugin"
	dsh> listeffects
		View the list of effects in your plug-in and determine which effect you want to test, if there are more than one
	dsh> instantiateforcontext {plugin: 0, effect: 0, plat: native, in: mono, out: mono, rate: 48000, alg: true}
		Use whatever context parameterization is appropriate for the plug-in configuration you want to test
	dsh> getcurvedata {plugin: 0, inst: 0, display: graph}
		Experiment with other display values to get other kinds of information
		You can edit the instance's parameter values within DSH using the "setparameter" command to see the effects of various parameter changes on the curve
			\endverbatim
		
			The "getcurvedata" command will check all three curve data types and will present information for each supported type.
		
			Here is an example of the command output using Avid's Dynamics III plug-in:
			\verbatim
	cmd_result:
	  curve_data:
		AXdr:
		  values:
			supported: false
		AXdy:
		  values:
			ascii_art: |
					0|                                                                                
					 |                                                                                
					 |                                                                                
					 |                                                                                
					 |                                                                                
					 |                                                                        ********
					 |                                                            ************        
					 |                                                ************                    
					 |                                            ****                                
					 |                                       *****                                    
					 |                                   *****                                        
					 |                               *****                                            
					 |                           *****                                                
					 |                       *****                                                    
					 |                   *****                                                        
					 |               *****                                                            
					 |           *****                                                                
					 |       *****                                                                    
					 |   *****                                                                        
				  -60|****                                                                            
			  ----------------------------------------------------------------------------------------
					 | -60                                                                           0
		  
			supported: true
		AXeq:
		  values:
			supported: false
	  instanceID: 0
	  pluginID: 0
	message_type: cmd_result
	...
			\endverbatim			
		</DIV>
		
	</DIV>
		
 */
