back to main JSFX reference page
JSFX Programming Reference - Memory/Slider/FFT/MDCT Functions
Host Interaction Functions
top Memory/FFT/MDCT Functions
- mdct(start_index, size), imdct(start_index, size)
Performs a modified DCT (or inverse in the case of imdct()) on the data
in the local memory buffer at the offset specified by the first parameter.
The second parameter controls the size of the MDCT, and it MUST be one of
the following: 64, 128, 256, 512, 1024, 2048, or 4096. The MDCT takes the number of
inputs provided, and replaces the first half of them with the results. The
IMDCT takes size/2 inputs, and gives size results.
Note that the MDCT must NOT cross a 65,536 item boundary, so be sure to
specify the offset accordingly.
The MDCT/IMDCT provided also provide windowing, so your code is not required
to window the overlapped results, but simply add them. See the example
effects for more information.
- fft(start_index, size), ifft(start_index, size)
fft_real(start_index, size), ifft_real(start_index, size)
// need to scale output by 1/512.0, too.
Performs a FFT (or inverse in the case of ifft()) on the data in the local
memory buffer at the offset specified by the first parameter.
The size of the FFT is specified by the second parameter, which must be
16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384, or 32768. The outputs
are permuted, so if you plan to use them in-order, call fft_permute(buffer, size)
before and fft_ipermute(buffer,size) after your in-order use.
Your inputs or outputs will need to be scaled down by 1/size, if used.
Note that the FFT/IFFT require real/imaginary input pairs (so a
256 point FFT actually works with 512 items).
Note that the FFT/IFFT must NOT cross a 65,536 item boundary, so be sure to
specify the offset accordingly.
The fft_real()/ifft_real() variants operate on a set of size real inputs, and produce size/2 complex
outputs. The first output pair is DC,nyquist. Normally this is used with fft_permute(buffer,size/2).
Used to convolve two buffers, typically after FFTing them.
convolve_c works with complex numbers. The sizes specify number
of items (the number of complex number pairs).
Note that the convolution must NOT cross a 65,536 item boundary,
so be sure to specify the offset accordingly.
The freembuf() function provides a facility for you to notify the memory
manager that you are no longer using a portion of the local memory buffer.
For example, if the user changed a parameter on your effect halving your
memory requirements, you should use the lowest indices possible, and call
this function with the highest index you are using plus 1, i.e. if you are
using 128,000 items, you should call freembuf(128001); If you are no longer
using any memory, you should call freembuf(0);
Note that calling this does not guarantee that the memory is freed or
cleared, it just provides a hint that it is OK to free it.
The memcpy() function provides the ability to quickly copy regions of the
local memory buffer. If the buffers overlap and either buffer crosses a 65,536 item boundary, the
results may be undefined.
The memset() function provides the ability to quickly set a region of the
local memory buffer to a particular value.
- mem_multiply_sum(buf1,buf2,length) -- REAPER 6.74+
Sums the products of length items of buf1 and buf2. If buf2 is exactly -1, then sums the squares of items in buf1. If buf2 is exactly -2 then sums the absolute values of buf1. If buf2 is exactly -3 then sums the values of buf1. If buf2 is another negative value, the result is undefined.
- mem_insert_shuffle(buf,len,value) -- REAPER 6.74+
Shuffles buf to the right by one element, inserting value as buf, and returning the previous buf[len-1].
Returns the total number of memory slots available to the plug-in.
A small (approximately 4096 item) user stack is available for use in code (REAPER 4.25+):
Atomic Variable Access
Pushes value onto the user stack, returns a reference to the value.
Pops a value from the user stack into value, or into a temporary buffer if value is not specified, and returns a reference to where the stack was popped. Note that no checking is done to determine if the stack is empty, and as such stack_pop() will never fail.
Returns a reference to the item on the top of the stack (if index is 0), or to the Nth item on the stack if index is greater than 0.
Exchanges a value with the top of the stack, and returns a reference to the parameter (with the new value).
Guaranteed-atomic updates/accesses of values across contexts (specifically @gfx and other contexts). Normally these are unnecessary, but they are provided for the discriminating JSFX user -- REAPER 4.5+:
Sets dest to newvalue if dest equals value. Returns the old value of dest. On Windows this is known as InterlockedCompareExchange().
Exchanges val1 and val2, returns the new value of val1.
Adds val2 to dest_val1, returns the value of dest_val1.
Sets dest_val1 to val2, returns the value of dest_val1.
Returns the value of val.
top Host Interaction Functions
For these functions, the parameter can be the variables slider1-sliderN, in
which case that slider is refreshed. Otherwise, it can be a bitmask of which
sliders have changed, where 1 would be the first slider, 2 would be the
second, 4 would be the third, 32768 being the 16th slider, and so on.
- sliderchange(mask or sliderX)
sliderchange(2 ^ sliderindex);
The sliderchange() function provides a facility for you to notify REAPER/JS
that you have changed a sliderX variable from code
so that it can update any embedded displays.
This function does not send automation notifications to the host -- use slider_automate() if that is desired.
If sliderchange() is called from @gfx with -1.0 as a parameter, REAPER will add a new undo point. This is useful if internal state changes due to user interaction in @gfx.
- slider_automate(mask or sliderX[, end_touch]) -- end_touch requires REAPER 6.74+
slider_automate(2 ^ sliderindex);
The slider_automate() function provides a facility for you to notify REAPER/JS
that you have changed a sliderX variable so that
it can update the display, and record the move as automation. This function is not
necessary to call from the @slider code section,
it is provided so that other code sections can write programmatic automation messages.
In REAPER 6.74+, you can call slider_automate(mask, 1) in order to end a touch automation recording session.
- slider_show(mask or sliderX[, value]) -- REAPER 6.30+
Queries (if value is omitted) or sets the visibility of one or more sliders. If value is -1, toggles visibility, value of 0 hides, 1 shows. Returns the mask of requested visible sliders.
Pin Mapper Functions
- export_buffer_to_project(buffer,length_samples,nch,srate,track_index[,flags,tempo,planar_pitch]) -- REAPER 6.05+
Writes the audio contents of buffer(s) to an audio file and inserts into project. This may only be called from the @gfx section, it should not be called from any other context.
- buffer: a pointer to the first sample of the first channel of audio data
- length_samples: number of samples (or sample-pairs etc) of audio data to write
- nch: number of channels to write
- srate: samplerate to write
- track_index: track index to insert media
- (optional) flags: bitmask:
- 4: stretch/loop item to fit time selection
- 8: tempo match to project 1x
- 16: tempo match to project 0.5x
- 32: tempo match to project 2x
- 64: do not preserve pitch when matching tempo
- 256: force loop of item regardless of preference of default item looping
- 0x10000: move edit cursor to end of project
- 0x20000: set tempo from tempo parameter
- (optional) tempo: ignored if flags does not have 0x20000 set, otherwise sets the project tempo to this value at the insertion point
- (optional) planar_pitch: if 0 or not specified, then multichannel exports are interleaved samples. If nonzero, then each channel is a separate buffer, and buffer is the first channel, (buffer+planar_pitch) is the second channel, (buffer+planar_pitch*2) is the third channel, etc. -- REAPER 6.30+
REAPER 6.27+ - these functions allow interacting with REAPER's pin mapper in advanced ways:
Host Placement Functions
Get the number of track or media item take channels
Set the number of track or media item take channels. only valid in @gfx section
Get a bitfield (maximum 32 bits) representing the channel mappings for this pin
Set the channel mappings for this pin/startchan/chanmask. only valid in @gfx section
- get_pinmapper_flags(no parameters)
Get the pinmapper flags for this fx. !&1=pass through unmapped output channels, &1=zero out unmapped output channels
Set the pinmapper flags for this fx. see get_pinmapper_flags. only valid in @gfx section
- get_host_placement([chain_pos, flags]) -- REAPER 6.74+
Returns track index, or -1 for master track, or -2 for hardware output FX. chain_pos will be position in chain. flags will have 1 set if takeFX, 2 set if record input, 4 set if in inactive project.