<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="locsig">
  <refmeta>
    <refentrytitle>locsig</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>locsig</refname>
    <refpurpose>
      Takes and input signal and distributes between 2 or 4 channels.
      <indexterm id="IndexLocsig"><primary>locsig</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      <emphasis>locsig</emphasis> takes an input signal and distributes it among 2 or 4 channels using values in degrees to calculate the balance between adjacent channels. It also takes arguments for distance (used to attenuate signals that are to sound as if they are some distance further than the loudspeaker itself), and for the amount the signal that will be sent to reverberators. This unit is based upon the example in the Charles Dodge/Thomas Jerse book, <emphasis>Computer Music</emphasis>, page 320.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis>a1, a2 <command>locsig</command> asig, kdegree, kdistance, kreverbsend</synopsis>

    <synopsis>a1, a2,  a3, a4 <command>locsig</command> asig, kdegree, kdistance, kreverbsend</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kdegree</emphasis> -- value between 0 and 360 for placement of the signal in a 2 or 4 channel space configured as: a1=0, a2=90, a3=180, a4=270 (kdegree=45 would balanced the signal equally between a1 and a2). <emphasis>locsig</emphasis> maps <emphasis>kdegree</emphasis> to sin and cos functions to derive the signal balances (ie.: asig=1, kdegree=45, a1=a2=.707).
    </para>

    <para>
      <emphasis>kdistance</emphasis> -- value &gt;= 1 used to attenuate the signal and to calculate reverb level to simulate distance cues.  As <emphasis>kdistance</emphasis> gets larger the sound should get softer and somewhat more reverberant (assuming the use of <emphasis>locsend</emphasis> in this case).
    </para>

    <para>
      <emphasis>kreverbsend</emphasis> -- the percentage of the direct signal that will be factored along with the distance and degree values to derive signal amounts that can be sent to a reverb unit such as reverb, or reverb2.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Examples</title>
    <para>
      <informalexample>
        <programlisting>
  asig some audio signal
  kdegree            <emphasis>line</emphasis>    0, p3, 360
  kdistance          <emphasis>line</emphasis>    1, p3, 10
  a1, a2, a3, a4     <emphasis>locsig</emphasis>  asig, kdegree, kdistance, .1
  ar1, ar2, ar3, ar4 <emphasis>locsend</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 sent around a complete circle once during the duration of a note while at the same time it becomes more and more &quot;distant&quot; from the listeners' location. <emphasis>locsig</emphasis> sends the appropriate amount of the signal internally to <emphasis>locsend</emphasis>. The outputs of the <emphasis>locsend</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>locsig</emphasis> is 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.
    </para>

    <para>
      <informalexample>
        <programlisting>
<emphasis>instr</emphasis> 1
  a1, a2             <emphasis>locsig</emphasis>  asig, p4, p5, .1
  ar1, ar2           <emphasis>locsend</emphasis>
  ga1=ga1+ar1
  ga2=ga2+ar2
                     <emphasis>outs</emphasis> a1, a
<emphasis>endin
instr</emphasis> 99 
  ; reverb....
<emphasis>endin</emphasis>
        </programlisting>
      </informalexample>
    </para>

    <para>
      A few notes:
      <informalexample>
        <programlisting>
  ;place the sound in the left speaker and near:
  i1 0 1 0 1
  
  ;place the sound in the right speaker and far:
  i1 1 1 90 25
  
  ;place the sound equally between left and right and in the middle ground distance:
  i1 2 1 45 12
  e
        </programlisting>
      </informalexample>
    </para>

    <para>
      The next example shows a simple intuitive use of the distance value to simulate Doppler shift. The same value is used to scale the frequency as is used as the distance input to <emphasis>locsig</emphasis>.
      <informalexample>
        <programlisting>
  kdistance          <emphasis>line</emphasis>    1, p3, 10
  kfreq = (ifreq * 340) / (340 + kdistance)
  asig               <emphasis>oscili</emphasis>  iamp, kfreq, 1
  kdegree            <emphasis>line</emphasis>    0, p3, 360
  a1, a2, a3, a4     <emphasis>locsig</emphasis>  asig, kdegree, kdistance, .1
  ar1, ar2, ar3, ar4 <emphasis>locsend</emphasis>
        </programlisting>
      </informalexample>
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="locsend"><citetitle>locsend</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>
