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

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

    <digest>
		Encode multiple audio sources to Ambisonics B-Format - multichannel version
    </digest>

    <description>
		Encode multiple audio sources to Ambisonics B-Format, in three possible formats: Furse-Malham, Normalized 3D, and Semi-Normalized 3D aka. ambiX format.
		This multi-channel version accepts single- and multi-channel signals and outputs a single multi-channel signal.
		<bluebox>
			<p><b>Multichannel signals:</b></p>
			<p>The inlets accept traditional single-channel signal or multi-channel signals. The number of input channels can change dynamically, depending on the the type and number of input channels at each inlet.</p>
			<p>The outlet always carries a single multi-channel signal, containing the order-appropriate number of output signals - order change dynamically alters the number of output signals</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 output channels in the multichannel-signal get adapted.</p>
	    </description>
	</objarg>
	<objarg name="number of inlets" optional="1" type="int">
	    <description>
			<p>The number of inlets (default: 1, limit: 1024). Generates required number of inlets. The inlets accept both single and multi-channel signals.</p>
			<p><b>NB: audio source indices are increased in an accumulated manner across single- and multi-channel inputs.</b></p>
	    </description>
	</objarg>
    </objarglist>

    <!--MESSAGES-->
    <methodlist>
		
		<method name="aed">
		    <description>
				Input ambipoint with polar/spherical coordinates, setting the corresponding point-source 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 point-source 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 input 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 source n. Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global gain).
	    </description>
	</method>
	
	<method name="order_n">
	    <description>
			Set the order of source n. Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global order).
	    </description>
	</method>
	
	<method name="distance_mode_n">
	    <description>
			Set the distance mode of source n. Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global distance mode).
	    </description>
	</method>
	
	<method name="db_unit_n">
	    <description>
			Set the fall-off dB unit of source n. Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global dB unit).
	    </description>
	</method>

	<method name="dist_att_n">
	    <description>
			Set the distance attenuation unit of source n. Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global distance attenuation).
	    </description>
	</method>	
	

	<method name="active_n">
	    <description>
			Set the active_status source n (unmute). Arguments: ID <m>int</m> value <m>float</m> (overridden by changes in global active attribute).
	    </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 encoding 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 encoding order, set by argument 1 (default: 1).</p>
			<p>Can be lowered, but not raised beyond initial order.</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: on).</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="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>


		<attribute name="distance_mode" get="0" set="0" type="int" size="1" value="Distance Coding Mode">
		    <description>
				Distance Coding Mode: attenuation of amplitude for distances inside and outside the center zone. Applied to signal <b>before</b> encoding (default: 1 Exponential Decay): 
				<ul>
					<li>0: Off</li>
					<li>1: Exponential Decay</li>
					<li>2: Inverse Proportional Decay</li>
				</ul>
				<p><bi>NB: For this and the following attributes, see <m>Distance Encoding</m> sub-patcher in the help-file.</bi></p>
		    </description>
		</attribute>

		<attribute name="db_unit" get="0" set="0" type="float" size="1" value="Distance Rolloff dB per Unit">
		    <description>
				<p>Distance Rolloff dB per Unit, for exponential mode (mode 1).</p>
		    </description>
		</attribute>

		<attribute name="dist_att" get="0" set="0" type="float" size="1" value="Distance Attenuation Rolloff Factor">
		    <description>
				<p>Distance Attenuation Rolloff Factor, for inverse proportional mode (mode 2).</p>
		    </description>
		</attribute>
		
		<attribute name="center_att_db" get="0" set="0" type="float" size="1" value="Center Attenuation Rolloff dB">
		    <description>
				<p>Center Attenuation Rolloff dB.</p>
		    </description>
		</attribute>

		<attribute name="center_curve" get="0" set="0" type="float" size="1" value="Center Curve Factor">
		    <description>
				<p>Center Curve Factor.</p>
		    </description>
		</attribute>
		
		<attribute name="center_size" get="0" set="0" type="float" size="1" value="Center Zone Size">
		    <description>
				<p>Center Zone Size.</p>
		    </description>
		</attribute>				
		
    </attributelist>
	
    <misc name = "Input">
	<entry name ="Inlet 1 [bang, int, float, list, anything, single- and multi-channel audio signal 1]">
	    <description>
		Input ambipoints, control parameters and other messages. Also input first source audio single- and multi-channel signals.
	    </description>
	</entry>
	<entry name ="Inlet 2 ... n, source audio signals 2 - n [single- and multi-channel audio signals]">
	    <description>
		Input subsequent source audio single- and multi-channel signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet 1 [1 multichannel audio signal]">
	    <description>
		Multichannel signal carries the B-Format component signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Discussion">
	<entry name ="Keywords">
	    <description>
		mc.ambiencode, audio spatialisation, multiple audio source encoding, 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>
