Crate reaper_low

This crate contains the low-level API of reaper-rs.

It is not recommended to use this API directly because it just exposes the raw REAPER C++ functions, types and constants one to one in Rust. If you want idiomatic Rust, type safety and convenience, please use the medium-level or high-level API instead.

At times it can still be useful to access the low-level API, mostly as fallback if the function that you are looking for has not yet been lifted to the medium-level API. To get started, best navigate to the Reaper struct, which contains all exposed functions.

Example

use c_str_macro::c_str;
use std::ptr::null_mut;

unsafe {
    reaper.ShowConsoleMsg(c_str!("Hello world from reaper-rs low-level API!").as_ptr());
    let track = reaper.GetTrack(null_mut(), 0);
    reaper.DeleteTrack(track);
}

Design

Goal

The ultimate goal of the low-level API is to be on par with the REAPER C++ API, meaning that everything which is possible with the REAPER C++ API is also possible with the reaper-rs low-level API. Improvements regarding safety, convenience or style are not in its scope. It should serve as a base for more idiomatic APIs built on top of it.

Generated code

Most parts of the low-level API are auto-generated from reaper_plugin_functions.h using a combination of bindgen and custom build script.

C++ glue code

There’s some code which is not auto-generated, most notably the code to “restore” functionality which “got lost in translation”. The problem is that some parts of the REAPER C++ API not just use C but also C++ features, in particular virtual base classes. Rust can’t call virtual functions or implement them.

The solution is to take a detour via C++ glue code:

• Rust calling a C++ virtual function provided by REAPER:

  • Implement a method on the raw struct in Rust which calls a function written in C which in turn calls the C++ virtual function (Rust function → C function → C++ virtual function)
  • Example: midi.rs & midi.cpp

• REAPER calling a C++ virtual function provided by Rust:

  • Implement the virtual base class in C++, let each function delegate to a corresponding free Rust function which in turn calls a method of a trait object (REAPER → C++ virtual function → Rust function)
  • Example: control_surface.cpp & control_surface.rs

Modules

raw

Exposes important raw types, functions and constants from the C++ REAPER API.

Macros

reaper_vst_plugin

Macro which gathers things that go into the static REAPER VST plug-in context.

Structs

ExtensionPluginContext

Additional data available in the context of extension plug-ins.

PluginContext

This represents the context which is needed to access REAPER functions from plug-ins.

Reaper

This is the low-level API access point to all REAPER functions.

ReaperFunctionPointers

Container for the REAPER function pointers.

StaticExtensionPluginContext

Contains those parts of the REAPER extension plug-in context which must be obtained from static variables.

StaticVstPluginContext

Contains those parts of the REAPER VST plug-in context which must be obtained in static scope.

Swell

This is the low-level API access point to all SWELL functions.

SwellFunctionPointers

Container for the SWELL function pointers.

VstPluginContext

Additional data available in the context of VST plug-ins.

Enums

ContextFromExtensionPluginError

An error which can occur when attempting to create a REAPER plug-in context from an extension plug-in.

ContextFromVstPluginError

An error which can occur when attempting to create a REAPER plug-in context from a VST plug-in.

TypeSpecificPluginContext

Additional stuff available in the plug-in context specific to a certain plug-in type.

Traits

IReaperControlSurface

This is the Rust analog to the C++ virtual base class IReaperControlSurface.

PCM_sink

This is the Rust analog to the C++ virtual base class PCM_sink.

PCM_source

This is the Rust analog to the C++ virtual base class PCM_source.

ProjectStateContext

This is the Rust analog to the C++ virtual base class ProjectStateContext.

Functions

bootstrap_extension_plugin^⚠

This is a convenience function for bootstrapping extension plug-ins.

copy_heap_buf_to_buf^⚠

Copies the content of the given heap buffer to the given output buffer (which must be sized correctly).

create_cpp_to_rust_control_surface^⚠

Creates an IReaperControlSurface object on C++ side and returns a pointer to it.

create_cpp_to_rust_pcm_sink^⚠

Creates a PCM_sink object on C++ side and returns a pointer to it.

create_cpp_to_rust_pcm_source^⚠

Creates a PCM_source object on C++ side and returns a pointer to it.

create_cpp_to_rust_project_state_context^⚠

Creates a ProjectStateContext object on C++ side and returns a pointer to it.

create_heap_buf

Creates a heap buffer and passes ownership to the caller.

delete_cpp_control_surface^⚠

Destroys a C++ IReaperControlSurface object.

delete_cpp_pcm_sink^⚠

Destroys a C++ PCM_sink object.

delete_cpp_pcm_source^⚠

Destroys a C++ PCM_source object.

delete_cpp_project_state_context^⚠

Destroys a C++ ProjectStateContext object.

delete_cpp_reaper_pitch_shift^⚠

Destroys a C++ IReaperPitchShift object.

delete_cpp_reaper_resample_interface^⚠

Destroys a C++ REAPER_Resample_Interface object.

execute_plugin_destroy_hooks^⚠

This function executes all registered plug-in destroy hooks.

firewall

This function catches panics before they reach REAPER.

load_pcm_source_state_from_buf^⚠

Restores the PCM source state from the given buffer.

register_hinstance

Registers the module handle globally.

register_plugin_destroy_hook^⚠

Registers a function that will be executed when the plug-in module gets unloaded.

register_swell_function_provider

Registers the given SWELL function provider globally.

save_pcm_source_state_to_heap_buf^⚠

Saves the state of the given PCM source into the given heap buffer and returns the size of the data written into the buffer.

static_extension_plugin_context

Exposes the (hopefully) obtained static extension plug-in context.

static_vst_plugin_context

Exposes the (hopefully) obtained static VST plug-in context.