<!-- Converted to DocBook/SGML by Kevin Conder -->
<refentry id="tablemix">
  <refmeta>
    <refentrytitle>tablemix</refentrytitle>
  </refmeta>
 
  <refnamediv>
    <refname>tablemix</refname>
    <refpurpose>
      Mixes two tables.
      <indexterm id="IndexTablemix"><primary>tablemix</primary></indexterm>
    </refpurpose>
  </refnamediv>
 
  <refsect1>
    <title>Description</title>
    <para>
      Mixes two tables.
    </para>
  </refsect1>
 
  <refsect1>
    <title>Syntax</title>
    <synopsis><command>tablemix</command> kdft, kdoff, klen, ks1ft, ks1off, ks1g, ks2ft, ks2off, ks2g</synopsis>
  </refsect1>
 
  <refsect1>
    <title>Performance</title>
    <para>
      <emphasis>kdft</emphasis> -- Destination function table.
    </para>

    <para>
      <emphasis>kdoff</emphasis> -- Offset to start writing from. Can be negative.
    </para>

    <para>
      <emphasis>klen</emphasis> -- Number of write operations to perform. Negative means work backwards.
    </para>

    <para>
      <emphasis>ks1ft</emphasis>, <emphasis>ks2ft</emphasis> -- Source function tables. These can be the same as the destination table, if care is exercised about direction of copying data.
    </para>

    <para>
      <emphasis>ks1off</emphasis>, <emphasis>ks2off</emphasis> -- Offsets to start reading from in source tables.
    </para>

    <para>
      <emphasis>ks1g</emphasis>, <emphasis>ks2g</emphasis> -- Gains to apply when reading from the source tables. The results are added and the sum is written to the destination table.
    </para>

    <para>
      <emphasis>tablemix</emphasis> -- This opcode mixes from two tables, with separate gains into the destination table. Writing is done for <emphasis>klen</emphasis> locations, usually stepping forward through the table - if <emphasis>klen</emphasis> is positive. If it is negative, then the writing and reading order is backwards - towards lower indexes in the tables. This bi-directional option makes it easy to shift the contents of a table sideways by reading from it and writing back to it with a different offset.
    </para>

    <para>
      If <emphasis>klen</emphasis> is 0, no writing occurs. Note that the internal integer value of <emphasis>klen</emphasis> is derived from the ANSI C floor() function - which returns the next most negative integer. Hence a fractional negative <emphasis>klen</emphasis> value of -2.3 would create an internal length of 3, and cause the copying to start from the offset locations and proceed for two locations to the left.
    </para>

    <para>
      The total index for table reading and writing is calculated from the starting offset for each table, plus the index value, which starts at 0 and then increments (or decrements) by 1 as mixing proceeds.
    </para>

    <para>
      These total indexes can potentially be very large, since there is no restriction on the offset or the <emphasis>klen</emphasis>. However each total index for each table is ANDed with a length mask (such as 0000 0111 for a table of length 8) to form a final index which is actually used for reading or writing. So no reading or writing can occur outside the tables. This is the same as <quote>wrap</quote> mode in table read and write. These opcodes do not read or write the guardpoint. If a table has been rewritten with one of these, then if it has a guardpoint which is supposed to contain the same value as the location 0, then call <link linkend="tablegpw"><citetitle>tablegpw</citetitle></link> afterwards.
    </para>

    <para>
      The indexes and offsets are all in table steps - they are not normalized to 0 - 1. So for a table of length 256, <emphasis>klen</emphasis> should be set to 256 if all the table was to be read or written.
    </para>

    <para>
      The tables do not need to be the same length - wrapping occurs individually for each table.
    </para>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <link linkend="tablecopy"><citetitle>tablecopy</citetitle></link>,
      <link linkend="tablegpw"><citetitle>tablegpw</citetitle></link>,
      <link linkend="tableicopy"><citetitle>tableicopy</citetitle></link>,
      <link linkend="tableigpw"><citetitle>tableigpw</citetitle></link>,
      <link linkend="tableimix"><citetitle>tableimix</citetitle></link>
    </para>
  </refsect1>
 
  <refsect1>
    <title>Credits</title>
    <para>
      <simplelist>
        <member>Author: Robin Whittle</member>
        <member>Australia</member>
        <member>May 1997</member>
      </simplelist>
    </para>
  </refsect1>
</refentry>
