yabridge/docs/vst3.md

VST3 serialization

TODO: Flesh this out further, update the instantiation part, make the proxying part clearer

TODO: Link to src/common/serialization/vst3/README.md

The VST3 SDK uses an architecture where every concrete object inherits from an interface, and every interface inherits from FUnknown. FUnkonwn offers a dynamic casting interface through queryInterface() and a reference counting mechanism that calls delete this; when the reference count reaches 0. Every interface gets a unique identifier. It then uses a smart pointer system (FUnknownPtr<I>) that queries whether the FUnknown matches a certain interface by checking whether the IDs match up, allowing casts to that interface if the FUnkonwn matches. Those smart pointers also use that reference counting mechanism to destroy the object when the last pointer gets dropped.

Another important part of this system is interface versioning. Old interfaces cannot be changed, so when the SDK adds new functionality to an existing interface it defines a new interface that inherits from the old one. The queryInterface() implementation should then allow casts to all of the implemented interface versions.

Lastly, the interfaces provide both getters for static, non-chancing data (such as the classes registered in a plugin factory) as well as functions that perform side effects or return dynamically changing data (such as the input/output configuration for an audio processor).

Yabridge's serialization and communication model for VST3 is thus a lot more complicated than for VST2 since all of these objects are loosely coupled and are instantiated and managed by the host. The basic model works as follows:

1. The main idea behind yabridge's VST3 implementation is that we define monolithic proxy objects that can proxy any object created by the Windows VST3 plugin. These proxy objects indirectly inherit from all applicable interfaces defiend in the VST3 SDK. Vst3PluginProxy implements all interfaces that can be implemented by plugins, and Vst3HostProxy implements all interfaces that are to be implemented by the host.

   TODO: Find out if Vst3HostProxy is needed, or if objects provided by the host never implement multiple interfaces (which I think might be the case)

2. For every interface IFoo, we provide an abstract implementation called YaFoo. This implementation mostly contain message object we use to make specific function calls on the actual objects we are proxying. The implementation also comes with a function that takes an FUnknown pointer, checks whether the object behind that pointer supports IFoo, and then stores the result along with any potential static payload data as a YaFoo::ConstrctArgs object.

3. Proxy object are instantiated while handling IPluginFactory::createInstance() for Vst3PluginProxy, and during IPluginBase::initialize() and IPluginFactory::setHostContext() for Vst3HostProxy (TODO: Same here). On the receiving side of those functions (where we call the actual function implemented by the plugin or the host), we receive an IPtr<T> smart pointer to an object provided by the host or the plugin. We use this object to iterate over every applicable YaFoo as mentioend above. All of these YaFoo::ConstructArgs objects along with a unique identifier for this specific object are then serialized and transmitted to the other side. With this information we can create a proxy object that supports all the same interfaces (and thus allows calls to the functions in those interfaces) as the original object we are proxying.

4. As mentioend, every object we instantiate gets assigned a unique identifier. When dealign with objects created by the Windows VST3 plugin, the object's FUnknown pointer will be stored in an std::map<size_t, PluginObject> map. This way we can refer to it later on when we receive a request to call a specific function on the plugin.

5. If IFoo is a versioned interface such as IPluginFactory{,2,3}, the creation of YaFoo::ConstrctArgs and the definition of YaFoo's query interface work slightly differently. When copying the data for a plugin factory, we'll start copying from IPluginFactory, and we'll copy data from each newer version of the interface that the IPtr<IPluginFactory> supports. During this process we keep track of which interfaces were supported by the native plugin. In our query interface method we then only report support for the same interface versions that were supported by the original IPtr<IPluginFactory> we are proxying.

Interface Instantiation

Creating a new instance of an interface using the plugin factory wroks as follows. This describes the object lifecycle. The actual serialization and proxying is described in the section above.

1. The host calls createInterface(cid, _iid, obj) on an IPluginFactory implementation exposed to the host as described above.
2. We check which interface we support matches the _iid. If we don't support the interface, we'll log a message about it and return that we do not support the itnerface.
3. If we determine that _iid matches IFoo, then we'll send a YaFoo::Construct{cid} to the Wine plugin host process.
4. The Wine plugin host will then call module->getFactory().createInstance<IFoo>(cid) using the Windows VST3 plugin's plugin factory to ask it to create an instance of that interface. If this operation fails and returns a null pointer, we'll send a kNotImplemented result code back to indicate that the instantiation was not successful and we relay this on the plugin side.
5. As mentioned above, we will generate a unique instance identifier for the newly generated object so we can refer to it later. We then serialize that identifier along with what other static data is available in IFoo in a YaFoo::ConstructArgs object.
6. We then move IPtr<IFoo> to an std::map<size_t, IPtr<IFoo>> with that unique identifier we generated earlier as a key so we can refer to it later in later function calls.
7. On the plugin side we can now use the YaFoo::Arguments object we received to create a YaFooPluginImpl object that can send control messages to the Wine plugin host.
8. Finally a pointer to this YaFooPluginImpl gets returned as the last step of the initialization process.

Simple objects

For serializing objects of interfaces that purely contain getters and setters (and thus don't need to perform any host callbacks), we'll simply have a constructor that takes the IFoo by IPtr or reference (depending on how it's used in the SDK) and reads the data from it to create a serializable copy of that object.

Safety notes

• None of the destructors in the interfaces defined by the SDK are marked as virtual because this could apparently break binary compatibility. This means that the destructor of the class that implemented release() will be called. This is something to keep in mind when dealing with inheritence.
• Since everything behind the scenes makes use of these addRef() and release() reference counting functions, we can't use the standard library's smart pointers when dealing with objects that are shared with the host or with the Windows VST3 plugin. In IPtr<T>'s destructor it will call release, and the objects will clean themselfs up with a delete this; when the reference count reaches 0. Combining this with the STL cmart pointers this would result in a double free.