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


-- | A functional interface to 2D drawing in OpenGL
--   
--   This module is a functional wrapper around OpenGL, so you don't have
--   to go into the deep, dark world of imperative stateful programming
--   just to draw stuff. It supports 2D only (for now), with support
--   drawing geometry, images, and text.
@package graphics-drawingcombinators
@version 1.2.2


-- | An affine transformation is a linear transformation followed by a
--   translation; i.e. it is a function
--   
--   <pre>
--   \x -&gt; A*x + b
--   </pre>
--   
--   Where A is a linear transformation. Affine transformations are the set
--   of image transformations supported by Graphics.DrawingCombinators,
--   roughly translate, rotate, scale, and compositions thereof.
module Graphics.DrawingCombinators.Affine
type R = GLdouble
type R2 = (R, R)

-- | An Affine transformation from R2 to R2.
--   
--   <pre>
--   [[Affine]] = R2 -&gt; R2
--   </pre>
--   
--   With the Monoid instance <tt>(identity, compose)</tt>
data Affine

-- | <pre>
--   [[compose a b]] = [[a]] . [[b]]
--   </pre>
compose :: Affine -> Affine -> Affine

-- | <pre>
--   [[apply a]] = [[a]]
--   </pre>
apply :: Affine -> R2 -> R2

-- | <pre>
--   [[identity]] = id
--   </pre>
identity :: Affine

-- | <pre>
--   [[translate t]] x = [[t]] x + t
--   </pre>
translate :: R2 -> Affine

-- | <pre>
--   [[rotate r]] (x,y) = (cos(r)x - sin(r)y, sin(r)x + cos(r)y)
--   </pre>
rotate :: R -> Affine

-- | <pre>
--   [[scale xs ys]] (x,y) = (xs*x, ys*y)
--   </pre>
scale :: R -> R -> Affine

-- | <pre>
--   [[inverse x]] = inverse [[x]]
--   </pre>
--   
--   If the transformation is not invertible, this operation is undefined.
inverse :: Affine -> Affine

-- | Multiply this Affine by the top of the OpenGL matrix stack. Don't mind
--   this, it's an implementation detail.
multGLmatrix :: Affine -> IO ()
instance Monoid Affine


-- | Drawing combinators as a functional interface to 2D graphics using
--   OpenGL.
--   
--   This module is intended to be imported <tt>qualified</tt>, as in:
--   
--   <pre>
--   import qualified Graphics.DrawingCombinators as Draw
--   </pre>
--   
--   Whenever possible, a <i>denotational semantics</i> for operations in
--   this library is given. Read <tt>[[x]]</tt> as "the meaning of
--   <tt>x</tt>".
--   
--   Intuitively, an <a>Image</a> <tt>a</tt> is an infinite plane of pairs
--   of colors <i>and</i> <tt>a</tt>'s. The colors are what are drawn on
--   the screen when you <a>render</a>, and the <tt>a</tt>'s are what you
--   can recover from coordinates using <a>sample</a>. The latter allows
--   you to tell, for example, what a user clicked on.
--   
--   The following discussion is about the associated data. If you are only
--   interested in drawing, rather than mapping from coordinates to values,
--   you can ignore the following and just use <a>mappend</a> and
--   <a>mconcat</a> to overlay images.
--   
--   Wrangling the <tt>a</tt>'s -- the associated data with each "pixel" --
--   is done using the <a>Functor</a>, <a>Applicative</a>, and
--   <a>Monoid</a> instances.
--   
--   The primitive <tt>Image</tt>s such as <a>circle</a> and <a>text</a>
--   all return <tt>Image Any</tt> objects. <a>Any</a> is just a wrapper
--   around <a>Bool</a>, with <tt>(||)</tt> as its monoid operator. So e.g.
--   the points inside the circle will have the value <tt>Any True</tt>,
--   and those outside will have the value <tt>Any False</tt>. Returning
--   <tt>Any</tt> instead of plain <tt>Bool</tt> allows you to use
--   <tt>Image</tt>s as a monoid, e.g. <a>mappend</a> to overlay two
--   images. But if you are doing anything with sampling, you probably want
--   to map this to something. Here is a drawing with two circles that
--   reports which one was hit:
--   
--   <pre>
--   twoCircles :: Image String
--   twoCircles = liftA2 test (translate (-1,0) %% circle) (translate (1,0) %% circle)
--     where 
--     test (Any False) (Any False) = "Miss!"
--     test (Any False) (Any True)  = "Hit Right!"
--     test (Any True)  (Any False) = "Hit Left!"
--     test (Any True)  (Any True)  = "Hit Both??!"
--   </pre>
--   
--   The last case would only be possible if the circles were overlapping.
module Graphics.DrawingCombinators

-- | The type of images.
--   
--   <pre>
--   [[Image a]] = R2 -&gt; (Color, a)
--   </pre>
--   
--   The semantics of the instances are all consistent with <i>type class
--   morphism</i>. I.e. Functor, Applicative, and Monoid act point-wise,
--   using the <a>Color</a> monoid described below.
data Image a

-- | Draw an Image on the screen in the current OpenGL coordinate system
--   (which, in absense of information, is (-1,-1) in the lower left and
--   (1,1) in the upper right).
render :: Image a -> IO ()

-- | Like <a>render</a>, but clears the screen first. This is so you can
--   use this module and pretend that OpenGL doesn't exist at all.
clearRender :: Image a -> IO ()

-- | Sample the value of the image at a point.
--   
--   <pre>
--   [[sample i p]] = snd ([[i]] p)
--   </pre>
--   
--   Even though this ought to be a pure function, it is <i>not</i> safe to
--   <tt>unsafePerformIO</tt> it, because it uses OpenGL state.
sample :: Image a -> R2 -> IO a

-- | A single "pixel" at the specified point.
--   
--   <pre>
--   [[point p]] r | [[r]] == [[p]] = (one, Any True) 
--                 | otherwise      = (zero, Any False)
--   </pre>
point :: R2 -> Image Any

-- | A line connecting the two given points.
line :: R2 -> R2 -> Image Any

-- | A regular polygon centered at the origin with n sides.
regularPoly :: (Integral a) => a -> Image Any

-- | An (imperfect) unit circle centered at the origin. Implemented as:
--   
--   <pre>
--   circle = regularPoly 24
--   </pre>
circle :: Image Any

-- | A convex polygon given by the list of points.
convexPoly :: [R2] -> Image Any

-- | Transform an image by an <a>Affine</a> transformation.
--   
--   <pre>
--   [[tr % im]] = [[im]] . inverse [[tr]]
--   </pre>
(%%) :: Affine -> Image a -> Image a

-- | A Bezier curve given a list of control points. It is a curve that
--   begins at the first point in the list, ends at the last one, and
--   smoothly interpolates between the rest. It is the empty image
--   (<a>mempty</a>) if zero or one points are given.
bezierCurve :: [R2] -> Image Any

-- | Color is defined in the usual computer graphics sense: a 4 vector
--   containing red, green, blue, and alpha.
--   
--   The Monoid instance is given by alpha composition, described at
--   <tt>http://lukepalmer.wordpress.com/2010/02/05/associative-alpha-blending/</tt>
--   
--   In the semantcs the values <tt>zero</tt> and <tt>one</tt> are used,
--   which are defined as:
--   
--   <pre>
--   zero = Color 0 0 0 0
--   one = Color 1 1 1 1
--   </pre>
data Color
Color :: !R -> !R -> !R -> !R -> Color

-- | Modulate two colors by each other.
--   
--   <pre>
--   modulate (Color r g b a) (Color r' g' b' a') 
--             = Color (r*r') (g*g') (b*b') (a*a')
--   </pre>
modulate :: Color -> Color -> Color

-- | Tint an image by a color; i.e. modulate the colors of an image by a
--   color.
--   
--   <pre>
--   [[tint c im]] = first (modulate c) . [[im]]
--      where first f (x,y) = (f x, y)
--   </pre>
tint :: Color -> Image a -> Image a

-- | A Sprite represents a finite bitmap image.
--   
--   <pre>
--   [[Sprite]] = [-1,1]^2 -&gt; Color
--   </pre>
data Sprite

-- | Load an image from a file and create a sprite out of it.
openSprite :: FilePath -> IO Sprite

-- | The image of a sprite at the origin.
--   
--   <pre>
--   [[sprite s]] p | p `elem` [-1,1]^2 = ([[s]] p, Any True) 
--                  | otherwise         = (zero, Any False)
--   </pre>
sprite :: Sprite -> Image Any
data Font

-- | Load a TTF font from a file.
openFont :: String -> IO Font

-- | The image representing some text rendered with a font. The baseline is
--   at y=0, the text starts at x=0, and the height of a lowercase x is 1
--   unit.
text :: Font -> String -> Image Any

-- | <tt>textWidth font str</tt> is the width of the text in <tt>text font
--   str</tt>.
textWidth :: Font -> String -> R

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><tt>mappend mempty x = x</tt></li>
--   <li><tt>mappend x mempty = x</tt></li>
--   <li><tt>mappend x (mappend y z) = mappend (mappend x y) z</tt></li>
--   <li><tt>mconcat = <a>foldr</a> mappend mempty</tt></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Minimal complete definition: <a>mempty</a> and <a>mappend</a>.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <a>Sum</a> and <a>Product</a>.
class Monoid a
mempty :: (Monoid a) => a
mappend :: (Monoid a) => a -> a -> a
mconcat :: (Monoid a) => [a] -> a

-- | Boolean monoid under disjunction.
newtype Any :: *
Any :: Bool -> Any
getAny :: Any -> Bool
instance Eq Color
instance Show Color
instance Monoid Color
instance (Monoid m) => Monoid (Image m)
instance Applicative Image
instance Functor Image