<?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  - multichannel version
    </digest>

    <description>
		Decode Ambisonics B-Format to multiple audio sinks, in three possible formats: Furse-Malham, Normalized 3D, and Semi-Normalized 3D aka. ambiX format.
		This multi-channel version accepts a B-Format in a single multi-channel signal and produces the sinks as a single multi-channel output.
		<bluebox>
			<p><b>Multichannel signals:</b></p>
			<p>The inlet accepts one multi-channel signals carrying the B-Format stream. The number of input channels determines the order of ambisonics processing.</p>
			<p>The outlet produces a single multi-channel signal carrying the resulting audio streams.</p>
			<p>All multi-channel changes only takes effect upon <b>DSP RESTART</b>.</p>
		</bluebox>
    </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 audio channels in output multichannel signal.</p>
			<p>NB: when changing the order, the number of input channels processed gets changed. Normally the order gets set by the upstream encoder.</p>
	    </description>
	</objarg>
	
	<objarg name="number of output signals" optional="1" type="int">
	    <description>
			<p>The number of output signals (default: 1, limit: 192).</p>
			<p>The outlet carries a single multichannel signal with the predefined number of output signals; this number is <b>FIXED</b> and can only defined by the second argument.</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 [bang, int, float, list, anything, multi-channel audio signal]">
	    <description>
		Input ambipoints, control parameters and other messages. Also input B-Format as one multi-channel signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet [1 multichannel audio signal]">
	    <description>
		Multichannel signal carries the n sink signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Discussion">
	<entry name ="Keywords">
	    <description>
		mc.ambidecode, audio spatialisation, multiple audio sink decoding, multi-channel connections
	    </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>
