Crate reaper_medium

Expand description

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

To get started, have a look at the ReaperSession struct.

General usage hints

Whenever you find an identifier in this crate that ends with index, you can assume it’s a zero-based integer. That means the first index is 0, not 1!

Example

use reaper_medium::ProjectContext::CurrentProject;

let reaper = session.reaper();
reaper.show_console_msg("Hello world from reaper-rs medium-level API!");
let track = reaper.get_track(CurrentProject, 0).ok_or("no tracks")?;
unsafe { reaper.delete_track(track); }

The ultimate goal of the medium-level API is to provide all functions offered by the low-level API, but in an idiomatic and type-safe way. The result is still a plain list of functions, where each function is basically named like its original. Going all object-oriented, using reactive extensions, introducing a fluid API, finding function names that make more sense … all of that is intentionally out of scope. The medium-level API is intended to stay close to the original API. This has the benefit that ReaScript (e.g. Lua) and C++ code seen in forum threads, blogs and existing extensions can be helpful even for writing plug-ins in Rust.

Design principles

In order to achieve these goals, this API follows a bunch of design principles.

Follow Rust naming conventions

Most low-level functions and types don’t follow the Rust naming conventions. We adjust them accordingly while still staying as close as possible to the original names.

Use unsigned integers where appropriate

We don’t use signed integers when it’s totally clear that a number can never be negative. Example: insert_track_at_index()

Use enums where appropriate

We want more type safety and more readable code. Enums can contribute to that a lot. Here’s how we use them:

If the original function uses an integer which represents a limited set of options that can be easily named, we introduce an enum. Example: get_track_automation_mode(), AutomationMode
If the original function uses a string and there’s a clear set of predefined options, we introduce an enum. Example: get_media_track_info_value(), TrackAttributeKey
If the original function uses a bool and the name of the function doesn’t give that bool meaning, introduce an enum. Example: set_current_bpm(), UndoBehavior
If the original function can have different mutually exclusive results, introduce an enum. Example: get_last_touched_fx(), GetLastTouchedFxResult
If the original function has several parameters of which only certain combinations are valid, introduce an enum for combining those. Example: kbd_on_main_action_ex(), ActionValueChange
If the original function takes a parameter which describes how another parameter is interpreted, introduce an enum. Example: csurf_on_pan_change_ex(), ValueChange
If the original function takes an optional value and one cannot conclude from the function name what a None would mean, introduce an enum. Example: count_tracks(), ProjectContext

The first design didn’t have many enums. Then, with every enum introduced in the medium-level API, the high-level API code was getting cleaner, more understandable and often even shorter. More importantly, some API usage bugs suddenly became obvious!

Adjust return types where appropriate

Use bool instead of i32 as return value type for “yes or no” functions. Example: is_in_real_time_audio()
Use return values instead of output parameters. Example: gen_guid()
If a function has multiple results, introduce and return a struct for aggregating them. Example: get_focused_fx()
If a function can return a value which represents that something is not present, return an Option. Example: named_command_lookup()

Use newtypes where appropriate

If a value represents an ID, introduce a newtype. Example: CommandId
If a number value is restricted in its value range, represents a mathematical unit or can be easily confused, consider introducing a meaningful newtype. Example: ReaperVolumeValue

We don’t use newtypes for numbers that represent indexes.

Use convenience functions where necessary

In general, the medium-level API shouldn’t have too much additional magic and convenience. However, there are some low-level functions which are true allrounders. With allrounders it’s often difficult to find accurate signatures and impossible to avoid unsafe. Adding multiple convenience functions can sometimes help with that, at least with making them a bit more safe to use. Examples: get_set_media_track_info(), plugin_register_add_command_id()

Make it easy to work with strings

String parameters are used as described in ReaperStringArg. Example: string_to_guid()
Strings in return positions are dealt with in different ways:
- When returning an owned string, we return ReaperString. Consumers can easily convert them to regular Rust strings when needed. Example: guid_to_string()
- When returning a string owned by REAPER and we know that string has a static lifetime, we return a 'static reference. Example: get_app_version()
- When returning a string owned by REAPER and we can’t give it a proper lifetime annotation (in most cases we can’t), we grant the user only temporary access to that string by taking a closure with a &ReaperStr argument which is executed right away. Example: undo_can_undo_2()
Strings in enums are often Cow<ReaperStr> because we want them to be flexible enough to carry both owned and borrowed strings.

Use pointer wrappers where appropriate

When we deal with REAPER, we have to deal with pointers. REAPER often returns pointers and we can’t give them a sane lifetime annotation. Depending on the type of plug-in and the type of pointer, some are rather static from the perspective of the plug-in and others can come and go anytime. In any case, just turning them into 'static references would be plain wrong. At the same time, annotating them with a bounded lifetime 'a (correlated to another lifetime) is often impossible either, because mostly we don’t have another lifetime at the disposal which can serve as frame of reference.

In most cases the best we can do is passing pointers around. How exactly this is done, depends on the characteristics of the pointed-to struct and how it is going to be used.

Case 1: Internals not exposed | no vtable

Strategy

Use NonNull pointers directly
Make them more accessible by introducing an alias

Explanation

Such structs are relevant for the consumers as pointers only. Because they are completely opaque (internals not exposed, not even a vtable) and we never own them. We don’t create a newtype because the NonNull guarantee is all we need and we will never provide any methods on them (no vtable emulation, no convenience methods). Using a wrapper just for reasons of symmetry would not be good because it comes with a cost (more code to write, less substitution possibilities) but in this case without any benefit.

We use pointers instead of references because there’s no way we could name a lifetime. REAPER itself provides functions for checking if those pointers are still valid.

Examples

Case 2: Internals exposed | no vtable

Strategy

Don’t create an alias for a NonNull pointer! In situations where just the pointer is interesting and not the internals, write NonNull<...> everywhere. Reason: We need the alias name for a newtype that’s going to be used in situations where the internals matter.
If the consumer shall get access to the internals: Create a newtype that wraps a value of this struct (not a reference and not a pointer!). By using refcast, we can use this newtype not just for owned values but also for borrowed ones (by taking the newtype by reference, as one would expect). For borrowed structs, it won’t matter if they are owned by REAPER or by our Rust code. Previously, the guideline was to create an extra newtype for borrowed usage that would wrap the NonNull pointer, but this is unnecessary now.
The newtype should expose the internals in a way which is idiomatic for Rust (like the rest of the medium-level API does).
If the consumer needs to be able to create such a struct: Provide an idiomatic Rust factory function on the newtype.
In situations where the raw struct is not completely owned (contains pointers itself) and we need a completely owned version, add an owned version of that struct, prefixed with Owned. Ideally it should wrap the raw struct. That way, the owned struct can conveniently deref to the borrowed struct.

Explanation

Unlike raw::MediaTrack and friends, these structs are not opaque. Also, we might create and own such values.

Up-to-date examples (using ref-cast)

raw::PCM_source_transfer_t → PcmSourceTransfer

Legacy examples (NonNull pointer wrappers with separation into borrowed and owned versions)

raw::KbdSectionInfo → KbdSectionInfo & MediumKdbSectionInfo (not yet existing)
raw::audio_hook_register_t → AudioHookRegister & OwnedAudioHookRegister
raw::gaccel_register_t → GaccelRegister (not yet existing) & OwnedGaccelRegister

Case 3: Internals not exposed | vtable

Strategy

Create an alias for a NonNull pointer!
If the consumer shall get access to the virtual functions: Wrap low-level struct in a public newtype starting with Borrowed and use RefCast. This newtype should expose the virtual functions in a way which is idiomatic for Rust. It’s intended for the communication from Rust to REAPER. This needs appropriate companion C code in the low-level API.
If the consumer shall be able to own the type, introduce another newtype starting with Owned that wraps a NonNull pointer.
If the consumer needs to be able to provide such a type (for communication from REAPER to Rust): Create a new trait which can be implemented by the consumer. This also needs appropriate companion C code in the low-level API.

Up-to-date examples (using ref-cast)

PcmSource (most complete example so far)
PcmSink
ReaperPitchShift
ReaperResample

Legacy examples

raw::IReaperControlSurface → ReaperControlSurface (not yet existing) & ControlSurface
raw::midi_Input → MidiInput &
raw::MIDI_eventlist → BorrowedMidiEventList &

Panic/error/safety strategy

We panic if a REAPER function is not available, e.g. because it’s an older REAPER version. Rationale: If all function signatures would be cluttered up with Results, it would be an absolute nightmare to use the API. It’s also not necessary: The consumer can always check if the function is there, and mostly it is (see reaper_low::Reaper).
We panic when passed parameters don’t satisfy documented preconditions which can be easily satisfied by consumers. Rationale: This represents incorrect API usage.
- Luckily, the need for precondition checks is mitigated by using lots of newtypes and enums, which don’t allow parameters to be out of range in the first place. Example: track_fx_get_fx_name()
When a function takes pointers, we generally mark it as unsafe. Rationale: Pointers can dangle (e.g. a pointer to a track dangles as soon as that track is removed). Passing a dangling pointer to a REAPER function can and often will make REAPER crash. Example: delete_track()
- That’s a bit unfortunate, but unavoidable given the medium-level APIs design goal to stay close to the original API. The unsafe is a hint to the consumer to be extra careful with those functions.
- The consumer has ways to ensure that the passed pointer is valid:
  1. Using obtained pointers right away instead of caching them (preferred)
  2. Using validate_ptr_2() to check if the cached pointer is still valid.
  3. Using a hidden control surface to be informed whenever e.g. a MediaTrack is removed and invalidating the cached pointer accordingly.
There’s one exception to this: If the parameters passed to the function in question are enough to check whether the pointer is still valid, we do it, right in that function. If it’s invalid, we panic. We use validate_ptr_2() to check the pointer. Sadly, for all but project pointers it needs a project context to be able to validate a pointer. Otherwise we could apply this rule much more. Rationale: This allows us to remove the unsafe (if there was no other reason for it). That’s not ideal either but it’s far better than undefined behavior. Failing fast without crashing is one of the main design principles of reaper-rs. Because checking the pointer is an “extra” thing that the medium-level API does, we also offer an unsafe _unchecked variant of the same function, which doesn’t do the check. Example: count_tracks() and count_tracks_unchecked()
If a REAPER function can return a value which represents that execution was not successful, return a Result. Example: string_to_guid()

Verdict: Making the API completely safe to use can’t be done in the medium-level API. But it can be done in the high-level API because it’s not tied to the original REAPER flat function signatures. For example, there could be a Track struct which holds a ReaProject pointer, the track index and the track’s GUID. With that combination it’s possible to detect reliably whether a track is still existing. Needless to say, this is far too opinionated for the medium-level API.

Try to follow “zero-cost” principle

If someone uses C++ or Rust instead of just settling with ReaScript, chances are that better performance is at least one of the reasons. The medium-level API acknowledges that and tries to be very careful not to introduce possibly performance-harming indirections. In general it shouldn’t do extra stuff. Just the things which are absolutely necessary to reach the design goals mentioned above. This is essential for code that is intended to be executed in the real-time audio thread (no heap allocations etc.).

This is an important principle. It would be bad if it’s necessary to reach out to the low-level API whenever someone wants to do something performance-critical. The low-level API shouldn’t even be considered as a serious Rust API, it’s too raw and unsafe for Rust standards.