<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<c74object name="mc.ambidecode~" module="ICST Ambisonics">

    <digest>
		Decode Ambisonics B-Format to multiple audio sinks
    </digest>

    <description>
		Decode Ambisonics B-Format to multiple audio sinks, in three possible formats: Furse-Malham, Normalized 3D, and Semi-Normalized 3D a.k.a. ambiX format.
    </description>

    <!--METADATA-->
    <metadatalist>
	<metadata name="author">ICST | Zurich University of the Arts</metadata>
	<metadata name="tag">ICST Ambisonics</metadata>
	<metadata name="copyright">
	 © 2003 - 2021 ICST | Zurich University of the Arts
	</metadata>
	<metadata name="version">
	3.0 (Build 02/2021)
	</metadata>
    </metadatalist>

    <!--DISCUSSION-->
    <discussion>

    </discussion>

    <!--INLETS-->
    <!--do not use-->
    <inletlist>
    </inletlist>

    <!--OUTLETS-->
    <!--do not use-->
    <outletlist>
    </outletlist>

    <!--ARGUMENTS-->
    <objarglist>
	<objarg name="order" optional="1" type="int">
	    <description>
			<p>The ambisonic encoding order, from 1 to 11 (default: 1). Generates order-appropriate number of inlets for receiving B-Format components.</p>
			<p>NB: when changing the order, it can be lowered but not raised beyond originally set order.</p>
	    </description>
	</objarg>
	
	<objarg name="number of output signals" optional="1" type="int">
	    <description>
			<p>The number of output signals and outlets (default: 1, limit: 192).</p>
	    </description>
	</objarg>
    </objarglist>

    <!--MESSAGES-->
    <methodlist>
		
		<method name="aed">
		    <description>
				Input ambipoint with polar/spherical coordinates, setting the corresponding sink's panning coefficients. 
				<code>"aed" &#60;point-ID&#62; &#60;azimuth&#62; &#60;elevation&#62; &#60;distance&#62;</code>
				<p><b>NB: group and orientation data have no effect</b></p>
		    </description>
		</method>
	
		<method name="xyz">
		    <description>
				Input ambipoint with cartesian/rectangular coordinates, setting the corresponding sink's panning coefficients.
					<code>"xyz" &#60;point-ID&#62;&#60;x-value&#62;&#60;y-value&#62;&#60;z-value&#62;</code>
					<p><b>NB: group and orientation data have no effect</b></p>
			</description>
		</method>
		
		<method name="scene_rotation">
		    <description>
				<p>Rotate the entire sound scene (at the output stage).</p>
				<p><b>NB: Angles turn the opposite direction from source/sink definitions.</b> Consider that when you turn your head one way, the sounds turn the other way...</p>
				<code>"scene_rotation" &#60;x-axis&#62;&#60;y-axis&#62;&#60;z-axis&#62;</code>
			</description>
		</method>
				
	<method name="gain_n">
	    <description>
			Set the gain of sink n. Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global gain).
	    </description>
	</method>
	

	<method name="active_n">
	    <description>
			Set the active_status of sink n (unmute). Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global active attribute).
	    </description>
	</method>		
	
	<method name="defaultweights">
	    <description>
			Resets the decoding weights to their order-appropriate defaults.
	    </description>
	</method>	
	
	
	<method name="setcoefs">
	    <description>
			Manually set the entire coefficient matrix. Input format: <code>&#60;input-index int/float&#62; &#60;coef float&#62; &#60;coef float&#62; &#60;coef float&#62; .....</code>
	    </description>
	</method>			
	
	<method name="dumpcoefs">
	    <description>
			Print all coefficients to Max' console window.
	    </description>
	</method>	

	<method name="read">
	    <description>
			Read settings from an xml-formatted file. A settings-file stores the entire parameter setup.
		</description>
	</method>
		
	<method name="write">
	    <description>
			Write settings to an xml-formatted file. A settings-file stores the entire parameter setup.
		</description>
	</method>	

	<method name="import_coefs">
	    <description>
			Read a coefficient-set from an xml-formatted file. A coefficient-file stores all the coefficients of the signal-matrix.
		</description>
	</method>
		
	<method name="export_coefs">
	    <description>
			Write a coefficient-set to an xml-formatted file. A coefficient-file stores all the coefficients of the signal-matrix.
		</description>
	</method>
	
	<method name="report">
	    <description>
			Print entire internal state to Max' console window.
	    </description>
	</method>
	
	<method name="version">
	    <description>
			Print version information to Max' console window.
	    </description>
	</method>
    </methodlist>

    <!--ATTRIBUTES-->
    <attributelist>
	<attribute name="type" get="0" set="0" type="symbol" size="1" value="Ambisonics Type">
	    <description>
			<p>The Ambisonics decoding type (default: 2 ambiX).</p>
			Types are: 
			<ul>
				<li>0: FuMa Furse-Malham</li>
				<li>1: N3D (normalized 3D)</li>
				<li>2: ambiX SN3D (semi-normalized 3D)</li>
			</ul>
		</description>
	</attribute>
	
	<attribute name="order" get="0" set="0" type="int" size="1" value="Order">
	    <description>
			<p>The Ambisonics decoding order, set by input signal-width (default: 1, maximum 11).</p>
	    </description>
	</attribute>
	
	<attribute name="aed_scale" get="0" set="0" type="float" size="1" value="aed_scale">
	    <description>
			<p>Scaling factor for polar/spherical coordinates (default: 10).</p>
			<p><bi>NB: the default 10-fold scaling allows to control a scene with an extent of 10 units from a non-zoomed ambimonitor.</bi></p>
	    </description>
	</attribute>
	
	<attribute name="xyz_scale" get="0" set="0" type="float" size="1" value="aed_scale">
	    <description>
			<p>Scaling factor for cartesian/rectangular coordinates (default: 10).</p>
			<p><bi>NB: the default 10-fold scaling allows to control a scene with an extent of 10 units from a non-zoomed ambimonitor.</bi></p>
	    </description>
	</attribute>
	
	<attribute name="coord_system" get="0" set="0" type="int" size="1" value="Coordinate System">
	    <description>
			The input coordinate system type (default: 0 Navigation): 
			<ul>
				<li>0: Navigation</li>
				<li>1: Acoustics</li>
				<li>0: Mathematics</li>
				<li>1: OpenGL</li>
			</ul>
			<p>See Coordinate System sub-patcher in the help-file.</p>
	    </description>
	</attribute>

	<attribute name="coord_angles" get="0" set="0" type="int" size="1" value="Angle Type">
	    <description>
			The input-angle type: 
			<ul>
				<li>0: Degrees - input angles in degrees (default).</li>
				<li>1: Radians - input angles in radians.</li>
			</ul>
	    </description>
	</attribute>

	<attribute name="rotate_order" get="0" set="0" type="int" size="1" value="Scene rotate order">
	    <description>
			In mode <bi>rotate</bi>: determines the order of rotations.<br/>
			Options are: xyz, xzy, yxz, yzx, zxy, zyx; and: xyx, xzx, yxy, yzy, zxz, zyz. <br/>
			The order of rotations and not permutable, i.e, changing he order of rotation changes the outcome.
			The first six options rotate about all three axes, the following six rotate about two axes only.
			<bluebox><p><b>NB:</b> The option <bi>zyx</bi> (default) is the most commonly used and produces the generally expected order of yaw-pitch-roll.</p>
			<p><i>"The order of rotations follows the M*v convention, meaning that XYZ returns the Euler angles for rotating a vector v in the order X * (Y * (Z * v))). If you don't know which one to use, then it's probably the Euler ZYX."</i></p>
		</bluebox>
	    </description>
	</attribute>

	<attribute name="interpolation" get="0" set="0" type="onoff" size="1" value="Interpolation mode">
	    <description>
			<p>Activate/deactivate interpolated block-wise coefficient interpolation, enabling clickless signal processing (default: off).</p>
			<p><bi>NB: change takes place upon DSP restart</bi></p>
	    </description>
	</attribute>

	<attribute name="interpolation_time" get="0" set="0" type="float" size="1" value="Interpolation time">
	    <description>
				<p>Length of interpolation ramp in ms.</p>
				<p>Interpolation sample-length is quantised to next lower multiple of vector-size (minimum interpolation time is duration of one signal vector).</p>
				<p><bi>NB: change takes place upon DSP restart</bi></p>
			</description>
	</attribute>
	
	<attribute name="orderweight" get="0" set="0" type="float" size="variable number of" value="Order Weights">
	    <description>
				<p>Order Weights, per order weighting factor. Influences phase behaviour of decoder.</p>
			</description>
	</attribute>	

	<attribute name="gain" get="0" set="0" type="float" size="1" value="Gain">
	    <description>
			<p>Set overall gain (default: 1).</p>
	    </description>
	</attribute>

	<attribute name="active" get="0" set="0" type="int" size="various number of" value="Active">
	    <description>
			<p>Activate (unmute) input signals, list of input channels (default: all 1).</p>
	    </description>
	</attribute>
		
    </attributelist>
	
    <misc name = "Input">
	<entry name ="Inlet 1 [bang, int, float, list, anything, audio signal]">
	    <description>
		Input ambipoints, control parameters and other messages. Also input B-Format's first component.
	    </description>
	</entry>
	<entry name ="Inlet 2-n [audio signal]">
	    <description>
		Input remaining B-Format component signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet 1-n [audio signals]">
	    <description>
		Output n sink signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Discussion">
	<entry name ="Keywords">
	    <description>
		ambidecode, audio spatialisation, multiple audio sink decoding
	    </description>
	</entry>
    </misc>
	
    <!--SEEALSO-->
	<seealsolist>
		
		<seealso name="ambiencode~"/>
		<!-- <seealso name="ambidecode~"/> -->
		<seealso name="ambipanning~"/>
				
		<seealso name="mc.ambiencode~"/>
		<seealso name="mc.ambidecode~"/>
		<seealso name="mc.ambipanning~"/>
		
		<seealso name="ambimonitor"/>
		<seealso name="ambicontrol"/>
		<seealso name="ambipoint"/>
		
		<seealso name="icst.map"/>
		<seealso name="icst.random"/>
		<seealso name="icst.spline"/>
		
		<seealso name="icst.button"/>
		<seealso name="icst.intui"/>
		<seealso name="icst.floatui"/>
		<seealso name="icst.listui"/>

	</seealsolist>

</c74object>
