<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="spat3dt">
  <refmeta>
    <refentrytitle>spat3dt</refentrytitle>
  </refmeta>

  <refnamediv>
    <refname>spat3dt</refname>
    <refpurpose>
      Can be used to render an impulse response for a 3D space at i-time.
      <indexterm id="IndexSpat3dt"><primary>spat3dt</primary></indexterm>
    </refpurpose>
  </refnamediv>
  
  <refsect1>
    <title>Description</title>
    <para>
      This opcode positions the input sound in a 3D space, with optional simulation of room acoustics, in various output formats. <emphasis>spat3dt</emphasis> can be used to render the impulse response at i-time, storing output in a function table, suitable for convolution.
    </para>
  </refsect1>

  <refsect1>
    <title>Syntax</title>
    <synopsis><command>spat3dt</command> ioutft, iX, iY, iZ, idist, ift, imode, irlen [, iftnocl]</synopsis>
  </refsect1>

  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ioutft</emphasis> -- Output ftable number for spat3dt. W, X, Y, and Z outputs are written interleaved to this table. If the table is too short, output will be truncated.
    </para>

    <para>
      <emphasis>iX</emphasis> -- Sound source X coordinate in meters (positive: right, negative: left)
    </para>

    <para>
      <emphasis>iY</emphasis> -- Sound source Y coordinate in meters (positive: front, negative: back)
    </para>

    <para>
      <emphasis>iZ</emphasis> -- Sound source Z coordinate in meters (positive: up, negative: down)
    </para>

    <para>
      <emphasis>idist</emphasis> -- For modes 0 to 3, <emphasis>idist</emphasis> is the unit circle distance in meters. For mode 4, <emphasis>idist</emphasis> is the distance between microphones. 
    </para>

    <para>
      The following formulas describe amplitude and delay as a function of sound source distance from microphone(s):
      <literallayout>
amplitude = 1 / (0.1 + distance)
      </literallayout>

      <literallayout>
delay = distance / 340 (in seconds)
      </literallayout>
    </para>

    <para>
      Distance can be calculated as:

      <literallayout>
distance = sqrt(iX&circ;2 + iY&circ;2 + iZ&circ;2)
      </literallayout>

      In Mode 4, distance can be calculated as:

      <literallayout>
distance from left mic = sqrt((iX + idist/2)&circ;2 + iY&circ;2 + iZ&circ;2)
distance from right mic = sqrt((iX - idist/2)&circ;2 + iY&circ;2 + iZ&circ;2)
      </literallayout>
    </para>

    <para>
      With <emphasis>spat3d</emphasis> the distance between the sound source and any microphone should be at least (340 * 18) / sr meters. Shorter distances will work, but may produce artifacts in some cases.  There is no such limitation for <emphasis>spat3di</emphasis> and <emphasis>spat3dt</emphasis>.
    </para>

    <para>
      Sudden changes or discontinuities in sound source location can result in pops or clicks. Very fast movement may also degrade quality.
    </para>

    <para>
      <emphasis>ift</emphasis> -- Function table storing room parameters (for free field spatialization, set it to zero or negative). Table size is 64. The values in the table are:

      <informaltable frame="all">
        <tgroup cols="2" colsep="1" rowsep="1">
          <thead>
            <row>
              <entry>Room Parameter</entry>
              <entry>Purpose</entry>
            </row>
          </thead>

         <tbody>
            <row>
              <entry>0</entry>
              <entry>Early reflection recursion depth (0 is the sound source, 1 is the first reflection etc.) for spat3d and spat3di. The number of echoes for four walls (front, back, right, left) is: N = (2*R + 2) * R. If all six walls are enabled: N = (((4*R + 6)*R + 8)*R) / 3</entry>
            </row>

            <row>
              <entry>1</entry>
              <entry>Late reflection recursion depth (used by spat3dt only). spat3dt skips early reflections and renders echoes up to this level. If early reflection depth is negative, spat3d and spat3di will output zero, while spat3dt will start rendering from the sound source.</entry>
            </row>

            <row>
              <entry>2</entry>
              <entry>imdel for spat3d. Overrides opcode parameter if non-negative.</entry>
            </row>

            <row>
              <entry>3</entry>
              <entry>irlen for spat3dt. Overrides opcode parameter if non-negative.</entry>
            </row>

            <row>
              <entry>4</entry>
              <entry>idist value. Overrides opcode parameter if >= 0.</entry>
            </row>

            <row>
              <entry>5</entry>
              <entry>Random seed (0 - 65535) -1 seeds from current time.</entry>
            </row>

            <row>
              <entry>6 - 53</entry>
              <entry>wall parameters (w = 6: ceil, w = 14: floor, w = 22: front, w = 30: back, w = 38: right, w = 46: left)</entry>
            </row>

            <row>
              <entry>w + 0</entry>
              <entry>Enable reflections from this wall (0: no, 1: yes)</entry>
            </row>

            <row>
              <entry>w + 1</entry>
              <entry>Wall distance from listener (in meters)</entry>
            </row>

            <row>
              <entry>w + 2</entry>
              <entry>Randomization of wall distance (0 - 1) (in units of 1 / (wall distance))</entry>
            </row>

            <row>
              <entry>w + 3</entry>
              <entry>Reflection level (-1 - 1)</entry>
            </row>

            <row>
              <entry>w + 4</entry>
              <entry>Parametric equalizer frequency in Hz.</entry>
            </row>

            <row>
              <entry>w + 5</entry>
              <entry>Parametric equalizer level (1.0: no filtering)</entry>
            </row>

            <row>
              <entry>w + 6</entry>
              <entry>Parametric equalizer Q (0.7071: no resonance)</entry>
            </row>

            <row>
              <entry>w + 7</entry>
              <entry>Parametric equalizer mode (0: peak EQ, 1: low shelf, 2: high shelf)</entry>
            </row>
         </tbody>
        </tgroup>
      </informaltable>
    </para>

    <para>
      <emphasis>imode</emphasis> -- Output mode
      <itemizedlist>
        <listitem><para>0: B format with W output only (mono)
<literallayout>
aout    =  aW
</literallayout>
        </para></listitem>

        <listitem><para>1: B format with W and Y output (stereo)
<literallayout>
aleft   =  aW + 0.7071*aY
aright  =  aW - 0.7071*aY
</literallayout>
        </para></listitem>

        <listitem><para>2: B format with W, X, and Y output (2D). This can be converted to UHJ:
<literallayout>
aWre, aWim      hilbert aW
aXre, aXim      hilbert aX
aYre, aYim      hilbert aY
aWXr    =  0.0928*aXre + 0.4699*aWre
aWXiYr  =  0.2550*aXim - 0.1710*aWim + 0.3277*aYre
aleft   =  aWXr + aWXiYr
aright  =  aWXr - aWXiYr
</literallayout>
        </para></listitem>

        <listitem><para>3: B format with all outputs (3D)</para></listitem>

        <listitem><para>4: Simulates a pair of microphones (stereo output)
<literallayout>
aW      butterlp aW, ifreq      ; recommended values for ifreq
aY      butterlp aY, ifreq      ; are around 1000 Hz
aleft   =  aW + aX
aright  =  aY + aZ
</literallayout>
        </para></listitem>
      </itemizedlist>
    </para>

    <para>
      Mode 0 is the cheapest to calculate, while mode 4 is the most expensive.
    </para>

    <para>
      In Mode 4, The optional lowpass filters can change the frequency response depending on direction. For example, if the sound source is located left to the listener then the high frequencies are attenuated in the right channel and slightly increased in the left. This effect can be disabled by not using filters. You can also experiment with other filters (tone etc.) for better effect.
    </para>

    <para>
      Note that mode 4 is most useful for listening with headphones, and is also more expensive to calculate than the B-format (0 to 3) modes. The <emphasis>idist</emphasis> parameter in this case sets the distance between left and right microphone; for headphones, values between 0.2 - 0.25 are recommended, although higher settings up to 0.4 may be used for wide stereo effects.
    </para>

    <para>
      More information about B format can be found here: <ulink url="http://www.york.ac.uk/inst/mustech/3d_audio/ambis2.htm"><citetitle>http://www.york.ac.uk/inst/mustech/3d_audio/ambis2.htm</citetitle></ulink>
    </para>

    <para>
      <emphasis>irlen</emphasis> -- Impulse response length of echoes (in seconds). Depending on filter parameters, values around 0.005-0.01 are suitable for most uses (higher values result in more accurate output, but slower rendering)
    </para>

    <para>
      <emphasis>iftnocl</emphasis> (optional, default=0) -- Do not clear output ftable (mix to existing data) if set to 1, clear table before writing if set to 0 (default: 0).
    </para>
  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      If you encounter very slow performance (up to 100 times slower), it may be caused by denormals (this is also true of many other IIR opcodes, including <link linkend="butterlp"><citetitle>butterlp</citetitle></link>, <link linkend="pareq"><citetitle>pareq</citetitle></link>, <link linkend="hilbert"><citetitle>hilbert</citetitle></link>, and many others). Underflows can be avoided by:
      <itemizedlist>
        <listitem><para>mixing low level DC or noise to the input signal, e.g. <literallayout>atmp rnd31 1/1e24, 0, 0</literallayout> <literallayout>aW, aX, aY, aZ spa3di ain + atmp, ...</literallayout> or <literallayout>aW, aX, aY, aZ spa3di ain + 1/1e24, ...</literallayout></para></listitem>
        <listitem><para>reducing <emphasis>irlen</emphasis> in the case of <emphasis>spat3dt</emphasis> (which does not have an input signal). A value of about 0.005 is suitable for most uses, although it also depends on EQ settings. If the equalizer is not used, <quote>irlen</quote> can be set to 0.</para></listitem>
      </itemizedlist>
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      See the examples for <link linkend="spat3d"><citetitle>spat3d</citetitle></link>.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="spat3d"><citetitle>spat3d</citetitle></link>,
      <link linkend="spat3di"><citetitle>spat3di</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: &nameistvan;</member>
        <member>2001</member>
      </simplelist>
    </para>

    <para>New in version 4.12</para>
    <para>Updated April 2002 by &nameistvan;</para>
  </refsect1>
</refentry>
