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


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


-- | Reading and writing uncompressed BMP files.
--   
--   Supports uncompressed 24bit RGB and 32bit RGBA WindowsV3, WindowsV4
--   and WindowsV5 formats.
--   
--   We don't support the plain OS/2 BitmapCoreHeader and BitmapCoreHeader2
--   image headers, but I haven't yet seen one of these in the wild.
--   
--   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>
--   
--   Release Notes:
--   
--   <pre>
--   * bmp 1.2.5
--     Add support for writing uncompressed 32-bit files.
--   
--   * bmp 1.2.4
--     Update to use binary 0.6.
--   
--   * bmp 1.2.3
--     Add pure parseBMP / renderBMP API.
--   
--   * bmp 1.2.2
--     Allow the physical image buffer to be larger than the image
--      size stated in the header, to accept output of foolish Win7 codec.
--   </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

-- | (+0) Magic numbers 0x42 0x4d
[fileHeaderType] :: FileHeader -> Word16

-- | (+2) Size of the file, in bytes.
[fileHeaderFileSize] :: FileHeader -> Word32

-- | (+6) Reserved, must be zero.
[fileHeaderReserved1] :: FileHeader -> Word16

-- | (+8) Reserved, must be zero.
[fileHeaderReserved2] :: FileHeader -> Word16

-- | (+10) Offset in bytes to the start of the pixel data.
[fileHeaderOffset] :: FileHeader -> Word32

-- | A wrapper for the various image header types.
data BitmapInfo
InfoV3 :: BitmapInfoV3 -> BitmapInfo
InfoV4 :: BitmapInfoV4 -> BitmapInfo
InfoV5 :: BitmapInfoV5 -> BitmapInfo

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

-- | (+0) Size of the image header, in bytes.
[dib3Size] :: BitmapInfoV3 -> Word32

-- | (+4) Width of the image, in pixels.
[dib3Width] :: BitmapInfoV3 -> Word32

-- | (+8) Height of the image, in pixels.
[dib3Height] :: BitmapInfoV3 -> Word32

-- | If the height field in the file is negative then this is interpreted
--   as an image with the rows flipped.
[dib3HeightFlipped] :: BitmapInfoV3 -> Bool

-- | (+12) Number of color planes.
[dib3Planes] :: BitmapInfoV3 -> Word16

-- | (+14) Number of bits per pixel.
[dib3BitCount] :: BitmapInfoV3 -> Word16

-- | (+16) Image compression mode.
[dib3Compression] :: BitmapInfoV3 -> Compression

-- | (+20) Size of raw image data. Some encoders set this to zero, so we
--   need to calculate it based on the overall file size.
--   
--   If it is non-zero then we check it matches the file size - header
--   size.
[dib3ImageSize] :: BitmapInfoV3 -> Word32

-- | (+24) Prefered resolution in pixels per meter, along the X axis.
[dib3PelsPerMeterX] :: BitmapInfoV3 -> Word32

-- | (+28) Prefered resolution in pixels per meter, along the Y axis.
[dib3PelsPerMeterY] :: BitmapInfoV3 -> Word32

-- | (+32) Number of color entries that are used.
[dib3ColorsUsed] :: BitmapInfoV3 -> Word32

-- | (+36) Number of significant colors.
[dib3ColorsImportant] :: BitmapInfoV3 -> Word32

-- | Device Independent Bitmap (DIB) header for Windows V4 (95 and newer)
data BitmapInfoV4
BitmapInfoV4 :: BitmapInfoV3 -> Word32 -> Word32 -> Word32 -> Word32 -> Word32 -> (CIEXYZ, CIEXYZ, CIEXYZ) -> Word32 -> Word32 -> Word32 -> BitmapInfoV4

-- | Size of the image header, in bytes.
[dib4InfoV3] :: BitmapInfoV4 -> BitmapInfoV3

-- | Color masks specify components of each pixel. Only used with the
--   bitfields compression mode.
[dib4RedMask] :: BitmapInfoV4 -> Word32
[dib4GreenMask] :: BitmapInfoV4 -> Word32
[dib4BlueMask] :: BitmapInfoV4 -> Word32
[dib4AlphaMask] :: BitmapInfoV4 -> Word32

-- | The color space used by the image.
[dib4ColorSpaceType] :: BitmapInfoV4 -> Word32

-- | Specifies the XYZ coords of the three colors that correspond to the
--   RGB endpoints for the logical color space associated with the bitmap.
--   Only used when ColorSpaceType specifies a calibrated image.
[dib4Endpoints] :: BitmapInfoV4 -> (CIEXYZ, CIEXYZ, CIEXYZ)

-- | Toned response curves for each component. Only used when the
--   ColorSpaceType specifies a calibrated image.
[dib4GammaRed] :: BitmapInfoV4 -> Word32
[dib4GammaGreen] :: BitmapInfoV4 -> Word32
[dib4GammaBlue] :: BitmapInfoV4 -> Word32

-- | Device Independent Bitmap (DIB) header for Windows V5 (98/2000 and
--   newer)
data BitmapInfoV5
BitmapInfoV5 :: BitmapInfoV4 -> Word32 -> Word32 -> Word32 -> Word32 -> BitmapInfoV5
[dib5InfoV4] :: BitmapInfoV5 -> BitmapInfoV4

-- | Rendering intent for the bitmap.
[dib5Intent] :: BitmapInfoV5 -> Word32

-- | Offset (in bytes) from the beginning of the header to the start of the
--   profile data.
[dib5ProfileData] :: BitmapInfoV5 -> Word32

-- | Size (in bytes) of embedded profile data.
[dib5ProfileSize] :: BitmapInfoV5 -> Word32

-- | Reserved, should be zero.
[dib5Reserved] :: BitmapInfoV5 -> Word32

-- | The Compression mode says how the image data is encoded in the file.
data Compression
CompressionRGB :: Compression
CompressionRLE8 :: Compression
CompressionRLE4 :: Compression
CompressionBitFields :: Compression
CompressionJPEG :: Compression
CompressionPNG :: Compression
CompressionUnknown :: Word32 -> Compression

-- | Contains the XYZ coordinates of a specific color in a specified color
--   space.
data CIEXYZ
CIEXYZ :: Word32 -> Word32 -> Word32 -> CIEXYZ

-- | Things that can go wrong when loading a BMP file.
data Error

-- | Magic number was not at the start of the file, so this probably isn't
--   a BMP file.
ErrorBadMagic :: Word16 -> Error
[errorMagic] :: Error -> Word16

-- | File is too short to contain a file header.
ErrorFileHeaderTruncated :: Error

-- | File is too short to contain an image header.
ErrorImageHeaderTruncated :: Error

-- | File is too short to contain the image data.
ErrorImageDataTruncated :: Int -> Int -> Error
[errorBytesNeeded] :: Error -> Int
[errorBytesAvailable] :: Error -> Int

-- | Reserved fields should be zero.
ErrorReservedFieldNotZero :: Error

-- | The offset to the image data from the file header doesn't point
--   anywhere sensible.
ErrorDodgyFileHeaderFieldOffset :: Word32 -> Error
[errorFileHeaderOffset] :: Error -> Word32

-- | We handle V3 V4 and V5 image headers, but the size of the header
--   indicates it has some other format.
ErrorUnhandledBitmapHeaderSize :: Word32 -> Error
[errorBitmapHeaderSize] :: Error -> Word32

-- | We only handle single color planes.
ErrorUnhandledPlanesCount :: Word16 -> Error
[errorPlanesCount] :: Error -> Word16

-- | We only handle 24 and 32 bit images.
ErrorUnhandledColorDepth :: Word16 -> Error
[errorColorDepth] :: Error -> Word16

-- | We only handle uncompressed images.
ErrorUnhandledCompressionMode :: Compression -> Error
[errorCompression] :: Error -> Compression

-- | Mismatch between the image size stated in the header and that which is
--   calculuated from the other fields.
ErrorImagePhysicalSizeMismatch :: Word32 -> Word32 -> Error
[errorImageSizeFromHeader] :: Error -> Word32
[errorImageSizeOfBuffer] :: Error -> Word32

-- | Something went wrong in the library.
ErrorInternalErrorPleaseReport :: Error

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

-- | Get a BMP image from a file handle.
hGetBMP :: Handle -> IO (Either Error BMP)

-- | Parse a BMP image from a lazy <a>ByteString</a>
parseBMP :: ByteString -> Either Error BMP

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

-- | Put a BMP image to a file handle.
hPutBMP :: Handle -> BMP -> IO ()

-- | Render a BMP image to a lazy <a>ByteString</a>.
renderBMP :: BMP -> ByteString

-- | Pack a string of RGBA component values into a 32-bit BMP image.
--   
--   Alias for <a>packRGBA32ToBMP32</a>.
packRGBA32ToBMP :: Int -> Int -> ByteString -> BMP

-- | Pack a string of RGBA component values into a 32-bit BMP image.
--   
--   <ul>
--   <li>If the given dimensions don't match the input string then
--   <a>error</a>.</li>
--   <li>If the width or height fields are negative then <a>error</a>.</li>
--   </ul>
packRGBA32ToBMP32 :: Int -> Int -> ByteString -> BMP

-- | Pack a string of RGBA component values into a 24-bit BMP image,
--   discarding the alpha channel of the source data.
--   
--   <ul>
--   <li>If the given dimensions don't match the input string then
--   <a>error</a>.</li>
--   <li>If the width or height fields are negative then <a>error</a>.</li>
--   </ul>
packRGBA32ToBMP24 :: Int -> Int -> ByteString -> BMP

-- | Unpack a BMP image to a string of RGBA component values.
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)
