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

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

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

    <description>
		Encode multiple audio sources to Ambisonics B-Format, 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 outlets (default: 4 outlets).</p>
			<p>NB: when creating a box with higher than 3rd order and applying the Furse-Malham coding, the output-channels above 16 will stay silent.</p>
	    </description>
	</objarg>
	<objarg name="sources" optional="1" type="int">
	    <description>
			The number of sources (default: 1, limit: 1024). Generates required number of inlets.
	    </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="set_coefs">
	    <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>
			<p><i>See also:</i><br/>
			Henderson, D. M. (1977), Euler Angles, Quaternions, and Transformation Matrices - Working Relationships, (NASA-TM-74839), download <a href='https://ntrs.nasa.gov/api/citations/19770024290/downloads/19770024290.pdf'>pdf</a> (last accessed 2020/12/13).</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 length" 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, audio signal 1]">
	    <description>
		Input ambipoints, control parameters and other messages. Also input first source audio signals.
	    </description>
	</entry>
	<entry name ="Inlet 2 ... n, source audio signals 2 - n [signal]">
	    <description>
		Input subsequent source audio signals.
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet 1 - n [audio signals]">
	    <description>
		Signal output carry the B-Format component signals.
	    </description>
	</entry>
    </misc>

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