libghc-bmp-doc 1.2.3.4-2 / usr / share / doc / libghc-bmp-doc / html / bmp.txt

-- 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.3.4


-- | Reading and writing uncompressed BMP files.
--   
--   Reading works for both uncompressed 24bit RGB and 32bit RGBA
--   WindowsV3, WindowsV4 and WindowsV5 formats.
--   
--   Writing is limited to the uncompressed 24bit RGB WindowsV3 format.
--   
--   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.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.
--   
--   * bmp 1.2.1
--     Fix slow ByteString conversion via lists.  
--   
--   * bmp 1.2.0
--     Accept files with zero padding on the end of the file.
--     Accept RGBA files with V3 headers.
--   
--   * bmp 1.1.2   
--     Accept files with the image size field set to zero.
--   </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 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>
--   <li>This currently ignores the alpha component of the input string and
--   produces a 24bit RGB image.</li>
--   </ul>
packRGBA32ToBMP :: 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)