lv2_wrapper.h

Design notes

effect:      [0..P-1] control in | [P] audio in L | [P+1] in R
             | [P+2] out L | [P+3] out R
instrument:  [0..P-1] control in | [P] atom MIDI in | [P+1] out L | [P+2] out R

Types 4

Functions 44

• fninline const char* outputGuardWork()
  What run() hands the worker to have the output guard's report made: an exact byte string, which no file-load payload can equal (a payload ends with a path after the purpose's terminator, and this ends at its own).
  lv2::outputGuardWork · lv2_wrapper.h:122
• fninline void pluginUri(char* out, size_t capacity)
  The plugin URI: derived from the reverse-DNS id, which is already unique per product. LV2 identifies plugins by URI exactly as VST3 does by UID.
  lv2::pluginUri · lv2_wrapper.h:133
• fninline LV2_Handle instantiate(const LV2_Descriptor*, double sampleRate, const char*, const LV2_Feature* const* features)lv2::instantiate · lv2_wrapper.h:280
• fninline void updateFreeWheel(Plugin* self)
  Re-run prepare() when the host starts or stops freewheeling.
  lv2::updateFreeWheel · lv2_wrapper.h:345
• fninline void connectPort(LV2_Handle handle, uint32_t port, void* data)lv2::connectPort · lv2_wrapper.h:360
• fninline void refreshUiState(Plugin* self)
  Rebuild the answer an interface gets when it asks what the plugin has.
  lv2::refreshUiState · lv2_wrapper.h:444
• fninline void freeRetiredUiText(Plugin* self)
  [worker-thread or main-thread] Free what work_response() has finished with. Never on the audio thread, which only pushes.
  lv2::freeRetiredUiText · lv2_wrapper.h:454
• fninline void activate(LV2_Handle handle)lv2::activate · lv2_wrapper.h:468
• fninline void claimMidiOut(Plugin* self)
  Claim the MIDI output buffer for this run(): note the host's capacity and leave an empty sequence, whatever follows. First thing in run(), because a host reads atom.size back as how much was written -- and a run() of zero frames, or one that returned early, claimed it nowhere and left the capacity there, which reads as a buffer full of events.
  lv2::claimMidiOut · lv2_wrapper.h:500
• fninline void writeMidiOut(Plugin* self, uint32_t frameOffset, uint32_t frames)
  Append this slice's emitted MIDI to the host's output sequence.
  lv2::writeMidiOut · lv2_wrapper.h:516
• fninline void writeUiNotify(Plugin* self)
  [audio-thread] Put the state on the notify port, if anything is owed.
  lv2::writeUiNotify · lv2_wrapper.h:582
• fninline bool atomNumber(const Plugin* self, const LV2_Atom* a, double* out)
  A number out of an atom of any of the four types a host may send one in.
  lv2::atomNumber · lv2_wrapper.h:644
• fninline bool readTimePosition(Plugin* self, const LV2_Atom* obj)
  [audio-thread] Take a time:Position into the transport.
  lv2::readTimePosition · lv2_wrapper.h:663
• fninline void advanceTransport(Plugin* self, uint32_t frames)
  [audio-thread] Carry the transport over frames at the host's speed, so the next run() starts where this one ended.
  lv2::advanceTransport · lv2_wrapper.h:714
• fninline void ttlNumber(char* out, size_t capacity, float value)
  A float as Turtle: the fewest significant digits that read back as the same float, with a full stop whatever the locale. %g gave six, so a default of 0.70710678 was published as 0.707107 -- a different float, and a host that resets a control to its default put it somewhere the plugin never did. Nine is always enough; 0.1 still prints as 0.1.
  lv2::ttlNumber · lv2_wrapper.h:737
• fninline int frameInRun(int64_t frame, uint32_t sampleCount)
  An atom event's frame, clamped into a run of sampleCount: at or past the end a note-off was never reached and the note hung, and a frame past what an int holds came out negative (see clapwrap::eventTime).
  lv2::frameInRun · lv2_wrapper.h:749
• fninline void run(LV2_Handle handle, uint32_t sampleCount)lv2::run · lv2_wrapper.h:754
• fninline void reportOutputGuard(Plugin* self)
  [worker-thread or main-thread] The output guard's report, once: a warning in the host's log where it gave one, stderr otherwise. Never run(): the log's printf is for non-realtime contexts only.
  lv2::reportOutputGuard · lv2_wrapper.h:987
• fninline Lv2WorkerStatus workerWork(LV2_Handle handle, Lv2WorkerRespondFunction respond, Lv2WorkerRespondHandle responder, uint32_t size, const void* data)
  [worker-thread] Read the file the interface picked.
  lv2::workerWork · lv2_wrapper.h:1009
• fninline Lv2WorkerStatus workerResponse(LV2_Handle handle, uint32_t size, const void* data)
  [audio-thread] The worker finished. Swapping two std::strings moves two pointers and allocates nothing, and pushing the husk is a compare-and-swap, which is what makes this legal here.
  lv2::workerResponse · lv2_wrapper.h:1059
• fninline void deactivate(LV2_Handle handle)
  Instantiation class, so not realtime: the output guard's report for a host with no worker, or one whose worker has not got to it yet.
  lv2::deactivate · lv2_wrapper.h:1082
• fninline void cleanup(LV2_Handle handle)lv2::cleanup · lv2_wrapper.h:1084
• fninline LV2_State_Status stateSave(LV2_Handle handle, LV2_State_Store_Function store, LV2_State_Handle host, uint32_t, const LV2_Feature* const*)lv2::stateSave · lv2_wrapper.h:1099
• fninline LV2_State_Status stateRestore(LV2_Handle handle, LV2_State_Retrieve_Function retrieve, LV2_State_Handle host, uint32_t, const LV2_Feature* const*)lv2::stateRestore · lv2_wrapper.h:1132
• fninline const void* extensionData(const char* uri)lv2::extensionData · lv2_wrapper.h:1162
• fninline const LV2_Descriptor* descriptor()lv2::descriptor · lv2_wrapper.h:1177
• fninline const char* audioPortSymbol(int c)
  The suffix of main-bus audio port c's symbol and name. "l"/"r" for the first two, which every existing session's port symbols already say and which must not change; the channel's number after that. It used to be c ? 'r' : 'l' for every channel, so a quad bus declared four ports and three of them were "in_r" -- symbols LV2 requires to be unique.
  lv2::audioPortSymbol · lv2_wrapper.h:1202
• fninline const char* audioPortName(int c)lv2::audioPortName · lv2_wrapper.h:1206
• fninline void writeTurtleString(std::FILE* out, const char* text)
  Escape a string for a Turtle literal.
  lv2::writeTurtleString · lv2_wrapper.h:1217
• fninline void writeTurtleIri(std::FILE* out, const char* text)
  An IRI inside <...>: the characters Turtle forbids there are percent-encoded, so a URL with a space or a stray quote yields a file every host can still parse rather than one none can.
  lv2::writeTurtleIri · lv2_wrapper.h:1233
• fninline const char* lv2UnitFor(const char* unit)
  LV2's own unit for a parameter's unit string -- the units extension's spelling of the ones the SDK uses (the AU wrapper maps the same set) -- or null for one it has no word for, which the TTL then declares itself.
  lv2::lv2UnitFor · lv2_wrapper.h:1247
• fninline void lv2Symbol(const char* id, char* out, size_t capacity)
  lv2:symbol is [_a-zA-Z][_a-zA-Z0-9]*. A parameter id outside that -- a hyphen, a leading digit -- is mapped onto it, and the SAME mapping is used for the presets file, so the two always name the same port.
  lv2::lv2Symbol · lv2_wrapper.h:1264
• fninline bool lv2ReservedSymbol(const char* symbol)
  Whether symbol is one the wrapper may give a port of its own: the designated controls, the meters, the atom ports, and every audio port name it can write (in_/out_ l, r, 3..8 and x, sc_l and sc_r, auxB_C).
  lv2::lv2ReservedSymbol · lv2_wrapper.h:1281
• fninline std::vector<std::string> lv2ParamSymbols()
  Every parameter's lv2:symbol, in table order.
  lv2::lv2ParamSymbols · lv2_wrapper.h:1319
• fninline int numFactoryPresets()
  How many factory presets are genuinely usable.
  lv2::numFactoryPresets · lv2_wrapper.h:1343
• fninline void writePresetsTtl(std::FILE* out, const char* uri)
  Factory presets in LV2's own spelling: one pset:Preset per preset, naming each port by the symbol the plugin published and the value it should take.
  lv2::writePresetsTtl · lv2_wrapper.h:1354
• fninline const char* lv2ClassFor(const PluginDescriptor& d)
  Map the descriptor's plain-word category onto lv2core's plugin taxonomy. Hosts (and lv2lint) treat the bare base class as "uncategorised", so a known word buys real browser placement; an unknown one falls back rather than guessing.
  lv2::lv2ClassFor · lv2_wrapper.h:1408
• fninline void lv2VersionFromProduct(const char* version, int* outMinor, int* outMicro)
  LV2's version pair is its own numbering domain: even minor >= 2 announces a stable public release, 0 or odd reads as pre-release/development to every host (and lv2lint flags it). Copying the product's semver digits verbatim would brand 1.0.1 unstable, so map monotonically onto the convention: doubling keeps ordering and keeps everything even.
  lv2::lv2VersionFromProduct · lv2_wrapper.h:1439
• fninline void writeTtl(std::FILE* out, const char* binaryName)lv2::writeTtl · lv2_wrapper.h:1455
• fninline int ttlGeneratorMain(int argc, char** argv)lv2::ttlGeneratorMain · lv2_wrapper.h:1927
• fnLV2_SYMBOL_EXPORT const sonore::lv2ui::Lv2UiDescriptor* lv2ui_descriptor( uint32_t index)
  The interface entry point, beside the plugin's own.
  lv2_wrapper.h:2044
• fnint main(int argc, char** argv)lv2_wrapper.h:2051
• fnLV2_SYMBOL_EXPORT const LV2_Descriptor* lv2_descriptor(uint32_t index)
  The host's entry point.
  lv2_wrapper.h:2054
• fnextern "C" int sonore_lv2_ttlgen_main(int argc, char** argv)lv2_wrapper.h:2066

Enums 1

• enumenum Lv2WorkerStatuslv2::Lv2WorkerStatus · lv2_wrapper.h:81

Constants 1

• constconstexpr uint32_t kUiNotifyMinimumBytes = 65536
  What the notify port asks a host for (rsz:minimumSize): room for the state as one JSON message.
  lv2::kUiNotifyMinimumBytes · lv2_wrapper.h:566

Macros 3

• macro#define SONORE_LV2_WORKER__schedule "http://lv2plug.in/ns/ext/worker#schedule"
  Declared here rather than vendored, the same way lv2_ui.h declares the UI ABI: the SDK vendors the headers it uses heavily and spells out the small ones, and a file of ours claiming to BE upstream's would be worse than one that says it mirrors the spec.
  lv2_wrapper.h:73
• macro#define SONORE_LV2_TIME "http://lv2plug.in/ns/ext/time#"
  The time extension is URIs only -- time:Position is an atom object whose properties a host fills in -- so its header is not vendored for one prefix.
  lv2_wrapper.h:77
• macro#define SONORE_LV2_LOG__log "http://lv2plug.in/ns/ext/log#log"
  Declared the same way, for one message: the output guard's report, which goes to the host's log as a warning where the host offers one. The spec allows its printf from any NON-realtime context, so it is called from the worker or from deactivate()/cleanup(), never from run().
  lv2_wrapper.h:107