-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An API for managing renderable resources.
--   
--   The <a>renderable</a> package provides a method for managing resources
--   of a rendering system. Resources are allocated according to a strategy
--   and released automatically when your renderable data changes. These
--   changes are detected during each draw call based on the hash of your
--   renderable datatype. This package is meant to be pulled in as a
--   portion of your rendering system. It aims to ease the task of managing
--   allocation of resources over time as the value of your renderable
--   datatype changes.
@package renderable
@version 0.2.0.1

module Data.Renderable

-- | A <a>RenderStrategy</a> is a method for creating a renderer that can
--   render your primitives. Examples of primitives are are points, lines,
--   triangles and other shapes. A <a>RenderStrategy</a> is parameterized
--   by four types -
--   
--   <tt>m</tt> - the monad in which rendering calls will take place.
--   
--   <tt>t</tt> - type of the graphics transformation that can be applied
--   to the renderer
--   
--   <tt>r</tt> - type that holds static resources such as windows,
--   shaders, etc.
--   
--   <tt>a</tt> - type of the primitive that can be renderered.
data RenderStrategy m t r a
RenderStrategy :: (r -> a -> Bool) -> (r -> a -> m (Renderer m t)) -> RenderStrategy m t r a

-- | Determines whether a renderer can be allocated for the primitive. A
--   result of <a>False</a> will defer compilation until a later time (the
--   next frame).
[canAllocPrimitive] :: RenderStrategy m t r a -> r -> a -> Bool

-- | Allocates resources for rendering the primitive and return a monadic
--   call that renders the primitive using a transform. Tuples that with a
--   call to clean up the allocated resources.
[compilePrimitive] :: RenderStrategy m t r a -> r -> a -> m (Renderer m t)

-- | A Renderer is the pairing of a Rendering and a Cleanup.
type Renderer m t = (CleanOp m, Rendering m t)

-- | A Rendering is an effectful computation for displaying something given
--   a transform.
type Rendering m t = t -> m ()

-- | A CleanOp is an effectfull computaton that cleans up any resources
--   allocated during the creation of an associated Rendering.
type CleanOp m = m ()

-- | A cache of renderers.
type Cache m t = IntMap (Renderer m t)

-- | A sum of lists of rendering hashes between two cache states. Used for
--   debugging resource management.
data CacheStats a
CacheStats :: [Int] -> [Int] -> [Int] -> [Int] -> [Int] -> CacheStats a

-- | All the keys of the previous cache state.
[cachedPrev] :: CacheStats a -> [Int]

-- | The keys needed for the next state that were found in the previous
--   cache (no need to allocate).
[cachedFound] :: CacheStats a -> [Int]

-- | The keys needed for the next state that were not found in the previous
--   cache (these will need allocating).
[cachedMissing] :: CacheStats a -> [Int]

-- | The keys found in the previous cache that are not needed for the next
--   state (these can be deallocated).
[cachedStale] :: CacheStats a -> [Int]

-- | All the keys of the next cache state.
[cachedNext] :: CacheStats a -> [Int]

-- | Render a list of primitives using renderings stored in the given
--   cache, return a new cache that can be used to render the next list of
--   primitives.
renderPrims :: (Functor m, Monad m, Monoid t, Hashable a) => RenderStrategy m t r a -> r -> Cache m t -> [(t, a)] -> m (Cache m t)

-- | Render a list of primitives using renderings stored in the given
--   cache, return a new cache that can be used to render the next list of
--   primitives. Optionally print some debug info.
renderPrimsDebug :: (Functor m, MonadIO m, Monoid t, Hashable a) => Bool -> RenderStrategy m t r a -> r -> Cache m t -> [(t, a)] -> m (Cache m t)

-- | Render a list of primitives using renderings stored in the given
--   cache, return a new cache that can be used to render the next list of
--   primitives, along with some info about the comparison of the given and
--   returned cache.
renderPrimsWithStats :: (Functor m, Monad m, Monoid t, Hashable a) => RenderStrategy m t r a -> r -> Cache m t -> [(t, a)] -> m (Cache m t, CacheStats a)

-- | Create a renderer that renders nothing and releases no resources.
emptyRenderer :: Monad m => Renderer m t

-- | Appends two renderers into one.
appendRenderer :: Monad m => Renderer m t -> Renderer m t -> Renderer m t
