SynthstromAudible · RJ-Eckie · Nov 7, 2024 · Nov 7, 2024 · Nov 7, 2024 · Nov 8, 2024
diff --git a/code_docs/CodeDocumentation.md b/code_docs/CodeDocumentation.md
@@ -0,0 +1,2 @@
+# Code Documentation
+
diff --git a/code_docs/CodeGuidelines.md b/code_docs/CodeGuidelines.md
@@ -0,0 +1,6 @@
+# Proposed Code Guidelines
+
+## Naming Conventions
+### Menu Items
+- Menu item strings for oled should be descriptive. *F.e.: `delay divs on golden knobs` as opposed to `alternative golden knob delay params`*
+- As much as possible, menu item strings for oled should fit on the display without scrolling to keep the menu scrolling experience as fluent as possible. *F.e.: `stutter quantize` versus `stutter rate quantize`. The same information is conveyed while avoiding a scrolling menu string.*
diff --git a/code_docs/DirectoryReference.md b/code_docs/DirectoryReference.md
@@ -0,0 +1,107 @@
+# Deluge Community Firmware Github Directory Reference
+- [Deluge Community Firmware Github Directory Reference](#deluge-community-firmware-github-directory-reference)
+- [Main Folder](#main-folder)
+- [Source Folder](#source-folder)
+- [Deluge Folder](#deluge-folder)
+  - [GUI Folder](#gui-folder)
+    - [UI Folder](#ui-folder)
+    - [Views Folder](#views-folder)
+    - [Model Folder](#model-folder)
+
+# Main Folder
+`DelugeFirmware/`
+
+*Contains the main README.md file and several files and directories related to managing the repository and building the software.* 
+
+Important folders:
+| Folder | Contents
+|-|-
+| docs | Contains documentation for using the Deluge
+| pages/public | Contains the public website for the community firmware
+| [src](#source-folder) | Contains the source code
+
+# Source Folder 
+`DelugeFirmware/src/`
+
+*Contains all source code. Most functional code lives in subfolder [`deluge/`](#deluge-folder). Everything else is managing low-level systems, global definitions, etc.*
+
+# Deluge Folder
+`DelugeFirmware/src/deluge`
+
+*Main directory for firmware code. `deluge.cpp` runs the boot sequence and main loop*
+
+| Folder | Contents
+|-|-
+| drivers | mostly deals with managing hardware
+| dsp | digital signal processing, manages audio effects
+| [gui](#gui-folder) | graphical user interface, manages all user-facing behavior of the Deluge
+| hid | human interface device, manages basic functionality of knobs, buttons, pads, LEDs, display
+| io | input/output, manages debug-logging and incoming midi
+| memory | memory management
+| [model](#model-folder) | manages model_stack, the model Deluge uses to represent and pass around its internal state
+| modulation | manages internal modulating of parameters, including automation and midi
+| playback | manages playback and recording modes
+| processing | manages various processes: audio, CV and live audio engines, sound instruments, metronome, stem export
+| storage | manages using files from the SD card
+| testing | automated tests
+| util | collection of general utilities
+| version | deals with the code version
+
+## GUI Folder
+`DelugeFirmware/src/deluge/gui`
+
+*Graphical User Interface. This folder manages all user-facing behavior of the Deluge and is therefor the main focus for fixing bugs and developing new features*
+
+| Folder | Contents
+|-|-
+| colour | colour definitions
+| context_menu | the context menu pops up on top of the regular menu, depending on contextual actions
+| fonts | font definitions
+| l10n | list of strings used in the ui for both 7SEG and oled, can be used for localization
+| menu_item | definitions for the options of all menus
+| ui | manages the foundational layer of the ui including menus, browsers, keyboard views and saving/loading. `ui.cpp` serves as a base-class that the different views/modes of the Deluge are built on
+| [views](#views-folder) | manages the main views/modes of the Deluge, such as clip view and arranger view
+| waveform | manages the waveform view
+
+### UI Folder
+`DelugeFirmware/src/deluge/gui/ui/`
+
+*User Interface. Many low-level and base methods of the user interface are defined here, and reused in higher level code*
+
+| Class | Relevance
+|-|-
+| `AudioRecorder` | is a `UI`
+| menus | Handles the main menu system. There's no overarching class here
+| `QwertyUI` | is a `UI` that uses the grid pads as a qwerty keyboard
+| `RootUI` | is a `UI`
+| `SampleMarkerEditor` |
+| `Slicer` |
+| `SoundEditor` |
+| `UI` | Absolute base class of all UIs
+
+### Views Folder
+`DelugeFirmware/src/deluge/gui/views`
+
+*This folder manages all the main modes of the Deluge ui*
+
+Each of the `final` views - that is, each view that is not meant to be a base-class for something else - defines a global variable of itself at the bottom of its header file. For example:
+```cpp
+extern AutomationView automationView;
+```
+This global variable is reused anytime that view is activated.
+
+| View | Info
+|-|-
+| `ArrangerView final` | is a `TimelineView` representing the arranger view
+| `AudioClipView final` | is a `ClipView` for audio clips
+| `AutomationView final` | is a `ClipView` that handles the automation view in different contexts
+| `ClipNavigationTimelineView` | is a `TimelineView`
+| `ClipView` | is a `ClipNavigationTimelineView` set up to handle a single clip
+| `InstrumentClipView final` | is a `ClipView` for instrument clips
+| `PerformanceSessionView final` | is a `ClipNavigationTimelineView` that implements performance fx view
+| `SessionView final` | is a `ClipNavigationTimelineView`. This is *Song View* and contains both *Song Row View* and *Song Grid View*
+| `TimelineView` | inherits from `RootUI` and `UI`, and is itself a base class for all other views
+| `View` | defines a global variable `view` which represents a layer of the user interface which is always available, regardless of what specific view we're in
+
+### Model Folder
+`DelugeFirmware/src/deluge/model`
diff --git a/code_docs/Organization.md b/code_docs/Organization.md
@@ -0,0 +1,73 @@
+# Community firmware organization
+#### To work out
+- docs folder, (dev/bug_fixes) cleanup, consistency, how-to-use
+- what functionality is in hid vs gui and why?
+- why is colour in gui
+- why is waveform not in ui or views?
+
+### Naming conventions
+#### General observations
+- Naming conventions sometimes don't align between the public UI and the code. Song view being called session_view in code is a good example. These differences are also not documented. This makes it difficult for especially people new to the project to find their way
+- Some features could have more descriptive names. For example green/blue mode in Grid View are sometimes called launch and edit mode, but are in code and documentation referenced as green and blue. It would be helpful for both users and developers to refer to features by a descriptive name, both in code and documentation
+-  Some new menu-items - especially in `community firmware` - don't have descriptive names but are listed as "alternate [x] behavior", which puts the load on the user's memory to remember what they do. It would be helpful to have all menu names be descriptive
+-  At the same time, many menu items are longer than the display allows. This is probably not possible to avoid altogether, but navigating a menu with items that fit the display is significantly faster. It could pay off to rework menu items' naming to be both descriptive and short. For example: `stutter quantize` conveys as much information as `stutter rate quantize` while still fitting on the display. *(Note: some longer names from the community features menu will get shorter automatically when they are implemented in their dedicated spot in the regular menu, f.e. `grid view loop layer pads` will become `loop layer pads` when placed in the grid view menu)*
+#### Modes vs Views vs Layouts
+If there is a learning curve to the Deluge, I feel the biggest hurdle is the lack of distinction between the scope and significance of different views. Currently, everything from the arranger, to the grid, to sequencing, to audio recording, to loading files is called a **view**. Having no structure to place all these fundamentally different features into makes it difficult to build up a good understanding what is happening.
+
+Having a more descriptive, hierarchical naming convention for different kinds of features makes it easier for beginners to feel at ease with the interface, *and* makes it easier for developers to add features in a way that keeps the interface manageable. This could be part of refactoring ui & views, if we decide to do so. A proposal:
+
+1. **Modes** describe mutually exclusive fundamental ways in which the device behaves. Currenly this would only apply to **Song Mode** and **Arranger Mode**. At any time, either one or the other is active - never both. This allows us to rename the Song Mode layouts to **Rows View** and **Grid View**. *This could be implemented without changing anything else.*
+2. **Views** exclusively describe ways of **viewing** and **interacting** with a **mode**. Currently this would only apply to **Rows View**, **Grid View** and **Performance View**. *(One could imagine a grid view for arranger mode, where the arrangement plays top to bottom, which would make all views compatible with both modes.)*
+3. **Editors:** clip and automation view operate fundamentally different from the more similar aforementioned views. To distinguish them from those views, they are labeled **Clip Editor**, **Clip Automation Editor** and **Arranger Automation Editor**.
+4. **Tools:** There is a selection of mostly autonomous tools/features that can be called in different places in the UI, but operate largely the same regardless of where they are called. Think of the browser, waveform editor and audio recorder. These currently aren't called views, but they are documented in the manual under the views they appear in. Instead they should be documented as what they are: a clearly delineated, autonomous tool. *There may be a better name for this.*
+
+The documentation structure would look something like this:
+- General UI
+  - Browser
+  - ...
+- Modes
+  - Song Mode
+  - Arranger Mode
+- Views
+  - Rows View
+  - Grid View
+  - Performance View
+- Clip Editor *(gets its own main header because of how much happens here, and has a dedicated ui button)*
+  - Sequencing
+  - Modulation
+  - ...
+- Tools
+  - Automation Editor
+  - Waveform Editor
+  - Audio Recorder
+  - ...
+
+
+### Code Cleanup
+#### Views
+- The current general strategy is to create global variables for all the main views and reuse them when activated. Is it safer/easier to refactor them to static properties?
+- None of the views inherit from view.h, which could be assumed would be the case from how the files are named. Instead all views inherit from `TimelineView`
+- `ClipNavigationTimelineView` is a `TimelineView` and only implements a few methods. `TimelineView` itself is only used as a base class for `ArrangerView`. This could probably be simplified into one class
+- **Proposal:**
+  - Combine `TimelineView` and `ClipNavigationTimelineView` to a new `View` class. This is a `RootUI` and will remain the base class of all other views. Shared behavior for views lives here
+  - The current `View` holds three types of behavior, which should all be relocated to their appropriate locations:
+    - View-specific behavior moves to their respective views, where possible as overrides from the new `View`
+    - Shared behavior between all views moves to the new `View` class
+    - Global UI behavior really doesn't belong in the views folder at all, should probably move to `src/ui/ui.cpp`
+  - *I have yet to dive into the code rigorously enough to realise whether or not there are any code-breaking issues that prevent this solution*
+- *Song View* is called `SessionView` in the repo
+- *Song Row View* and *Song Grid View* both live in `SessionView` and are probably different enough to live in their own separate files.
+- **Proposal:**
+  - Rename `SessionView` to `SongView`
+  - Separate unique behavior for *Song View, Row Layout* and *Song View, Grid Layout* into `song_view_grid_layout.h` and `song_view_row_layout.h`
+  - Rename `PerformanceSessionView` to `PerformanceView`
+  - Refactor methods and properties accordingly
+- `PerformanceSessionView` is not a `SessionView` 
+- **Proposal:**
+  - Rename `PerformanceSessionView` to `PerformanceView`
+- `AutomationView` is too large to manage
+- **Proposal:**
+  - Refactor `AutomationView` to a base-class which can be inherited from in different contexts, behavior can be organized in child-classes
+
+#### UI
+- There's a whole bunch of global stuff here. It would probably help legibility in other parts of the code if these were captured in a (static) class. UI mode defines could be in an enum : uint32_t for the same reason.
diff --git a/code_docs/ui_dependencies.md b/code_docs/ui_dependencies.md
@@ -0,0 +1,13 @@
+# UI
+Absolute base class for all UI. Implements base virtual methods for all user actions, which get overridden in sub-classes.
+```cpp
+	virtual ActionResult padAction(int32_t x, int32_t y, int32_t velocity);
+	virtual ActionResult buttonAction(deluge::hid::Button b, bool on, bool inCardRoutine);
+	virtual ActionResult horizontalEncoderAction(int32_t offset);
+	virtual ActionResult verticalEncoderAction(int32_t offset, bool inCardRoutine);
+	virtual void selectEncoderAction(int8_t offset);
+	virtual void modEncoderAction(int32_t whichModEncoder, int32_t offset);
+	virtual void modButtonAction(uint8_t whichButton, bool on);
+	virtual void modEncoderButtonAction(uint8_t whichModEncoder, bool on);
+```
+Plus a whole bunch of general, rendering, conversion (etc.) virtual methods.