1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397
//! General Plugin-related traits and functions. use crate::{Feature, FeaturesList}; use std::ffi::CStr; use std::os::raw::*; /** Plugin Instance Handle. */ pub type Handle = *mut c_void; /** Plugin Descriptor. This structure provides the core functions necessary to instantiate and use a plugin. */ #[repr(C)] pub struct Descriptor { /** A globally unique, case-sensitive identifier for this plugin. This MUST be a valid URI string as defined by RFC 3986. All plugins with the same URI MUST be compatible to some degree, see http://lv2plug.in/ns/lv2core for details. */ pub uri: *const c_char, /** Instantiate the plugin. Note that instance initialisation should generally occur in activate() rather than here. If a host calls instantiate(), it MUST call cleanup() at some point in the future. descriptor: Descriptor of the plugin to instantiate. sample_rate: Sample rate, in Hz, for the new plugin instance. bundle_path: Path to the LV2 bundle which contains this plugin binary. It MUST include the trailing directory separator (e.g. '/') so that simply appending a filename will yield the path to that file in the bundle. features: A NULL terminated array of LV2_Feature structs which represent the features the host supports. Plugins may refuse to instantiate if required features are not found here. However, hosts MUST NOT use this as a discovery mechanism: instead, use the RDF data to determine which features are required and do not attempt to instantiate unsupported plugins at all. This parameter MUST NOT be NULL, i.e. a host that supports no features MUST pass a single element array containing NULL. return value: A handle for the new plugin instance, or NULL if instantiation has failed. */ pub instantiate: unsafe extern "C" fn( descriptor: *const Descriptor, sample_rate: f64, bundle_path: *const c_char, features: *const *const Feature, ) -> Handle, /** Connect a port on a plugin instance to a memory location. Plugin writers should be aware that the host may elect to use the same buffer for more than one port and even use the same buffer for both input and output (see lv2:inPlaceBroken in lv2.ttl). If the plugin has the feature lv2:hardRTCapable then there are various things that the plugin MUST NOT do within the connect_port() function; see lv2core.ttl for details. connect_port() MUST be called at least once for each port before run() is called, unless that port is lv2:connectionOptional. The plugin must pay careful attention to the block size passed to run() since the block allocated may only just be large enough to contain the data, and is not guaranteed to remain constant between run() calls. connect_port() may be called more than once for a plugin instance to allow the host to change the buffers that the plugin is reading or writing. These calls may be made before or after activate() or deactivate() calls. instance: Plugin instance containing the port. port: Index of the port to connect. The host MUST NOT try to connect a port index that is not defined in the plugin's RDF data. If it does, the plugin's behaviour is undefined (a crash is likely). data_location: Pointer to data of the type defined by the port type in the plugin's RDF data (e.g. an array of float for an lv2:AudioPort). This pointer must be stored by the plugin instance and used to read/write data when run() is called. Data present at the time of the connect_port() call MUST NOT be considered meaningful. */ pub connect_port: unsafe extern "C" fn(instance: Handle, port: u32, data_location: *mut c_void), /** Initialise a plugin instance and activate it for use. This is separated from instantiate() to aid real-time support and so that hosts can reinitialise a plugin instance by calling deactivate() and then activate(). In this case the plugin instance MUST reset all state information dependent on the history of the plugin instance except for any data locations provided by connect_port(). If there is nothing for activate() to do then this field may be NULL. When present, hosts MUST call this function once before run() is called for the first time. This call SHOULD be made as close to the run() call as possible and indicates to real-time plugins that they are now live, however plugins MUST NOT rely on a prompt call to run() after activate(). The host MUST NOT call activate() again until deactivate() has been called first. If a host calls activate(), it MUST call deactivate() at some point in the future. Note that connect_port() may be called before or after activate(). */ pub activate: unsafe extern "C" fn(instance: Handle), /** Run a plugin instance for a block. Note that if an activate() function exists then it must be called before run(). If deactivate() is called for a plugin instance then run() may not be called until activate() has been called again. If the plugin has the feature lv2:hardRTCapable then there are various things that the plugin MUST NOT do within the run() function (see lv2core.ttl for details). As a special case, when `sample_count` is 0, the plugin should update any output ports that represent a single instant in time (e.g. control ports, but not audio ports). This is particularly useful for latent plugins, which should update their latency output port so hosts can pre-roll plugins to compute latency. Plugins MUST NOT crash when `sample_count` is 0. instance: Instance to be run. sample_count: The block size (in samples) for which the plugin instance must run. */ pub run: unsafe extern "C" fn(instance: Handle, n_samples: u32), /** Deactivate a plugin instance (counterpart to activate()). Hosts MUST deactivate all activated instances after they have been run() for the last time. This call SHOULD be made as close to the last run() call as possible and indicates to real-time plugins that they are no longer live, however plugins MUST NOT rely on prompt deactivation. If there is nothing for deactivate() to do then this field may be NULL Deactivation is not similar to pausing since the plugin instance will be reinitialised by activate(). However, deactivate() itself MUST NOT fully reset plugin state. For example, the host may deactivate a plugin, then store its state (using some extension to do so). Hosts MUST NOT call deactivate() unless activate() was previously called. Note that connect_port() may be called before or after deactivate(). */ pub deactivate: unsafe extern "C" fn(instance: Handle), /** Clean up a plugin instance (counterpart to instantiate()). Once an instance of a plugin has been finished with it must be deleted using this function. The instance handle passed ceases to be valid after this call. If activate() was called for a plugin instance then a corresponding call to deactivate() MUST be made before cleanup() is called. Hosts MUST NOT call cleanup() unless instantiate() was previously called. */ pub cleanup: unsafe extern "C" fn(instance: Handle), /** Return additional plugin data defined by some extenion. A typical use of this facility is to return a struct containing function pointers to extend the LV2_Descriptor API. The actual type and meaning of the returned object MUST be specified precisely by the extension. This function MUST return NULL for any unsupported URI. If a plugin does not support any extension data, this field may be NULL. The host is never responsible for freeing the returned value. */ pub extension_data: unsafe extern "C" fn(uri: *const c_char) -> *const c_void, } /// LV2 plugin trait. /// /// This trait helps you implementing plugins, since it requires you to implement all /// necessary functions. /// /// Almost every plugin function call from the host will be checked and "safed" before these trait /// functions are called. Therefore, all of them are safe. pub trait Plugin { /// Create a new instance of the plugin. /// /// Here, you should instantiate the plugin and supply it with general information. You can look /// at the plugin descriptor, the audio frame rate of the current session, the path from which /// the host has loaded the plugin and an slice of references to the features supported by the /// host. If, for one reason or another, you find yourself in a situation where you can't /// create a plugin instance, you can return `None`. fn instantiate( descriptor: &Descriptor, rate: f64, bundle_path: &CStr, features: Option<&FeaturesList>, ) -> Option<Self> where Self: Sized; /// Set internal data pointers. /// /// This function will be called by the host when the location of a port has changed and the /// plugin should update it's internal pointers. /// /// When this function is called, the data pointers may not be valid yet and therefore, you /// shouldn't use them. fn connect_port(&mut self, port: u32, data: *mut ()); /// Activate the plugin. /// /// If your plugin can be turned on or off, you should override this function and set the plugin /// up for active use. /// /// The default implementation does nothing. fn activate(&mut self) {} /// Run plugin specific operations. /// /// This is where the action happens! Here, you should execute the actions that make your plugin /// unique. /// /// Pointers, which were previously set by the [`connect_port`](#tyfunction.connect_port) /// function are guaranteed to be valid now. If they aren't, it's the host's fault, not yours. /// Also, sample arrays or atom sequence will have a length of `n_samples` elements. This /// number may change during the life time of the plugin and therefore, you should not store /// it somewhere. fn run(&mut self, n_samples: u32); /// Deactivate the plugin. /// /// If your plugin can be turned on or off, you should override this function and destroy the /// plugins active state. /// /// The default implementation does nothing. fn deactivate(&mut self) {} /// Return extension specific data to the host. /// /// Some LV2 extensions require special data from a plugin in order to work. This is where you /// provide the data. The passed C string reference is the URI of the extension in question and /// you can return a static reference to some data. If you do not know the passed URI, you /// should return `None`. /// /// The return value must be a static reference since we don't know how long it needs to be /// alive; as stated in the [LV2 header](http://lv2plug.in/doc/html/group__core.html#ae907a7668d6579f099ac08c134b2e634), /// the host is not responsible for freeing the returned value. Therefore, the referenced data /// need to live for the entirety of the program. fn extension_data(_uri: &CStr) -> Option<&'static ExtensionData> { None } } /// Marker trait for extension data. /// /// This trait was introduced in order to make a [`Plugin`](trait.Plugin.html)'s /// [`extension_data`](trait.Plugin.html#method.extension_data) function more dynamic. /// Apart from that, it has absolutely no meaning. pub trait ExtensionData {} /// Helper function for the `instantiate` plugin call. /// /// This function takes the raw parameters provided by the C API and turns them into safe Rust data /// types. Only functions generated by the `lv2_main` should call the function any other should not. pub unsafe fn instantiate<P: Plugin>( descriptor: *const Descriptor, rate: f64, bundle_path: *const c_char, features: *const *const Feature, ) -> Handle { let descriptor = match descriptor.as_ref() { Some(desc) => desc, None => return std::ptr::null_mut(), }; let bundle_path = if bundle_path.is_null() { return std::ptr::null_mut(); } else { CStr::from_ptr(bundle_path as *const c_char) }; let features = { if features.is_null() { None } else { let mut length = 0; let mut features_cp = features; loop { match features_cp.as_ref() { Some(feature) => { if feature.is_null() { break; } else { length += 1; features_cp = features_cp.add(1); } } None => return std::ptr::null_mut(), } } Some(std::slice::from_raw_parts( features as *const &'static Feature, length, )) } }; match P::instantiate(descriptor, rate, bundle_path, features) { Some(instance) => { let instance = Box::new(instance); Box::leak(instance) as *const P as Handle } None => std::ptr::null_mut(), } } /// Helper function for the `connect_port` plugin call. /// /// This function takes the raw parameters provided by the C API and turns them into safe Rust data /// types. Only functions generated by the `lv2_main` should call the function any other should not. pub unsafe fn connect_port<P: Plugin>(instance: Handle, port: u32, data: *mut c_void) { let instance = (instance as *mut P).as_mut().unwrap(); instance.connect_port(port, data as *mut ()); } /// Helper function for the `activate` plugin call. /// /// This function takes the raw parameters provided by the C API, turns them into safe Rust data /// types, and calls the trait's function. Only functions generated by the `lv2_main` should call /// this function, any other must not. pub unsafe fn activate<P: Plugin>(instance: Handle) { let instance = (instance as *mut P).as_mut().unwrap(); instance.activate(); } /// Helper function for the `run` plugin call. /// /// This function takes the raw parameters provided by the C API, turns them into safe Rust data /// types, and calls the trait's function. Only functions generated by the `lv2_main` should call /// this function, any other must not. pub unsafe fn run<P: Plugin>(instance: Handle, n_samples: u32) { let instance = (instance as *mut P).as_mut().unwrap(); instance.run(n_samples); } /// Helper function for the `deactivate` plugin call. /// /// This function takes the raw parameters provided by the C API, turns them into safe Rust data /// types, and calls the trait's function. Only functions generated by the `lv2_main` should call /// this function, any other must not. pub unsafe fn deactivate<P: Plugin>(instance: Handle) { let instance = (instance as *mut P).as_mut().unwrap(); instance.deactivate(); } /// Helper function for the `cleanup` plugin call. /// /// This function takes the raw parameters provided by the C API, turns them into safe Rust data /// types, and calls the trait's function. Only functions generated by the `lv2_main` should call /// this function, any other must not. pub unsafe fn cleanup<P: Plugin>(instance: Handle) { core::ptr::drop_in_place(instance as *mut P); } /// Helper function for the `extension_data` plugin call. /// /// This function takes the raw parameters provided by the C API, turns them into safe Rust data /// types, and calls the trait's function. Only functions generated by the `lv2_main` should call /// this function, any other must not. pub unsafe fn extension_data<P: Plugin>(uri: *const c_char) -> *const c_void { let uri = CStr::from_ptr(uri); let result = P::extension_data(uri); std::mem::forget(uri); match result { Some(ext_data) => ext_data as *const ExtensionData as *const c_void, None => std::ptr::null(), } }