1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
<refentry id="setksmps">
<indexterm id="IndexSetksmps"><primary>setksmps</primary></indexterm>
<refentryinfo><title>Signal I/O:Software Bus</title></refentryinfo>
<refmeta>
<refentrytitle>setksmps</refentrytitle>
</refmeta>
<refnamediv>
<refname>setksmps</refname>
<refpurpose>
Sets the local ksmps value in an instrument or user-defined opcode block
</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>setksmps</command> iksmps</synopsis>
</refsect1>
<refsect1>
<title>Initialization</title>
<para>
<emphasis>iksmps</emphasis> -- sets the local ksmps value.
</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 setting up the instrument local ksmps to the new value. 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). It also means that you cannot use a local <link linkend="ksmps"><citetitle>ksmps</citetitle></link> that is higher than the global <link linkend="ksmps"><citetitle>ksmps</citetitle></link>.
</para>
</note>
<warning>
<title>Warning about local ksmps</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 be carefully coded to access the data in a vector according to the local ksmps. The audio rate bus channel opcodes (chnget/chnset) can be used freely, however, as they will do the necessary conversion between ksmp sizes.
</para>
<para>
Other opcodes that require some care 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 cannot be used in local-ksmps UDOs (these read from, and write to global a-rate buffers), but are safe in local-ksmps instruments</para></listitem>
</itemizedlist>
</para>
<para>
In general, the local <emphasis>ksmps</emphasis> should be used with care as it is an experimental feature. Though it works correctly in most cases.
</para>
</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.
</para>
</refsect1>
<refsect1>
<title>Performance</title>
<para>
The syntax of a user-defined opcode block is as follows:
<programlisting>
<emphasis role="oblock">opcode</emphasis> name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN] <emphasis role="opc">xin</emphasis>
[<emphasis role="opc">setksmps</emphasis> iksmps]
... the rest of the instrument's code.
<emphasis role="opc">xout</emphasis> xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
<emphasis role="oblock">endop</emphasis>
</programlisting>
</para>
<para>
The new opcode can then be used with the usual syntax:
<literallayout>
[xinarg1] [, xinarg2] ... [xinargN] name [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]
</literallayout>
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
See the example for the <link linkend="opcode"><citetitle>opcode</citetitle></link> opcode.
</para>
</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: Istvan Varga, 2002; based on code by Matt J. Ingalls; Modified by V Lazzarini for Csound 6</para>
<para>New in version 4.22</para>
</refsect1>
</refentry>
|
