filling out the guides

Author: boydm

guides/getting_started.md

@@ -1,78 +1,8 @@
 # Getting Started
 
-This guide will walk you through installing the OpenGL related dependencies,
+This guide will walk you through installing the new project generator,
 then building your first Scenic application.
 
-## Install Dependencies
-
-The design of Scenic goes to great lengths to minimize its dependencies to just
-the minimum. Namely, it needs Erlang/Elixir and OpenGL.
-
-Rendering your application into a window on your local computer (MacOS, Ubuntu
-and others) is done by the `scenic_driver_glfw` driver. It uses the GLFW and
-GLEW libraries to connect to OpenGL.
-
-The instructions below assume you have already installed Elixir/Erlang. If you
-need to install Elixir/Erlang there are instructions on the [elixir-lang
-website](https://elixir-lang.org/install.html).
-
-### Installing on MacOS
-
-The easiest way to install on MacOS is to use Homebrew. Just run the following
-in a terminal:
-
-```bash
-brew update
-brew install glfw3 glew pkg-config
-```
-
-Once these components have been installed, you should be able to build the
-`scenic_driver_glfw` driver.
-
-### Installing on Ubuntu 16
-
-The easiest way to install on Ubuntu is to use apt-get. Just run the following:
-
-```bash
-sudo apt-get update
-sudo apt-get install pkgconf libglfw3 libglfw3-dev libglew1.13 libglew-dev
-```
-
-Once these components have been installed, you should be able to build the
-`scenic_driver_glfw` driver.
-
-### Installing on Ubuntu 18
-
-The easiest way to install on Ubuntu is to use apt-get. Just run the following:
-
-```bash
-sudo apt-get update
-sudo apt-get install pkgconf libglfw3 libglfw3-dev libglew2.0 libglew-dev
-```
-
-Once these components have been installed, you should be able to build the
-`scenic_driver_glfw` driver.
-
-### Installing on Fedora
-
-The easiest way to install on Fedora is to use dnf. Just run the following:
-
-```
-dnf install glfw glfw-devel pkgconf glew glew-devel
-```
-
-Once these components have been installed, you should be able to build the `scenic_driver_glfw` driver.
-
-### Installing on Archlinux
-
-The easiest way to install on Archlinux is to use pacman. Just run the following:
-
-```bash
-sudo pacman -S glfw-x11 glew
-```
-
-If you're using wayland, you'll probably need `glfw-wayland` instead of `glfw-x11` and `glew-wayland` instead of `glew`
-
 ## Install `scenic.new`
 
 The Scenic Archive is the home of the `scenic.new` mix task, which layout a

guides/install_dependencies.md

@@ -0,0 +1,69 @@
+# Install Dependencies
+
+The design of Scenic goes to great lengths to minimize its dependencies to just
+the minimum. Namely, it needs Erlang/Elixir and OpenGL.
+
+Rendering your application into a window on your local computer (MacOS, Ubuntu
+and others) is done by the `scenic_driver_glfw` driver. It uses the GLFW and
+GLEW libraries to connect to OpenGL.
+
+The instructions below assume you have already installed Elixir/Erlang. If you
+need to install Elixir/Erlang there are instructions on the [elixir-lang
+website](https://elixir-lang.org/install.html).
+
+### Installing on MacOS
+
+The easiest way to install on MacOS is to use Homebrew. Just run the following
+in a terminal:
+
+```bash
+brew update
+brew install glfw3 glew pkg-config
+```
+
+Once these components have been installed, you should be able to build the
+`scenic_driver_glfw` driver.
+
+### Installing on Ubuntu 16
+
+The easiest way to install on Ubuntu is to use apt-get. Just run the following:
+
+```bash
+sudo apt-get update
+sudo apt-get install pkgconf libglfw3 libglfw3-dev libglew1.13 libglew-dev
+```
+
+Once these components have been installed, you should be able to build the
+`scenic_driver_glfw` driver.
+
+### Installing on Ubuntu 18
+
+The easiest way to install on Ubuntu is to use apt-get. Just run the following:
+
+```bash
+sudo apt-get update
+sudo apt-get install pkgconf libglfw3 libglfw3-dev libglew2.0 libglew-dev
+```
+
+Once these components have been installed, you should be able to build the
+`scenic_driver_glfw` driver.
+
+### Installing on Fedora
+
+The easiest way to install on Fedora is to use dnf. Just run the following:
+
+```
+dnf install glfw glfw-devel pkgconf glew glew-devel
+```
+
+Once these components have been installed, you should be able to build the `scenic_driver_glfw` driver.
+
+### Installing on Archlinux
+
+The easiest way to install on Archlinux is to use pacman. Just run the following:
+
+```bash
+sudo pacman -S glfw-x11 glew
+```
+
+If you're using wayland, you'll probably need `glfw-wayland` instead of `glfw-x11` and `glew-wayland` instead of `glew`

guides/overview_general.md

@@ -57,25 +57,17 @@ be used to build portable applications.
 
 Scenic is built as a three-layer architectural cake.
 
-### Scene Layer
+### [Scene Layer](overview_scene.html)
 
-At the top is the **Scene Layer**, which encapsulates all application business
-logic. The developer will do most of their Scenic work in the Scene layer.
+At the top is the [**Scene Layer**](overview_scene.html), which encapsulates all application business logic. The developer will do most of their Scenic work in the Scene layer.
 
-### ViewPort Layer
+### [ViewPort Layer](overview_viewport.html)
 
-In the middle is the **ViewPort Layer**, which acts as a bridge between the
-Scenes and the Drivers. The ViewPort controls the scene life-cycle (More on that
-in [Scene Overview](overview_scene.html)), sends graphs down to the drivers, and
-routes user input up to the correct scene.
+In the middle is the [**ViewPort Layer**](overview_viewport.html), which acts as a bridge between the Scenes and the Drivers. The ViewPort controls the scene life-cycle (More on that in [Scene Overview](overview_scene.html)), sends graphs down to the drivers, and routes user input up to the correct scene.
 
-### Driver layer
+### [Driver layer](overview_driver.html)
 
-At the bottom is the **Driver layer**, which is where knowledge of the graphics
-hardware and/or remote configuration lives. Drivers draw everything on the
-screen and originate the raw user input. Developers can write their own drivers,
-but that will be rare if at all. Dealing with Sensors and other hardware is a
-different problem space.
+At the bottom is the [**Driver layer**](overview_driver.html), which is where knowledge of the graphics hardware and/or remote configuration lives. Drivers draw everything on the screen and originate the raw user input. Developers can write their own drivers, but that will be rare if at all. Dealing with Sensors and other hardware is a different problem space.
 
 ## Mental Model
 

guides/overview_graph.md

@@ -45,11 +45,11 @@ For example, in the following graph, the font and font_size styles are set at th
 
 ## Transforms
 
-The final type of primitive control is transforms. Unlike html, which uses auto-layout to position items on the screen, Scenic moves primitives around using matrix based transforms. This is common in video games and provides powerful control of your primitives.
+The final type of primitive control is transforms. Unlike html, which uses auto-layout to position items on the screen, Scenic moves primitives around using matrix transforms. This is common in video games and provides powerful control of your primitives.
 
 A [matrix](https://en.wikipedia.org/wiki/Matrix_(mathematics)) is an array of numbers that can be used to change the positions, rotations, scale and more of locations.
 
-In Scenic, you will only rarely create matrices on your own (you can if you know what you are doing!), and will instead use the very easy transform helpers.
+**Don’t worry!** You will not need to look at any matrices unless you want to get fancy. In Scenic, you will rarely (if ever) create matrices on your own (you can if you know what you are doing!), and will instead use the transform helpers.
 
 [You can read about the transform types here.](overview_transforms.html)
 
@@ -84,30 +84,11 @@ 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 a pipeline. 
+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.
 
 
-## Graph Internals
+## What to read next?
 
-
-
-Coming soon
-
-## Positions, rotation, scale and more
-
-A major mental model difference between Scenic and everything web is how things
-are positioned on the screen. In this case, Scenic is built like a game.
-
-Scenic is aimed at fixed-screen devices and apps that control their own layout.
-On the web, there is no guarantee what size screen or window the client will
-use, so it relies on dynamic layout that is computed on the client.
-
-Scenic does not have an auto-layout engine. Instead, everything rendered on the
-screen is positioned with transform matrices, just like a game.
-
-**Don’t worry!** You will not need to look at any matrices unless you want to
-get fancy.
-
-To move something on the screen, just add one of the transform options. Like
-this
+If you are exploring Scenic, then you should read the [Primitives Overview](overview_primitives.html) next.

guides/overview_primitives.md

@@ -1,15 +1,111 @@
-# Styles Overview
-
-* [Arc](Scenic.Primitive.Arc)
-* [Circle](Scenic.Primitive.Circle)
-* [Ellipse](Scenic.Primitive.Ellipse)
-* [Group](Scenic.Primitive.Group)
-* [Line](Scenic.Primitive.Line)
-* [Path](Scenic.Primitive.Path)
-* [Quad](Scenic.Primitive.Quad)
-* [Rectangle](Scenic.Primitive.Rectangle)
-* [RoundedRectangle](Scenic.Primitive.RoundedRectangle)
-* [Scene Ref](Scenic.Primitive.SceneRef)
-* [Sector](Scenic.Primitive.Sector)
-* [Text](Scenic.Primitive.Text)
-* [Triangle](Scenic.Primitive.Triangle)
+# Primitives Overview
+
+Primitives are the simplest thing that Scenic know how to draw to the screen. Everything that you see in a Scenic application is drawn by combining multiple primitives together to make complex UIs.
+
+There is a fixed set of primitives. This simplifies the internals of Scenic, particularly when it comes to communicating to the drivers. New primitives may be added in the future, but those require serious thought and coordination.
+
+* [`Arc`](Scenic.Primitive.Arc.html) draws an arc. This would be a line cut out of a part of the edge of a circle. If you want a shape that looks like a piece of pie, then you should use the [`Sector`](Scenic.Primitive.Sector.html).
+* [`Circle`](Scenic.Primitive.Circle.html) draws a circle. 
+* [`Ellipse`](Scenic.Primitive.Ellipse.html) draws an ellipse.
+* [`Group`](Scenic.Primitive.Group.html) doesn't draw anything. Instead, it creates a node in the graph that you can insert more primitives into. Any styles or transforms you apply to the Group are inherited by all the primitives below it.
+* [`Line`](Scenic.Primitive.Line.html) draws a line.
+* [`Path`](Scenic.Primitive.Path.html) is sort of an escape valve for complex shapes not covered by the other primitives. You supply a list of instructions, such as :move_to, :line_to, :bezier_to, etc to generate a complex shape.
+* [`Quad`](Scenic.Primitive.Quad.html) draws polygon with four sides.
+* [`Rectangle`](Scenic.Primitive.Rectangle.html) draws a rectangle.
+* [`RoundedRectangle`](Scenic.Primitive.RoundedRectangle.html) draws a rectangle with the corners rounded by a given radius.
+* [`SceneRef`](Scenic.Primitive.SceneRef.html) doesn't draw anything by itself. Instead it points to another scene/graph and tells the driver to draw that here.
+* [`Sector`](Scenic.Primitive.Sector.html) draws a shape that looks like a piece of pie. If you want to stroke just the curved edge, then combine it with an [`Arc`](Scenic.Primitive.Arc.html).
+* [`Text`](Scenic.Primitive.Text.html) draws a string of text.
+* [`Triangle`](Scenic.Primitive.Triangle.html) draws a triangle.
+
+## Using Primitives
+
+The easiest way to insert primitives into your graph is to import the functions in `Scenic.Primitives` into your scene module. This adds a helper function for each primitive that you can use in a pipeline to build a graph.
+
+      defmodule MyApp.Scene.Example do
+        use Scenic.Scene
+        alias Scenic.Graph
+        import Scenic.Primitives
+
+        @graph Graph.build(font: :roboto, font_size: 22)
+          |> text("Hello World", text_align: :center, translate: {300, 350})
+          |> circle(150, fill: :green, translate: {300, 350})
+
+        ...
+
+      end
+
+In the example above, the scene calls `import Scenic.Primitives`, which imports helpers for all the primitives. Since the graph only uses text and circle, you could save a tiny bit of memory by just importing what you need.
+
+        import Scenic.Primitives, only: [{:text,3}, {:circle, 3}]
+
+Once the helpers are imported, you call each call appends a primitive to the graph.
+
+## Styles
+
+In addition to the fixed set of primitives, there is also a fixed set of primitive styles. (Some components support more styles, but they really get boiled down to the primitive styles when it is time to render)
+
+[Read more about the styles here.](overview_styles.html)
+
+Styles are inherited down the graph hierarchy. This means that if you set a style on the root of a graph, or in a group, then any primitives below that node inherit those styles without needing to explicitly set them on every single primitive.
+
+For example, in the following graph, the font and font_size styles are set at the root. Both text primitives inherit those values, although the second one overrides the size with something bigger.
+
+    @graph Graph.build(font: :roboto, font_size: 24)
+      |> text("Hello World", translate: {300, 300})
+      |> text("Bigger Hello", font_size: 40, translate: {400, 300})
+
+
+## Transforms
+
+The final type of primitive control is transforms. Unlike html, which uses auto-layout to position items on the screen, Scenic moves primitives around using matrix based transforms. This is common in video games and provides powerful control of your primitives.
+
+A [matrix](https://en.wikipedia.org/wiki/Matrix_(mathematics)) is an array of numbers that can be used to change the positions, rotations, scale and more of locations.
+
+**Don’t worry!** You will not need to look at any matrices unless you want to get fancy. In Scenic, you will rarely (if ever) create matrices on your own (you can if you know what you are doing!), and will instead use the transform helpers.
+
+[You can read about the transform types here.](overview_transforms.html)
+
+Transforms are inherited down the graph hierarchy. This means that if you place a rotation transform at the root of a graph, then all the primitives will be rotated around a common point.
+
+If you want to zoom in, scroll, or rotate a UI, or just pieces of the UI, you can do that very easily by applying transforms.
+
+In the example below, the first text line is translated, and the second is scaled bigger, and the whole graph rotated 0.4 radians.
+
+    @graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4)
+      |> text("Hello World", translate: {300, 300})
+      |> text("Bigger Hello", font_size: 40, scale: 1.5)
+
+
+## Modifying a Primitive
+
+Scenic was written specifically for Erlang/Elixir, which is a functional programming model with immutable data.
+
+As such, once you make a graph, it stays in memory unchanged - until you change it via `Graph.modify/3`. Technically you never change it (that's the immutable part), instead Graph.modify returns a new graph with different data in it.
+
+    @graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4)
+      |> text("Hello World", translate: {300, 300}, id: :small_text)
+      |> text("Bigger Hello", font_size: 40, scale: 1.5, id: :big_text)
+
+In the above graph, we've assigned `:id` values to both primitives. This makes it easy to find and modify that primitive in the graph. `Graph.modify/3` is very fast at finding primitives marked with an `:id`. If you marked multiple primitives withe `id: :small_text`, then they would all be modified by the call to  `Graph.modify/3`
+
+    graph =
+      @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.
+
+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.
+
+The following is the same as one of the calls above, but in expanded form to make it easier to see what is going on
+
+    graph = Graph.modify( graph, :small_text, fn(primitive) ->
+      text(primitive, "Smaller Hello", font_size: 16)
+    end)
+
+
+## What to read next?
+
+If you are exploring Scenic, then you should read the [Styles Overview](overview_styles.html) next.