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


-- | Read and write uncompressed 24bit BMP image files.
--   
--   Read and write uncompressed 24bit BMP image files. 100% robust Haskell
--   implementation.
@package bmp
@version 1.0.0.0


-- | Reading and writing uncompressed 24 bit BMP files. We only handle
--   Windows V3 file headers, but this is the most common.
--   
--   To write a file do something like:
--   
--   <pre>
--   do let rgba   = Data.ByteString.pack [some list of Word8s]
--      let bmp    = packRGBA32ToBMP width height rgba
--      writeBMP fileName bmp
--   </pre>
--   
--   To read a file do something like:
--   
--   <pre>
--   do Right bmp  &lt;- readBMP fileName
--      let rgba   =  unpackBMPToRGBA32 bmp
--      let (width, height) = bmpDimensions bmp
--      ... 
--   </pre>
module Codec.BMP

-- | A BMP image. For an uncompressed image, the image data contains
--   triples of BGR component values. Each line may also have zero pad
--   values on the end, to bring them up to a multiple of 4 bytes in
--   length.
data BMP
BMP :: FileHeader -> BitmapInfo -> ByteString -> BMP
bmpFileHeader :: BMP -> FileHeader
bmpBitmapInfo :: BMP -> BitmapInfo
bmpRawImageData :: BMP -> ByteString

-- | BMP file header.
data FileHeader
FileHeader :: Word16 -> Word32 -> Word16 -> Word16 -> Word32 -> FileHeader

-- | Magic numbers 0x42 0x4d
fileHeaderType :: FileHeader -> Word16

-- | Size of the file, in bytes.
fileHeaderFileSize :: FileHeader -> Word32

-- | Reserved, must be zero.
fileHeaderReserved1 :: FileHeader -> Word16

-- | Reserved, must be zero.
fileHeaderReserved2 :: FileHeader -> Word16

-- | Offset in bytes to the start of the pixel data.
fileHeaderOffset :: FileHeader -> Word32

-- | A wrapper for the bitmap info, in case we want to support other header
--   types in the future.
data BitmapInfo
InfoV3 :: BitmapInfoV3 -> BitmapInfo

-- | Device Independent Bitmap (DIB) header for Windows V3.
data BitmapInfoV3
BitmapInfoV3 :: Word32 -> Word32 -> Word32 -> Word16 -> Word16 -> Word32 -> Word32 -> Word32 -> Word32 -> Word32 -> Word32 -> BitmapInfoV3

-- | Size of the image header, in bytes.
dib3Size :: BitmapInfoV3 -> Word32

-- | Width of the image, in pixels.
dib3Width :: BitmapInfoV3 -> Word32

-- | Height of the image, in pixels.
dib3Height :: BitmapInfoV3 -> Word32

-- | Number of color planes.
dib3Planes :: BitmapInfoV3 -> Word16

-- | Number of bits per pixel.
dib3BitCount :: BitmapInfoV3 -> Word16

-- | Image compression mode. 0 = uncompressed.
dib3Compression :: BitmapInfoV3 -> Word32

-- | Size of raw image data.
dib3ImageSize :: BitmapInfoV3 -> Word32

-- | Prefered resolution in pixels per meter, along the X axis.
dib3PelsPerMeterX :: BitmapInfoV3 -> Word32

-- | Prefered resolution in pixels per meter, along the Y axis.
dib3PelsPerMeterY :: BitmapInfoV3 -> Word32

-- | Number of color entries that are used.
dib3ColorsUsed :: BitmapInfoV3 -> Word32

-- | Number of significant colors.
dib3ColorsImportant :: BitmapInfoV3 -> Word32

-- | Things that can go wrong when loading a BMP file.
data Error
ErrorReadOfFileHeaderFailed :: Error
ErrorReadOfImageHeaderFailed :: Error
ErrorReadOfImageDataFailed :: Error
ErrorBadMagic :: Word16 -> Error
ErrorReservedFieldNotZero :: Error
ErrorDodgyFileHeaderFieldOffset :: Int -> Error
ErrorDodgyFileHeaderFieldFileSize :: Int -> Error
ErrorFileIsTruncated :: Error
ErrorUnhandledBitmapHeaderSize :: Int -> Error
ErrorUnhandledPlanesCount :: Int -> Error
ErrorUnhandledColorDepth :: Int -> Error
ErrorUnhandledCompressionMode :: Int -> Error
ErrorZeroImageSize :: Error
ErrorLacksWholeNumberOfLines :: Error

-- | Wrapper for <a>hGetBMP</a>
readBMP :: FilePath -> IO (Either Error BMP)

-- | Wrapper for <a>hPutBMP</a>
writeBMP :: FilePath -> BMP -> IO ()

-- | Get a BMP image from a file handle. The file is checked for problems
--   and unsupported features when read. If there is anything wrong this
--   gives an <a>Error</a> instead.
hGetBMP :: Handle -> IO (Either Error BMP)

-- | Put a BMP image to a file handle. The size of the provided image data
--   is checked against the given dimensions. If these don't match then
--   <a>error</a>.
hPutBMP :: Handle -> BMP -> IO ()

-- | Pack a string of RGBA component values into a BMP image. The alpha
--   component is ignored. If the given dimensions don't match the input
--   string then <a>error</a>.
packRGBA32ToBMP :: Int -> Int -> ByteString -> BMP

-- | Unpack a BMP image to a string of RGBA component values. The alpha
--   component is set to 255 for every pixel.
unpackBMPToRGBA32 :: BMP -> ByteString

-- | Get the width and height of an image. It's better to use this function
--   than to access the headers directly.
bmpDimensions :: BMP -> (Int, Int)