diff --git a/README.md b/README.md index 4dbff37..1bb6e40 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,71 @@ # DISTRHO Cardinal -*Cardinal, bring forth the Rack!* +*Cardinal, the Rack!* -WORK IN PROGRESS - nothing to see here +**! THIS PROJECT IS A WORK IN PROGRESS !** -Just an experiment to see how far we can go about a VCV plugin version that is opensource and uses original VCV source core directly. -Maybe it will work, maybe not, hard to say at this point. +This is a [DPF-based](https://github.com/DISTRHO/DPF/) plugin wrapper around [VCV Rack](https://github.com/VCVRack/Rack/), +using its code directly instead of forking the project. +The target is to have a proper, self-contained, fully free and open-source plugin version of Rack. +See [project overview](doc/OVERVIEW.md) document for an overview on how the project source code is structured. -This is a DPF'ied build of [VCVRack](https://github.com/VCVRack/Rack), allowing it to be used as an audio plugin. +Because it is using DPF, Cardinal already supports LV2 and VST2 with an extra JACK standalone mode if self-compiled. +A VST3 version is in progress, already part of the build but still experimental. + +**The project should be considered in alpha state at the moment.** + +## Current status + +Most of the features already work, you can assume things work in general except when stated otherwise. +Currently the following features are known NOT to work: + +- Clipboard (copy&paste) +- Clock related triggers in built-in MIDI modules +- Export/import module selection +- File dialogs triggered by module right-click menus + +### Current builds + +If you want to try this out early, checkout the GitHub actions tab. +There is absolutely no warranty, use at your own risk and all that... + +## Why + +Cardinal was created first and foremost as a way to have Rack as a **proper open-source audio plugin**. +A proper audio plugin should be self-contained as much as possible, as to not interfere with the DAW/Host. +Loading external modules clearly goes against this idea. +Not to mention being **open-source**, otherwise we are at the mercy of the wishes of a company for what we can and cannot do, +which is not something Cardinal's authors wish to abide by. + +A self-contained plugin can't be overstated, as DLL/shared-object symbol conflicts can trigger hard-to-debug crashes. +While Rack tries to mitigate this as much as possible, crashes due to conflicting modules have already been seen in v2 builds. +On the other side, Cardinal redefines class and function names as needed to avoid as many conflicts as possible. + +Support for ARM and non-mainstream platforms (for example BSD) has also always been missing from the official Rack since the start. +While we can patch the Rack free version to support these, same can't be done with VCV Rack Pro with it being a closed-source product. +The online library/store only supports a very specific set of platforms too, +so non-supported platforms would need any 3rd-party modules to be manually compiled to make them usable. + +Unhappiness with the audio threading behaviour of Rack also plays a role. +Both audio and MIDI should be locked to the host audio thread as to minimize (or even altogether remove) latency and jitter. +The use of separate threads for MIDI is bad design, one that has been corrected in DAWs and JACK-MIDI for several years... +But Rack's use of RtMidi requires separate threading, so Cardinal does not use it. + +Other relevant reasons include: + + - LV2 plugin version from the start + - Proper dark mode support + - Proper optimized build (because all code is compiled to a single file, we can use LTO over the whole thing) + - Removing online access from the plugin and included modules (no phone-home here!) + - Works as a test case for [DPF](https://github.com/DISTRHO/DPF/) and [Carla](https://github.com/falkTX/Carla/) + - It is fun :) + +## Vs. Rack Pro + +It needs to be said that Cardinal project and its author(s) do not wish anything bad to the original/official Rack project. +In fact, Cardinal wouldn't exist if not for Rack v2 release. (which has many needed things to make a plugin version work) + +Cardinal and Rack should be able to co-exist friendly and peacefully, as they clearly have different targets. +It is likely most people will prefer to use Rack Pro for its official support and its big module collection (including commercial ones). + +A feature comparison between Cardinal and Rack Pro can be seen [here](doc/DIFFERENCES.md). diff --git a/doc/DIFFERENCES.md b/doc/DIFFERENCES.md index dc39f0b..2513128 100644 --- a/doc/DIFFERENCES.md +++ b/doc/DIFFERENCES.md @@ -42,4 +42,4 @@ Additionally, Cardinal contains the following built-in modules not present in th * Ildaeil Host * Host Parameters (24 host-exposed parameters as CV sources) * Host Time (play, reset, bar, beat, tick, bar-phase and beat-phase CV sources) - * Host CV (for the CV IO variant, allows direct CV access to/from the DAW) + * Host CV (for the Raw-CV plugin variant, allows direct CV access to/from the DAW) diff --git a/doc/OVERVIEW.md b/doc/OVERVIEW.md new file mode 100644 index 0000000..2171f01 --- /dev/null +++ b/doc/OVERVIEW.md @@ -0,0 +1,138 @@ +# PROJECT OVERVIEW + +This document describes how the DISTRHO Cardinal project is structured, +so developers and interested third-parties can have an easier time contributing code and resources. + +On the root folder the following directories can be seen; + + * carla + * deps + * doc + * dpf + * include + * lv2export + * patches + * plugins + * src + +Going through one by one in alphebetical order we have... + +## CARLA + +This directory contains the source code for Carla, a modular plugin host created by falkTX, the same author of Cardinal, DPF and many other projects. +Cardinal uses Carla as the base for all internal plugin hosting. +Being GPLv2+ the code license is compatible with Cardinal's GPLv3+. + +## DEPS + +3rd-party libraries build setup. +No actual code is hosted here, only a Makefile with steps for fetching source code and build it. +It basically overrides Rack's `dep.mk` things for a proper static build, and supporting more platforms. + +## DOC + +Here you find several files (like this one you are reading now) describing the Cardinal project. +It is intentionally not using something like GitHub Wiki so that rehosting does not lose any information. +Also allows for offline hosting and reading. + +## DPF + +This directory contains the source code for DPF, the plugin framework used by Cardinal that handles all the complex parts of plugin format support. +Implementing new plugin formats will be done here. + +## INCLUDE + +This directory contains special header files needed to build the original Rack code as required by Cardinal. +These headers are included before the official Rack ones, allowing us to override some implementation details. + +Additionally a few compatiblity headers are present, helping compile the code for more targets than officially supported in Rack. + +## LV2EXPORT + +An experiment for building individual Rack modules directly as LV2 plugins. +Only quick&dirty hacks so far, nothing interesting to see here yet. + +## PATCHES + +Public domain or CC0 licensed Rack patches, suitable for use in Cardinal. +Must be stored as plain text files (not zstd compressed) so they play nicely with git. + +## PLUGINS + +Module/Plugin related code and build setup. +Only Cardinal internal modules are hosted here, everything else uses a git submodule reference. + +See https://github.com/DISTRHO/Cardinal/discussions/28 for how to add more modules yourself. + +## SRC + +The main code for Cardinal, where the magic happens. +There are quite a few files here, so let's describe them in detail. + +### Cardinal / CardinalFX / CardinalSynth + +Directories that contain the supported Cardinal plugin variants. +Everything is a symlink except `DistrhoPluginInfo.h` (setting plugin info) and `Makefile` (set the unique name). + +The source code is the same for all the variants, with compiler macros used to tweak behaviour and IO count. + +### extra + +A few extra files for having access to a few utilities, code borrowed from Carla, which in turn borrowed it from JUCE. +The important one is `SharedResourcePointer`, as a way to easily manage a shared class lifecycle. + +### override + +Here are files that need to be customized by Cardinal, where it is not possible or wanted to use the originals from Rack. +This can be for disabling certain features, or simply tweaking engine/UI behaviour. +The filenames should be self-explanatory in what they override from Rack. + +### Rack + +A git submodule reference to the official Rack source code repository. + +### AsyncDialog.{cpp,hpp} + +Custom Cardinal code for showing a dialog in async fashion, optionally with a callback for when the user clicks "Ok". + +### CardinalPlugin.cpp + +The DSP/plugin side of the plugin, and also where the global/shared class lifecycle is managed. +This file implements the DPF `Plugin` class. + +### CardinalUI.cpp + +The UI-specific side of the plugin, dealing with e.g. Window events. +This file implements the DPF `UI` class. + +### Makefile + +The file describing rules for building Rack's code as a rack.a static library. + +### Makefile.cardinal.mk + +A makefile imported by each of Cardinal's plugin variants, which will build the actual plugin. +This same file is used by all variants, changing behaviour based on the plugin variant name. + +### PluginContext.hpp + +And handy but perhaps somewhat hacky `rack::Context` class extension, so internal modules can have direct access to DAW provided data. +This also extends the base `Plugin` and `UI` classes from DPF, to provide methods needed for Rack Audio/MIDI drivers. + +### PluginDriver.hpp + +Code that glues Rack Audio/MIDI drivers to the DPF side of things. + +### ResizeHandle.hpp + +A DPF-related Widget that does what you think it does. +Handles all the resizing for us. + +### template.vcv + +The default template patch as used by Cardinal + +### WindowParameters.hpp + +Defines a few methods for saving and restoring Rack Window state, in order to allow many Cardinal/Rack UIs to be open at once even though Rack `settings` is a global. +Used by `CardinalUI.cpp` and `override/Window.cpp`.