Struct reaper_medium::ReaperFunctions

pub struct ReaperFunctions<UsageScope = MainThreadScope> { /* fields omitted */ }

This is the main access point for most REAPER functions.

Basics

You can obtain an instance of this struct by calling Reaper::functions(). This unlocks all functions which are safe to execute in the main thread. If you want access to the functions which are safe to execute in the real-time audio thread, call Reaper::create_real_time_functions() instead. REAPER functions which are related to registering/unregistering things are located in Reaper.

Please note that this struct contains nothing but function pointers, so you are free to clone it, e.g. in order to make all functions accessible somewhere else. This is sometimes easier than passing references around. Don't do it too often though. It's just a bitwise copy of all function pointers, but there are around 800 of them, so each copy will occupy about 7 kB of memory on a 64-bit system.

Panics

Don't assume that all REAPER functions exposed here are always available. It's possible that the user runs your plug-in in an older version of REAPER where a function is missing. See the documentation of low-level Reaper for ways how to deal with this.

Work in progress

Many functions which are available in the low-level API have not been lifted to the medium-level API yet. Unlike the low-level API, the medium-level one is hand-written and probably a perpetual work in progress. If you can't find the function that you need, you can always resort to the low-level API by navigating to low(). Of course you are welcome to contribute to bring the medium-level API on par with the low-level one.

Design

What's the <MainThreadScope> in ReaperFunctions<MainThreadScope> about?

In REAPER and probably many other DAWs there are at least two important threads:

1. The main thread (responsible for things like UI, driven by the UI main loop).
2. The real-time audio thread (responsible for processing audio and MIDI buffers, driven by the audio hardware)

Most functions offered by REAPER are only safe to be executed in the main thread. If you execute them in another thread, REAPER will crash. Or worse: It will seemingly work on your machine and crash on someone else's. There are also a few functions which are only safe to be executed in the audio thread. And there are also very few functions which are safe to be executed from any thread (thread-safe).

There's currently no way to make sure at compile time that a function is called in the correct thread. Of course that would be the best. In an attempt to still let the compiler help you a bit, the traits MainThreadOnly and RealTimeAudioThreadOnly have been introduced. They are marker traits which are used as type bound on each method which is not thread-safe. So depending on the context we can expose an instance of ReaperFunctions which has only functions unlocked which are safe to be executed from e.g. the real-time audio thread. The compiler will complain if you attempt to call a real-time-audio-thread-only method on ReaperFunctions<MainThreadScope> and vice versa.

Of course that technique can't prevent anyone from acquiring a main-thread only instance and use it in the audio hook. But still, it adds some extra safety.

The alternative to tagging functions via marker traits would have been to implement e.g. audio-thread-only functions in a trait CallableFromRealTimeAudioThread as default functions and create a struct that inherits those default functions. Disadvantage: Consumer always would have to bring the trait into scope to see the functions. That's confusing. It also would provide less amount of safety.

Why no fail-fast at runtime when getting threading wrong?

Another thing which could help would be to panic when a main-thread-only function is called in the real-time audio thread or vice versa. This would prevent "it works on my machine" scenarios. However, this is currently not being done because of possible performance implications.

Implementations

impl<UsageScope> ReaperFunctions<UsageScope>

pub fn low(&self) -> &Reaper

Gives access to the low-level Reaper instance.

pub fn enum_projects(
    &self,
    project_ref: ProjectRef,
    buffer_size: u32
) -> Option<EnumProjectsResult> where
    UsageScope: MainThreadOnly, 

Returns the requested project and optionally its file name.

With buffer_size you can tell REAPER how many bytes of the file name you want. If you are not interested in the file name at all, pass 0.

Example

use reaper_medium::ProjectRef::Tab;

let result = reaper.functions().enum_projects(Tab(4), 256).ok_or("No such tab")?;
let project_dir = result.file_path.ok_or("Project not saved yet")?.parent();

pub fn get_track(
    &self,
    project: ProjectContext,
    track_index: u32
) -> Option<MediaTrack> where
    UsageScope: MainThreadOnly, 

Returns the track at the given index.

Panics

Panics if the given project is not valid anymore.

Example

use reaper_medium::ProjectContext::CurrentProject;

let track = reaper.functions().get_track(CurrentProject, 3).ok_or("No such track")?;

pub unsafe fn get_track_unchecked(
    &self,
    project: ProjectContext,
    track_index: u32
) -> Option<MediaTrack> where
    UsageScope: MainThreadOnly, 

Like get_track() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn validate_ptr_2<'a>(
    &self,
    project: ProjectContext,
    pointer: impl Into<ReaperPointer<'a>>
) -> bool

Checks if the given pointer is still valid.

Example

use reaper_medium::ProjectContext::CurrentProject;

let track = reaper.functions().get_track(CurrentProject, 0).ok_or("No track")?;
let track_is_valid = reaper.functions().validate_ptr_2(CurrentProject, track);
assert!(track_is_valid);

Returns true if the pointer is a valid object of the correct type in the given project. The project is ignored if the pointer itself is a project.

pub fn validate_ptr<'a>(&self, pointer: impl Into<ReaperPointer<'a>>) -> bool where
    UsageScope: MainThreadOnly, 

Checks if the given pointer is still valid.

Returns true if the pointer is a valid object of the correct type in the current project.

pub fn update_timeline(&self) where
    UsageScope: MainThreadOnly, 

Redraws the arrange view and ruler.

pub fn show_console_msg<'a>(&self, message: impl Into<ReaperStringArg<'a>>)

Shows a message to the user in the ReaScript console.

This is also useful for debugging. Send "\n" for newline and "" to clear the console.

pub unsafe fn get_set_media_track_info(
    &self,
    track: MediaTrack,
    attribute_key: TrackAttributeKey,
    new_value: *mut c_void
) -> *mut c_void where
    UsageScope: MainThreadOnly, 

Gets or sets a track attribute.

Returns the current value if new_value is null_mut().

It's recommended to use one of the convenience functions instead. They all start with get_set_media_track_info_ and are more type-safe.

Safety

REAPER can crash if you pass an invalid track or invalid new value.

pub unsafe fn get_set_media_track_info_get_par_track(
    &self,
    track: MediaTrack
) -> Option<MediaTrack> where
    UsageScope: MainThreadOnly, 

Convenience function which returns the given track's parent track (P_PARTRACK).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_project(
    &self,
    track: MediaTrack
) -> Option<ReaProject> where
    UsageScope: MainThreadOnly, 

Convenience function which returns the given track's parent project (P_PROJECT).

In REAPER < 5.95 this returns None.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_name<R>(
    &self,
    track: MediaTrack,
    use_name: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Convenience function which grants temporary access to the given track's name (P_NAME).

Returns None if the given track is the master track.

Example

use std::ffi::CString;
let reaper = reaper_medium::Reaper::default();

let track = reaper.functions().get_track(CurrentProject, 0).ok_or("no track")?;
let track_name_c_string = unsafe {
    reaper.functions().get_set_media_track_info_get_name(
        track,
        |name| name.to_owned()
    )
};
let track_name = match &track_name_c_string {
    None => "Master track",
    Some(name) => name.to_str()?
};
reaper.functions().show_console_msg(format!("Track name is {}", track_name));

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_rec_mon(
    &self,
    track: MediaTrack
) -> InputMonitoringMode where
    UsageScope: MainThreadOnly, 

Convenience function which returns the given track's input monitoring mode (I_RECMON).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_rec_input(
    &self,
    track: MediaTrack
) -> Option<RecordingInput> where
    UsageScope: MainThreadOnly, 

Convenience function which returns the given track's recording input (I_RECINPUT).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_track_number(
    &self,
    track: MediaTrack
) -> Option<TrackRef> where
    UsageScope: MainThreadOnly, 

Convenience function which returns the type and location of the given track (IP_TRACKNUMBER).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_media_track_info_get_guid(
    &self,
    track: MediaTrack
) -> GUID where
    UsageScope: MainThreadOnly, 

Convenience function which returns the given track's GUID (GUID).

Safety

REAPER can crash if you pass an invalid track.

pub fn is_in_real_time_audio(&self) -> bool

Returns whether we are in the real-time audio thread.

Real-time means somewhere between OnAudioBuffer calls, not in some worker or anticipative FX thread.

pub fn main_on_command_ex(
    &self,
    command: CommandId,
    flag: i32,
    project: ProjectContext
)

Performs an action belonging to the main section.

To perform non-native actions (ReaScripts, custom or extension plugin actions) safely, see named_command_lookup().

Panics

Panics if the given project is not valid anymore.

pub unsafe fn main_on_command_ex_unchecked(
    &self,
    command_id: CommandId,
    flag: i32,
    project: ProjectContext
)

Like main_on_command_ex() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub unsafe fn csurf_set_surface_mute(
    &self,
    track: MediaTrack,
    mute: bool,
    notification_behavior: NotificationBehavior
)

Mutes or unmutes the given track.

Safety

REAPER can crash if you pass an invalid track.

Example

use reaper_medium::{NotificationBehavior::NotifyAll, ProjectContext::CurrentProject};

let track = reaper.functions().get_track(CurrentProject, 0).ok_or("no tracks")?;
unsafe {
    reaper.functions().csurf_set_surface_mute(track, true, NotifyAll);
}

pub unsafe fn csurf_set_surface_solo(
    &self,
    track: MediaTrack,
    solo: bool,
    notification_behavior: NotificationBehavior
)

Soloes or unsoloes the given track.

Safety

REAPER can crash if you pass an invalid track.

pub fn gen_guid(&self) -> GUID where
    UsageScope: MainThreadOnly, 

Generates a random GUID.

pub fn section_from_unique_id<R>(
    &self,
    section_id: SectionId,
    use_section: impl FnOnce(&KbdSectionInfo) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Grants temporary access to the section with the given ID.

Example

use reaper_medium::SectionId;

let action_count =
    reaper.functions().section_from_unique_id(SectionId::new(1), |s| s.action_list_cnt());

pub unsafe fn section_from_unique_id_unchecked(
    &self,
    section_id: SectionId
) -> Option<KbdSectionInfo> where
    UsageScope: MainThreadOnly, 

Like section_from_unique_id() but returns the section.

Safety

The lifetime of the returned section is unbounded.

pub unsafe fn kbd_on_main_action_ex(
    &self,
    command_id: CommandId,
    value_change: ActionValueChange,
    window: WindowContext,
    project: ProjectContext
) -> i32 where
    UsageScope: MainThreadOnly, 

Performs an action belonging to the main section.

Unlike main_on_command_ex(), this function also allows to control actions learned with MIDI/OSC.

Safety

REAPER can crash if you pass an invalid project or window.

pub fn get_main_hwnd(&self) -> Hwnd where
    UsageScope: MainThreadOnly, 

Returns the REAPER main window handle.

pub fn named_command_lookup<'a>(
    &self,
    command_name: impl Into<ReaperStringArg<'a>>
) -> Option<CommandId> where
    UsageScope: MainThreadOnly, 

Looks up the command ID for a named command.

Named commands can be registered by extensions (e.g. _SWS_ABOUT), ReaScripts (e.g. _113088d11ae641c193a2b7ede3041ad5) or custom actions.

pub fn clear_console(&self)

Clears the ReaScript console.

pub fn count_tracks(&self, project: ProjectContext) -> u32 where
    UsageScope: MainThreadOnly, 

Returns the number of tracks in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn count_tracks_unchecked(&self, project: ProjectContext) -> u32 where
    UsageScope: MainThreadOnly, 

Like count_tracks() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn insert_track_at_index(
    &self,
    index: u32,
    defaults_behavior: TrackDefaultsBehavior
)

Creates a new track at the given index.

pub fn get_max_midi_inputs(&self) -> u32

Returns the maximum number of MIDI input devices (usually 63).

pub fn get_max_midi_outputs(&self) -> u32

Returns the maximum number of MIDI output devices (usually 64).

pub fn get_midi_input_name(
    &self,
    device_id: MidiInputDeviceId,
    buffer_size: u32
) -> GetMidiDevNameResult where
    UsageScope: MainThreadOnly, 

Returns information about the given MIDI input device.

With buffer_size you can tell REAPER how many bytes of the device name you want. If you are not interested in the device name at all, pass 0.

pub fn get_midi_output_name(
    &self,
    device_id: MidiOutputDeviceId,
    buffer_size: u32
) -> GetMidiDevNameResult where
    UsageScope: MainThreadOnly, 

Returns information about the given MIDI output device.

With buffer_size you can tell REAPER how many bytes of the device name you want. If you are not interested in the device name at all, pass 0.

pub unsafe fn track_fx_add_by_name_query<'a>(
    &self,
    track: MediaTrack,
    fx_name: impl Into<ReaperStringArg<'a>>,
    fx_chain_type: TrackFxChainType
) -> Option<u32> where
    UsageScope: MainThreadOnly, 

Returns the index of the first FX instance in a track or monitoring FX chain.

The FX name can have a prefix to further specify its type: VST3: | VST2: | VST: | AU: | JS: | DX:

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_add_by_name_add<'a>(
    &self,
    track: MediaTrack,
    fx_name: impl Into<ReaperStringArg<'a>>,
    fx_chain_type: TrackFxChainType,
    behavior: AddFxBehavior
) -> Result<u32, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Adds an instance of an FX to a track or monitoring FX chain.

See track_fx_add_by_name_query() for possible FX name prefixes.

Errors

Returns an error if the FX couldn't be added (e.g. if no such FX is installed).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_enabled(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> bool where
    UsageScope: MainThreadOnly, 

Returns whether the given track FX is enabled.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_fx_name(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    buffer_size: u32
) -> Result<CString, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the name of the given FX.

With buffer_size you can tell REAPER how many bytes of the FX name you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_instrument(&self, track: MediaTrack) -> Option<u32> where
    UsageScope: MainThreadOnly, 

Returns the index of the first track FX that is a virtual instrument.

Doesn't look in the input FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_enabled(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    is_enabled: bool
)

Enables or disables a track FX.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_num_params(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> u32 where
    UsageScope: MainThreadOnly, 

Returns the number of parameters of given track FX.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_current_project_in_load_save(&self) -> Option<ReaProject> where
    UsageScope: MainThreadOnly, 

Returns the current project if it's just being loaded or saved.

This is usually only used from project_config_extension_t.

pub unsafe fn track_fx_get_param_name(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    buffer_size: u32
) -> Result<CString, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the name of the given track FX parameter.

With buffer_size you can tell REAPER how many bytes of the parameter name you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX or parameter doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_formatted_param_value(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    buffer_size: u32
) -> Result<CString, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the current value of the given track FX parameter formatted as string.

With buffer_size you can tell REAPER how many bytes of the parameter value string you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX or parameter doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_format_param_value_normalized(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    param_value: ReaperNormalizedFxParamValue,
    buffer_size: u32
) -> Result<CString, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the given value formatted as string according to the given track FX parameter.

With buffer_size you can tell REAPER how many bytes of the parameter value string you want.

This only works with FX that supports Cockos VST extensions.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if the FX or parameter doesn't exist. Also errors if the FX doesn't support formatting arbitrary parameter values and the given value is not equal to the current one. If the given value is equal to the current one, it's just like calling track_fx_get_formatted_param_value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_param_normalized(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32,
    param_value: ReaperNormalizedFxParamValue
) -> Result<(), ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Sets the value of the given track FX parameter.

Errors

Returns an error if the FX or parameter doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_focused_fx(&self) -> Option<GetFocusedFxResult> where
    UsageScope: MainThreadOnly, 

Returns information about the (last) focused FX window.

Returns Some if an FX window has focus or was the last focused one and is still open. Returns None if no FX window has focus.

pub fn get_last_touched_fx(&self) -> Option<GetLastTouchedFxResult> where
    UsageScope: MainThreadOnly, 

Returns information about the last touched FX parameter.

Returns Some if an FX parameter has been touched already and that FX is still existing. Returns None otherwise.

pub unsafe fn track_fx_copy_to_track(
    &self,
    source: (MediaTrack, TrackFxLocation),
    destination: (MediaTrack, TrackFxLocation),
    transfer_behavior: TransferBehavior
)

Copies, moves or reorders FX.

Reorders if source and destination track are the same.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_delete(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Result<(), ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Removes the given FX from the track FX chain.

Errors

Returns an error if the FX doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_parameter_step_sizes(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> Option<GetParameterStepSizesResult> where
    UsageScope: MainThreadOnly, 

Returns information about the given FX parameter's step sizes.

Returns None if the FX parameter doesn't report step sizes or if the FX or parameter doesn't exist (there's no way to distinguish with just this function).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_param_ex(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> GetParamExResult where
    UsageScope: MainThreadOnly, 

Returns the current value and min/mid/max values of the given track FX.

Safety

REAPER can crash if you pass an invalid track.

pub fn undo_begin_block_2(&self, project: ProjectContext)

Starts a new undo block.

Panics

Panics if the given project is not valid anymore.

Example

use reaper_medium::{ProjectContext::CurrentProject, UndoScope::Scoped, ProjectPart::*};

reaper.functions().undo_begin_block_2(CurrentProject);
// ... modify something ...
reaper.functions().undo_end_block_2(CurrentProject, "Modify something", Scoped(Items | Fx));

pub unsafe fn undo_begin_block_2_unchecked(&self, project: ProjectContext)

Like undo_begin_block_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_end_block_2<'a>(
    &self,
    project: ProjectContext,
    description: impl Into<ReaperStringArg<'a>>,
    scope: UndoScope
)

Ends the current undo block.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_end_block_2_unchecked<'a>(
    &self,
    project: ProjectContext,
    description: impl Into<ReaperStringArg<'a>>,
    scope: UndoScope
)

Like undo_end_block_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_can_undo_2<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Grants temporary access to the the description of the last undoable operation, if any.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_can_undo_2_unchecked<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Like undo_can_undo_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_can_redo_2<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Grants temporary access to the description of the next redoable operation, if any.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_can_redo_2_unchecked<R>(
    &self,
    project: ProjectContext,
    use_description: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Like undo_can_redo_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_do_undo_2(&self, project: ProjectContext) -> bool where
    UsageScope: MainThreadOnly, 

Makes the last undoable operation undone.

Returns false if there was nothing to be undone.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_do_undo_2_unchecked(&self, project: ProjectContext) -> bool where
    UsageScope: MainThreadOnly, 

Like undo_do_undo_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn undo_do_redo_2(&self, project: ProjectContext) -> bool where
    UsageScope: MainThreadOnly, 

Executes the next redoable action.

Returns false if there was nothing to be redone.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn undo_do_redo_2_unchecked(&self, project: ProjectContext) -> bool where
    UsageScope: MainThreadOnly, 

Like undo_do_redo_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn mark_project_dirty(&self, project: ProjectContext)

Marks the given project as dirty.

Dirty means the project needs to be saved. Only makes a difference if "Maximum undo memory" is not 0 in REAPER's preferences (0 disables undo/prompt to save).

Panics

Panics if the given project is not valid anymore.

pub unsafe fn mark_project_dirty_unchecked(&self, project: ProjectContext)

Like mark_project_dirty() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn is_project_dirty(&self, project: ProjectContext) -> bool where
    UsageScope: MainThreadOnly, 

Returns whether the given project is dirty.

Always returns false if "Maximum undo memory" is 0 in REAPER's preferences.

Also see mark_project_dirty()

Panics

Panics if the given project is not valid anymore.

pub unsafe fn is_project_dirty_unchecked(&self, project: ProjectContext) -> bool where
    UsageScope: MainThreadOnly, 

Like is_project_dirty() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn track_list_update_all_external_surfaces(&self)

Notifies all control surfaces that something in the track list has changed.

Behavior not confirmed.

pub fn get_app_version(&self) -> ReaperVersion<'static> where
    UsageScope: MainThreadOnly, 

Returns the version of the REAPER application in which this plug-in is currently running.

pub unsafe fn get_track_automation_mode(
    &self,
    track: MediaTrack
) -> AutomationMode where
    UsageScope: MainThreadOnly, 

Returns the track automation mode, regardless of the global override.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_global_automation_override(
    &self
) -> Option<GlobalAutomationModeOverride> where
    UsageScope: MainThreadOnly, 

Returns the global track automation override, if any.

pub unsafe fn get_track_envelope_by_chunk_name(
    &self,
    track: MediaTrack,
    chunk_name: EnvChunkName
) -> Option<TrackEnvelope> where
    UsageScope: MainThreadOnly, 

Returns the track envelope for the given track and configuration chunk name.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_envelope_by_name<'a>(
    &self,
    track: MediaTrack,
    env_name: impl Into<ReaperStringArg<'a>>
) -> Option<TrackEnvelope> where
    UsageScope: MainThreadOnly, 

Returns the track envelope for the given track and envelope display name.

For getting common envelopes (like volume or pan) using get_track_envelope_by_chunk_name() is better because it provides more type safety.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_media_track_info_value(
    &self,
    track: MediaTrack,
    attribute_key: TrackAttributeKey
) -> f64 where
    UsageScope: MainThreadOnly, 

Gets a track attribute as numerical value.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_count(&self, track: MediaTrack) -> u32 where
    UsageScope: MainThreadOnly, 

Gets the number of FX instances on the given track's normal FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_rec_count(&self, track: MediaTrack) -> u32 where
    UsageScope: MainThreadOnly, 

Gets the number of FX instances on the given track's input FX chain.

On the master track, this refers to the monitoring FX chain.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_fx_guid(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Result<GUID, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the GUID of the given track FX.

Errors

Returns an error if the FX doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_param_normalized(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    param_index: u32
) -> Result<ReaperNormalizedFxParamValue, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the current value of the given track FX in REAPER-normalized form.

Errors

Returns an error if the FX or parameter doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_master_track(&self, project: ProjectContext) -> MediaTrack where
    UsageScope: MainThreadOnly, 

Returns the master track of the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_master_track_unchecked(
    &self,
    project: ProjectContext
) -> MediaTrack where
    UsageScope: MainThreadOnly, 

Like get_master_track() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn guid_to_string(&self, guid: &GUID) -> CString where
    UsageScope: MainThreadOnly, 

Converts the given GUID to a string (including braces).

pub fn master_get_tempo(&self) -> Bpm where
    UsageScope: MainThreadOnly, 

Returns the master tempo of the current project.

pub fn set_current_bpm(
    &self,
    project: ProjectContext,
    tempo: Bpm,
    undo_behavior: UndoBehavior
)

Sets the current tempo of the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn set_current_bpm_unchecked(
    &self,
    project: ProjectContext,
    tempo: Bpm,
    undo_behavior: UndoBehavior
)

Like set_current_bpm() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn master_get_play_rate(
    &self,
    project: ProjectContext
) -> PlaybackSpeedFactor where
    UsageScope: MainThreadOnly, 

Returns the master play rate of the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn master_get_play_rate_unchecked(
    &self,
    project: ProjectContext
) -> PlaybackSpeedFactor where
    UsageScope: MainThreadOnly, 

Like master_get_play_rate() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub fn csurf_on_play_rate_change(&self, play_rate: PlaybackSpeedFactor)

Sets the master play rate of the current project.

pub fn show_message_box<'a>(
    &self,
    message: impl Into<ReaperStringArg<'a>>,
    title: impl Into<ReaperStringArg<'a>>,
    r#type: MessageBoxType
) -> MessageBoxResult where
    UsageScope: MainThreadOnly, 

Shows a message box to the user.

Blocks the main thread.

pub fn string_to_guid<'a>(
    &self,
    guid_string: impl Into<ReaperStringArg<'a>>
) -> Result<GUID, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Parses the given string as GUID.

Errors

Returns an error if the given string is not a valid GUID string.

pub unsafe fn csurf_on_input_monitoring_change_ex(
    &self,
    track: MediaTrack,
    mode: InputMonitoringMode,
    gang_behavior: GangBehavior
) -> i32 where
    UsageScope: MainThreadOnly, 

Sets the input monitoring mode of the given track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_media_track_info_value(
    &self,
    track: MediaTrack,
    attribute_key: TrackAttributeKey,
    new_value: f64
) -> Result<(), ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Sets a track attribute as numerical value.

Errors

Returns an error if an invalid (e.g. non-numerical) track attribute key is passed.

Safety

REAPER can crash if you pass an invalid track.

pub fn stuff_midimessage(
    &self,
    target: StuffMidiMessageTarget,
    message: impl ShortMessage
)

Stuffs a 3-byte MIDI message into a queue or send it to an external MIDI hardware.

pub fn db2slider(&self, value: Db) -> VolumeSliderValue where
    UsageScope: MainThreadOnly, 

Converts a decibel value into a volume slider value.

pub fn slider2db(&self, value: VolumeSliderValue) -> Db where
    UsageScope: MainThreadOnly, 

Converts a volume slider value into a decibel value.

pub unsafe fn get_track_ui_vol_pan(
    &self,
    track: MediaTrack
) -> Result<VolumeAndPan, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the given track's volume and pan.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_set_surface_volume(
    &self,
    track: MediaTrack,
    volume: ReaperVolumeValue,
    notification_behavior: NotificationBehavior
)

Sets the given track's volume.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_volume_change_ex(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperVolumeValue>,
    gang_behavior: GangBehavior
) -> ReaperVolumeValue where
    UsageScope: MainThreadOnly, 

Sets the given track's volume, also supports relative changes and gang.

Returns the value that has actually been set. I think this only deviates if 0.0 is sent. Then it returns a slightly higher value - the one which actually corresponds to -150 dB.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_set_surface_pan(
    &self,
    track: MediaTrack,
    pan: ReaperPanValue,
    notification_behavior: NotificationBehavior
)

Sets the given track's pan.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_pan_change_ex(
    &self,
    track: MediaTrack,
    value_change: ValueChange<ReaperPanValue>,
    gang_behavior: GangBehavior
) -> ReaperPanValue where
    UsageScope: MainThreadOnly, 

Sets the given track's pan. Also supports relative changes and gang.

Returns the value that has actually been set.

Safety

REAPER can crash if you pass an invalid track.

pub fn count_selected_tracks_2(
    &self,
    project: ProjectContext,
    master_track_behavior: MasterTrackBehavior
) -> u32 where
    UsageScope: MainThreadOnly, 

Counts the number of selected tracks in the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn count_selected_tracks_2_unchecked(
    &self,
    project: ProjectContext,
    master_track_behavior: MasterTrackBehavior
) -> u32 where
    UsageScope: MainThreadOnly, 

Like count_selected_tracks_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub unsafe fn set_track_selected(&self, track: MediaTrack, is_selected: bool)

Selects or deselects the given track.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_selected_track_2(
    &self,
    project: ProjectContext,
    selected_track_index: u32,
    master_track_behavior: MasterTrackBehavior
) -> Option<MediaTrack> where
    UsageScope: MainThreadOnly, 

Returns a selected track from the given project.

Panics

Panics if the given project is not valid anymore.

pub unsafe fn get_selected_track_2_unchecked(
    &self,
    project: ProjectContext,
    selected_track_index: u32,
    master_track_behavior: MasterTrackBehavior
) -> Option<MediaTrack> where
    UsageScope: MainThreadOnly, 

Like get_selected_track_2() but doesn't check if project is valid.

Safety

REAPER can crash if you pass an invalid project.

pub unsafe fn set_only_track_selected(&self, track: Option<MediaTrack>)

Selects exactly one track and deselects all others.

If None is passed, deselects all tracks.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn delete_track(&self, track: MediaTrack)

Deletes the given track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_num_sends(
    &self,
    track: MediaTrack,
    category: TrackSendCategory
) -> u32 where
    UsageScope: MainThreadOnly, 

Returns the number of sends, receives or hardware outputs of the given track.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_set_track_send_info(
    &self,
    track: MediaTrack,
    category: TrackSendCategory,
    send_index: u32,
    attribute_key: TrackSendAttributeKey,
    new_value: *mut c_void
) -> *mut c_void where
    UsageScope: MainThreadOnly, 

Returns the current value if new_value is null_mut().

Safety

REAPER can crash if you pass an invalid track or invalid new value.

pub unsafe fn get_track_send_info_desttrack(
    &self,
    track: MediaTrack,
    direction: TrackSendDirection,
    send_index: u32
) -> Result<MediaTrack, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Convenience function which returns the destination track (P_DESTTRACK) of the given send or receive.

Errors

Returns an error e.g. if the send or receive doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn get_track_state_chunk(
    &self,
    track: MediaTrack,
    buffer_size: u32,
    cache_hint: ChunkCacheHint
) -> Result<CString, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the RPPXML state of the given track.

With buffer_size you can tell REAPER how many bytes of the chunk you want.

Panics

Panics if the given buffer size is 0.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn create_track_send(
    &self,
    track: MediaTrack,
    target: SendTarget
) -> Result<u32, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Creates a send, receive or hardware output for the given track.

Returns the index of the created send or receive.

Errors

Returns an error if not successful (unclear when this happens).

Safety

REAPER can crash if you pass an invalid track.

Example

use reaper_medium::{ProjectContext::CurrentProject, SendTarget::HardwareOutput};

let src_track = reaper.functions().get_track(CurrentProject, 0).ok_or("no tracks")?;
let send_index = unsafe {
    reaper.functions().create_track_send(src_track, HardwareOutput)?;
};

pub unsafe fn csurf_on_rec_arm_change_ex(
    &self,
    track: MediaTrack,
    mode: RecordArmMode,
    gang_behavior: GangBehavior
) -> bool where
    UsageScope: MainThreadOnly, 

Arms or unarms the given track for recording.

Seems to return true if it was armed and false if not.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn set_track_state_chunk<'a>(
    &self,
    track: MediaTrack,
    chunk: impl Into<ReaperStringArg<'a>>,
    cache_hint: ChunkCacheHint
) -> Result<(), ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Sets the RPPXML state of the given track.

Errors

Returns an error if not successful (for example if the given chunk is not accepted).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_show(
    &self,
    track: MediaTrack,
    instruction: FxShowInstruction
)

Shows or hides an FX user interface.

pub unsafe fn track_fx_get_floating_window(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Option<Hwnd> where
    UsageScope: MainThreadOnly, 

Returns the floating window handle of the given FX, if there is any.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_open(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> bool where
    UsageScope: MainThreadOnly, 

Returns whether the user interface of the given FX is open.

Open means either visible in the FX chain window or visible in a floating window.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_send_volume_change(
    &self,
    track: MediaTrack,
    send_index: u32,
    value_change: ValueChange<ReaperVolumeValue>
) -> ReaperVolumeValue where
    UsageScope: MainThreadOnly, 

Sets the given track send's volume.

Returns the value that has actually been set. If the send doesn't exist, returns 0.0 (which can also be a valid value that has been set, so that's not very useful).

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn csurf_on_send_pan_change(
    &self,
    track: MediaTrack,
    send_index: u32,
    value_change: ValueChange<ReaperPanValue>
) -> ReaperPanValue where
    UsageScope: MainThreadOnly, 

Sets the given track send's pan.

Returns the value that has actually been set.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn kbd_get_text_from_cmd<R>(
    &self,
    command_id: CommandId,
    section: SectionContext,
    use_action_name: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Grants temporary access to the name of the action registered under the given command ID within the specified section.

Returns None if the action doesn't exist.

Safety

REAPER can crash if you pass an invalid section.

pub unsafe fn get_toggle_command_state_2(
    &self,
    section: SectionContext,
    command_id: CommandId
) -> Option<bool> where
    UsageScope: MainThreadOnly, 

Returns the current on/off state of a toggleable action.

Returns None if the action doesn't support on/off states (or if the action doesn't exist).

Safety

REAPER can crash if you pass an invalid section.

pub fn reverse_named_command_lookup<R>(
    &self,
    command_id: CommandId,
    use_command_name: impl FnOnce(&CStr) -> R
) -> Option<R> where
    UsageScope: MainThreadOnly, 

Grants temporary access to the name of the command registered under the given command ID.

The string will not start with _ (e.g. it will return SWS_ABOUT).

Returns None if the given command ID is a built-in action or if there's no such ID.

pub unsafe fn get_track_send_ui_vol_pan(
    &self,
    track: MediaTrack,
    send_index: u32
) -> Result<VolumeAndPan, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns a track send's volume and pan.

Errors

Returns an error if the send doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_get_preset_index(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation
) -> Result<TrackFxGetPresetIndexResult, ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Returns the index of the currently selected FX preset as well as the total preset count.

Errors

Returns an error e.g. if the FX doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_set_preset_by_index(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    preset: FxPresetRef
) -> Result<(), ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Selects a preset of the given track FX.

Errors

Returns an error e.g. if the FX doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

pub unsafe fn track_fx_navigate_presets(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    increment: i32
) -> Result<(), ReaperFunctionError> where
    UsageScope: MainThreadOnly, 

Navigates within the presets of the given track FX.

Errors

Returns an error e.g. if the FX doesn't exist.

Safety

REAPER can crash if you pass an invalid track.

Example

use reaper_medium::ProjectContext::CurrentProject;
use reaper_medium::TrackFxLocation::NormalFxChain;

let track = reaper.functions().get_track(CurrentProject, 0).ok_or("no tracks")?;
// Navigate 2 presets "up"
unsafe {
    reaper.functions().track_fx_navigate_presets(track, NormalFxChain(0), -2)?
};

pub unsafe fn track_fx_get_preset(
    &self,
    track: MediaTrack,
    fx_location: TrackFxLocation,
    buffer_size: u32
) -> TrackFxGetPresetResult where
    UsageScope: MainThreadOnly, 

Returns information about the currently selected preset of the given FX.

Currently selected means the preset which is currently showing in the REAPER dropdown.

With buffer size you can tell REAPER how many bytes of the preset name you want. If you are not interested in the preset name at all, pass 0.

Safety

REAPER can crash if you pass an invalid track.

pub fn get_midi_input<R>(
    &self,
    device_id: MidiInputDeviceId,
    use_device: impl FnOnce(&MidiInput) -> R
) -> Option<R> where
    UsageScope: AudioThreadOnly, 

Grants temporary access to an already open MIDI input device.

Returns None if the device doesn't exist, is not connected or is not already opened. The device must be enabled in REAPER's MIDI preferences.

This function is typically called in the audio hook. But it's also okay to call it in a VST plug-in as long as is_in_real_time_audio() returns true.

See audio hook for an example.

Design

The device is not just returned because then we would have to mark this function as unsafe. Returning the device would tempt the consumer to cache the pointer somewhere, which is bad because the MIDI device can appear/disappear anytime and REAPER doesn't notify us about it. If we would call get_read_buf() on a cached pointer and the MIDI device is gone, REAPER would crash.

Calling this function in every audio hook invocation is fast enough and the official way to tap MIDI messages directly. Because of that we take a closure and pass a reference.

Trait Implementations

impl<UsageScope: Clone> Clone for ReaperFunctions<UsageScope>

fn clone(&self) -> ReaperFunctions<UsageScope>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<UsageScope: Debug> Debug for ReaperFunctions<UsageScope>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<UsageScope: Default> Default for ReaperFunctions<UsageScope>

fn default() -> ReaperFunctions<UsageScope>

Returns the "default value" for a type.