reference/functions/nksp_change_pan_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>change_pan() function</title>
    <meta name="description" content="Modifies the panning (stereo balance) of voices of a particular note.">
  </head>
  <body>
    <h1>change_pan()</h1>
    <p>
      This function can be used to modify the stereo panorama (stereo balance) of active voices during
      their entire life time. So you may for example implement 
      pan envelopes by script by using this function. You need to pass the
      note ID of the voices you want to alter. This function will change the
      panning of all active voices associated with the requested note. So if you
      are using a layered instrument patch, then it will change the panning of
      all layers.
    </p>
    <p>
      The panning changes set by calling this function are always applied relatively to
      the panning/balance calculated by the synthesis model and sampler format. That means
      the various sources of panning/balance factors like MIDI CC #10 and other panning
      factors that may be defined by the instrument patch, are always processed and
      calculated for the voices first,
      and the final stereo balance applied is always a relative combination of all those
      factors and the one set with this function call. This does also not change
      when you pass <code>1</code> for argument <code>??relative??</code>.
      Or in other words: you cannot replace the panning/balance set by other synthesis
      sources with this function.
    </p>

    <note class="important">
    Release Trigger Samples: In case the affected voices cause release trigger
    samples to be spawned later on, the panning of those release trigger voices
    will not be affected by this function at all. So if you need to control the
    panning of release trigger samples by script, then you might rather also trigger
    those release trigger samples by script with <code lang="nksp">play_note()</code>
    instead of using the sampler format's internal support for release trigger samples.
    </note>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
change_pan(??note??, ??pan??, [??relative??])
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??note??</code></td>
        <td>Note ID Number or Note ID Array</td>
        <td>All voices of this note will be modified.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??pan??</code></td>
        <td>Integer Number</td>
        <td>Value between -1000 (most left) and +1000 (most right).<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??relative??</code></td>
        <td>Integer Number</td>
        <td>Whether change_pan() calls should be relative to each other.<br>
            0: A call to <code>change_pan()</code> upon the same note will
               replace the panning change value set by previous
               <code>change_pan()</code> calls upon the same note.<br>
            1: Successive calls to <code>change_pan()</code> upon the same
               note will be relatively applied against each other.<br>
            [optional, default: 0]</td>
      </tr>
    </table>

    <h3>Return Value</h3>
    <p>None.</p>

    <h3>Examples</h3>
    <p>None yet.<p>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn11.<p>

    <note>
      The third argument of this function <code>??relative??</code> is only
      optional with NKSP. If you want to keep compatibility with KSP, then you
      should always pass a value for that third argument of this function.
    </note>

  </body>
</html>
1	schoenebeck	2932	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>change_pan() function</title>
5			<meta name="description" content="Modifies the panning (stereo balance) of voices of a particular note.">
6			</head>
7			<body>
8			<h1>change_pan()</h1>
9			<p>
10			This function can be used to modify the stereo panorama (stereo balance) of active voices during
11			their entire life time. So you may for example implement
12			pan envelopes by script by using this function. You need to pass the
13			note ID of the voices you want to alter. This function will change the
14			panning of all active voices associated with the requested note. So if you
15			are using a layered instrument patch, then it will change the panning of
16			all layers.
17			</p>
18			<p>
19	schoenebeck	2933	The panning changes set by calling this function are always applied relatively to
20	schoenebeck	2932	the panning/balance calculated by the synthesis model and sampler format. That means
21			the various sources of panning/balance factors like MIDI CC #10 and other panning
22			factors that may be defined by the instrument patch, are always processed and
23			calculated for the voices first,
24			and the final stereo balance applied is always a relative combination of all those
25			factors and the one set with this function call. This does also not change
26			when you pass <code>1</code> for argument <code>??relative??</code>.
27			Or in other words: you cannot replace the panning/balance set by other synthesis
28			sources with this function.
29			</p>
30
31			<note class="important">
32			Release Trigger Samples: In case the affected voices cause release trigger
33			samples to be spawned later on, the panning of those release trigger voices
34			will not be affected by this function at all. So if you need to control the
35			panning of release trigger samples by script, then you might rather also trigger
36			those release trigger samples by script with <code lang="nksp">play_note()</code>
37			instead of using the sampler format's internal support for release trigger samples.
38			</note>
39
40			<h3>Function Prototype</h3>
41			<p/>
42			<code lang="nksp">
43			change_pan(??note??, ??pan??, [??relative??])
44			</code>
45
46			<h3>Arguments</h3>
47			<table>
48			<tr>
49			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
50			</tr>
51			<tr>
52			<td><code>??note??</code></td>
53	schoenebeck	2944	<td>Note ID Number or Note ID Array</td>
54	schoenebeck	2932	<td>All voices of this note will be modified.<br>
55			[required]</td>
56			</tr>
57			<tr>
58	schoenebeck	2936	<td><code>??pan??</code></td>
59	schoenebeck	2932	<td>Integer Number</td>
60	schoenebeck	3189	<td>Value between -1000 (most left) and +1000 (most right).<br>
61			[required]</td>
62	schoenebeck	2932	</tr>
63			<tr>
64			<td><code>??relative??</code></td>
65			<td>Integer Number</td>
66			<td>Whether change_pan() calls should be relative to each other.<br>
67			0: A call to <code>change_pan()</code> upon the same note will
68			replace the panning change value set by previous
69			<code>change_pan()</code> calls upon the same note.<br>
70			1: Successive calls to <code>change_pan()</code> upon the same
71			note will be relatively applied against each other.<br>
72			[optional, default: 0]</td>
73			</tr>
74			</table>
75
76			<h3>Return Value</h3>
77			<p>None.</p>
78
79			<h3>Examples</h3>
80			<p>None yet.<p>
81
82	schoenebeck	3196	<h3>Availability</h3>
83	schoenebeck	2932	<p>Since LinuxSampler 2.0.0.svn11.<p>
84
85	schoenebeck	3189	<note>
86			The third argument of this function <code>??relative??</code> is only
87			optional with NKSP. If you want to keep compatibility with KSP, then you
88			should always pass a value for that third argument of this function.
89			</note>
90
91	schoenebeck	2932	</body>
92			</html>