<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="spdist">
  <refmeta>
    <refentrytitle>spdist</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>spdist</refname>
    <refpurpose>
      Calculates distance values from xy coordinates.
      <indexterm id="IndexSpdist"><primary>spdist</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      <emphasis>spdist</emphasis> uses the same xy data as <link linkend="space"><citetitle>space</citetitle></link>, also either from a text file using <link linkend="GEN28"><citetitle>Gen28</citetitle></link> or from x and y arguments given to the unit directly. The purpose of this unit is to make available the values for distance that are calculated from the xy coordinates. 
    </para>

    <para>
       In the case of <emphasis>space</emphasis>, the xy values are used to determine a distance which is used to attenuate the signal and prepare it for use in <link linkend="spsend"><citetitle>spsend</citetitle></link>. But it is also useful to have these values for distance available to scale the frequency of the signal before it is sent to the <emphasis>space</emphasis> unit.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>k1 <command>spdist</command> ifn, ktime, kx, ky</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Initialization</title>
    <para>
      <emphasis>ifn</emphasis> -- number of the stored function created using <link linkend="GEN28"><citetitle>Gen28</citetitle></link>. This function generator reads a text file which contains sets of three values representing the xy coordinates and a time-tag for when the signal should be placed at that location. The file should look like:
      <literallayout>
  0       -1       1
  1        1       1
  2        4       4
  2.1     -4      -4
  3       10      -10
  5       -40      0
      </literallayout>
    </para>

    <para>
      If that file were named &quot;move&quot; then the <emphasis>Gen28</emphasis> call in the score would like:
      <literallayout>
  f1 0 0 28 &quot;move&quot;
      </literallayout>
    </para>

    <para>
      <emphasis>Gen28</emphasis> takes 0 as the size and automatically allocates memory. It creates values to 10 milliseconds of resolution. So in this case there will be 500 values created by interpolating X1 to X2 to X3 and so on, and Y1 to Y2 to Y3 and so on, over the appropriate number of values that are stored in the function table. In the above example, the sound will begin in the left front, over 1 second it will move to the right front, over another second it move further into the distance but still in the left front, then in just 1/10th of a second it moves to the left rear, a bit distant. Finally over the last .9 seconds the sound will move to the right rear, moderately distant, and it comes to rest between the two left channels (due west!), quite distant. Since the values in the table are accessed through the use of a time-pointer in the <emphasis>space</emphasis> unit, the actual timing can be made to follow the file's timing exactly or it can be made to go faster or slower through the same trajectory. If you have access to the GUI that allows one to draw and edit the files, there is no need to create the text files manually. But as long as the file is ASCII and in the format shown above, it doesn't matter how it is made!
    </para>

    <para>
      IMPORTANT: If <emphasis>ifn</emphasis> is 0 then <emphasis>space</emphasis> will take its values for the xy coordinates from <emphasis>kx</emphasis> and <emphasis>ky</emphasis>.
    </para>

  </refsect1>

  <refsect1>
    <title>Performance</title>
    <para>
      The configuration of the xy coordinates in space places the signal in the following way:
      <itemizedlist>
        <listitem>
           <para>a1 is -1, 1</para>
        </listitem>

        <listitem>
           <para>a2 is 1, 1</para>
        </listitem>

        <listitem>
           <para>a3 is -1, -1</para>
        </listitem>

        <listitem>
           <para>a4 is 1, -1</para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      This assumes a loudspeaker set up as a1 is left front, a2 is right front, a3 is left back, a4 is right back. Values greater than 1 will result in sounds being attenuated, as if in the distance. <emphasis>space</emphasis> considers the speakers to be at a distance of 1; smaller values of xy can be used, but <emphasis>space</emphasis> will not amplify the signal in this case. It will, however balance the signal so that it can sound as if it were within the 4 speaker <emphasis>space</emphasis>.  x=0, y=1, will place the signal equally balanced between left and right front channels, x=y=0 will place the signal equally in all 4 channels, and so on. Although there must be 4 output signals from <emphasis>space</emphasis>, it can be used in a 2 channel orchestra. If the xy's are kept so that Y&gt;=1, it should work well to do panning and fixed localization in a stereo field.
    </para>

    <para>
      <emphasis>ktime</emphasis> -- index into the table containing the xy coordinates. If used like:
      <literallayout>
  ktime           <emphasis>line</emphasis>  0, 5, 5
  a1, a2, a3, a4  <emphasis>space</emphasis> asig, 1, ktime, ...
      </literallayout>
    </para>

    <para>
      with the file &quot;move&quot; described above, the speed of the signal's movement will be exactly as described in that file. However:
      <literallayout>
  ktime           <emphasis>line</emphasis>  0, 10, 5
      </literallayout>
    </para>

    <para>
      the signal will move at half the speed specified. Or in the case of:
      <literallayout>
  ktime           <emphasis>line</emphasis>  5, 15, 0
      </literallayout>
    </para>

    <para>
      the signal will move in the reverse direction as specified and 3 times slower! Finally:
      <literallayout>
  ktime           <emphasis>line</emphasis>  2, 10, 3
      </literallayout>
    </para>

    <para>
      will cause the signal to move only from the place specified in line 3 of the text file to the place specified in line 5 of the text file, and it will take 10 seconds to do it.
    </para>

    <para>
      <emphasis>kx, ky</emphasis> -- when <emphasis>ifn</emphasis> is 0, <emphasis>space</emphasis> and <emphasis>spdist</emphasis> will use these values as the XY coordinates to localize the signal. 
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
<emphasis>instr</emphasis> 1
  asig    ;some audio signal
  ktime              <emphasis>line</emphasis>  0, p3, p10
  a1, a2, a3, a4     <emphasis>space</emphasis> asig,1, ktime, .1
  ar1, ar2, ar3, ar4 <emphasis>spsend</emphasis>        
  
  ga1 = ga1+ar1
  ga2 = ga2+ar2
  ga3 = ga3+ar3
  ga4 = ga4+ar4
  
                     <emphasis>outq</emphasis> a1, a2, a3, a4
<emphasis>endin</emphasis>

<emphasis>instr</emphasis> 99 ; reverb instrument
          
  a1 <emphasis>reverb2</emphasis> ga1, 2.5, .5
  a2 <emphasis>reverb2</emphasis> ga2, 2.5, .5
  a3 <emphasis>reverb2</emphasis> ga3, 2.5, .5
  a4 <emphasis>reverb2</emphasis> ga4, 2.5, .5
  
     <emphasis>outq</emphasis> a1, a2, a3, a4
  ga1=0
  ga2=0
  ga3=0
  ga4=0
        </programlisting>
      </informalexample>
    </para>

    <para>
      In the above example, the signal, <emphasis>asig</emphasis>, is moved according to the data in Function #1 indexed by <emphasis>ktime</emphasis>. <emphasis>space</emphasis> sends the appropriate amount of the signal internally to <emphasis>spsend</emphasis>. The outputs of the <emphasis>spsend</emphasis> are added to global accumulators in a common Csound style and the global signals are used as inputs to the reverb units in a separate instrument.
    </para>

    <para>
      <emphasis>space</emphasis> can useful for quad and stereo panning as well as fixed placed of sounds anywhere between two loudspeakers. Below is an example of the fixed placement of sounds in a stereo field using xy values from the score instead of a function table.
      <informalexample>
        <programlisting>
<emphasis>instr</emphasis> 1
  ...
  a1, a2, a3, a4     <emphasis>space</emphasis> asig, 0, 0, .1, p4, p5
  ar1, ar2, ar3, ar4 <emphasis>spsend
  </emphasis>
  ga1=ga1+ar1
  ga2=ga2+ar2
                     <emphasis>outs</emphasis>  a1, a2
<emphasis>endin</emphasis>

<emphasis>instr</emphasis> 99 ; reverb....
  ....
<emphasis>endin</emphasis>
        </programlisting>
      </informalexample>
    </para>

    <para>
      A few notes: p4 and p5 are the X and Y values
      <informalexample>
        <programlisting>
  ;place the sound in the left speaker and near
    i1 0 1 -1 1
  ;place the sound in the right speaker and far
    i1 1 1 45 45
  ;place the sound equally between left and right and in the middle ground distance
    i1 2 1 0 12
e
        </programlisting>
      </informalexample>
    </para>

    <para>
      The next example shows a simple intuitive use of the distance values returned by <emphasis>spdist</emphasis> to simulate Doppler shift.
      <informalexample>
        <programlisting>
  ktime              <emphasis>line</emphasis>   0, p3, 10
  kdist              <emphasis>spdist</emphasis> 1, ktime
  kfreq = (ifreq * 340) / (340 + kdist)
  asig               <emphasis>oscili</emphasis> iamp, kfreq, 1
  
  a1, a2, a3, a4     <emphasis>space</emphasis>  asig, 1, ktime, .1
  ar1, ar2, ar3, ar4 <emphasis>spsend</emphasis>
        </programlisting>
      </informalexample>
    </para>

    <para>
      The same function and time values are used for both <emphasis>spdist</emphasis> and <emphasis>space</emphasis>. This insures that the distance values used internally in the <emphasis>space</emphasis> unit will be the same as those returned by <emphasis>spdist</emphasis> to give the impression of a Doppler shift!
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="space"><citetitle>space</citetitle></link>,
      <link linkend="spsend"><citetitle>spsend</citetitle></link>
    </para>
  </refsect1>

  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Richard Karpen</member>
        <member>Seattle, WA USA</member>
        <member>1998</member>
      </simplelist>
    </para>

    <para>New in Csound version 3.48</para>
  </refsect1>
</refentry>
