Generator On/Off Fade

Macros: FadeOn, Fade

This option allows you to set an adjustable automatic fade-up and fade-down when the Generator is toggled on and off. The On/Off Fade button controls whether this feature will be used, while the edit control below it controls the duration of the fade.

You can set the duration in samples or seconds, depending on the state of the little Smpls/sec button at the right.

The fade is performed on the raw Generator data before it is sent to the sound card, raising or lowering the output by a tiny step on every sample until the fade is completed. There are no audible steps or other artifacts... it is completely smooth.

Please note that the fade-down does not begin the instant the Generator button is toggled off. The fade begins immediately in the data stream, but that stream goes through a buffer queue that acts like a delay line for the data before it reaches the sound card output. (The buffer allows other activities to go on while the sound is delivered as needed to the sound card.) So there could be up to 3 seconds delay for a mono output, or 1.5 secs for stereo or multi-channel operation, at the default 48000 Hz sample rate. Higher rates will have less delay, lower will have more.

While the fade-down is in progress, the toolbar Generator button is disabled. Note, however, that the wide Generator On/Off at the top of the Generator dialog is always enabled, and does not engage the fade system. You can thus toggle the Generator on and off instantly, re-enabling the toolbar button if needed. (You might need to do that if you accidentally set a ridiculously long fade length, such as setting 12000 with the intention of getting 12000/48000 = 0.25 second fades, without noticing that the Smpls/sec button is in sec mode instead of Smpls.)

Note that the auto-fade settings (button state and fade length) are not stored with the Generator setup like the other items in this dialog.

There is also a separate macro-controlled fade that allows independent control of fade-up and fade-down lengths and can be used as desired while the generator is running. See below for details.

Also note that the fade effect operates on the overall signal, including any Stream DC Offset that may be present. This means the DC component fades up and down along with the rest of the signal. Check to be sure this is what you want.

Macro Notes:

FadeOn=1 forces the On/Off Fade button on, FadeOn=0 forces it off, and FadeOn=x toggles the current state.

Fade#cN=UX sets the auto-fade length control to UX samples. Fade#cT=X sets it to the equivalent of X seconds. Both of these are independent of the current Smpls/sec button state. Fade#c=X sets the length to X samples or X seconds, according to the current Smpls/sec state.

You can read the current auto-fade length in samples via UF=Fade?N. To read seconds, use F=Fade?T.

If you want to toggle the Generator via a macro and include the auto-fade, you must use the Gen#F command form, as in Gen#F=1, Gen#F=0, or Gen#F=x. The plain Gen form ignores the preset automatic fades and toggles immediately.

Note that the fade-out (either Gen#F=0, or Gen#F=x when the prior state was 1) always fades down from the full-on level. If a prior fade-up is still in progress, the level will abruptly jump to 100% and then start the fade-out.

Also note that macro processing does not wait for a prior fade to complete. Consider the following macro for creating a one-shot tone burst:

    Gen#F=1                ;Fade sound up
    WaitSecs=2             ;Hold it on for 2 secs
    Gen#F=0                ;Fade it out

The WaitSecs timing begins immediately after the prior command. If the Fade duration was set to (say) 5 seconds, the fade-up will not be complete before the Gen#F=0 fade-out command, which will pop the level up to full-on and then fade for 5 seconds. Probably not what you wanted. One way to avoid this is to add the Fade?T duration to the desired hold-on time to set WaitSecs:

    Gen#F=1                ;Fade sound up
    WaitSecs=Fade?T + 2.00 ;Hold it on for 2 secs
    Gen#F=0                ;Fade it out

(Note that you can also use Event Triggering along with the Triggered_Burst macro to get tightly-controlled single bursts or burst trains, triggered by key press, sound card input, or via external Arduino or Numato device detection of switch, resistance, digital input, or analog voltage changes.)

The above commands affect the automatic fade settings only. The following commands are for macro-only fades that are completely independent.

If you give a fade-up command before toggling the Generator on, either manually or via a Gen=1 or Gen#F=1 command, the fade length will supercede the auto-fade length in the dialog control even if the On/Off Fade button is active.

Otherwise, if the Generator is already running, these fade commands affect the live sound, though with a delay due to the buffer queue mentioned above. Each command not only sets the fade length, it starts the fade process which acts on subsequent data samples until the fade is complete.

Fade=UX or Fade#N=UX set the macro-only fade length to UX samples, while Fade#T=X sets it to X seconds. Note that UX and X are signed values; if positive, the command sets a fade-up, while negative values set a fade-down. Also note that if you try to give a second command in the same direction as the previous one, it will be ignored.

After giving a macro fade command, you should wait until the fade is complete before giving the next one, or any other command that you want to take place after the fade is complete. For example, if you want to change settings like ToneFreq or Level without introducing a click, you'd fade the sound off, wait to make sure it's done, change the settings (using GenUpdate=0 to prevent the normal Generator restart when changing parameters), then fade up with the new settings.

You can read the fade status with UX=Fade; 1 means the fade is still in progress, 0 means it is done. You'd typically read it in a WHILE loop, as in the example below.

This example creates three (UI / 2) slow "bursts" of output signal, then goes off after the final fade-down. The signal is whatever the Generator is set for, anything from the initial 440 Hz default sine, to a complex multi-Stream or multi-channel extravaganza.

Each fade stage starts as soon as the prior completes, but you could extend the full-on and full-off times by adding a WaitSecs command at the start of the outer WHILE loop.

While running this example, you may notice that the initial part of the sequence seems more drawn-out than the rest. That's due to the buffer queue system. When the Generator is toggled on, it immediately fills the first half of the buffer, which is 65536 mono samples or 32768 stereo samples. This is filled "at once", when the Gen=1 command runs; if the fade length is less than the number of samples, as it is in this example if you are generating a mono signal, the queue will contain the complete series of UF=48000 fade-up samples, plus another 17536 fully-on samples for 65536 total.

There is no way the subsequent fade-down can start any sooner than 65536 samples, since those have been sent to the queue before the fade-down command is run. So the initial sound stays high for an extra 17536 samples, or 0.365 seconds at the default 48000 Hz sample rate.

While those samples are being played in the background, the macro continues to run. The next command is the first WHILE.Fade=1 loop, but as noted the fade-up samples were all sent in the initial burst (and the Fade status returned to 0), so that WHILE loop will be skipped and no WaitTrace= delay will happen.

After that initial fill of 65536 samples, subsequent fills will be smaller... typically 16384 mono samples (half of the Wave Block size which defaults to 32768 bytes). So the multiple fades within the WHILE.UI=>0 loop will each take more than one pass through the inner WHILE.Fade=1 loop to send all 48000 to the queue. The first fade-down will take 3 passes (3 * 16384 = 49152), ending with 1152 fully-off samples in the third one. And so on.

UF=48000               ;Fade length = 1 sec at 48000 Hz
UI=6                   ;Number of total fades (EVEN)

Fade#N=UF              ;Pre-set fade-up
Gen=1                  ;Generator on
WHILE.Fade=1           ;Fade in progress?
    WaitTrace=             ;Wait TraceUpdate msec
WEND.                  ;Wait until fade done
UI=UI-1                ;Count initial fades

WHILE.UI=>0            ;Do remaining fades
    UF=-UF                 ;Fade down if prior was up
    Fade#N=UF
    WHILE.Fade=1           ;Fade in progress?
        WaitTrace=             ;Wait TraceUpdate msec
    WEND.                  ;Wait until fade done
    UI=UI-1                ;Count the fade stage
WEND.                  ;Do all requested stages

WaitSecs=3             ;Final delay for buffer queue
Gen=0                  ;Generator off

Note the 3-second WaitSecs delay before the Gen=0 command to turn off the Generator. This is to allow the queue to send all its samples to the sound card. The queue buffer is 256 KB (262144 bytes) which is 131072 mono samples. At the default 48000 Hz samples per second this is 2.73 seconds.