Crate rea_rs_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.