reaper_medium

Struct ReaperFunctions

Source 
pub struct ReaperFunctions<UsageScope = MainThreadScope> { /* private fields */ }
Expand description

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§

Source§

impl<UsageScope> ReaperFunctions<UsageScope>

Source

pub fn low(&self) -> &Reaper

Gives access to the low-level Reaper instance.

Source

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();
Source

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")?;
Source

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.

Source

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.

Source

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.

Source

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

Redraws the arrange view and ruler.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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);
}
Source

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.

Source

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

Generates a random GUID.

Source

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());
Source

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.

Source

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.

Source

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

Returns the REAPER main window handle.

Source

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.

Source

pub fn clear_console(&self)

Clears the ReaScript console.

Source

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.

Source

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.

Source

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

Creates a new track at the given index.

Source

pub fn get_max_midi_inputs(&self) -> u32

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

Source

pub fn get_max_midi_outputs(&self) -> u32

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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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));
Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn track_list_update_all_external_surfaces(&self)

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

Behavior not confirmed.

Source

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.

Source

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.

Source

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

Returns the global track automation override, if any.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

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

Source

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

Returns the master tempo of the current project.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn csurf_on_play_rate_change(&self, play_rate: PlaybackSpeedFactor)

Sets the master play rate of the current project.

Source

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

Shows a message box to the user.

Blocks the main thread.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Converts a decibel value into a volume slider value.

Source

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

Converts a volume slider value into a decibel value.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Deletes the given track.

§Safety

REAPER can crash if you pass an invalid track.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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)?;
};
Source

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.

Source

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.

Source

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

Shows or hides an FX user interface.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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)?
};
Source

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.

Source

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§

Source§

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

Source§

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

Returns a copy of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

fn default() -> ReaperFunctions<UsageScope>

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl<UsageScope> Freeze for ReaperFunctions<UsageScope>

§

impl<UsageScope> RefUnwindSafe for ReaperFunctions<UsageScope>
where UsageScope: RefUnwindSafe,

§

impl<UsageScope> Send for ReaperFunctions<UsageScope>
where UsageScope: Send,

§

impl<UsageScope> Sync for ReaperFunctions<UsageScope>
where UsageScope: Sync,

§

impl<UsageScope> Unpin for ReaperFunctions<UsageScope>
where UsageScope: Unpin,

§

impl<UsageScope> UnwindSafe for ReaperFunctions<UsageScope>
where UsageScope: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.