Continue with Playtime usage docs

artwork-processor/src/main.rs

@@ -12,36 +12,64 @@ fn main() -> Result<()> {
 }
 
 fn render_artwork() -> Result<()> {
-    generate_toolbar_icons("playtime-logo.svg")?;
+    let playtime_logo_file = "resources/artwork/playtime-logo.svg";
+    generate_toolbar_icons(playtime_logo_file)?;
+    generate_icon(
+        playtime_logo_file,
+        "doc/playtime/modules/ROOT/images/screenshots/playtime-toolbar-icon.png",
+        (120, 120),
+        &[ToolbarIconStatus::Normal],
+    )?;
     Ok(())
 }
 
 fn generate_toolbar_icons(src_file: &str) -> Result<()> {
-    generate_toolbar_icon(src_file, "toolbar_icons/toolbar_playtime.png", (30, 30))?;
-    generate_toolbar_icon(src_file, "toolbar_icons/150/toolbar_playtime.png", (45, 45))?;
-    generate_toolbar_icon(src_file, "toolbar_icons/200/toolbar_playtime.png", (60, 60))?;
+    use ToolbarIconStatus::*;
+    let toolbar_statuses = [Normal, Hovered, Selected];
+    generate_icon(
+        src_file,
+        "resources/artwork/toolbar_icons/toolbar_playtime.png",
+        (30, 30),
+        &toolbar_statuses,
+    )?;
+    generate_icon(
+        src_file,
+        "resources/artwork/toolbar_icons/150/toolbar_playtime.png",
+        (45, 45),
+        &toolbar_statuses,
+    )?;
+    generate_icon(
+        src_file,
+        "resources/artwork/toolbar_icons/200/toolbar_playtime.png",
+        (60, 60),
+        &toolbar_statuses,
+    )?;
     Ok(())
 }
 
-fn generate_toolbar_icon(
+fn generate_icon(
     src_file: impl AsRef<Path>,
     dst_file: impl AsRef<Path>,
     (width, height): (u32, u32),
+    statuses: &[ToolbarIconStatus],
 ) -> Result<()> {
-    let artwork_dir = Path::new("resources/artwork");
-    let svg = fs::read_to_string(artwork_dir.join(src_file))?;
-    let pixmap = render_toolbar_icon(&svg, (width, height))?;
-    let abs_dst_file = artwork_dir.join(dst_file);
-    fs::create_dir_all(abs_dst_file.parent().context("no parent file")?)?;
-    pixmap.save_png(abs_dst_file)?;
+    let dst_file = dst_file.as_ref();
+    let svg = fs::read_to_string(src_file)?;
+    let pixmap = render_toolbar_icon(&svg, (width, height), statuses)?;
+    fs::create_dir_all(dst_file.parent().context("no parent file")?)?;
+    pixmap.save_png(dst_file)?;
     Ok(())
 }
 
-fn render_toolbar_icon(svg: &str, (width, height): (u32, u32)) -> Result<Pixmap> {
-    let sprite_count = 3;
+fn render_toolbar_icon(
+    svg: &str,
+    (width, height): (u32, u32),
+    statuses: &[ToolbarIconStatus],
+) -> Result<Pixmap> {
+    let sprite_count = statuses.len() as u32;
     let mut pixmap = Pixmap::new(width * sprite_count, height).unwrap();
     use ToolbarIconStatus::*;
-    for (i, status) in [Normal, Hovered, Selected].iter().enumerate() {
+    for (i, status) in statuses.iter().enumerate() {
         let root_classes = match status {
             Normal => "toolbar-icon",
             Hovered => "toolbar-icon hovered",

doc/helgobox/modules/ROOT/pages/app/user-interface.adoc

@@ -6,6 +6,6 @@ Each Helgobox instance can display its own xref:app.adoc[] window, embedded into
 . Press menu:Menu[Show App]
 
 .App window
-image::screenshots/app-window.png[]
+image::generated/screenshots/main/home-screen.png[]
 
 At the moment, the app primarily provides the user interface for xref:playtime::introduction.adoc[Playtime], but it will contain more stuff in the future.

doc/playtime/modules/ROOT/pages/installation.adoc

@@ -1,11 +1,37 @@
 = Installation
 
-At first, please follow the xref:helgobox::installation.adoc[installation instructions for Helgobox], the plug-in that contains Playtime.
+At first, please follow the xref:helgobox::installation.adoc[installation instructions for Helgobox], the add-on that contains Playtime.
 
-After installing Helgobox, the easiest way to access Playtime is by using the convenient btn:[Playtime] button in REAPER's main toolbar.
-If you don't see it, do this:
+== Playtime main toolbar button
+
+After installing Helgobox, the easiest way to access Playtime is by using the convenient image:screenshots/playtime-toolbar-icon.png[Playtime,width=50] button in REAPER's main toolbar.
+
+You can add this button very easily by doing this:
 
 . Select menu:Extensions[Helgobox > Show welcome screen]
 . Check "Add Playtime button to main toolbar"
 
 image::screenshots/helgobox-welcome-screen.png[width=500]
+
+== Alternatives
+
+If you don't like that button, here are a few alternatives.
+
+TIP: Manually removing the image:screenshots/playtime-toolbar-icon.png[Playtime,width=50] button from the main toolbar is not going to work: You will have it back the next time you start REAPER.
+In order to remove the button permanently, open above-mentioned welcome screen and disable the checkbox!
+
+=== Start directly via action
+
+Playtime provides the action xref:reaper-actions.adoc#show-hide-playtime[], which you can invoke from the REAPER action list or via menu:Extensions[Helgobox > Playtime > Show/hide Playtime].
+In the action list, you can also assign your preferred keyboard shortcut.
+The default is kbd:[Shift+Cmd/Ctrl+P].
+
+=== Add the button to another toolbar
+
+You can add the image:screenshots/playtime-toolbar-icon.png[Playtime,width=50] Playtime button to your own toolbar like this:
+
+. Right-click the toolbar and choose menu:Customize toolbar...[]
+. Click btn:[Add...] (should open the REAPER action list)
+. Search for the action xref:reaper-actions.adoc#show-hide-playtime[] and double-click it.
+
+That's it! you should now see the button in your custom toolbar.

doc/playtime/modules/ROOT/pages/usage.adoc

@@ -2,8 +2,9 @@
 
 Let's get familiar with the basics!
 
-A typical usage scenario of Playtime looks like this:
+A typical Playtime usage scenario, from beginning to end, looks like this:
 
+. <<prepare>>
 . <<record>>
 . <<import>>
 . <<play>>
@@ -14,6 +15,83 @@ A typical usage scenario of Playtime looks like this:
 
 In the following sections, we will learn step by step how to do this.
 
+[[prepare]]
+== Prepare
+
+This guide assumes that you already installed Playtime.
+If not, head to the xref:installation.adoc[] page!
+
+=== 1. Start REAPER
+
+Playtime runs within REAPER, so at first you need to start REAPER.
+
+=== 2. Set up your audio and MIDI devices
+
+If you haven't done it already, you should let REAPER know which audio and MIDI devices you are planning to use with it, because Playtime will use them as well!
+
+. Open the REAPER preferences via menu:Options[Settings...]
+. In the section menu:Audio[Device], configure your audio input and output.
+. In the section menu:Audio[MIDI Inputs], configure your MIDI input devices, such as music keyboards.
+. In the section menu:Audio[MIDI Outputs], configure your MIDI output devices, such as hardware synthesizers.
+
+If you want to know more about this process, please consult the one and only link:https://www.reaper.fm/userguide.php[REAPER user guide].
+
+=== 3. Fire up Playtime
+
+Press the image:screenshots/playtime-toolbar-icon.png[Playtime,width=50] button in the main toolbar, or use any of the alternative ways to start Playtime (described in xref:installation.adoc[]).
+After pressing the button, you should see the Playtime window with an empty xref:key-concepts.adoc#matrix[]:
+
+.Playtime window with empty matrix
+image::generated/screenshots/main/main-screen-empty.png[]
+
+At this point, you could directly continue with <<record>>, but I strongly recommend to read the following tip, as it will improve your understanding of how Playtime actually works!
+
+[TIP]
+.Understanding what happened when you pressed the Playtime button
+====
+Pressing the button actually does multiple things in one go!
+If you wanted, you could do all of those things also manually.
+
+[cols="1s,5,5a"]
+|===
+|Step | Description| How you could do the step manually
+
+|1
+|Create a new REAPER track named "Playtime" at the very top of the project
+.3+|
+* Right-click REAPER's track control panel and choose menu:Insert virtual instrument on new track...[]
+* Double-click instrument plug-in "VSTi: Helgobox - ReaLearn & Playtime (Helgoboss)"
+* Optionally rename the track to "Playtime"
+
+|2
+|Arm the track and set its input to "MIDI: All: All channels"
+
+|3
+|Add an xref:helgobox::key-concepts.adoc#instance[instance] of the Helgobox plug-in to the track's FX chain
+
+|4
+|Open the xref:helgobox::app.adoc[] associated with that new Helgobox instance
+|In the xref:helgobox::plug-in/user-interface.adoc[Helgobox plug-in window], press menu:Menu[Show app]
+
+|5
+|Navigate to the Playtime section of the App
+|In the xref:helgobox::app/user-interface.adoc[Helgobox app window], press the image:screenshots/playtime-toolbar-icon.png[Playtime,width=30] in the xref:helgobox::app/user-interface/navigation-bar.adoc[]
+
+|6
+|Create a xref:key-concepts.adoc#matrix[Playtime Matrix] in this Helgobox instance
+|Press the button btn:[Create a Playtime Matrix]
+|===
+
+What we learn from that:
+
+* Playtime is built into Helgobox, which is an instrument plug-in, so there needs to be an instance of it somewhere in your project. *→ This is a good thing because it means that you can <<play,play>> it like an instrument!*
+* A new Helgobox instance doesn't have a xref:key-concepts.adoc#matrix[Playtime Matrix] by default.
+You first need to create one.
+*→ This means Playtime doesn't consume any CPU and memory if you don't use it!*
+
+
+====
+
 [[record]]
 == Record clips