Add notes on things that can potentially go wrong

src/common/serialization/vst3/README.md

@@ -50,7 +50,16 @@ instantiated and managed by the host. The model works as follows:
 
 ## Plugin Factory
 
-Aside form the above, the plugin factory is the only place where we may
-potentially report different values from those reported by the Windows VST3
-plugin. If we encounter an itnerface we do not yet support, we will log a
-warning and we'll skip the interface since we wouldn't know how to handle it.
+TODO: Explain how we implement `createInstance()`
+
+## Safety notes
+
+- None of the destructors in the interfaces defined by the SDK are marked as
+  virtual because this could apparently [break binary
+  compatibility](https://github.com/steinbergmedia/vst3sdk/issues/21). 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.

src/plugin/bridges/vst3-impls.cpp

@@ -33,21 +33,22 @@ YaPluginFactoryPluginImpl::createInstance(Steinberg::FIDString cid,
     //          factory with thsoe same `cid` and `_iid` arguments.
     //       4. It this was successful, we'll assign this object a unique number
     //          (by just doing a fetch-and-add on an atomic size_t) so we can
-    //          refer to it and add it to an `std::map<size_t, IPtr<T>` (could
-    //          also throw everything in a single map with `FUnknown`s, but
-    //          while more verbose this sounds much less prone to breakage).
-    //       5. We'll serialize any payload data into a `YaT` **which includes
+    //          refer to it and add it to an `std::map<size_t, IP tr<T>`, where
+    //          `T` is the _original_ object (we don't have to and shouldn't
+    //          wrap it).
+    //       5. We'll copy over any payload data into a `YaT` **which includes
     //          that unique identifier we generated** and send it back to the
     //          plugin.
-    //       6. The plugin then converts it to the correct smart pointer format
-    //          and writes it to `obj`. We don't have to keep track of these
-    //          objects on the plugin side and the reference counting pointers
-    //          will cause everything to clean up after itself.
-    //       7. Since those `YaT` objects we'll return from `createInstance()`
-    //          will have a reference to `Vst3PluginBridge`, they can also send
-    //          control messages themselves.
+    //       6. On the plugin's side we'll create a new `YaTPluginImpl` inside
+    //          of a VST smart pointer and deserialize the `YaT` we got sent
+    //          into that. We then write that smart pointer into `obj`. We don't
+    //          have to keep track of these objects on the plugin side and the
+    //          reference counting pointers will cause everything to clean up
+    //          after itself.
+    //       7. Since those `YaTPluginImpl` objects we'll return from
+    //          `createInstance()` will have a reference to `Vst3PluginBridge`,
+    //          they can also send control messages themselves.
 
-    // TODO: Send a control message
     return Steinberg::kNotImplemented;
 }
 

src/plugin/bridges/vst3.h

@@ -86,6 +86,9 @@ class Vst3PluginBridge : PluginBridge<Vst3Sockets<std::jthread>> {
      * ourselves.
      *
      * @related get_plugin_factory
+     *
+     * FIXME: We can't use `std::unique_ptr` here because that breaks VST3's
+     *        reference counting mechanism.
      */
     std::unique_ptr<YaPluginFactory> plugin_factory;
 };