Patch Commands Defined

From Uzebox Wiki
Jump to: navigation, search

This is the definitive list of patch commands for sound effects. Commands are processed each frame. A frame equals 1/60th of a second, or the field VSYNC rate.


#define PC_ENV_SPEED 0

Defines the amount of increase or decrease to the channel's volume envelope per frame. If parameter is positive, envelope will raise, if negative envelope will decay and if set to zero, envelope function is disabled.



Applies only to patches played on channel 4 (noise channel). Parameter byte is defined like this:

bit 0:
*0=7 bit mode LFSR. All values in barrel shifter are repeated each 127 shift cycles. Produces more metallic sounds. 
*1=15 bit mode LFSR. All values in barrel shifter are repeated each 32768 shift cycles. Produces sounds more like white noise.
bit 1:6:
*Barrel shifter divider. Sound samples to wait between successive shifts.


#define PC_WAVE 2

Specify the wave pattern to use for channels 1,2 and 3. Wave patterns are defined in /trunk/kernel/data/

#define WSIN 0 //Sine
#define WSAW 1 //Up-sawtooth
#define WTRI 2 //Triangle
#define WS25 3 //Square-25%
#define WS50 4 //Square-50%
#define WS75 5 //Square-75%
#define WFS1 6 //Distorted sine 1
#define WFS2 7 //Distorted sine 2
#define WFS3 8 //Distorted sine 3
#define WFSQ 9 //Filtered square-50


#define PC_NOTE_UP 3

Increments the current channel's playing note (pitch) by one half step. For example if a C-4 is playing, after a PC_NOTE_UP(1) command, the sound engine will play a C#4.


#define PC_NOTE_DOWN 4

Decrements the current channel's playing note (pitch) by one half step. For example if a C-4 is playing, after a PC_NOTE_DOWN(1) command, the sound engine will play a B-3.


#define PC_NOTE_CUT 5

Stop playing the note on the current channel. Note cut actually sets the volume to zero and turns off the envelope function.


#define PC_NOTE_HOLD 6

A note hold will cause the music engine to wait for a MIDI note-off on the channel before resuming the command stream. A note off is, in most MIDI programs, a note-on command with a volume of zero. Note that the midi convert tool, discards note-offs by default to save space.


#define PC_ENV_VOL 7

Sets the value of the channel's volume envelope (0-255).


#define PC_PITCH 8

Sets the channel's playing note (pitch) in terms of half notes. Refer to /trunk/kernel/data/ for the values-to-notes mapping. I.e: C-6 corresponds to value 60.



Sets the amplitude of the tremolo effect. Tremolo is a modulation of the note's volume. The modulation uses WAVE #0 as a sinusoidal reference.


#define PC_TREMOLO_RATE 10

Sets the rate of the tremolo effect, that is, the speed at which the modulating sine wave is traversed.


#define PC_SLIDE 11

Defines a pitch increase or decrease in half steps, that the patch will slide to. This allows smooth pitch changes using 1/8 steps in between the normal half steps. I.e: 0,PC_SLIDE,-3, will slide the pitch downwards until it reaches 3 half steps from it's start. Put another way: C-3 -> PC_SLIDE=-3 -> A-2. PC_SLIDE_SPEED should be specified before use.


#define PC_SLIDE_SPEED 12

Sets the amount of frames that a PC_SLIDE command will take to reach it's target half step from it's original position. I.e: 0,PC_SLIDE_SPEED,10 would make the next PC_SLIDE command take 10 frames to reach it's target. This should be set before using the PC_SLIDE command.


#define PC_LOOP_START 13

Sets the starting point of a loop and takes the number of iterations as an argument. All commands between PC_LOOP_START and PC_LOOP_END will be repeated the number of times specified by the argument. This is designed to save flash space and make some sound effects easier to create.


#define PC_LOOP_END 14

Sets the end point of a loop started by PC_LOOP_START. Takes as argument the number of commands to go backwards in the stream(which usually would be the command immediately after PC_LOOP_START). Specifying 0 as argument will make the kernel scan backwards until it finds the first PC_LOOP_START available and it will continue from there. Use a non-zero number to increase performance(by eliminating the scan backwards).


#define PATCH_END 0xff

Every patch *must* end with this marker or random crashes may happen.