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


-- | Brillo picture data types and rendering functions.
--   
--   Brillo picture data types and rendering functions. These functions
--   don't do any window management. If you want Brillo to setup your
--   window as well, then use the plain <tt>brillo</tt> package.
@package brillo-rendering
@version 1.13.3

module Brillo.Rendering

-- | A 2D picture
data Picture

-- | A blank picture, with nothing in it.
Blank :: Picture

-- | A convex polygon filled with a solid color.
Polygon :: Path -> Picture

-- | A line along an arbitrary path.
Line :: Path -> Picture

-- | A circle with the given radius.
Circle :: Float -> Picture

-- | A circle with the given radius and thickness. If the thickness is 0
--   then this is equivalent to <a>Circle</a>.
ThickCircle :: Float -> Float -> Picture

-- | A circular arc drawn counter-clockwise between two angles (in degrees)
--   at the given radius.
Arc :: Float -> Float -> Float -> Picture

-- | A circular arc drawn counter-clockwise between two angles (in
--   degrees), with the given radius and thickness. If the thickness is 0
--   then this is equivalent to <a>Arc</a>.
ThickArc :: Float -> Float -> Float -> Float -> Picture

-- | Text to draw with a vector font
Text :: String -> Picture

-- | A bitmap image.
Bitmap :: BitmapData -> Picture

-- | A subsection of a bitmap image where the first argument selects a sub
--   section in the bitmap, and second argument determines the bitmap data.
BitmapSection :: Rectangle -> BitmapData -> Picture

-- | A picture drawn with this color.
Color :: Color -> Picture -> Picture

-- | A picture translated by the given x and y coordinates.
Translate :: Float -> Float -> Picture -> Picture

-- | A picture rotated clockwise by the given angle (in degrees).
Rotate :: Float -> Picture -> Picture

-- | A picture scaled by the given x and y factors.
Scale :: Float -> Float -> Picture -> Picture

-- | A picture consisting of several others.
Pictures :: [Picture] -> Picture

-- | A point on the x-y plane.
type Point = (Float, Float)

-- | A vector can be treated as a point, and vis-versa.
type Vector = Point

-- | A path through the x-y plane.
type Path = [Point]

-- | An abstract color value. We keep the type abstract so we can be sure
--   that the components are in the required range. To make a custom color
--   use <a>makeColor</a>.
data Color

-- | Make a custom color. All components are clamped to the range [0..1].
makeColor :: Float -> Float -> Float -> Float -> Color

-- | Make a custom color. All components are clamped to the range [0..255].
makeColorI :: Int -> Int -> Int -> Int -> Color

-- | Make a custom color.
--   
--   Using this function over <a>makeColor</a> avoids clamping the
--   components, which saves time. However, if the components are out of
--   range then this will result in integer overflow at rendering time, and
--   the actual picture you get will be implementation dependent.
--   
--   You'll only need to use this function when using the
--   <tt>brillo-raster</tt> package that builds a new color for every
--   pixel. If you're just working with the Picture data type then it there
--   is no need for raw colors.
makeRawColor :: Float -> Float -> Float -> Float -> Color

-- | Make a custom color, taking pre-clamped components.
makeRawColorI :: Int -> Int -> Int -> Int -> Color

-- | Take the RGBA components of a color.
rgbaOfColor :: Color -> (Float, Float, Float, Float)

-- | Clamp components of a raw color into the required range.
clampColor :: Color -> Color

-- | Represents a rectangular section in a bitmap
data Rectangle
Rectangle :: (Int, Int) -> (Int, Int) -> Rectangle

-- | x- and y-pos in the bitmap in pixels
[rectPos] :: Rectangle -> (Int, Int)

-- | width/height of the area in pixelsi
[rectSize] :: Rectangle -> (Int, Int)

-- | Abstract 32-bit RGBA bitmap data.
data BitmapData

-- | width, height in pixels
bitmapSize :: BitmapData -> (Int, Int)

-- | Description of how the bitmap is layed out in memory.
--   
--   <ul>
--   <li>Prior version of Brillo assumed `BitmapFormat BottomToTop
--   PxABGR`</li>
--   </ul>
data BitmapFormat
BitmapFormat :: RowOrder -> PixelFormat -> BitmapFormat
[rowOrder] :: BitmapFormat -> RowOrder
[pixelFormat] :: BitmapFormat -> PixelFormat

-- | Pixel formats describe the order of the color channels in memory.
data PixelFormat
PxRGBA :: PixelFormat
PxABGR :: PixelFormat

-- | Order of rows in an image are either:
--   
--   <ul>
--   <li><a>TopToBottom</a> - the top row, followed by the next-lower row
--   and so on.</li>
--   <li><a>BottomToTop</a> - the bottom row followed by the next-higher
--   row and so on.</li>
--   </ul>
data RowOrder
TopToBottom :: RowOrder
BottomToTop :: RowOrder

-- | O(1). Use a <a>ForeignPtr</a> of RGBA data as a bitmap with the given
--   width and height.
--   
--   The boolean flag controls whether Brillo should cache the data between
--   frames for speed. If you are programatically generating the image for
--   each frame then use <a>False</a>. If you have loaded it from a file
--   then use <a>True</a>.
bitmapOfForeignPtr :: Int -> Int -> BitmapFormat -> ForeignPtr Word8 -> Bool -> Picture
bitmapDataOfForeignPtr :: Int -> Int -> BitmapFormat -> ForeignPtr Word8 -> Bool -> BitmapData

-- | O(size). Copy a <a>ByteString</a> of RGBA data into a bitmap with the
--   given width and height.
--   
--   The boolean flag controls whether Brillo should cache the data between
--   frames for speed. If you are programatically generating the image for
--   each frame then use <a>False</a>. If you have loaded it from a file
--   then use <a>True</a>.
bitmapOfByteString :: Int -> Int -> BitmapFormat -> ByteString -> Bool -> Picture
bitmapDataOfByteString :: Int -> Int -> BitmapFormat -> ByteString -> Bool -> BitmapData

-- | O(size). Copy a <a>BMP</a> file into a bitmap.
bitmapOfBMP :: BMP -> Picture

-- | O(size). Copy a <a>BMP</a> file into a bitmap.
bitmapDataOfBMP :: BMP -> BitmapData

-- | Load an uncompressed 24 or 32bit RGBA BMP file as a bitmap.
loadBMP :: FilePath -> IO Picture

-- | Set up the OpenGL context, clear the buffer, and render the given
--   picture into it.
--   
--   This is the same as <a>renderPicture</a> composed with
--   <a>withModelview</a> and <a>withClearBuffer</a>. If you want to manage
--   your own OpenGL context then you can just call <a>renderPicture</a>.
--   
--   Using this function assumes that you've already opened a window and
--   set that to the active context. If you don't want to do your own
--   window management then use the <tt>brillo</tt> package instead.
displayPicture :: (Int, Int) -> Color -> State -> Float -> Picture -> IO ()

-- | Render a picture into the current OpenGL context.
--   
--   Assumes that the OpenGL matrix mode is set to <tt>Modelview</tt>
renderPicture :: State -> Float -> Picture -> IO ()

-- | Set up the OpenGL rendering context for orthographic projection and
--   run an action to draw the model.
withModelview :: (Int, Int) -> IO () -> IO ()

-- | Clear the OpenGL buffer with the given background color and run an
--   action to draw the model.
withClearBuffer :: Color -> IO () -> IO ()

-- | A mutable render state holds references to the textures currently
--   loaded into the OpenGL context. To ensure that textures are cached in
--   GPU memory, pass the same <a>State</a> each time you call
--   <tt>displayPicture</tt> or <tt>renderPicture</tt>.
initState :: IO State

-- | Abstract Brillo render state which holds references to textures loaded
--   into the GPU context.
data State