setksmps

setksmps — Sets the local ksmps value in a user-defined opcode block.

Description

Sets the local ksmps value in a user-defined opcode block.

The setksmps statement can be used to set the local ksmps value of the user-defined opcode block. It has one i-time parameter specifying the new ksmps value (which is left unchanged if zero is used). setksmps should be used before any other opcodes (but allowed after xin), otherwise unpredictable results may occur.

Syntax

setksmps iksmps

Initialization

iksmps -- sets the local ksmps value.

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

[Note] Note

The local ksmps 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).

[Warning] Warning about local ksmps

When the local ksmps is not the same as the orchestra level ksmps value (as specified in the orchestra header). Global a-rate operations must not be used in the user-defined opcode block.

These include:

  • any access to “ga” variables

  • a-rate zak opcodes (zar, zaw, etc.)

  • tablera and tablewa (these two opcodes may in fact work, but caution is needed)

  • The in and out opcode family (these read from, and write to global a-rate buffers)

In general, the local ksmps should be used with care as it is an experimental feature. Though it works correctly in most cases.

The setksmps statement can be used to set the local ksmps value of the user-defined opcode block. It has one i-time parameter specifying the new ksmps value (which is left unchanged if zero is used). setksmps should be used before any other opcodes (but allowed after xin), otherwise unpredictable results may occur.

Performance

The syntax of a user-defined opcode block is as follows:


opcode  name, outtypes, intypes
xinarg1 [, xinarg2] [, xinarg3] ... [xinargN]  xin
[setksmps  iksmps]
... the rest of the instrument's code.
xout  xoutarg1 [, xoutarg2] [, xoutarg3] ... [xoutargN]
endop
      

The new opcode can then be used with the usual syntax:


[xinarg1] [, xinarg2] ... [xinargN]  name  [xoutarg1] [, xoutarg2] ... [xoutargN] [, iksmps]
      

Examples

See the example for the opcode opcode.

See Also

endop, opcode, xin, xout

Credits

Author: Istvan Varga, 2002; based on code by Matt J. Ingalls

New in version 4.22