Add initial WIP for more user friendly docs

See May 2018 lv2-devel discussion for some of the motivations
for the different style of documentation.

1 files changed, 185 insertions, 0 deletions

diff --git a/doc/lv2_host_guide/lv2-host-perspective.adoc b/doc/lv2_host_guide/lv2-host-perspective.adoc
new file mode 100644
index 0000000..c890c54
--- /dev/null
+++ b/doc/lv2_host_guide/lv2-host-perspective.adoc
@@ -0,0 +1,185 @@
+Introduction to LV2, a Plugin Host Perspective
+==============================================
+:toc:
+
+Intro
+-----
+
+Hello there, if you're reading this document then you're likely trying to figure
+out how to work with existing LV2 plugins and understanding some of the details
+of the LV2 spec.
+This document assumes some cursory knowledge about prior plugin standards
+including LADSPA(link)/DSSI(link)/VST(link)/etc.
+At the end of reading this guide you should be comfortable with setting up a
+basic host which can process audio, MIDI, and control events using several of
+the LV2 utility libraries in C.
+If you're looking for a C++ implementation, we'll briefly explain how the
+information within this guide can be translated at the end of this article.
+
+For the most part in this guide we'll refer to the official API specifications
+for more clarifications, though several code examples will come from one of
+several simple hosts including jalv(link) which is the reference implementation,
+lv2file(link) (a simple wav file processor), lv2apply(), lv2ls(link), and  ...
+
+What can LV2 plugins do?
+------------------------
+
+talk about the raw basics of audio synthesis, audio effects, midi effects, and
+GUIs.
+Have a brief mention of extensions, but do *NOT* talk about them until later.
+
+Perhaps mention the existance of .ttl files here and say xxx is abstracted away
+by yyy.
+
+
+The LV2 Ecosystem
+-----------------
+
+If you're searching around for libraries related to LV2 you may come across a
+wide variety of them.
+This can include lilv(links), raul(for), suil(every), serd(one), sord(of the),
+LV2 toolkit(libraries), and a few others.
+Fortunately building a basic host is not that difficult and will primarily build
+off of lilv.
+
+Talk about the other components as need be
+
+How can you load a LV2 plugin?
+------------------------------
+
+So, now that we know that we're using lilv, how can we load a simple plugin.
+For this let's try to load one of the basic sample plugins 'eg-amp'.
+Plugins within LV2 are loaded based upon URIs, so in the case of the 'eg-amp'
+plugin LV2 names it 'http://lv2plug.in/plugins/eg-amp'.
+(perhaps a brief footnote on why this is the case, but nothing more)
+
+First let's verify that this plugin is installed on your system
+
+--------------------------------------------------------------------------------
+void list_plugins(void)
+{
+    LilvWorld *world = lilv_world_new();
+    lilv_world_load_all(world);
+    const LilvPlugins *plugins=lilv_world_get_all_plugins(lilvworld);
+
+    LilvIter *plug_itr = lilv_plugins_begin(plugins); 
+    for(int i=0; i<lilv_plugins_size(plugins); ++i) {
+        LilvPlugin *plugin   = lilv_plugins_get(plugins, plug_itr);
+        LilvNode   *uri_node =  lilv_plugin_get_uri(plugin);
+        const char *uri_str  = lilv_node_as_uri(uri_node);
+        printf("plugin.uri = %s\n", uri_str);
+        plug_itr = lilv_plugins_next(plugins, plug_itr);
+    }
+
+    some_teardown_code_that_I_didn_t_bother_to_implement();
+}
+
+int main()
+{
+    list_plugins();
+}
+--------------------------------------------------------------------------------
+
+You can compile this snippet via XXX.
+If you need some help getting the dependencies setup then please see appendix A
+(this appendix should describe setup steps for the popular dev distros which at
+the moment are (IMO) Ubuntu & Arch).
+This code will open the lilv library and iterate through all the plugins
+available to the LV2 host.
+As long as you can see 'http://lv2plug.in/plugins/eg-amp' in the output, then
+we're all ready to go to the next step, putting a few samples into the plugin.
+
+
+--------------------------------------------------------------------------------
+LilvPlugin *get_the_plugin(void) {}
+
+xxx *create_plugin_instance(plugin, ...) {}
+
+//Activate instance
+
+//instance run
+
+//Cleanup
+
+--------------------------------------------------------------------------------
+
+At this point we've created a plugin instance, activated it, and run it, but
+how do we send data to it and get the results?
+
+That brings us to the concept of LV2 ports.
+
+- Input
+- Output
+- Audio
+- Control (we'll get to this later)
+- Etc (we'll get to this later)
+
+--------------------------------------------------------------------------------
+void connect_input_output_buffer() {...}
+--------------------------------------------------------------------------------
+
+With this connection in place we can connect the input an output data from the
+host:
+
+--------------------------------------------------------------------------------
+//feed in dummy data before processing
+
+//read out the same dummy data (assuming that eg-amp defaults to unison gain)
+--------------------------------------------------------------------------------
+
+Great, we now have a plugin running and processing data within our trivial host
+
+
+How do you control a LV2 plugin?
+--------------------------------
+
+This brings us to how you can interact with control ports, ...
+
+
+LV2 Extensions
+--------------
+
+The core of LV2 does A, B, & C, but by design the specification makes it
+possible for hosts to implement extensions that the plugins can make use of.
+A common one is X.
+Let's walk through the implementation of this extension and what happens when
+plugin hosts have the functionality and when they do not have it.
+For this example we're going to use the X plugin which you can download from
+http://...
+
+Where to go from here?
+----------------------
+
+At this point in the guide you should have a rough idea as to what components
+are needed for a LV2 host and how to assemble them.
+There's still plenty more that can be done with LV2 and knowing about the
+available resources can make this a much easier process.
+
+- http://lv2plug.in/api_spec_url
+- http://the_link_to_liblilv
+
+Example hosts:
+
+- jalv - recommended for learning a,b,c
+- lv2file - largely discussed within this guide
+- ardour - see link to small part of the git repo to understand how X is used in
+  a large host as well as A,B,C to understand a few extensions
+
+Other interesting projects:
+
+
+- LV2 mailing list
+- LV2 IRC chat
+- etc
+
+
+
+Appendix A: LV2 dependency setup
+--------------------------------
+
+Apt get yada yada
+Compiler tweak abc,
+
+pacman xxx
+
+