diff --git a/README.md b/README.md index 6c20498f..87b27239 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,6 @@ easy to debug and maintain. Everything is implemented and ready for release after a few documentation updates: -- Add missing details if any to the architecture section. - Add a screenshot, because why not? ## Tested with @@ -253,99 +252,122 @@ meson configure build --buildtype=debug -Duse-winedbg=true ## Architecture -The project consists of two components, a Linux native VST plugin +The project consists of two components: a Linux native VST plugin (`libyabridge.so`) and a VST host that runs under Wine -(`yabridge-host.exe`/`yabridge-host.exe.so`). I'll refer to a copy of or a -symlink to `libyabridge.so` as _the plugin_, the native Linux VST host that's -hosting the plugin as _the native VST host_, the Wine VST host that's hosting a -Windows `.dll` file as _the Wine VST host_, and the Windows VST plugin that's -loaded in the Wine VST host is simply the _Windows VST plugin_. The whole -process works as follows: +(`yabridge-host.exe`/`yabridge-host.exe.so`, and +`yabridge-host-32.exe`/`yabridge-host-32.exe.so` if the bitbirdge is enabled). +I'll refer to the copy of or lthe symlink to `libyabridge.so` as _the plugin_, +the native Linux VST host that's hosting the plugin as _the native VST host_, +the Wine VST host application that's hosting a Windows `.dll` file as _the Wine +VST host_, and the Windows VST plugin that's being loaded in the Wine VST host +as the _Windows VST plugin_. The whole process works as follows: 1. Some copy of or a symlink to `libyabridge.so` gets loaded as a VST plugin in a Linux VST host. This file should have been renamed to match a Windows VST plugin `.dll` file in the same directory. For instance, if there's a `Serum_x64.dll` file you'd like to bridge, then there should be a symlink to `libyabridge.so` named `Serum_x64.so`. -2. The plugin first attempts to locate: +2. The plugin first attempts to locate and determine: - - The location of `yabridge-host.exe`. For this it will first search for the - file either alongside `libyabridge.so`. This is useful for development, as - it allows you to use a symlink from the build directory to cause yabridge - to use the `yabridge-host.exe` from that same build directory. If this file - can't be found, then it will fall back to searching through the search path. - - The wine prefix plugin is located in. - - The corresponding Windows VST plugin `.dll` file. + - The Windows VST plugin `.dll` file that should be loaded. + + - The architecture of that VST plugin file. This is done by inspecting the + headers if the `.dll` file. + + - The location of the Wine VST host. This will depend on the architecture + detected for the plugin. If the plugin was copmiled for the `x86_64` + architecture or the 'Any CPU' target, then we will look for + `yabridge-host.exe`. If the plugin was copmiled for the `x86` architecture, + when we'll search for `yabridge-host-32.exe`. + + We will first search for this file alongside the actual location of + `libyabridge.so`. This is useful for development, as it allows you to use a + symlink to `libyabridge.so` directly from the build directory causing + yabridge to automatically pick up the right version of the Wine VST host. + If this file cannot be found, then it will fall back to searching through + the search path. + + - The Wine prefix the plugin is located in. If the `WINEPREFIX` environment + variable is specified, then that will be used instead. 3. The plugin then sets up a Unix domain socket endpoint to communicate with the Wine VST host somewhere in a temporary directory and starts listening on it. - I chose to use Unix domain sockets rather than shared memory because this way - you get low latency communication with without any busy waits or manual - synchronisation for free. The added benefit is that it also makes it possible - to send arbitrarily large data without having to split it up into chunks - first, which is useful for transmitting audio and preset data which may have - any arbitrary size. + I chose to communicate over Unix domain sockets rather than using shared + memory directly because this way you get low latency communication with + without any busy waits or manual synchronisation for free. The added benefit + is that it also makes it possible to send arbitrarily large chunks of data + without having to split it up first. This is useful for transmitting audio + and preset data which may have any arbitrary size. 4. The plugin launches the Wine VST host in the detected wine prefix, passing the name of the `.dll` file it should be loading and the path to the Unix - domain socket that was just created. -5. Communication gets set up using multiple sockets over the same end point. - This allows us to use blocking read operations from multiple threads to - handle multiple different events without the risk of receiving packets in the - wrong order. The following types of events get assigned a socket: + domain socket that was just created as its arguments. +5. Communication gets set up using multiple sockets over the end point created + previously. This allows us to easily handle multiple data streams from + different threads using blocking read operations for synchronization. Doing + this greatly simplifies the way communication works without compromising on + latency. The following types of events each get their own socket: - - Calls from the native VST host to the plugin's `dispatch()` function. These - get forwarded to the Windows VST plugin through the Wine VST host. - - Calls from the native VST host to the plugin's `dispatch()` function with - `opcode=effProcessEvents`. These get forwarded to the Windows VST plugin - through the Wine VST host. This has to be handled separately from all other - events because of limitations of the Win32 API. Otherwise the plugin would - not receive any MIDI events while the GUI is being resized or a dropdown - menu or message box is open. - - Host callback calls from the Windows VST plugin loaded into the Wine VST - host through the `audioMasterCallback` function. These get forwarded to the - native VST host through the plugin. + - Calls from the native VST host to the plugin's `dispatcher()` function. + These get forwarded to the Windows VST plugin through the Wine VST host. + - Calls from the native VST host to the plugin's `dispatcher()` function with + the `effProcessEvents` opcode. These also get forwarded to the Windows VST + plugin through the Wine VST host. This has to be handled separately from + all other events because of limitations of the Win32 API. Without doing + this the plugin would not be able to receive any MIDI events while the GUI + is being resized or a dropdown menu or message box is shown. + - Host callback calls from the Windows VST plugin through the + `audioMasterCallback` function. These get forwarded to the native VST host + through the plugin. - Both the `dispatch()` and `audioMasterCallback()` functions are handled in - the same way, with some minor variations on how payload data gets - serialized depending on the opcode of the event being sent. + Both the `dispatcher()` and `audioMasterCallback()` functions are handled + in the same way, with some minor variations on how payload data gets + serialized depending on the opcode of the event being sent. See the section + below this for more details on this procedure. - Calls from the native VST host to the plugin's `getParameter()` and `setParameter()` functions. Both functions get forwarded to the Windows VST plugin through the Wine VST host using a single socket because they're very similar and don't need any complicated behaviour. - - Calls from the native VST host to the plugin's `process()` and - `processReplacing()` functions. Both functions get forwarded to the Windows - VST plugin through the Wine VST host using a single socket. The `process()` - function has been deprecated, so a VST host will never call it if - `processReplacing()` is supported by the plugin. - - Updates of the Windows VST plugin's `AEffect` object. This object tells the - host about the plugin's capabilities. A copy of this is sent over a socket - from the Wine VST hsot to the plugin after it loads the Windows VST plugin - so it can return a pointer to it to the native VST host. Whenever this - struct updates, the Windows VST plugin will call the `audioMasterIOChanged` - host callback and we'll repeat this process. + - Calls from the native VST host to the plugin's `processReplacing()` + function. This function gets forwarded to the Windows VST plugin through + the Wine VST. In the rare event that the plugin does not support + `processReplacing()` and only supports The deprecated commutative + `process()` function, then the Wine VST host will emulate the behavior of + `processReplacing()` instead. + - The Windows VST plugin's `AEffect` object. A copy of this is sent over a + socket from the Wine VST hsot to the plugin after the Windows VST plugin + has finished initializing. Whenever this struct gets updated by the Windows + VST plugin, the Windows VST plugin will call the `audioMasterIOChanged()` + host callback and we'll repeat the process. - The operations described above are all handled by first serializing the - function parameters and any payload into an object before they can be sent - over a socket. The objects used for encoding both the requests and and the - responses for theses events can be found in `src/common/communication.h` - along with functions that read and write these objects over streams and - sockets. The actual binary serialization is handled using - [bitsery](https://github.com/fraillt/bitsery). + The operations described above involving the host -> plugin `dispatcher()`and + plugin -> host `audioMaster()` functions are all handled by first serializing + the function parameters and any payload data into a binary format so they can + be sent over a socket. The objects used for encoding both the requests and + the responses for theses events can be found in `src/common/serialization.h`, + and the functions that actually read and write these objects over the sockets + are located in `src/common/communication.h`. The actual binary serialization + is handled using [bitsery](https://github.com/fraillt/bitsery). - Sending and receiving host -> plugin and plugin -> host events happen in the - `send_event()` and `receive_event()` functions. Reading data and writing the - results back for host-to-plugin `dispatcher()` calls and for plugin-to-host - `audioMaster()` callbacks happen in the `DispatchDataConverter` and - `HostCallbackDataConverter` classes respectively, with a bit of extra glue - for GUI related operations in `PluginBridge::dispatch_wrapper`. On the - receiving end, the `passthrough_event()` function calls the callback - functions and handles the marshalling between our data types and the VST - API's different pointer types. This behaviour is separated from - `receive_event()` so we can some special handling for MIDI events, since a - select few plugins only store pointers to the received events rather than - copies of the objects. This requires the received event data to live at least - until the next audio buffer gets processed. + Actually sending and receiving the events happens in the `send_event()` and + `receive_event()` functions. When calling either `dispatch()` or + `audioMaster()`, the caller will oftentimes either pass along some kind of + data structure through the void pointer function argument, or they expect the + function's return value to be a pointer to some kind of struct provided by + the plugin or host. The behaviour for reading from and writing into these + void pointers and returning pointers to objects when needed is encapsulated + in the `DispatchDataConverter` and `HostCallbackDataCovnerter` classes for + the `dispatcher()` and `audioMaster()` functions respectively. For operations + involving the plugin editor there is also some extra glue in + `PluginBridge::dispatch_wrapper`. On the receiving end of the function calls, + the `passthrough_event()` function calls the callback functions and handles + the marshalling between our data types created by the `*DataConverter` + classes and the VST API's different pointer types. This behaviour is + separated from `receive_event()` so we can handle MIDI events separately. + This is needed because a select few plugins only store pointers to the + received events rather than copies of the objects. Because of this, the + received event data must live at least until the next audio buffer gets + processed so it needs to be stored temporarily. 6. The Wine VST host loads the Windows VST plugin and starts forwarding messages over the sockets described above.