Merge pull request #146 from boydm/doc_review

Refactor Cache Docs

Author: boydm

CHANGELOG.md

@@ -49,12 +49,20 @@
 **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` |
+  | Asset Class   | Module  |
+  | ------------- | -----|
+  | Fonts      | `Scenic.Cache.Static.Font` |  
+  | Font Metrics | `Scenic.Cache.Static.FontMetrics` |
+  | Textures (images in a fill) | `Scenic.Cache.Static.Texture` |
+  | Raw Pixel Maps | `Scenic.Cache.Dynamic.Texture` |
+
+  Some of the Cache support modules have moved
+
+  | Old Module   | New Module  |
+  | ------------- | -----|
+  | `Scenic.Cache.Hash` | `Scenic.Cache.Support.Hash` |
+  | `Scenic.Cache.File` | `Scenic.Cache.Support.File` |
+  | `Scenic.Cache.Supervisor` | `Scenic.Cache.Support.Supervisor` |
 
 
 ## 0.9.0

lib/scenic/cache/base.ex

@@ -12,9 +12,18 @@ defmodule Scenic.Cache.Base do
 
   | Asset Class   | Module  |
   | ------------- | -----|
-  | Fonts      | [Scenic.Cache.Font](Scenic.Cache.Font.html) |
-  | Font Metrics | [Scenic.Cache.FontMetrics](Scenic.Cache.FontMetrics.html) |
-  | Textures (images in a fill) | [Scenic.Cache.Texture](Scenic.Cache.Texture.html) |
+  | Fonts      | `Scenic.Cache.Static.Font` |  
+  | Font Metrics | `Scenic.Cache.Static.FontMetrics` |
+  | Textures (images in a fill) | `Scenic.Cache.Static.Texture` |
+  | Raw Pixel Maps | `Scenic.Cache.Dynamic.Texture` |
+
+  Some of the Cache support modules have moved
+
+  | Old Module   | New Module  |
+  | ------------- | -----|
+  | `Scenic.Cache.Hash` | `Scenic.Cache.Support.Hash` |
+  | `Scenic.Cache.File` | `Scenic.Cache.Support.File` |
+  | `Scenic.Cache.Supervisor` | `Scenic.Cache.Support.Supervisor` |
 
   ## Overview
 
@@ -182,129 +191,6 @@ defmodule Scenic.Cache.Base do
         @behaviour Scenic.Cache.Base
       end
 
-      @moduledoc """
-      In memory cache for static #{unquote(using_opts)[:name]} assets.
-
-      Assets such as #{unquote(using_opts)[:name]} tend to be relatively large compared to
-      other data. These assets are often used across multiple scenes and may need to be shared
-      with multiple drivers.
-
-      These assets also tend to have a significant load cost. Fonts need to be rendered. Images
-      interpreted into their final binary form, etc.
-
-      ## Goals
-
-      Given this situation, the Cache module has multiple goals.
-      * __Reuse__ - assets used by multiple scenes should only be stored in memory once
-      * __Load Time__- loading cost should only be paid once
-      * __Copy time__ - assets are stored in ETS, so they don't need to be copied as they are used
-      * __Pub/Sub__ - Consumers of static assets (drivers...) should be notified when an asset is
-      loaded or changed. They should not poll the system.
-      * __Security__ - Base assets can become an attack vector. Helper modules are provided
-      to assist in verifying these files.
-
-      ## Scope
-
-      When a #{unquote(using_opts)[:name]} is loaded into the cache, it is assigned a scope. 
-      The scope is used to
-      determine how long to hold the asset in memory before it is unloaded. Scope is either
-      the atom `:global`, or a `pid`.
-
-      The typical flow is that a scene will load a #{unquote(using_opts)[:name]} into the cache.
-      A scope is automatically
-      defined that tracks the asset against the pid of the scene that loaded it. When the scene
-      is closed, the scope becomes empty and the asset is unloaded.
-
-      If, while that scene is loaded, another scene (or any process...) attempts to load
-      the same asset into the cache, a second scope is added and the duplicate load is
-      skipped. When the first scene closes, the asset stays in memory as long as the second
-      scope remains valid.
-
-      When a scene closes, it's scope stays valid for a short time in order to give the next
-      scene a chance to load its assets (or claim a scope) and possibly re-use the already
-      loaded assets.
-
-      This is also useful in the event of a scene crashing and being restarted. The delay
-      in unloading the scope means that the replacement scene will use already loaded
-      assets instead of loading the same files again for no real benefit.
-
-      When you load assets you can alternately provide your own scope instead of taking the
-      default, which is your processes pid. If you provide `:global`, then the asset will
-      stay in memory until you explicitly release it.
-
-      ## Hashes
-
-      At its simplest, accessing the cache is a key-value store. This cache is meant to be
-      static in nature, so the key is be a hash of the data.
-
-      Why? Read below...
-
-      ## Security
-
-      A lesson learned the hard way is that static assets (fonts, images, etc) that your app
-      loads out of storage can easily become attack vectors.
-
-      These formats are complicated! There is no guarantee (on any system) that a malformed
-      asset will not cause an error in the C code that interprets it. Again - these are complicated
-      and the renderers need to be fast...
-
-      The solution is to compute a SHA hash of these files during build-time of your
-      and to store the result in your applications code itself. Then during run time, you 
-      compare then pre-computed hash against the run-time of the asset being loaded.
-
-      Please take advantage of the helper modules [`Cache.File`](Scenic.Cache.File.html),
-      [`Cache.Term`](Scenic.Cache.Term.html), and [`Cache.Hash`](Scenic.Cache.Hash.html) to
-      do this for you. These modules load files and insert them into the cache while checking
-      a precomputed hash.
-
-      These scheme is much stronger when the application code itself is also signed and
-      verified, but that is an exercise for the packaging tools.
-
-      Full Example:
-
-          defmodule MyApp.MyScene do
-            use Scenic.Scene
-            import Scenic.Primitives
-
-            # build the path to the static asset file (compile time)
-            @asset_path :code.priv_dir(:my_app) |> Path.join("/static/images/asset.jpg")
-
-            # pre-compute the hash (compile time)
-            @asset_hash Scenic.Cache.Hash.file!( @asset_path, :sha )
-
-            # build a graph that uses the asset (compile time)
-            @graph Scenic.Graph.build()
-            |> rect( {100, 100}, fill: {:image, @asset_hash} )
-
-
-            def init( _, _ ) do
-              # load the asset into the cache (run time)
-              Scenic.Cache.File.load(@asset_path, @asset_hash)
-
-              {:ok, :some_state, push: @graph}
-            end
-
-          end
-
-      When assets are loaded this way, the `@asset_hash` term is also used as the key in
-      the cache. This has the additional benefit of allowing you to pre-compute
-      the graph itself, using the correct keys for the correct assets.
-
-      ## Pub/Sub
-
-      Drivers (or any process...) listen to the #{unquote(using_opts)[:name]}
-      Cache via a simple pub/sub api.
-
-      Because the graph, may be computed during compile time and pushed at some
-      other time than the assets are loaded, the drivers need to know when the assets
-      become available.
-
-      Whenever any asset is loaded into the cache, messages are sent to any
-      subscribing processes along with the affected keys. This allows them to react in a
-      loosely-coupled way to how the assets are managed in your scene.
-
-      """
-
       unless unquote(using_opts)[:name] do
         raise "You must supply a :name option to the \"use Scenic.Cache.Base\" macro."
       end
@@ -373,8 +259,7 @@ defmodule Scenic.Cache.Base do
         * `scope` - Optional scope to track the lifetime of this asset against. Can be `:global`
         but is usually nil, which defaults to the pid of the calling process.
 
-        Returns:
-        {:ok, hash}
+        Returns: `{:ok, hash}`
         """
         @spec put(
                 hash :: Scenic.Cache.Base.hash(),
@@ -400,8 +285,7 @@ defmodule Scenic.Cache.Base do
       * `scope` - Optional scope to track the lifetime of this asset against. Can be `:global`
       but is usually nil, which defaults to the pid of the calling process.
 
-      Returns:
-      {:ok, hash}
+      Returns: `{:ok, hash}`
       """
       @spec put_new(
               hash :: Scenic.Cache.Base.hash(),
@@ -692,46 +576,6 @@ defmodule Scenic.Cache.Base do
     GenServer.call(service, {:put, normalize_scope(scope), key, data})
   end
 
-  # # --------------------------------------------------------
-  # @doc """
-  # Insert an item into the Cache. If it is already in the cache, then it
-  # does nothing and returns {:ok, hash}
-
-  # Parameters:
-  # * `key` - term to use as the retrieval key. Typically a hash of the data itself.
-  # * `data` - term to use as the stored data
-  # * `scope` - Optional scope to track the lifetime of this asset against. Can be `:global`
-  # but is usually nil, which defaults to the pid of the calling process.
-
-  # ## Examples
-  #     iex> Scenic.Cache.get("test_key")
-  #     nil
-
-  #     iex> :ets.insert(:scenic_cache_key_table, {"test_key", 1, :test_data})
-  #     ...> true
-  #     ...> Scenic.Cache.get("test_key")
-  #     :test_data
-  # """
-  # @spec put_new(
-  #         service :: atom,
-  #         hash :: Scenic.Cache.Base.hash(),
-  #         data :: term(),
-  #         scope :: :global | nil | GenServer.server()
-  #       ) :: term()
-
-  # def put_new(service, hash, data, scope \\ nil)
-  #     when service != nil and (is_atom(service) or is_pid(service)) do
-  #   scope = normalize_scope(scope)
-
-  #   case :ets.member(service, hash) do
-  #     true ->
-  #       {:ok, hash}
-
-  #     false ->
-  #       GenServer.call(service, {:put_new, scope, hash, data})
-  #   end
-  # end
-
   # --------------------------------------------------------
   @doc """
   Add a scope to an existing asset in the cache.
@@ -776,7 +620,7 @@ defmodule Scenic.Cache.Base do
   processes a chance to claim a scope before it is unloaded.
   """
 
-  # returns :ok
+  # returns `:ok`
   @spec release(
           service :: atom,
           hash :: Scenic.Cache.Base.hash(),
@@ -815,9 +659,11 @@ defmodule Scenic.Cache.Base do
   Pass in the service, hash, and a scope.
 
   returns one of:
-    {:ok, hash}           # it is claimed by the given scope
-    {:ok, :global}        # it is NOT claimed by the given scope, but is :global
-    {:error, :not_found}  # it is not in the cache at all
+  ```elixir
+  {:ok, hash}           # it is claimed by the given scope
+  {:ok, :global}        # it is NOT claimed by the given scope, but is :global
+  {:error, :not_found}  # it is not in the cache at all
+  ```
   """
   @spec status(
           service :: atom,
@@ -855,7 +701,7 @@ defmodule Scenic.Cache.Base do
 
   Pass in the service and a hash.
 
-  returns true or false.
+  returns `true` or `false`.
   """
   @spec member?(
           service :: atom,
@@ -870,7 +716,7 @@ defmodule Scenic.Cache.Base do
 
   Pass in the service, hash, and scope.
 
-  returns true or false.
+  returns `true` or `false`.
   """
   @spec claimed?(
           service :: atom,

lib/scenic/cache/dynamic/texture.ex

@@ -9,6 +9,76 @@ defmodule Scenic.Cache.Dynamic.Texture do
 
   # import IEx
 
+  @moduledoc """
+  In memory cache for static dynamic Image assets.
+
+  In graphics-speak, an image that is being drawn to the screen is a "Texture".
+
+  Unlike `Scenic.Cache.Static.Texture`, this module assumes that the pixels to be rendered
+  in the image are being generated on the at runtime and change, perhaps rapidly.
+
+  The primary example is capturing an image off of a camera. This data is generated
+  on the fly and needs to be presented to the video card with as little encoding being done
+  as possible.
+
+  So instead of using a hash of the data as a key (which doesn't make sense given that the data
+  is changing...), you pick a unique string to represent the stream of data. It is up to you
+  to make sure the names you choose are unique in your app.
+
+  The only data the `Scenic.Cache.Dynamic.Texture` accepts is a raw pixel map. Please use the `Scenic.Utilities.Texture`
+  module to help build and manage these data sets.
+
+  ## Goals
+
+  Given this situation, the dynamic Cache module has multiple goals.
+  * __Reuse__ - assets used by multiple scenes should only be stored in memory once
+  * __Copy time__ - assets are stored in ETS, so they don't need to be copied as they are used
+  * __Pub/Sub__ - Consumers of static assets (drivers...) should be notified when an asset is
+  loaded or changed. They should not poll the system.
+
+  ## Scope
+
+  When a texture term is loaded into the cache, it is assigned a scope. 
+  The scope is used to
+  determine how long to hold the asset in memory before it is unloaded. Scope is either
+  the atom `:global`, or a `pid`.
+
+  The typical flow is that a scene will load a font into the cache. A scope is automatically
+  defined that tracks the asset against the pid of the scene that loaded it. When the scene
+  is closed, the scope becomes empty and the asset is unloaded.
+
+  If, while that scene is loaded, another scene (or any process...) attempts to load
+  the same asset into the cache, a second scope is added and the duplicate load is
+  skipped. When the first scene closes, the asset stays in memory as long as the second
+  scope remains valid.
+
+  When a scene closes, it's scope stays valid for a short time in order to give the next
+  scene a chance to load its assets (or claim a scope) and possibly re-use the already
+  loaded assets.
+
+  This is also useful in the event of a scene crashing and being restarted. The delay
+  in unloading the scope means that the replacement scene will use already loaded
+  assets instead of loading the same files again for no real benefit.
+
+  When you load assets you can alternately provide your own scope instead of taking the
+  default, which is your processes pid. If you provide `:global`, then the asset will
+  stay in memory until you explicitly release it.
+
+  ## Pub/Sub
+
+  Drivers (or any process...) listen to the font
+  Cache via a simple pub/sub api.
+
+  Because the graph, may be computed during compile time and pushed at some
+  other time than the assets are loaded, the drivers need to know when the assets
+  become available.
+
+  Whenever any asset is loaded into the cache, messages are sent to any
+  subscribing processes along with the affected keys. This allows them to react in a
+  loosely-coupled way to how the assets are managed in your scene.
+
+  """
+
   # --------------------------------------------------------
   def put(key, data, opts) do
     case validate(data) do