Skip to content

Commit 5762ff5

Browse files
author
vlazzarini
committed
starting manual for version 7
1 parent e8c7972 commit 5762ff5

File tree

6 files changed

+81
-147
lines changed

6 files changed

+81
-147
lines changed

‎manual.xml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1026,6 +1026,7 @@
10261026
<!ENTITY opcodesoutvalue SYSTEM "opcodes/outvalue.xml">
10271027
<!ENTITY opcodesoutx SYSTEM "opcodes/outx.xml">
10281028
<!ENTITY opcodesoutz SYSTEM "opcodes/outz.xml">
1029+
<!ENTITY opcodesoversample SYSTEM "opcodes/oversample.xml">
10291030
<!ENTITY opcodesp5gconnect SYSTEM "opcodes/p5gconnect.xml">
10301031
<!ENTITY opcodesp5gdata SYSTEM "opcodes/p5gdata.xml">
10311032
<!ENTITY opcodespan SYSTEM "opcodes/pan.xml">
@@ -1913,7 +1914,7 @@
19131914
<!ENTITY experimental SYSTEM "experimental/top.xml">
19141915
<!ENTITY deprecated SYSTEM "deprecated/top.xml">
19151916

1916-
<!ENTITY csoundversion "6.18.0">
1917+
<!ENTITY csoundversion "7.0">
19171918
]>
19181919

19191920
<book id="index" lang="en">

‎opcodes/opcode.xml

Lines changed: 3 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
</para>
1919

2020
<para>
21-
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.
21+
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.
2222
</para>
2323

2424
<para>
@@ -203,10 +203,6 @@
203203
</informaltable>
204204
</para>
205205

206-
<para>
207-
The maximum allowed number of input arguments is 256.
208-
</para>
209-
210206
<para>
211207
<emphasis>outtypes</emphasis> -- list of output types. The format is the same as in the case of <emphasis>intypes</emphasis>.
212208
</para>
@@ -275,72 +271,7 @@
275271
The maximum allowed number of output arguments is 256.
276272
</para>
277273

278-
<para>
279-
<emphasis>iksmps</emphasis> (optional, default=0) -- sets the local
280-
<emphasis>ksmps</emphasis> value. Must be a positive integer, and also
281-
the <emphasis>ksmps</emphasis> of the
282-
calling instrument or opcode must be an integer multiple of this value.
283-
For example, if <emphasis>ksmps</emphasis> is 10 in the instrument from which
284-
the opcode was called, the allowed values for <emphasis>iksmps</emphasis>
285-
are 1, 2, 5, and 10.
286-
</para>
287-
288-
<para>
289-
If <emphasis>iksmps</emphasis> is set to zero, the
290-
<emphasis>ksmps</emphasis> of the caller instrument or opcode is used
291-
(this is the default behavior).
292-
</para>
293-
294-
<note>
295-
<title>Note</title>
296-
<para>
297-
The local <emphasis>ksmps</emphasis> is implemented by splitting up
298-
a control period into smaller sub-kperiods and temporarily modifying
299-
internal Csound global variables. This also requires converting the
300-
rate of k-rate input and output arguments (input variables receive
301-
the same value in all sub-kperiods, while outputs are written only
302-
in the last one).
303-
</para>
304-
</note>
305-
306-
<warning>
307-
<title>Warning about local <emphasis>ksmps</emphasis></title>
308-
<para>
309-
When the local <emphasis>ksmps</emphasis> is not the same as the
310-
orchestra level <emphasis>ksmps</emphasis> value (as specified in the
311-
orchestra header), global a-rate operations must not be used in the
312-
user-defined opcode block.
313-
</para>
314-
315-
<para>
316-
These include:
317-
318-
<itemizedlist>
319-
<listitem><para>any access to <quote>ga</quote> variables</para></listitem>
320-
<listitem><para>a-rate zak opcodes (<link linkend="zar"><citetitle>zar</citetitle></link>, <link linkend="zaw"><citetitle>zaw</citetitle></link>, etc.)</para></listitem>
321-
<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>
322-
<listitem><para>The <emphasis>in</emphasis> and <emphasis>out</emphasis> opcode family (these read from, and write to global a-rate buffers)</para></listitem>
323-
</itemizedlist>
324-
</para>
325-
326-
<para>
327-
In general, the local <emphasis>ksmps</emphasis> should be used with
328-
care as it is an experimental feature, although it works correctly in
329-
most cases.
330-
</para>
331-
</warning>
332-
333-
<para>
334-
The <link linkend="setksmps"><citetitle>setksmps</citetitle></link>
335-
statement can be used to set the local <emphasis>ksmps</emphasis> value
336-
of the user-defined opcode block. It has one i-time parameter specifying
337-
the new <emphasis>ksmps</emphasis> value (which is left unchanged if zero
338-
is used, see also the notes about <emphasis>iksmps</emphasis> above).
339-
<emphasis>setksmps</emphasis> should be used before any other opcodes
340-
(but allowed after <emphasis>xin</emphasis>), otherwise unpredictable
341-
results may occur.
342-
</para>
343-
274+
344275
<para>
345276
The input parameters can be read with <emphasis>xin</emphasis>, and the
346277
output is written by <emphasis>xout</emphasis> opcode. Only one instance
@@ -350,13 +281,6 @@
350281
as in the declaration of the user-defined opcode block (see tables above).
351282
</para>
352283

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

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

379303
<programlisting>
380-
[xoutarg1] [, xoutarg2] ... [xoutargN] <command>name</command> [xinarg1] [, xinarg2] ... [xinargN] [, iksmps]</programlisting>
304+
[xoutarg1] [, xoutarg2] ... [xoutargN] <command>name</command> [xinarg1] [, xinarg2] ... [xinargN]</programlisting>
381305
</para>
382306

383307
<note>

‎opcodes/oversample.xml

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
2+
<refentry id="oversample">
3+
<indexterm id="IndexOversample"><primary>oversample</primary></indexterm>
4+
<refentryinfo><title>Signal I/O:Software Bus</title></refentryinfo>
5+
<refmeta>
6+
<refentrytitle>oversample</refentrytitle>
7+
</refmeta>
8+
9+
<refnamediv>
10+
<refname>oversample</refname>
11+
<refpurpose>
12+
Sets a local sampling rate based on an oversampling factor.
13+
</refpurpose>
14+
</refnamediv>
15+
16+
<refsect1>
17+
<title>Description</title>
18+
<para>
19+
Sets the local ksmps value in an instrument or user-defined opcode block.
20+
</para>
21+
</refsect1>
22+
23+
<refsect1>
24+
<title>Syntax</title>
25+
<synopsis><command>oversample</command> ifactor[,imode] </synopsis>
26+
</refsect1>
27+
28+
<refsect1>
29+
<title>Initialization</title>
30+
<para>
31+
<emphasis>ifactor</emphasis> -- sets the oversampling factor. It
32+
needs to be a positive integer > 1. A factor of 1 is a non-op,
33+
zero or negative factors are illegal.
34+
</para>
35+
<para>
36+
<emphasis>imode</emphasis> -- oversampling mode: if Secret
37+
Rabbit Code is used, then 0 - best quality sync (default); 1 - medium
38+
quality sync; 2 - fast sync; 3 - zero-order hold; and 4 - linear.
39+
</para>
40+
<para>
41+
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).
42+
</para>
43+
44+
<note>
45+
<title>Note</title>
46+
<para>
47+
Oversampling is not allowed with local ksmps. The opcode can
48+
only be used in UDOs. Audio or control rate array arguments
49+
are not allowed. Global variables or bus channels should not be used.
50+
</para>
51+
</note>
52+
</refsect1>
53+
54+
<refsect1>
55+
<title>See Also</title>
56+
<para>
57+
<link linkend="endop"><citetitle>endop</citetitle></link>,
58+
<link linkend="opcode"><citetitle>opcode</citetitle></link>,
59+
<link linkend="xin"><citetitle>xin</citetitle></link>,
60+
<link linkend="xout"><citetitle>xout</citetitle></link>
61+
</para>
62+
</refsect1>
63+
64+
<refsect1>
65+
<title>Credits</title>
66+
<para>Author: Victor Lazzarini</para>
67+
<para>New in version 7.0</para>
68+
</refsect1>
69+
</refentry>

‎opcodes/setksmps.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
</warning>
6666

6767
<para>
68-
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.
68+
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.
6969
</para>
7070
</refsect1>
7171

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

9090
<literallayout>
91-
[xinarg1] [, xinarg2] ... [xinargN] name [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]
91+
[xinarg1] [, xinarg2] ... [xinargN] name [xoutarg1] [, xoutarg2] ... [xoutargN]
9292
</literallayout>
9393
</para>
9494
</refsect1>

‎opcodes/top.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -793,6 +793,7 @@
793793
&opcodesoutvalue;
794794
&opcodesoutx;
795795
&opcodesoutz;
796+
&opcodesoversample;
796797
&opcodesp5gconnect;
797798
&opcodesp5gdata;
798799
&opcodesp;

‎preface/whatsnew.xml

Lines changed: 4 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,9 @@
11
<section id="PrefaceWhatsNew"><title>What's new in Csound &csoundversion;</title>
2-
<!-- <bridgehead>Release Notes for Csound 6.XX ()</bridgehead>
2+
3+
<bridgehead>Release Notes for Csound 7.</bridgehead>
34
<para>
4-
<itemizedlist>
5-
<listitem>
6-
<para>New opcodes:
7-
<itemizedlist>
8-
<listitem>
9-
<simpara><link linkend=""><citetitle></citetitle></link></simpara>
10-
</listitem>
11-
</itemizedlist>
12-
</para>
13-
</listitem>
14-
<listitem>
15-
<para>
16-
New functionality
17-
<itemizedlist>
18-
<listitem>
19-
<simpara>
20-
</simpara>
21-
</listitem>
22-
<listitem>
23-
<simpara>
24-
</simpara>
25-
</listitem>
26-
</itemizedlist>
27-
</para>
28-
</listitem>
29-
<listitem>
30-
<para>Bug fixes and improvements:
31-
<itemizedlist>
32-
<listitem>
33-
<simpara>
34-
</simpara>
35-
</listitem>
36-
<listitem>
37-
<simpara>
38-
</simpara>
39-
</listitem>
40-
</itemizedlist>
41-
</para>
42-
</listitem>
43-
<listitem>
44-
<para>
45-
Internal Changes:
46-
<itemizedlist>
47-
<listitem>
48-
<simpara>
49-
</simpara>
50-
</listitem>
51-
<listitem>
52-
<simpara>
53-
</simpara>
54-
</listitem>
55-
<listitem>
56-
<simpara>
57-
</simpara>
58-
</listitem>
59-
<listitem>
60-
<simpara>
61-
</simpara>
62-
</listitem>
63-
</itemizedlist>
64-
</para>
65-
</listitem>
66-
</itemizedlist>
67-
</para>-->
5+
Major new version.
6+
</para>
687

698
<bridgehead>Release Notes for Csound 6.18 (2022 October)</bridgehead>
709
<para>

0 commit comments

Comments
 (0)