update push_graph docs and some cache docs

Author: boydm

CHANGELOG.md

@@ -49,6 +49,14 @@
 **Breaking Changes:**
 * Breaking changes to Scenic.Cache. It has been replaced by asset specific caches.
 
+| Asset Type | Module |
+| --- | --- |
+| Static Textures | `Scenic.Cache.Static.Texture` |
+| Fonts | `Scenic.Cache.Static.Font` |
+| Font Metrics | `Scenic.Cache.Static.FontMetrics` |
+| Dynamic Textures | `Scenic.Cache.Dynamic.Texture` |
+
+
 ## 0.9.0
 * Much improved testing
 * Much improved documentation

guides/custom_fonts.md

@@ -2,12 +2,12 @@
 
 Scenic ships standard with support for the [Roboto](https://fonts.google.com/specimen/Roboto) and [Roboto_Mono](https://fonts.google.com/specimen/Roboto+Mono) fonts. The [Roboto_Slab](https://fonts.google.com/specimen/Roboto+Slab) font is no longer standard in Scenic.
 
-You can add the RobotoSlab font, and most any other TrueType font you want to use into Scenic.
+You can, however, add the RobotoSlab font, and most any other TrueType font you want to use into Scenic.
 
 To do this you will need do the following steps.
 
   1. Download the font you want to use and add it to the static files of your `priv/` folder in your application. Please be aware of font licenses and make good choices.
-  2. Use the truetype_metrics hex package to generate a `*.metrics` file, which you also add to your `priv/` folder. This tool will also change the name of your font so that a hash of the data is included in the file name.
+  2. Use the [truetype_metrics](https://hex.pm/packages/truetype_metrics) hex package to generate a `*.metrics` file, which you also add to your `priv/` folder. This tool will also change the name of your font so that a hash of the data is included in the file name.
   3. Load the `*.metrics` file into the `Scenic.Cache.Static.FontMetrics` cache.
   4. refer to the font by the key to the metrics file in the graph where you want to use it.
 
@@ -28,9 +28,9 @@ priv/
 
 ## Generate the `\*.metrics` file
 
-Use the truetype_metrics tool to generate a font metrics file. This tool is not included in Scenic because this code is complicated (don't get me started on the TrueType format) and only needs to be run once when you set it up.
+Use the [truetype_metrics](https://hex.pm/packages/truetype_metrics) tool to generate a font metrics file. This tool is not included in Scenic because this code is complicated (don't get me started on the TrueType format) and only needs to be used once when you set up your project.
 
-This tool will do two things. It will create a .metrics file and decorate the name of the font itself with a hash of its contents.
+This tool will do two things. It will create a `\*.metrics` file and decorate the name of the font itself with a hash of its contents.
 
 You may need to install the tool as an archive first
 
@@ -56,24 +56,41 @@ priv/
         RobotoSlab-Regular.ttf.metrics
 ```
 
-Read the truetype_metrics documentation to learn how to recurse font folders, control the font name decoration and force the file to be re-generated.
+Read the [truetype_metrics](https://hex.pm/packages/truetype_metrics) documentation to learn how to recurse font folders, control the font name decoration and force the file to be re-generated.
 
-## Load the `\*.metrics` file into the cache
+## Load the `\*.metrics` file and the font into the cache
 
-In your scene, you need to make load the `\*.metrics` file into the `Scenic.Cache.Static.FontMetrics` cache.
+In your scene, you need to make load both the `\*.metrics` file into the `Scenic.Cache.Static.FontMetrics` cache and the font itself into the `Scenic.Cache.Static.Font` cache.
 
 
 ```elixir
+@font_folder :code.priv_dir(:my_app) |> Path.join("/static/fonts")
+@custom_font_hash "0IXAWqFTtjn6MKSgQOzxUgxNKGrmyhqz1e2d90PVHck"
+@custom_metrics_path :code.priv_dir(:scenic_example)
+           |> Path.join("/static/fonts/Roboto_Slab/RobotoSlab-Regular.ttf.metrics")
+@custom_metrics_hash Scenic.Cache.Support.Hash.file!(@custom_metrics_path, :sha)
+
+def init(_, _opts) do
+  # load the custom font
+  Cache.Static.Font.load(@font_folder, @custom_font_hash)
+  Cache.Static.FontMetrics.load(@custom_metrics_path, @custom_metrics_hash)
+
+  # no need to put the graph into state as we won't be using it again
+  {:ok, nil, push: @graph}
+end
 ```
 
 Note that if you use this font everywhere, you may want to load it once during app startup with the `:global` scope. Then you can just refer to it without having to load it in every scene.
 
 ```elixir
+Cache.Static.Font.load(@font_folder, @custom_font_hash, scope: :global)
+Cache.Static.FontMetrics.load(@custom_metrics_path, @custom_metrics_hash, scope: :global)
 ```
 
 ## Refer to the font by the metrics key
 
 Finally, you use the key to refer to the font metrics in the graph. The font itself will be loaded and used automatically as needed. The metrics file already contains the hash of the font itself.
 
 ```elixir
+text_spec("Font Test", translate: {0, 40}, font_size: 60, font: @custom_metrics_hash)
 ```

guides/overview_graph.md

@@ -84,9 +84,8 @@ This time, we've assigned ids to both of the text primitives. This makes it easy
       @graph
       |> Graph.modify( :small_text, &text(&1, "Smaller Hello", font_size: 16))
       |> Graph.modify( :big_text, &text(&1, "Bigger Hello", font_size: 60))
-      |> push_graph()
 
-Notice that the graph is modified multiple times in the pipeline. The `push_graph/1` function is relatively heavy when the graph references other scenes. The recommended pattern is to make multiple changes to the graph and then push once at the end.
+Notice that the graph is modified multiple times in the pipeline.
 
 
 ## What to read next?

guides/overview_primitives.md

@@ -93,9 +93,8 @@ In the above graph, we've assigned `:id` values to both primitives. This makes i
       @graph
       |> Graph.modify( :small_text, &text(&1, "Smaller Hello", font_size: 16))
       |> Graph.modify( :big_text, &text(&1, "Bigger Hello", font_size: 60))
-      |> push_graph()
 
-Notice that the graph is modified multiple times in the pipeline. The `push_graph/1` function is relatively heavy when the graph references other scenes. The recommended pattern is to make multiple changes to the graph and then push once at the end.
+Notice that the graph is modified multiple times in the pipeline.
 
 The last parameter to `Graph.modify/3` is a pointer to a function that receives a primitive and returns the the new primitive that should be inserted in its place.
 

guides/overview_scene.md

@@ -55,8 +55,7 @@ whose helper function is imported from the `Scenic.Components` module.
           |> button({"Do Something", :btn_something}, translate: {20, 180})
 
         def init( _scene_args, _options ) do
-          push_graph( @graph )
-          {:ok, @graph}
+          {:ok, @graph, push: @graph}
         end
 
         ...
@@ -85,14 +84,12 @@ build and push your first graph, the user will see a blank space or screen until
 you are ready.
 
     def init( _scene_args, opts ) do
-      push_graph( @graph )
-
       state = %{
         graph: @graph,
         viewport: opts[:viewport]
       }
 
-      {:ok, state}
+      {:ok, state, push: @graph}
     end
 
 The first argument, `scene_args`, is any term that you pass to your scene when
@@ -134,51 +131,40 @@ option      | description
 
 ## Pushing a Graph
 
-`push_graph/1` is a "magic" function. Magic functions embody knowledge of the
-system outside of the data passed into them and are not purely "functional" in
-the programming sense. I am generally against using magic functions. However,
-after much thought and experimentation, I landed on this one bit of magic to
-accomplish a difficult job.
-
-> `push_graph/1` is a private function that is injected into your scene by the
-> `use Scenic.Scene` macro. Your scene will not work without it.
-
-In a nutshell, `push_graph/1` does two jobs.
-
-First, it triggers the [life-cycle](scene_lifecycle.html) of any components the
-graph references. This means that component processes may start or stop when you
-push a graph. This will only happen if you change components used in the graph.
+Previous to v0.10, the way to push a graph to the ViewPort was the magic `push_graph/1` function, This has been deprecated in favor of a more functional return option. `push_graph/1` was also interfering with the newer OTP 21+ continue callbacks and timeouts and such. Since this is only a deprecation `push_graph/1` will continue to work, but will log a warning when used. `push_graph/1` will be removed in a future release.
 
-Second, it prepares the graph for use by the [Drivers](overview_driver.html) and
-the input path of the [ViewPort](overview_viewport.html). This mostly involves
-stripping internal data and caching the resulting term in an
-[ets](https://elixirschool.com/en/lessons/specifics/ets/) table so that it can
-be used very quickly, on demand, by those systems.
+The new, better way to push a graph is via a {:push, graph} option when you return from any scene callback.
 
-`push_graph/1` returns the original graph passed in to it. This is so you can
-hang the call off the end of a pipe chain that transforms the graph. This isn't
-really necessary, but I like it as it visually indicates that the graph was
-transformed and pushed as a logical unit.
+```elixir
+def init(_,_) do
+  {:ok, :whatever_state_you_want, push: @graph}
+end
 
-      graph
-      |> Graph.modify(:background, &update_opts(&1, fill: clear_color) )
-      |> push_graph()
+def handle_info(:some_msg, your_state) do
+  graph = Graph.modify( @graph, :some_id, &text(&1, "modified text") )
+  {:noreply, your_state, push: graph}
+end
+```
 
-More on `Graph.modify` in the [input](#user-input) and [events](#events)
-sections below. Also see the [Graph Overview](overview_graph.html) page.
+Almost all (except terminate...) of the callbacks accept a `{:push, graph}` option. Replacing the call of `push_graph(graph)` within a callback function depends slightly on the context in which it is used.
 
-As you can guess, `push_graph/1` is relatively heavy since it scans every node
-in your graph every time you call it. You should only call it once per input or
-event that you handle.
+  * in `init/2`:
+    * `{:ok, state, [push: graph]}`
+  * in `filter_event/3`:
+    * `{:halt, state, [push: graph]}`
+    * `{:cont, event, state, [push: graph]}`
+  * in `handle_cast/2`:
+    * `{:noreply, state, [push: graph]}`
+  * in `handle_info/2`:
+    * `{:noreply, state, [push: graph]}`
+  * in `handle_call/3`:
+    * `{:reply, reply, state, [push: graph]}`
+    * `{:noreply, state, [push: graph]}`
+  * in `handle_continue/3`:
+    * `{:noreply, state, [push: graph]}`
 
-> A best practice is to make multiple modifications to a graph and then call
-> `push_graph/1` at the end.
+See the [documentation for scene callbacks](Scenic.Scene.html#callbacks) for more information.
 
-      graph = graph
-      |> Graph.modify(:text, &text(&1, "I've been modified") )
-      |> Graph.modify(:a_box, &rect(&1, {100, 200}) )
-      |> Graph.modify(:a_circle, &update_opts(&1, fill: :blue) )
-      |> push_graph()
 
 ## User Input
 
@@ -228,14 +214,13 @@ This will be included in the error that gets raised.
           graph = @graph
           |> Graph.modify(:_root_, &update_opts(&1, styles: opts[:styles]) )
           |> Graph.modify(:text, &text(&1, text) )
-          |> push_graph()
 
           state = %{
             graph: graph,
             text: text
           }
 
-          {:ok, state}
+          {:ok, state, push: graph}
         end
 
         ...

lib/scenic/scene.ex

@@ -245,8 +245,7 @@ defmodule Scenic.Scene do
       use Scenic.Component, has_children: false
 
   Setting `has_children` to `false` this will do two things. First, it won't create
-  a dynamic supervisor for this scene, which saves some resources. Second,
-  `push_graph/1` goes through a fast pass that doesn't scan the graph for dynamic children.
+  a dynamic supervisor for this scene, which saves some resources.
 
   For example, the Button component sets `has_children` to `false`.
   """