Skip to content

Commit

Permalink
starting manual for version 7
Browse files Browse the repository at this point in the history
  • Loading branch information
vlazzarini committed Mar 18, 2024
1 parent e8c7972 commit 5762ff5
Show file tree
Hide file tree
Showing 6 changed files with 81 additions and 147 deletions.
3 changes: 2 additions & 1 deletion manual.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1026,6 +1026,7 @@
<!ENTITY opcodesoutvalue SYSTEM "opcodes/outvalue.xml">
<!ENTITY opcodesoutx SYSTEM "opcodes/outx.xml">
<!ENTITY opcodesoutz SYSTEM "opcodes/outz.xml">
<!ENTITY opcodesoversample SYSTEM "opcodes/oversample.xml">
<!ENTITY opcodesp5gconnect SYSTEM "opcodes/p5gconnect.xml">
<!ENTITY opcodesp5gdata SYSTEM "opcodes/p5gdata.xml">
<!ENTITY opcodespan SYSTEM "opcodes/pan.xml">
Expand Down Expand Up @@ -1913,7 +1914,7 @@
<!ENTITY experimental SYSTEM "experimental/top.xml">
<!ENTITY deprecated SYSTEM "deprecated/top.xml">

<!ENTITY csoundversion "6.18.0">
<!ENTITY csoundversion "7.0">
]>

<book id="index" lang="en">
Expand Down
82 changes: 3 additions & 79 deletions opcodes/opcode.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
</para>

<para>
A user-defined opcode block must precede the instrument (or other opcode) from which it is used. But it is possible to call the opcode from itself. This allows recursion of any depth that is limited only by available memory. Additionally, there is an experimental feature that allows running the opcode definition at a higher control rate than the <link linkend="kr"><citetitle>kr</citetitle></link> value specified in the orchestra header.
A user-defined opcode block must precede the instrument (or other opcode) from which it is used. But it is possible to call the opcode from itself. This allows recursion of any depth that is limited only by available memory.
</para>

<para>
Expand Down Expand Up @@ -203,10 +203,6 @@
</informaltable>
</para>

<para>
The maximum allowed number of input arguments is 256.
</para>

<para>
<emphasis>outtypes</emphasis> -- list of output types. The format is the same as in the case of <emphasis>intypes</emphasis>.
</para>
Expand Down Expand Up @@ -275,72 +271,7 @@
The maximum allowed number of output arguments is 256.
</para>

<para>
<emphasis>iksmps</emphasis> (optional, default=0) -- sets the local
<emphasis>ksmps</emphasis> value. Must be a positive integer, and also
the <emphasis>ksmps</emphasis> of the
calling instrument or opcode must be an integer multiple of this value.
For example, if <emphasis>ksmps</emphasis> is 10 in the instrument from which
the opcode was called, the allowed values for <emphasis>iksmps</emphasis>
are 1, 2, 5, and 10.
</para>

<para>
If <emphasis>iksmps</emphasis> is set to zero, the
<emphasis>ksmps</emphasis> of the caller instrument or opcode is used
(this is the default behavior).
</para>

<note>
<title>Note</title>
<para>
The local <emphasis>ksmps</emphasis> is implemented by splitting up
a control period into smaller sub-kperiods and temporarily modifying
internal Csound global variables. This also requires converting the
rate of k-rate input and output arguments (input variables receive
the same value in all sub-kperiods, while outputs are written only
in the last one).
</para>
</note>

<warning>
<title>Warning about local <emphasis>ksmps</emphasis></title>
<para>
When the local <emphasis>ksmps</emphasis> is not the same as the
orchestra level <emphasis>ksmps</emphasis> value (as specified in the
orchestra header), global a-rate operations must not be used in the
user-defined opcode block.
</para>

<para>
These include:

<itemizedlist>
<listitem><para>any access to <quote>ga</quote> variables</para></listitem>
<listitem><para>a-rate zak opcodes (<link linkend="zar"><citetitle>zar</citetitle></link>, <link linkend="zaw"><citetitle>zaw</citetitle></link>, etc.)</para></listitem>
<listitem><para><link linkend="tablera"><citetitle>tablera</citetitle></link> and <link linkend="tablewa"><citetitle>tablewa</citetitle></link> (these two opcodes may in fact work, but caution is needed)</para></listitem>
<listitem><para>The <emphasis>in</emphasis> and <emphasis>out</emphasis> opcode family (these read from, and write to global a-rate buffers)</para></listitem>
</itemizedlist>
</para>

<para>
In general, the local <emphasis>ksmps</emphasis> should be used with
care as it is an experimental feature, although it works correctly in
most cases.
</para>
</warning>

<para>
The <link linkend="setksmps"><citetitle>setksmps</citetitle></link>
statement can be used to set the local <emphasis>ksmps</emphasis> value
of the user-defined opcode block. It has one i-time parameter specifying
the new <emphasis>ksmps</emphasis> value (which is left unchanged if zero
is used, see also the notes about <emphasis>iksmps</emphasis> above).
<emphasis>setksmps</emphasis> should be used before any other opcodes
(but allowed after <emphasis>xin</emphasis>), otherwise unpredictable
results may occur.
</para>


<para>
The input parameters can be read with <emphasis>xin</emphasis>, and the
output is written by <emphasis>xout</emphasis> opcode. Only one instance
Expand All @@ -350,13 +281,6 @@
as in the declaration of the user-defined opcode block (see tables above).
</para>

<para>
The input and output arguments must agree with the definition both in
number (except if the optional i-time input is used) and type.
An optional i-time input parameter (<emphasis>iksmps</emphasis>) is
automatically added to the <emphasis>intypes</emphasis> list, and
(similarly to setksmps) sets the local <emphasis>ksmps</emphasis> value.
</para>
</refsect1>

<refsect1>
Expand All @@ -377,7 +301,7 @@ xinarg1 [, xinarg2] [, xinarg3] ... [xinargN] <emphasis role="opc">xin</emphasi
The new opcode can then be used with the usual syntax:

<programlisting>
[xoutarg1] [, xoutarg2] ... [xoutargN] <command>name</command> [xinarg1] [, xinarg2] ... [xinargN] [, iksmps]</programlisting>
[xoutarg1] [, xoutarg2] ... [xoutargN] <command>name</command> [xinarg1] [, xinarg2] ... [xinargN]</programlisting>
</para>

<note>
Expand Down
69 changes: 69 additions & 0 deletions opcodes/oversample.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@

<refentry id="oversample">
<indexterm id="IndexOversample"><primary>oversample</primary></indexterm>
<refentryinfo><title>Signal I/O:Software Bus</title></refentryinfo>
<refmeta>
<refentrytitle>oversample</refentrytitle>
</refmeta>

<refnamediv>
<refname>oversample</refname>
<refpurpose>
Sets a local sampling rate based on an oversampling factor.
</refpurpose>
</refnamediv>

<refsect1>
<title>Description</title>
<para>
Sets the local ksmps value in an instrument or user-defined opcode block.
</para>
</refsect1>

<refsect1>
<title>Syntax</title>
<synopsis><command>oversample</command> ifactor[,imode] </synopsis>
</refsect1>

<refsect1>
<title>Initialization</title>
<para>
<emphasis>ifactor</emphasis> -- sets the oversampling factor. It
needs to be a positive integer > 1. A factor of 1 is a non-op,
zero or negative factors are illegal.
</para>
<para>
<emphasis>imode</emphasis> -- oversampling mode: if Secret
Rabbit Code is used, then 0 - best quality sync (default); 1 - medium
quality sync; 2 - fast sync; 3 - zero-order hold; and 4 - linear.
</para>
<para>
If <emphasis>iksmps</emphasis> is set to zero, the <emphasis>ksmps</emphasis> of the caller instrument or opcode is used (this is the default behavior).
</para>

<note>
<title>Note</title>
<para>
Oversampling is not allowed with local ksmps. The opcode can
only be used in UDOs. Audio or control rate array arguments
are not allowed. Global variables or bus channels should not be used.
</para>
</note>
</refsect1>

<refsect1>
<title>See Also</title>
<para>
<link linkend="endop"><citetitle>endop</citetitle></link>,
<link linkend="opcode"><citetitle>opcode</citetitle></link>,
<link linkend="xin"><citetitle>xin</citetitle></link>,
<link linkend="xout"><citetitle>xout</citetitle></link>
</para>
</refsect1>

<refsect1>
<title>Credits</title>
<para>Author: Victor Lazzarini</para>
<para>New in version 7.0</para>
</refsect1>
</refentry>
4 changes: 2 additions & 2 deletions opcodes/setksmps.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@
</warning>

<para>
The <emphasis>setksmps</emphasis> statement can be used to set the local <link linkend="ksmps"><citetitle>ksmps</citetitle></link> value of the instrument or user-defined opcode block. It has one i-time parameter specifying the new <emphasis>ksmps</emphasis> value (which is left unchanged if zero is used). <emphasis>setksmps</emphasis> should be used before any other opcodes (but allowed after <link linkend="xin"><citetitle>xin</citetitle></link> in UDOs), otherwise unpredictable results may occur.
The <emphasis>setksmps</emphasis> statement can be used to set the local <link linkend="ksmps"><citetitle>ksmps</citetitle></link> value of the instrument or user-defined opcode block. It has one i-time parameter specifying the new <emphasis>ksmps</emphasis> value. <emphasis>setksmps</emphasis> should be used before any other opcodes (but allowed after <link linkend="xin"><citetitle>xin</citetitle></link> in UDOs), otherwise unpredictable results may occur.
</para>
</refsect1>

Expand All @@ -88,7 +88,7 @@ xinarg1 [, xinarg2] [, xinarg3] ... [xinargN] <emphasis role="opc">xin</emphasi
The new opcode can then be used with the usual syntax:

<literallayout>
[xinarg1] [, xinarg2] ... [xinargN] name [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]
[xinarg1] [, xinarg2] ... [xinargN] name [xoutarg1] [, xoutarg2] ... [xoutargN]
</literallayout>
</para>
</refsect1>
Expand Down
1 change: 1 addition & 0 deletions opcodes/top.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -793,6 +793,7 @@
&opcodesoutvalue;
&opcodesoutx;
&opcodesoutz;
&opcodesoversample;
&opcodesp5gconnect;
&opcodesp5gdata;
&opcodesp;
Expand Down
69 changes: 4 additions & 65 deletions preface/whatsnew.xml
View file
Original file line number Diff line number Diff line change
@@ -1,70 +1,9 @@
<section id="PrefaceWhatsNew"><title>What's new in Csound &csoundversion;</title>
<!-- <bridgehead>Release Notes for Csound 6.XX ()</bridgehead>

<bridgehead>Release Notes for Csound 7.</bridgehead>
<para>
<itemizedlist>
<listitem>
<para>New opcodes:
<itemizedlist>
<listitem>
<simpara><link linkend=""><citetitle></citetitle></link></simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
New functionality
<itemizedlist>
<listitem>
<simpara>
</simpara>
</listitem>
<listitem>
<simpara>
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Bug fixes and improvements:
<itemizedlist>
<listitem>
<simpara>
</simpara>
</listitem>
<listitem>
<simpara>
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Internal Changes:
<itemizedlist>
<listitem>
<simpara>
</simpara>
</listitem>
<listitem>
<simpara>
</simpara>
</listitem>
<listitem>
<simpara>
</simpara>
</listitem>
<listitem>
<simpara>
</simpara>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>-->
Major new version.
</para>

<bridgehead>Release Notes for Csound 6.18 (2022 October)</bridgehead>
<para>
Expand Down

0 comments on commit 5762ff5

Please sign in to comment.