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


-- | Picture loading/serialization (in png, jpeg and bitmap)
--   
--   This library can load and store images in various image formats, for
--   now mainly in PNG/Bitmap and Jpeg (jpeg writing not implemented yet
--   though)
@package JuicyPixels
@version 1.0


-- | Module providing the basic types for image manipulation in the
--   library. Defining the types used to store all those _Juicy Pixels_
module Codec.Picture.Types

-- | Image or pixel buffer, the coordinates are assumed to start from the
--   upper-left corner of the image, with the horizontal position first,
--   then the vertical one.
data Image a
Image :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> UArray Int Word8 -> Image a

-- | Width of the image in pixels
imageWidth :: Image a -> {-# UNPACK #-} !Int

-- | Height of the image in pixels.
imageHeight :: Image a -> {-# UNPACK #-} !Int

-- | The real image, to extract pixels at some position you should use the
--   helpers functions.
imageData :: Image a -> UArray Int Word8

-- | Image or pixel buffer, the coordinates are assumed to start from the
--   upper-left corner of the image, with the horizontal position first,
--   then the vertical one. The image can be transformed in place.
data MutableImage s a
MutableImage :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> STUArray s Int Word8 -> MutableImage s a

-- | Width of the image in pixels
mutableImageWidth :: MutableImage s a -> {-# UNPACK #-} !Int

-- | Height of the image in pixels.
mutableImageHeight :: MutableImage s a -> {-# UNPACK #-} !Int

-- | The real image, to extract pixels at some position you should use the
--   helpers functions.
mutableImageData :: MutableImage s a -> STUArray s Int Word8

-- | Type allowing the loading of an image with different pixel structures
data DynamicImage

-- | A greyscale image.
ImageY8 :: (Image Pixel8) -> DynamicImage

-- | An image in greyscale with an alpha channel.
ImageYA8 :: (Image PixelYA8) -> DynamicImage

-- | An image in true color.
ImageRGB8 :: (Image PixelRGB8) -> DynamicImage

-- | An image in true color and an alpha channel.
ImageRGBA8 :: (Image PixelRGBA8) -> DynamicImage

-- | An image in the colorspace used by Jpeg images.
ImageYCbCr8 :: (Image PixelYCbCr8) -> DynamicImage

-- | Describe pixel kind at runtime
data PixelType

-- | For 2 bits pixels
PixelMonochromatic :: PixelType
PixelGreyscale :: PixelType
PixelGreyscaleAlpha :: PixelType
PixelRedGreenBlue8 :: PixelType
PixelRedGreenBlueAlpha8 :: PixelType
PixelYChromaRChromaB8 :: PixelType

-- | Simple alias for greyscale value in 8 bits.
type Pixel8 = Word8

-- | Pixel type storing Luminance (Y) and alpha information on 8 bits.
--   Value are stored in the following order :
--   
--   <ul>
--   <li>Luminance</li>
--   <li>Alpha</li>
--   </ul>
data PixelYA8
PixelYA8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelYA8

-- | Pixel type storing classic pixel on 8 bits Value are stored in the
--   following order :
--   
--   <ul>
--   <li>Red</li>
--   <li>Green</li>
--   <li>Blue</li>
--   </ul>
data PixelRGB8
PixelRGB8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelRGB8

-- | Pixel type storing a classic pixel, with an alpha component. Values
--   are stored in the following order
--   
--   <ul>
--   <li>Red</li>
--   <li>Green</li>
--   <li>Blue</li>
--   <li>Alpha</li>
--   </ul>
data PixelRGBA8
PixelRGBA8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelRGBA8

-- | Pixel storing data in the YCbCr colorspace, value are stored in teh
--   following order :
--   
--   <ul>
--   <li>Y (luminance)</li>
--   <li>Cr</li>
--   <li>Cb</li>
--   </ul>
data PixelYCbCr8
PixelYCbCr8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelYCbCr8

-- | Implement upcasting for pixel types Minimal declaration declaration
--   <a>promotePixel</a> It is strongly recommanded to overload
--   promoteImage to keep performance acceptable
class (Pixel a, Pixel b) => ColorConvertible a b
promotePixel :: ColorConvertible a b => a -> b
promoteImage :: ColorConvertible a b => Image a -> Image b

-- | Typeclass used to query a type about it's properties regarding casting
--   to other pixel types
class Serialize a => Pixel a
canPromoteTo :: Pixel a => a -> PixelType -> Bool
componentCount :: Pixel a => a -> Int
pixelBaseIndex :: Pixel a => Image a -> Int -> Int -> Int
mutablePixelBaseIndex :: Pixel a => MutableImage s a -> Int -> Int -> Int
promotionType :: Pixel a => a -> PixelType
pixelAt :: Pixel a => Image a -> Int -> Int -> a
readPixel :: Pixel a => MutableImage s a -> Int -> Int -> ST s a
writePixel :: Pixel a => MutableImage s a -> Int -> Int -> a -> ST s ()

-- | This class abstract colorspace conversion. This conversion can be
--   lossy, which ColorConvertible cannot
class (Pixel a, Pixel b) => ColorSpaceConvertible a b
convertPixel :: ColorSpaceConvertible a b => a -> b
convertImage :: ColorSpaceConvertible a b => Image a -> Image b

-- | Tell if you can convert between two pixel types, both arguments are
--   unused.
canConvertTo :: (Pixel a, Pixel b) => a -> b -> Bool
instance Eq PixelType
instance ColorSpaceConvertible PixelYCbCr8 PixelRGB8
instance Pixel PixelYCbCr8
instance Pixel PixelRGBA8
instance ColorConvertible PixelRGB8 PixelRGBA8
instance Pixel PixelRGB8
instance ColorConvertible PixelYA8 PixelRGBA8
instance ColorConvertible PixelYA8 PixelRGB8
instance Pixel PixelYA8
instance ColorConvertible Pixel8 PixelRGBA8
instance ColorConvertible Pixel8 PixelRGB8
instance ColorConvertible Pixel8 PixelYA8
instance Pixel Pixel8
instance Pixel a => ColorConvertible a a
instance Serialize PixelRGBA8
instance Serialize PixelYCbCr8
instance Serialize PixelRGB8
instance Serialize PixelYA8


-- | Module used for loading &amp; writing 'Portable Network Graphics'
--   (PNG) files. The API has two layers, the high level, which load the
--   image without looking deeply about it and the low level, allowing
--   access to data chunks contained in the PNG image.
--   
--   For general use, please use <a>decodePng</a> function.
--   
--   The loader has been validated against the pngsuite
--   (http:<i></i>www.libpng.org<i>pub</i>png/pngsuite.html)
module Codec.Picture.Png

-- | Encode an image into a png if possible.
class PngSavable a
encodePng :: PngSavable a => Image a -> ByteString

-- | Helper function trying to load a png file from a file on disk.
readPng :: FilePath -> IO (Either String DynamicImage)

-- | Transform a raw png image to an image, without modifying the
--   underlying pixel type. If the image is greyscale and &lt; 8 bits, a
--   transformation to RGBA8 is performed. This should change in the
--   future. The resulting image let you manage the pixel types.
--   
--   This function can output the following pixel types :
--   
--   <ul>
--   <li>PixelY8</li>
--   <li>PixelYA8</li>
--   <li>PixelRGB8</li>
--   <li>PixelRGBA8</li>
--   </ul>
decodePng :: ByteString -> Either String DynamicImage

-- | Helper function to directly write an image as a png on disk.
writePng :: PngSavable pixel => FilePath -> Image pixel -> IO ()

-- | Encode a dynamic image in bmp if possible, supported pixel type are :
--   
--   <ul>
--   <li>RGB8</li>
--   <li>RGBA8</li>
--   <li>Y8</li>
--   </ul>
encodeDynamicPng :: DynamicImage -> Either String ByteString

-- | Write a dynamic image in a .png image file if possible. The same
--   restriction as encodeDynamicPng apply.
writeDynamicPng :: FilePath -> DynamicImage -> IO (Either String Bool)


-- | Module used for JPEG file loading and writing.
module Codec.Picture.Jpg

-- | Try to load a jpeg file and decompress. The colorspace is still YCbCr
--   if you want to perform computation on the luma part. You can convert
--   it to RGB using <tt>colorSpaceConversion</tt>
readJpeg :: FilePath -> IO (Either String DynamicImage)

-- | Try to decompress a jpeg file and decompress. The colorspace is still
--   YCbCr if you want to perform computation on the luma part. You can
--   convert it to RGB using <tt>colorSpaceConversion</tt>
--   
--   This function can output the following pixel types :
--   
--   <ul>
--   <li>PixelY8</li>
--   <li>PixelYCbCr8</li>
--   </ul>
decodeJpeg :: ByteString -> Either String DynamicImage
instance Eq JpgFrameKind
instance Show JpgFrameKind
instance Show JpgComponent
instance Show JpgFrameHeader
instance Show JpgScanSpecification
instance Show JpgScanHeader
instance Show JpgQuantTableSpec
instance Show JpgHuffmanTableSpec
instance Show JpgFrame
instance Show JpgImage
instance Serialize JpgScanHeader
instance Serialize JpgScanSpecification
instance Serialize JpgFrameHeader
instance Serialize JpgComponent
instance Serialize RestartInterval
instance Serialize JpgFrameKind
instance Serialize JpgImage
instance Serialize JpgHuffmanTableSpec
instance SizeCalculable JpgHuffmanTableSpec
instance Serialize JpgQuantTableSpec
instance SizeCalculable JpgQuantTableSpec
instance (SizeCalculable a, Serialize a) => Serialize (TableList a)


-- | Modules used for Bitmap file (.bmp) file loading and writing
module Codec.Picture.Bitmap

-- | Write an image in a file use the bitmap format.
writeBitmap :: BmpEncodable pixel => FilePath -> Image pixel -> IO ()

-- | Encode an image into a bytestring in .bmp format ready to be written
--   on disk.
encodeBitmap :: BmpEncodable pixel => Image pixel -> ByteString

-- | Try to decode a bitmap image. Right now this function can output the
--   following pixel types :
--   
--   <ul>
--   <li>PixelRGB8</li>
--   </ul>
decodeBitmap :: ByteString -> Either String DynamicImage

-- | Encode a dynamic image in bmp if possible, supported pixel type are :
--   
--   <ul>
--   <li>RGB8</li>
--   <li>RGBA8</li>
--   <li>Y8</li>
--   </ul>
encodeDynamicBitmap :: DynamicImage -> Either String ByteString

-- | Write a dynamic image in a .bmp image file if possible. The same
--   restriction as encodeDynamicBitmap apply.
writeDynamicBitmap :: FilePath -> DynamicImage -> IO (Either String Bool)

-- | All the instance of this class can be written as a bitmap file using
--   this library.
class BmpEncodable pixel
instance BmpEncodable PixelRGB8
instance BmpEncodable PixelRGBA8
instance BmpEncodable Pixel8
instance Serialize BmpInfoHeader
instance Serialize BmpHeader


-- | Main module exporting import/export functions into various image
--   formats.
--   
--   To use the library without thinking about it, look after
--   <a>decodeImage</a> and <a>readImage</a>.
--   
--   Generally, the read* functions read the images from a file and try to
--   decode it, and the decode* functions try to decode a bytestring.
--   
--   For an easy image writing use the write* functions and writeDynamic*
--   functions.
module Codec.Picture

-- | Load an image file without even thinking about it, it does everything
--   as <a>decodeImage</a>
readImage :: FilePath -> IO (Either String DynamicImage)

-- | If you want to decode an image in a bytestring without even thinking
--   in term of format or whatever, this is the function to use. It will
--   try to decode in each known format and if one decoding succeed will
--   return the decoded image in it's own colorspace
decodeImage :: ByteString -> Either String DynamicImage

-- | All the instance of this class can be written as a bitmap file using
--   this library.
class BmpEncodable pixel

-- | Write an image in a file use the bitmap format.
writeBitmap :: BmpEncodable pixel => FilePath -> Image pixel -> IO ()

-- | Encode an image into a bytestring in .bmp format ready to be written
--   on disk.
encodeBitmap :: BmpEncodable pixel => Image pixel -> ByteString

-- | Try to decode a bitmap image. Right now this function can output the
--   following pixel types :
--   
--   <ul>
--   <li>PixelRGB8</li>
--   </ul>
decodeBitmap :: ByteString -> Either String DynamicImage

-- | Encode a dynamic image in bmp if possible, supported pixel type are :
--   
--   <ul>
--   <li>RGB8</li>
--   <li>RGBA8</li>
--   <li>Y8</li>
--   </ul>
encodeDynamicBitmap :: DynamicImage -> Either String ByteString

-- | Write a dynamic image in a .bmp image file if possible. The same
--   restriction as encodeDynamicBitmap apply.
writeDynamicBitmap :: FilePath -> DynamicImage -> IO (Either String Bool)

-- | Try to load a jpeg file and decompress. The colorspace is still YCbCr
--   if you want to perform computation on the luma part. You can convert
--   it to RGB using <tt>colorSpaceConversion</tt>
readJpeg :: FilePath -> IO (Either String DynamicImage)

-- | Try to decompress a jpeg file and decompress. The colorspace is still
--   YCbCr if you want to perform computation on the luma part. You can
--   convert it to RGB using <tt>colorSpaceConversion</tt>
--   
--   This function can output the following pixel types :
--   
--   <ul>
--   <li>PixelY8</li>
--   <li>PixelYCbCr8</li>
--   </ul>
decodeJpeg :: ByteString -> Either String DynamicImage

-- | Encode an image into a png if possible.
class PngSavable a
encodePng :: PngSavable a => Image a -> ByteString

-- | Helper function trying to load a png file from a file on disk.
readPng :: FilePath -> IO (Either String DynamicImage)

-- | Transform a raw png image to an image, without modifying the
--   underlying pixel type. If the image is greyscale and &lt; 8 bits, a
--   transformation to RGBA8 is performed. This should change in the
--   future. The resulting image let you manage the pixel types.
--   
--   This function can output the following pixel types :
--   
--   <ul>
--   <li>PixelY8</li>
--   <li>PixelYA8</li>
--   <li>PixelRGB8</li>
--   <li>PixelRGBA8</li>
--   </ul>
decodePng :: ByteString -> Either String DynamicImage

-- | Helper function to directly write an image as a png on disk.
writePng :: PngSavable pixel => FilePath -> Image pixel -> IO ()

-- | Encode a dynamic image in bmp if possible, supported pixel type are :
--   
--   <ul>
--   <li>RGB8</li>
--   <li>RGBA8</li>
--   <li>Y8</li>
--   </ul>
encodeDynamicPng :: DynamicImage -> Either String ByteString

-- | Write a dynamic image in a .png image file if possible. The same
--   restriction as encodeDynamicPng apply.
writeDynamicPng :: FilePath -> DynamicImage -> IO (Either String Bool)

-- | Image or pixel buffer, the coordinates are assumed to start from the
--   upper-left corner of the image, with the horizontal position first,
--   then the vertical one.
data Image a

-- | Type allowing the loading of an image with different pixel structures
data DynamicImage

-- | A greyscale image.
ImageY8 :: (Image Pixel8) -> DynamicImage

-- | An image in greyscale with an alpha channel.
ImageYA8 :: (Image PixelYA8) -> DynamicImage

-- | An image in true color.
ImageRGB8 :: (Image PixelRGB8) -> DynamicImage

-- | An image in true color and an alpha channel.
ImageRGBA8 :: (Image PixelRGBA8) -> DynamicImage

-- | An image in the colorspace used by Jpeg images.
ImageYCbCr8 :: (Image PixelYCbCr8) -> DynamicImage

-- | Typeclass used to query a type about it's properties regarding casting
--   to other pixel types
class Serialize a => Pixel a
canPromoteTo :: Pixel a => a -> PixelType -> Bool
componentCount :: Pixel a => a -> Int
pixelBaseIndex :: Pixel a => Image a -> Int -> Int -> Int
mutablePixelBaseIndex :: Pixel a => MutableImage s a -> Int -> Int -> Int
promotionType :: Pixel a => a -> PixelType
pixelAt :: Pixel a => Image a -> Int -> Int -> a
readPixel :: Pixel a => MutableImage s a -> Int -> Int -> ST s a
writePixel :: Pixel a => MutableImage s a -> Int -> Int -> a -> ST s ()

-- | Simple alias for greyscale value in 8 bits.
type Pixel8 = Word8

-- | Pixel type storing Luminance (Y) and alpha information on 8 bits.
--   Value are stored in the following order :
--   
--   <ul>
--   <li>Luminance</li>
--   <li>Alpha</li>
--   </ul>
data PixelYA8
PixelYA8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelYA8

-- | Pixel type storing classic pixel on 8 bits Value are stored in the
--   following order :
--   
--   <ul>
--   <li>Red</li>
--   <li>Green</li>
--   <li>Blue</li>
--   </ul>
data PixelRGB8
PixelRGB8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelRGB8

-- | Pixel type storing a classic pixel, with an alpha component. Values
--   are stored in the following order
--   
--   <ul>
--   <li>Red</li>
--   <li>Green</li>
--   <li>Blue</li>
--   <li>Alpha</li>
--   </ul>
data PixelRGBA8
PixelRGBA8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelRGBA8

-- | Pixel storing data in the YCbCr colorspace, value are stored in teh
--   following order :
--   
--   <ul>
--   <li>Y (luminance)</li>
--   <li>Cr</li>
--   <li>Cb</li>
--   </ul>
data PixelYCbCr8
PixelYCbCr8 :: {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> {-# UNPACK #-} !Word8 -> PixelYCbCr8