rea_rs_low/
lib.rs

1#![doc(html_root_url = "https://docs.rs/rea-rs-low/0.1.31")]
2#![allow(renamed_and_removed_lints)]
3#![deny(broken_intra_doc_links)]
4
5//! This crate contains the low-level API of [reaper-rs](https://github.com/helgoboss/reaper-rs).
6//!
7//! It is not recommended to use this API directly because it just exposes the
8//! raw REAPER C++ functions, types and constants one to one in Rust. If you
9//! want idiomatic Rust, type safety and convenience, please use the
10//! [medium-level] or high-level API instead.
11//!
12//! At times it can still be useful to access the low-level API, mostly as
13//! fallback if the function that you are looking for has not yet been lifted
14//! to the medium-level API. To get started, best navigate to the [`Reaper`]
15//! struct, which contains all exposed functions.
16//!
17//! # Example
18//!
19//! ```no_run
20//! # let reaper = rea_rs_low::Reaper::default();
21//! use c_str_macro::c_str;
22//! use std::ptr::null_mut;
23//!
24//! unsafe {
25//!     reaper.ShowConsoleMsg(c_str!("Hello world from reaper-rs low-level API!").as_ptr());
26//!     let track = reaper.GetTrack(null_mut(), 0);
27//!     reaper.DeleteTrack(track);
28//! }
29//! ```
30//!
31//! # Design
32//!
33//! ## Goal
34//!
35//! The ultimate goal of the low-level API is to be on par with the REAPER C++
36//! API, meaning that everything which is possible with the REAPER C++ API is
37//! also possible with the *reaper-rs* low-level API. Improvements regarding
38//! safety, convenience or style are not in its scope. It should serve as a
39//! base for more idiomatic APIs built on top of it.
40//!
41//! ## Generated code
42//!
43//! Most parts of the low-level API are auto-generated from
44//! `reaper_plugin_functions.h` using a combination of [bindgen](https://docs.rs/bindgen) and custom build script.
45//!
46//! ## C++ glue code
47//!
48//! There's some code which is not auto-generated, most notably the code to
49//! "restore" functionality which "got lost in translation". The problem is
50//! that some parts of the REAPER C++ API not just use C but also C++ features,
51//! in particular virtual base classes. Rust can't call virtual functions or
52//! implement them.
53//!
54//! The solution is to take a detour via C++ glue code:
55//!
56//! - Rust calling a C++ virtual function provided by REAPER:
57//!     - Implement a method on the raw struct in Rust which calls a function
58//!       written in C which in turn calls the C++ virtual function (Rust
59//!       function → C function → C++ virtual function)
60//!     - Example: `midi.rs` & `midi.cpp`
61//!
62//! - REAPER calling a C++ virtual function provided by Rust:
63//!     - Implement the virtual base class in C++, let each function delegate
64//!       to a corresponding free Rust function which in turn calls a method of
65//!       a trait object (REAPER → C++ virtual function → Rust function)
66//!     - Example: `control_surface.cpp` & `control_surface.rs`
67//!
68//! [medium-level]: https://docs.rs/reaper-medium
69//! [`Reaper`]: struct.Reaper.html
70#[macro_use]
71mod macros;
72
73mod bindings;
74
75pub mod raw;
76
77mod control_surface;
78pub use control_surface::*;
79
80mod util;
81pub use util::*;
82
83mod plugin_context;
84pub use plugin_context::*;
85
86mod reaper;
87pub use reaper::*;
88
89mod reaper_impl;
90pub use reaper_impl::*;
91
92mod swell;
93pub use swell::*;
94
95mod static_context;
96pub use static_context::*;
97
98mod swell_impl;
99
100mod midi;
101pub use midi::*;
102
103mod resample;
104pub use resample::*;
105
106mod pitch_shift;
107pub use pitch_shift::*;
108
109mod pcm_source;
110pub use pcm_source::*;
111
112mod pcm_sink;
113pub use pcm_sink::*;
114
115mod project_state_context;
116pub use project_state_context::*;
rea_rs_low/lib.rs

rea_rs_low/
lib.rs
