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


-- | A library and application for generating pixelated avatars.
--   
--   
--   Pixelated Avatar Generator is a library and application for generating
--   pixelated avatar images from seed strings.
@package pixelated-avatar-generator
@version 0.1.3


-- | This module provides types and functions for creating and working with
--   pixelated avatars.
--   
--   Avatars can be generated by providing a <a>Seed</a>. Seeds can be
--   created by passing a random String into <a>createSeed</a>. The given
--   String is then turned into an MD5 checksum, which is used as the seed
--   value.
--   
--   Once a Seed has been created, an Avatar can be generated from it by
--   passing it into <a>generateAvatar</a>. By default, Avatars start at a
--   size of 8x8px. The size of an Avatar can be increased by passing it
--   into <a>scaleAvatar</a>. Once you have scaled the Avatar to the size
--   you want it to be it can then be saved to a file by passing it into
--   <a>saveAvatar</a>.
--   
--   By default, the <a>saveAvatar</a> function saves the avatar as a png
--   image file, however you can also save avatars in other image formats
--   by using <a>saveAvatarWith</a>. It allows you to specify the function
--   to use to convert the avatar image into an image ByteString.
--   
--   <h1>Example</h1>
--   
--   The following is an example showing how to construct a function which
--   will generate a 256x256px avatar from a given seed string, and save it
--   at the given location.
--   
--   <pre>
--   import Graphics.Avatars.Pixelated
--   
--   createAndSaveAvatar :: String -&gt; FilePath -&gt; IO ()
--   createAndSaveAvatar s path = saveAvatar avatar path
--     where avatar = scaleAvatar 32 $ generateAvatar seed
--           seed   = createSeed s
--   </pre>
module Graphics.Avatars.Pixelated

-- | A seed to use in generating an avatar. Can be created from a String by
--   using the <a>createSeed</a> function.
--   
--   Seeds are expected to be 32 character hexidecimal MD5 checksums.
newtype Seed
Seed :: String -> Seed
[unSeed] :: Seed -> String

-- | Creates a seed from a given String.
--   
--   <pre>
--   &gt;&gt;&gt; createSeed "Hello"
--   Seed {unSeed = "8b1a9953c4611296a827abf8c47804d7"}
--   </pre>
createSeed :: String -> Seed

-- | A generated avatar, comprised of a color and a grid representing the
--   visual pattern of the avatar image. Can be created from a seed using
--   <a>generateAvatar</a>.
--   
--   Avatars are generated at a size of 8x8px, and can be scaled up to
--   larger image sizes by using the <a>scaleAvatar</a> function.
data Avatar
Avatar :: Color -> AvatarGrid -> Avatar
[color] :: Avatar -> Color
[grid] :: Avatar -> AvatarGrid

-- | Generates an avatar from the given seed.
--   
--   <pre>
--   &gt;&gt;&gt; generateAvatar Seed {unSeed = "8b1a9953c4611296a827abf8c47804d7"}
--   Grey
--   ██ ██ ██
--   ██    ██
--   █      █
--     █  █  
--   ██    ██
--   ████████
--   █  ██  █
--     █  █  
--   </pre>
generateAvatar :: Seed -> Avatar

-- | Scales the given Avatar by the given scaling factor.
--   
--   For example, scaling an 8x8px avatar by a factor of 4 would transform
--   it into a 32x32px avatar.
scaleAvatar :: Int -> Avatar -> Avatar

-- | Saves the given avatar as a png image file to the given file path. The
--   filepath should be the path and name of the image file to be created,
--   including the file extension.
--   
--   For saving an avatar in a non-png format, use <a>saveAvatarWith</a>.
--   
--   <pre>
--   makeAvatar :: Seed -&gt; FilePath -&gt; IO ()
--   makeAvatar seed path = do
--     let avatar = generateAvatar seed path
--     saveAvatar avatar path
--   </pre>
saveAvatar :: Avatar -> FilePath -> IO ()

-- | Saves the given avatar to the given file location, using the given
--   function to encode it into a specific image format.
--   
--   Some examples of encoding functions are <a>encodeToGif</a> and
--   <a>encodeToTiff</a>.
--   
--   <pre>
--   saveTiffAvatar :: Seed -&gt; FilePath -&gt; IO ()
--   saveTiffAvatar seed path = do
--     let avatar = generateAvatar seed path
--     saveAvatarWith encodeTiff avatar path
--   </pre>
saveAvatarWith :: ImageConversion -> Avatar -> FilePath -> IO ()

-- | Converts the given Avatar into an Image.
convertAvatarToImage :: Avatar -> Image PixelRGB8

-- | A function which converts an image into a lazy ByteString.
type ImageConversion = (Image PixelRGB8 -> ByteString)

-- | Converts an image into a Png image ByteString.
encodeToPng :: ImageConversion

-- | Converts an image into a Gif image ByteString.
encodeToGif :: ImageConversion

-- | Converts an image into a Tiff image ByteString.
encodeToTiff :: ImageConversion

-- | A color of an avatar. The color of an avatar is the color that is
--   applied to the pattern of the avatar when it is converted into an
--   image.
data Color
Black :: Color
Blue :: Color
Green :: Color
Grey :: Color
Orange :: Color
Purple :: Color
Red :: Color
Yellow :: Color

-- | Converts the given color into a RGB pixel representation.
--   
--   <pre>
--   &gt;&gt;&gt; getColorValue Orange
--   PixelRGB8 255 140 65
--   </pre>
getColorValue :: Color -> PixelRGB8

-- | Picks an avatar color using the given seed.
--   
--   Each of the eight possible colors has roughly an equal chance of being
--   chosen with a random seed.
--   
--   <pre>
--   &gt;&gt;&gt; colorFromSeed $ Seed {unSeed = "8b1a9953c4611296a827abf8c47804d7"}
--   Grey
--   </pre>
colorFromSeed :: Seed -> Color

-- | A grid of boolean values representing an Avatar. True values indicate
--   colored pixels, and False values indicate blank pixels.
newtype AvatarGrid
AvatarGrid :: [[Bool]] -> AvatarGrid
[unAvatarGrid] :: AvatarGrid -> [[Bool]]

-- | Converts a grid of boolean values into a String representation.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn $ showGrid [[True, False], [False, True]]
--   █ 
--    █
--   </pre>
showGrid :: [[Bool]] -> String

-- | Generates an AvatarGrid using the given Seed.
--   
--   It works by generating the left half of the grid using the contents of
--   the Seed, and then mirroring the left half to create the full grid.
--   
--   <pre>
--   &gt;&gt;&gt; generateAvatarGrid Seed {unSeed = "8b1a9953c4611296a827abf8c47804d7"}
--   ██ ██ ██
--   ██    ██
--   █      █
--     █  █  
--   ██    ██
--   ████████
--   █  ██  █
--     █  █  
--   </pre>
generateAvatarGrid :: Seed -> AvatarGrid

-- | Scales the given list by the given scaling factor.
--   
--   <pre>
--   &gt;&gt;&gt; scaleList 2 [1, 2]
--   [1,1,2,2]
--   
--   &gt;&gt;&gt; scaleList 3 [0, 1]
--   [0,0,0,1,1,1]
--   </pre>
scaleList :: Int -> [a] -> [a]
instance GHC.Classes.Eq Graphics.Avatars.Pixelated.Avatar
instance GHC.Classes.Eq Graphics.Avatars.Pixelated.AvatarGrid
instance GHC.Enum.Enum Graphics.Avatars.Pixelated.Color
instance GHC.Show.Show Graphics.Avatars.Pixelated.Color
instance GHC.Classes.Eq Graphics.Avatars.Pixelated.Color
instance GHC.Show.Show Graphics.Avatars.Pixelated.Seed
instance GHC.Classes.Eq Graphics.Avatars.Pixelated.Seed
instance GHC.Show.Show Graphics.Avatars.Pixelated.AvatarGridSide
instance GHC.Show.Show Graphics.Avatars.Pixelated.Avatar
instance GHC.Show.Show Graphics.Avatars.Pixelated.AvatarGrid
