Imported Upstream version 5.12~dfsg

8 files changed, 188 insertions, 7 deletions

diff --git a/scoregens/f.xml b/scoregens/f.xml
index 4daa81a..162ed93 100644
--- a/scoregens/f.xml
+++ b/scoregens/f.xml
@@ -61,8 +61,11 @@
       <note><para>Not all opcodes accept tables whose size is not a power of two, since they may depend on this for internal optimization.</para>
       </note>
       <para>For arrays whose length is a power of 2, space allocation always provides for 2<superscript>n</superscript> points plus an additional <emphasis>guard point</emphasis>. The guard point value, used during interpolated lookup, can be automatically set to reflect the table's purpose: If <emphasis>size</emphasis> is an exact power of 2, the guard point will be a copy of the first point; this is appropriate for <emphasis>interpolated wrap-around lookup</emphasis> as in <emphasis>oscili</emphasis>, etc., and should even be used for non-interpolating <emphasis>oscil</emphasis> for safe consistency. If <emphasis>size</emphasis> is set to 2 <superscript>n</superscript> + 1, the guard point value automatically extends the contour of table values; this is appropriate for single-scan functions such in <emphasis>envplx</emphasis>, <emphasis>oscil1</emphasis>, <emphasis>oscil1i</emphasis>, etc.
+      
+      </para>
+      <para>
+	The size of the table is used as a code to tell Csound how to fill this guard-point. If the size is exactly power-of-two, then the guard point contains a copy of the first point on the table. If the size is power-of-two plus one, Csound will extend the contour of the function stored in the table for one extra point.
       </para>
-
       <para>
         Table space is allocated in primary memory, along with instrument data space. The maximum table number used to be 200. This has been changed to be limited by memory only. (Currently there is an internal soft limit of 300, this is automatically extended as required.)
       </para>
diff --git a/scoregens/gen23.xml b/scoregens/gen23.xml
index deef8ad..44dedc5 100644
--- a/scoregens/gen23.xml
+++ b/scoregens/gen23.xml
@@ -37,7 +37,7 @@
     <note>
       <title>Note</title>
       <para>
-        All characters following ';' (comment) are ignored until next line (numbers too).
+        All characters following ';' or '#' (comment) are ignored until next line (numbers too).
       </para>
     </note>
   </refsect1>
@@ -52,6 +52,7 @@
       </simplelist>
     </para>
 
-    <para>New in Csound version 3.47</para>
+    <para>New in Csound version 3.47. Comments starting with '#' are
+    ignored from Csound version 5.12.</para>
   </refsect1>
 </refentry>
diff --git a/scoregens/gen42.xml b/scoregens/gen42.xml
index 070cec8..87d546e 100644
--- a/scoregens/gen42.xml
+++ b/scoregens/gen42.xml
@@ -11,7 +11,7 @@
       Generates a random distribution of discrete ranges of values.
     </refpurpose>
   </refnamediv>
-  
+
   <refsect1>
     <title>Description</title>
     <para>
@@ -27,7 +27,7 @@
   <refsect1>
     <title>Performance</title>
     <para>
-      The first number of each group is a the minimum value of the range, the second is the maximum value and the third is the probability of that an element belonging to that range of values can be chosen by a random algorithm. Even if any number can be assigned to the probability element of each group, it is suggested to give it a percent value, in order to make it clearer to the user.
+      The first number of each group is a the minimum value of the range, the second is the maximum value and the third is the probability of that an element belonging to that range of values can be chosen by a random algorithm. Probabilities for a range should be a fraction of 1, and the sum of the probabilities for all the ranges should total 1.0.
     </para>
 
     <para>
diff --git a/scoregens/gen43.xml b/scoregens/gen43.xml
index 283ca8d..ae988b7 100644
--- a/scoregens/gen43.xml
+++ b/scoregens/gen43.xml
@@ -79,6 +79,6 @@ pvstencil, it is easiest to skip table normalisation (negative GEN code).
 
   <refsect1>
     <title>Credits</title>
-    <para>Author: Victor Lazzarini</para>
+    <para>Author: &namevictor;</para>
   </refsect1>
 </refentry>
diff --git a/scoregens/gen49.xml b/scoregens/gen49.xml
new file mode 100644
index 0000000..c20bd8f
--- /dev/null
+++ b/scoregens/gen49.xml
@@ -0,0 +1,111 @@
+
+<refentry id="GEN49">
+      <indexterm id="IndexGEN49"><primary>GEN49</primary></indexterm>
+  <refmeta>
+    <refentrytitle>GEN49</refentrytitle>
+  </refmeta>
+ 
+  <refnamediv>
+    <refname>GEN49</refname>
+    <refpurpose>
+      Transfers data from an MP3 soundfile into a function table.
+    </refpurpose>
+  </refnamediv>
+ 
+  <refsect1>
+    <title>Description</title>
+    <para>
+      This subroutine transfers data from an MP3 soundfile into a function table.
+    </para>
+  </refsect1>
+ 
+  <refsect1>
+    <title>Syntax</title>
+    <synopsis><command>f</command>#  time  size  49  filcod  skiptime  format</synopsis>
+  </refsect1>
+ 
+  <refsect1>
+    <title>Performance</title>
+    <para>
+      <emphasis>size</emphasis> -- number of points in the
+      table. Ordinarily a power of 2 or a power-of-2 plus 1
+      (see <link linkend="f"><citetitle>f
+      statement</citetitle></link>); the maximum tablesize is 16777216
+      (2<superscript>24</superscript>) points. The allocation of table
+      memory can be <emphasis>deferred</emphasis> by setting this
+      parameter to 0; the size allocated is then the number of points
+      in the file (probably not a power-of-2), and the table is not
+      usable by normal oscillators, but it is usable by
+      a <link linkend="loscil"><citetitle>loscil</citetitle></link>
+      unit. The soundfile can also be mono or stereo. 
+    </para>
+
+    <para>
+      <emphasis>filcod</emphasis> -- integer or character-string
+      denoting the source soundfile name. An integer denotes the
+      file <emphasis>soundin</emphasis>.<emphasis>filcod</emphasis> ;
+      a character-string (in double quotes, spaces permitted) gives
+      the filename itself, optionally a full pathname. If not a full
+      path, the file is sought first in the current directory, then in
+      that given by the environment variable SSDIR (if defined) then
+      by SFDIR. See
+      also <link linkend="soundin"><citetitle>soundin</citetitle></link>.
+    </para>
+
+    <para>
+      <emphasis>skiptime</emphasis> -- begin reading at <emphasis>skiptime</emphasis> seconds into the file.
+    </para>
+
+    <para>
+      <emphasis>format</emphasis> -- specifies the audio data-file format required:
+        <literallayout>
+1 - Mono file                 3 - First channel (left)
+2 - Stereo file               4 - Second channel (right)
+        </literallayout>
+    </para>
+
+    <para>
+      If <emphasis>format</emphasis> = 0 the sample format is taken from the soundfile header.
+    </para>
+
+    <note>
+      <title>Note</title>
+      <para>
+        <itemizedlist>
+          <listitem>
+            <para>
+              Reading stops at end-of-file or when the table is full. Table locations not filled will contain zeros.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              If p4 is positive, the table will be post-normalized (rescaled to a maximum absolute value of 1 after generation). A negative p4 will cause rescaling to be skipped.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </note>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+    <para>
+	    Here is a simple example of the GEN49 routine. It uses the files <ulink url="examples/gen49.csd"><citetitle>gen49.csd</citetitle></ulink>, and <ulink url="examples/beats.mp3"><citetitle>beats.mp3</citetitle></ulink>. It uses the MP3 file <quote>beats.mp3</quote>.
+
+      <example>
+        <title>A simple example of the GEN49 routine.</title>
+
+        <xi:include href="examples-xml/gen49.csd.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+      </example>
+    </para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Credits</title>
+    <para>Written by &namejohn;</para>
+    <para>February 2009.</para>
+  </refsect1>
+</refentry>
diff --git a/scoregens/i.xml b/scoregens/i.xml
index 6e512c9..e8d7a0a 100644
--- a/scoregens/i.xml
+++ b/scoregens/i.xml
@@ -113,7 +113,36 @@
     <para>
       Beginning with Csound version 3.53, strings are recognized in  p-fields for opcodes that accept them (<emphasis>convolve, adsyn, diskin,</emphasis> etc.).  There may be only one string per score line.
     </para>
+    <para>
+      You can also turnoff notes from the score by using a negative
+      number for the instrument (p1). This is equivalent to using
+      the <link linkend="turnoff2"><citetitle>turnoff2</citetitle></link>
+      opcode. When a note is turned off from the score, it is allowed
+      to release
+      (if <link linkend="xtratim"><citetitle>xtratim</citetitle></link>
+      or opcodes with release section
+      like <link linkend="linenr"><citetitle>linenr</citetitle></link>
+      are used) and only notes with the same fractional part are
+      turned off. Also, only the last instance of the instrument will
+      be turned off, so there have to be as many negative instrument
+      numbers as positive ones for all notes to be turned off.
 
+      <informalexample>
+        <programlisting>
+<emphasis role="stamnt">i</emphasis> 1.1    1    300    8.00
+<emphasis role="stamnt">i</emphasis> 1.2    1    300    8.04
+<emphasis role="stamnt">i</emphasis> 1.3    1    -300    8.07
+<emphasis role="stamnt">i</emphasis> 1.3    1    -300    8.09
+
+<emphasis role="comment">; notice that p-fields after p2 will be ignored if </emphasis>
+<emphasis role="comment">; instrument number is negative</emphasis>
+<emphasis role="stamnt">i</emphasis> -1.1    3    1    4.00
+<emphasis role="stamnt">i</emphasis> -1.2    4    51    4.04
+<emphasis role="stamnt">i</emphasis> -1.3    5    1    4.07
+<emphasis role="stamnt">i</emphasis> -1.3    6    10    4.09
+	</programlisting>
+      </informalexample>
+    </para>
     <refsect2>
       <title>Special Considerations</title>
 
diff --git a/scoregens/n.xml b/scoregens/n.xml
index f9cd79b..ba74615 100644
--- a/scoregens/n.xml
+++ b/scoregens/n.xml
@@ -36,6 +36,38 @@
     <para>
       This can be helpful in setting a up verse and chorus structure in the score. Names may contain letters and numerals.
     </para>
+    <para>
+      For example, the following score:
+    </para>
+    <programlisting>
+m foo
+i1 0 1
+i1 1 1.5
+i1 2.5 2
+s
+i1 0 10
+s
+n foo
+e
+    </programlisting>
+    <para>
+      Will be passed from the preprocessor to Csound as:
+    </para>
+    <programlisting>
+i1 0 1
+i1 1 1.5
+i1 2.5 2
+s
+i1 0 10
+s
+;; this is named section repeated
+i1 0 1
+i1 1 1.5
+i1 2.5 2
+s
+;; end of named section
+e
+    </programlisting>
   </refsect1>
  
   <refsect1>
diff --git a/scoregens/top.xml b/scoregens/top.xml
index 518d58e..c2b9fd6 100644
--- a/scoregens/top.xml
+++ b/scoregens/top.xml
@@ -143,7 +143,11 @@
       <listitem>
       <simpara><link linkend="GEN28"><citetitle>GEN28</citetitle></link> -  Reads a text file which contains a time-tagged trajectory.</simpara>
       </listitem>
-    </itemizedlist>
+      <listitem>
+      <simpara><link linkend="GEN49"><citetitle>GEN49</citetitle></link>
+      -  Transfers data from an MP3 soundfile into a function table.</simpara>
+      </listitem>
+     </itemizedlist>
 
     <bridgehead>
       Numeric Value Access GEN Routines
@@ -297,6 +301,7 @@
     &scoregensgen41;
     &scoregensgen42;
     &scoregensgen43;
+    &scoregensgen49;
     &scoregensgen51;
     &scoregensgen52;