Merge remote-tracking branch 'origin/master' into develop

1 files changed, 258 insertions, 0 deletions

diff --git a/users/snowe/readme_ocean_dream.md b/users/snowe/readme_ocean_dream.md
new file mode 100644
index 0000000000..ca15dd47cd
--- /dev/null
+++ b/users/snowe/readme_ocean_dream.md
@@ -0,0 +1,258 @@
+# Ocean Dream
+
+Tapping away at your IMX Corne with Box Jades, you feel yourself
+drifting off, into a soundscape of waves and rustling leaves.
+You open your eyes only to find yourself in an _Ocean Dream_.
+
+Introducing, **Ocean Dream**, an animation for keyboards with tall OLED 
+screens. Built for 128x32 screens, this animation should work for 128x64
+at least, though it hasn't been tested there. 
+
+Completely customizable, you can change everything about the animation, 
+from the number of falling stars, to how likely a star is to twinkle, and 
+even if the moon has phases or not.
+
+# Installation
+
+Installation is easy.
+
+1. Add `ocean.h` and `ocean.c` to your keyboard folder or userspace.
+2. In your `keymap.c` or wherever you handle your oled code, add
+```c
+#    ifdef OCEAN_DREAM_ENABLE
+        render_stars();
+#    endif
+```
+to `oled_task_user(void)`, where you would like (see [my keymap](../../keyboards/crkbd/keymaps/snowe/keymap.c) for an example)
+3. In your `keymap.c` or wherever you handle your process_record code, 
+   add an event that sets `is_calm` when you press `ctrl`
+```c
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+    switch (keycode) {
+        case KC_LCTL:
+        case KC_RCTL:
+#ifdef OCEAN_DREAM_ENABLE
+            is_calm = (record->event.pressed) ? true : false;
+#endif
+            break;
+    }
+    return true;
+}
+```
+4. In your `rules.mk` to make it easier to turn the animation on/off, add
+```makefile
+ifeq ($(strip $(OLED_DRIVER_ENABLE)), yes)
+    #... your code here...
+
+    ifdef OCEAN_DREAM_ENABLE
+        ifeq ($(strip $(OCEAN_DREAM_ENABLE)), yes)
+            SRC += ocean_dream.c
+            OPT_DEFS += -DOCEAN_DREAM_ENABLE
+        endif
+    endif
+    ifndef OCEAN_DREAM_ENABLE
+        SRC += ocean_dream.c
+        OPT_DEFS += -DOCEAN_DREAM_ENABLE
+    endif
+endif
+```
+
+You're done! Now you can enable **Ocean Dream** by simply turning on the OLED feature
+```makefile
+OLED_DRIVER_ENABLE = yes
+```
+
+And if you want to disable it without turning off the OLED Driver you can simply set 
+```makefile
+OCEAN_DREAM_ENABLE = no
+```
+
+# Settings
+
+**Ocean Dream** comes with several different animations, all individually configurable:
+
+* 🌌 Stars that twinkle
+* 🌠 Meteor showers that get more vibrant the faster you type
+* 🌊 Waves that get rougher the faster you type
+* 🏝 An island with a palm tree that blows in the wind the faster you type
+* 🌗 A moon that goes through the moon phases (or not, your choice!)
+
+Each feature can be individually turned on and off, with a simple `#define`. 
+
+You can see all the options and more documentation by looking at `ocean_dream.h`.
+
+All options come enabled by default.
+
+## Global Flags:
+
+### Toggles:
+
+You can toggle on/off any features using these flags:
+
+* `ENABLE_MOON`            // Uses 182 bytes
+* `ENABLE_WAVE`            // Uses 844 bytes
+* `ENABLE_SHOOTING_STARS`  // Uses 872 bytes
+* `ENABLE_ISLAND`
+* `ENABLE_STARS`  // Uses 606 bytes
+
+### Global Configuration:
+
+* `STARRY_NIGHT_ANIM_FRAME_DURATION` - configures how long each frame lasts in ms
+* `NUMBER_OF_FRAMES` - configures the number of frames that constitute a single 'round trip' of animation. 
+  Enables keeping animations in sync/timed with each other. 
+  Probably shouldn't touch this, not sure how stuff will work if it's changed. 
+  If changed should probably be multiple of 1, 2, 3, 4, and 5
+* `WIDTH` - for vertical displays, configures the width (the shortest measurement of your display). defaults to `OLED_DISPLAY_HEIGHT` 
+* `HEIGHT` - for vertical displays, configures the height (the longest measurement of your display). defaults to `OLED_DISPLAY_WIDTH`
+
+## Stars
+
+### Description
+
+The 🌌 stars animation is a background of slowly twinkling stars. 
+The stars are built on a grid of sorts, where each cell of the grid
+is 8x8 pixels with 1 star per cell. There is a probability of any 
+star twinkling on any given frame, decided by the corresponding flags.
+
+### Flags
+
+Enabled with the `#define ENABLE_STARS` directive.
+
+The stars come with several configuration options:
+
+* `STARS_PER_LINE` - configures the number of stars per line. Defaulting to 4, this would
+  mean that you have 4 stars across each line (8x32 on a 128x32 display), where each star 
+  is in a 8x8 grid
+* `NUMBER_OF_STAR_LINES` - configures the number of lines to fill up with stars. 
+  Defaults to 16, filling the whole display.
+* `TWINKLE_PROBABILITY` - configures the probability of a star twinkling on a given frame.
+* `STAR_ANIMATION_SPEED` - configures the number of frames you want to animate the star at. 
+  Must be equal to or lower than `NUMBER_OF_FRAMES`. 
+  Example: 
+  ```c
+    #define NUMBER_OF_FRAMES 20
+    #define STAR_ANIMATION_SPEED 5
+  ```
+  would result in the star animation happening every 4 frames. 20 would result in every frame, 
+  1 would be once every 20 frames. This essentially changes how fast stars will twinkle, but 
+  does not change the probability of the stars twinkling. 
+
+## Moon
+
+### Description
+
+The 🌗 moon animation is an 8x8 animation of a moon, or, if you are running out of program memory, you 
+can set it to just a static crescent moon, with no animation. 
+
+### Flags
+
+Enabled with the `#define ENABLE_MOON` directive.
+
+The moon comes with only a few configuration options:
+
+* `STATIC_MOON` - include this directive if you want your moon to have no animation. It will simply be a static crescent 
+  moon, only taking up 6 bytes of space. If you do not include this directive, then the moon will have an animation. 
+  The default is a moon with animation.
+* `MOON_LINE` - defines the line that the moon sits on. Default is `4`. (see [reference](#reference))
+* `MOON_COLUMN` - defines the column that the moon sits at. Default is `4`. (see [reference](#reference))
+* `ANIMATE_MOON_EVERY_N_FRAMES` - only enabled when `STATIC_MOON` is disabled, this affects how often the moon changes phases. 
+  Example: 
+  ```c
+  #define STARRY_NIGHT_ANIM_FRAME_DURATION 30
+  #ifndef STATIC_MOON
+  #    define ANIMATE_MOON_EVERY_N_FRAMES 100  
+  #endif
+  ```
+  would result in the moon changing phases every 3000ms, or every 3 seconds.
+
+## Ocean
+
+### Description
+
+The 🌊 ocean animation is a full width animation of ocean waves, where the waves get rougher the faster you type. 
+You can configure the boundaries for each degree of _wave ferocity_ as well as how fast the ocean/waves move.
+
+### Flags
+
+* `OCEAN_LINE` - where to render the ocean at. Defaults to `14`. (see [reference](#reference))
+* `OCEAN_ANIMATION_SPEED` - configures the number of frames you want to animate the ocean at.
+  Must be equal to or lower than `NUMBER_OF_FRAMES`.
+  Example:
+  ```c
+    #define NUMBER_OF_FRAMES 20
+    #define OCEAN_ANIMATION_SPEED 5
+  ```
+  would result in the ocean animation happening every 4 frames. 20 would result in every frame,
+  1 would be once every 20 frames. This essentially changes how fast the waves will move.
+* `WAVE_CALM` - Defines the WPM at which the _Wave Ferocity_ kicks up. 
+  At any WPM between `WAVE_CALM` and `WAVE_HEAVY_STORM`, the waves will be just tiny ripples.
+* `WAVE_HEAVY_STORM` - Defines the WPM at which the _Wave Ferocity_ kicks up to medium. 
+  At any WPM between `WAVE_HEAVY_STORM` and `WAVE_HURRICANE`, the waves will be medium sized waves.
+* `WAVE_HURRICANE` - Defines the WPM at which the _Wave Ferocity_ kicks up to the last notch. 
+  At any WPM above `WAVE_HURRICANE`, the waves will be torrential.
+
+## Shooting Stars
+
+The 🌠 shooting star animation is a full screen animation that renders a meteor shower based on your typing speed. The
+faster you type, the more shooting stars there are!
+
+You can configure many parts of the shooting stars, from shower size, to speed, to length of each trail, to how spaced 
+out they are.
+
+Note: Each frame of a shooting star is only 2 pixels in length. This is a design decision, and could probably be changed 
+with a decent amount of work, but was chosen for looks and memory constraints. 
+
+### Flags
+
+* `SHOOTING_STAR_DELAY` - Decides number of frames to delay, based on modulus, e.g. 12 means 0-11 frames of delay between each shooting star
+* `SHOOTING_STAR_FRAMES` - how long each shooting star will be. A size of `16` will result in shooting stars that are 32 pixels long 
+* `MAX_NUMBER_OF_SHOOTING_STARS` - maximum number of shooting stars that can be on screen at the same time
+* `SHOOTING_STAR_WPM_INCREMENT` - every n WPM increase, add an extra star, up to MAX_NUMBER_OF_SHOOTING_STARS
+  Example: an increment of 5 would result in 1 shooting star at 5-9wpm, 2 at 10-14, etc.
+* `SHOOTING_STAR_ANIMATION_SPEED` - configures the number of frames you want to animate the shooting stars at.
+  Must be equal to or lower than `NUMBER_OF_FRAMES`.
+  Example:
+  ```c
+    #define NUMBER_OF_FRAMES 20
+    #define SHOOTING_STAR_ANIMATION_SPEED 5
+  ```
+  would result in the shooting star animation happening every 4 frames. 20 would result in every frame,
+  1 would be once every 20 frames. This essentially changes how fast the stars move through the sky.
+
+
+## Island
+
+The 🏝 island animation is a 32w x 16h animation of a small island with a single palm tree blowing in the wind. The faster
+you type the harder the palm tree blows in the wind!
+
+Since this animation has significant black space to the left side of the tree, certain design decisions were made to allow the 
+shooting stars to still show up in the sky there. This animation should work on any size screen >=32 pixels wide, and you 
+can place it anywhere on the screen, but above the ocean is recommended. 
+
+### Flags
+
+* `ISLAND_LINE` - where to render the island at. Defaults to `12`. The island is 2 lines tall. (see [reference](#reference))
+* `ISLAND_COLUMN` - where to render the island at. Defaults to `0`. The island is 32 pixels wide. (see [reference](#reference))
+* `ISLAND_CALM` - Defines the WPM at which the _Storm Ferocity_ kicks up.
+  At any WPM between `ISLAND_CALM` and `ISLAND_HEAVY_STORM`, the palm tree will just calmly blow in the wind.
+* `ISLAND_HEAVY_STORM` - Defines the WPM at which the _Storm Ferocity_ kicks up.
+  At any WPM between `ISLAND_HEAVY_STORM` and `ISLAND_HURRICANE`, the palm tree will be blowing hard in the wind
+* `ISLAND_HURRICANE` - Defines the WPM at which the _Storm Ferocity_ kicks up.
+  At any WPM above `ISLAND_HURRICANE`, the palm tree will almost be torn from its roots!
+
+
+# Reference
+
+Any reference to `_LINE` or `COLUMN` refers to setting a cursor position using `oled_set_cursor()`, which uses 
+`OLED_FONT_WIDTH` and `OLED_FONT_HEIGHT` internally.  
+This will be the top-leftmost pixel of the image, so `_LINE 1` would start at the 9th pixel down and `_COLUMN 1` 
+would be the 7th pixel to the right, starting from the topleftmost pixel on the screen.
+
+This code has been untested with different font heights/widths, so you might have to adjust a bit to make it work if you 
+have modified those values.
+
+# ToDo
+
+- [ ] don't require `is_calm` as a keyboard event. Not sure if the code will work without it currently.
+- [ ] make all the stars twinkle brightly based on keypresses rather than timed. Not just a movement twinkle, but a larger
+     'full' twinkle, where the star actually gets bigger. This will be quite difficult, thus is left out of the v1.