ViewVC logotype

Annotation of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_change_sustain_function.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 3605 - (hide annotations) (download) (as text)
Tue Sep 17 19:44:02 2019 UTC (14 months, 2 weeks ago) by schoenebeck
File MIME type: text/html
File size: 3487 byte(s)
- Minor fixes regarding real numbers, unit and finalness.

1 schoenebeck 3318 <html>
2     <head>
3     <meta name="author" content="Christian Schoenebeck">
4     <title>change_sustain() function</title>
5 schoenebeck 3361 <meta name="description" content="Modifies the amplitude sustain level of voices of a particular note.">
6 schoenebeck 3318 </head>
7     <body>
8     <h1>change_sustain()</h1>
9     <p>
10 schoenebeck 3361 This function can be used to modify the amplitude sustain level of active voices of a
11     particular note.
12 schoenebeck 3318 In contrast to other synthesis parameter related functions,
13     this function only allows to change the sustain level when the respective note
14     is new, that is either i.e. at the beginning of a <code lang="nksp">note</code>
15     event handler or right after calling <code>play_note()</code>. So you should
16     perform the sustain level change as soon as possible, especially before calling any
17     <code>wait()</code> function and before entering a loop which might take a
18     long time to execute (which might cause your script to get
19     forcely suspended by the script engine due to real-time constraints).
20     </p>
21     <p>
22     The sustain level changes set by calling this function are always applied relatively to
23     the sustain level calculated by the synthesis model and sampler format. That means
24     the various sources of sustain factors like MIDI CCs and other sustain parameter
25     factors that may be defined by the instrument patch, are always processed and
26     calculated for the voices first, and the final sustain level applied is always
27     a relative combination of all those factors and the one set with this function call.
28     Or in other words: you cannot replace the sustain set by other synthesis
29     sources with this function.
30     </p>
32     <note class="important">
33     Release Trigger Samples: In case the affected voices cause release trigger
34     samples to be spawned later on, the sustain level of those release trigger voices
35     will not be affected by this function at all. So if you need to control the
36     sustain level of release trigger samples by script, then you might rather also trigger
37     those release trigger samples by script with <code lang="nksp">play_note()</code>
38     instead of using the sampler format's internal support for release trigger samples.
39     </note>
41     <h3>Function Prototype</h3>
42     <p/>
43     <code lang="nksp">
44     change_sustain(??note??, ??level??)
45     </code>
47     <h3>Arguments</h3>
48     <table>
49     <tr>
50     <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
51     </tr>
52     <tr>
53     <td><code>??note??</code></td>
54     <td>Note ID Number or Note ID Array</td>
55     <td>All voices of this note will be modified.<br>
56     [required]</td>
57     </tr>
58     <tr>
59     <td><code>??level??</code></td>
60 schoenebeck 3601 <td>Integer&nbsp;Number&nbsp;or<br>
61     Real&nbsp;Number</td>
62 schoenebeck 3318 <td>Sustain Level (abstract non-negative value, i.e.
63     <code>0</code> for zero sustain level, <code>1000000</code> for neutral sustain factor,
64     <code>2000000</code> for doubling the effective sustain level).<br>
65     [required]</td>
66     </tr>
67     </table>
69     <h3>Return Value</h3>
70     <p>None.</p>
72 schoenebeck 3601 <h3>Remarks</h3>
73     <p>
74 schoenebeck 3605 This functions optionally accepts <code>B</code> (for "Bel") as standard unit and
75 schoenebeck 3601 finalness for its argument <code>??level??</code>.
76     </p>
78 schoenebeck 3318 <h3>Examples</h3>
79     <p>None yet.<p>
81     <h3>Availability</h3>
82     <p>
83     Since LinuxSampler 2.0.0.svn72.
84     </p>
86     </body>
87     </html>

  ViewVC Help
Powered by ViewVC