Safe Haskell	None
Language	Haskell98

Codec.BMP

Contents

Data Structures
Reading
Writing
Pack and Unpack

Description

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:

do let rgba   = Data.ByteString.pack [some list of Word8s]
   let bmp    = packRGBA32ToBMP width height rgba
   writeBMP fileName bmp

To read a file do something like:

do Right bmp  <- readBMP fileName
   let rgba   =  unpackBMPToRGBA32 bmp
   let (width, height) = bmpDimensions bmp
   ...

Release Notes:

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

Synopsis

data BMP = BMP {
- bmpFileHeader :: FileHeader
- bmpBitmapInfo :: BitmapInfo
- bmpRawImageData :: ByteString
}
data FileHeader = FileHeader {
- fileHeaderType :: Word16
- fileHeaderFileSize :: Word32
- fileHeaderReserved1 :: Word16
- fileHeaderReserved2 :: Word16
- fileHeaderOffset :: Word32
}
data BitmapInfo
- = InfoV3 BitmapInfoV3
- | InfoV4 BitmapInfoV4
- | InfoV5 BitmapInfoV5
data BitmapInfoV3 = BitmapInfoV3 {
- dib3Size :: Word32
- dib3Width :: Word32
- dib3Height :: Word32
- dib3HeightFlipped :: Bool
- dib3Planes :: Word16
- dib3BitCount :: Word16
- dib3Compression :: Compression
- dib3ImageSize :: Word32
- dib3PelsPerMeterX :: Word32
- dib3PelsPerMeterY :: Word32
- dib3ColorsUsed :: Word32
- dib3ColorsImportant :: Word32
}
data BitmapInfoV4 = BitmapInfoV4 {
- dib4InfoV3 :: BitmapInfoV3
- dib4RedMask :: Word32
- dib4GreenMask :: Word32
- dib4BlueMask :: Word32
- dib4AlphaMask :: Word32
- dib4ColorSpaceType :: Word32
- dib4Endpoints :: (CIEXYZ, CIEXYZ, CIEXYZ)
- dib4GammaRed :: Word32
- dib4GammaGreen :: Word32
- dib4GammaBlue :: Word32
}
data BitmapInfoV5 = BitmapInfoV5 {
- dib5InfoV4 :: BitmapInfoV4
- dib5Intent :: Word32
- dib5ProfileData :: Word32
- dib5ProfileSize :: Word32
- dib5Reserved :: Word32
}
data Compression
- = CompressionRGB
- | CompressionRLE8
- | CompressionRLE4
- | CompressionBitFields
- | CompressionJPEG
- | CompressionPNG
- | CompressionUnknown Word32
data CIEXYZ = CIEXYZ Word32 Word32 Word32
data Error
- = ErrorBadMagic {
  - errorMagic :: Word16
  }
- | ErrorFileHeaderTruncated
- | ErrorImageHeaderTruncated
- | ErrorImageDataTruncated {
  - errorBytesNeeded :: Int
  - errorBytesAvailable :: Int
  }
- | ErrorReservedFieldNotZero
- | ErrorDodgyFileHeaderFieldOffset {
  - errorFileHeaderOffset :: Word32
  }
- | ErrorUnhandledBitmapHeaderSize {
  - errorBitmapHeaderSize :: Word32
  }
- | ErrorUnhandledPlanesCount {
  - errorPlanesCount :: Word16
  }
- | ErrorUnhandledColorDepth {
  - errorColorDepth :: Word16
  }
- | ErrorUnhandledCompressionMode {
  - errorCompression :: Compression
  }
- | ErrorImagePhysicalSizeMismatch {
  - errorImageSizeFromHeader :: Word32
  - errorImageSizeOfBuffer :: Word32
  }
- | ErrorInternalErrorPleaseReport
readBMP :: FilePath -> IO (Either Error BMP)
hGetBMP :: Handle -> IO (Either Error BMP)
parseBMP :: ByteString -> Either Error BMP
writeBMP :: FilePath -> BMP -> IO ()
hPutBMP :: Handle -> BMP -> IO ()
renderBMP :: BMP -> ByteString
packRGBA32ToBMP :: Int -> Int -> ByteString -> BMP
packRGBA32ToBMP32 :: Int -> Int -> ByteString -> BMP
packRGBA32ToBMP24 :: Int -> Int -> ByteString -> BMP
unpackBMPToRGBA32 :: BMP -> ByteString
bmpDimensions :: BMP -> (Int, Int)

Data Structures

data BMP Source #

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.

Constructors

BMP
Fields bmpFileHeader :: FileHeader bmpBitmapInfo :: BitmapInfo bmpRawImageData :: ByteString

Instances

Show BMP Source #
Instance details Defined in Codec.BMP.Base Methods showsPrec :: Int -> BMP -> ShowS # show :: BMP -> String # showList :: [BMP] -> ShowS #

data FileHeader Source #

BMP file header.

Constructors

FileHeader
Fields fileHeaderType :: Word16 (+0) Magic numbers 0x42 0x4d fileHeaderFileSize :: Word32 (+2) Size of the file, in bytes. fileHeaderReserved1 :: Word16 (+6) Reserved, must be zero. fileHeaderReserved2 :: Word16 (+8) Reserved, must be zero. fileHeaderOffset :: Word32 (+10) Offset in bytes to the start of the pixel data.

Instances

Show FileHeader Source #
Instance details Defined in Codec.BMP.FileHeader Methods showsPrec :: Int -> FileHeader -> ShowS # show :: FileHeader -> String # showList :: [FileHeader] -> ShowS #
Binary FileHeader Source #
Instance details Defined in Codec.BMP.FileHeader Methods put :: FileHeader -> Put # get :: Get FileHeader # putList :: [FileHeader] -> Put #

data BitmapInfo Source #

A wrapper for the various image header types.

Constructors

InfoV3 BitmapInfoV3
InfoV4 BitmapInfoV4
InfoV5 BitmapInfoV5

Instances

Show BitmapInfo Source #
Instance details Defined in Codec.BMP.BitmapInfo Methods showsPrec :: Int -> BitmapInfo -> ShowS # show :: BitmapInfo -> String # showList :: [BitmapInfo] -> ShowS #
Binary BitmapInfo Source #
Instance details Defined in Codec.BMP.BitmapInfo Methods put :: BitmapInfo -> Put # get :: Get BitmapInfo # putList :: [BitmapInfo] -> Put #

data BitmapInfoV3 Source #

Device Independent Bitmap (DIB) header for Windows V3.

Constructors

BitmapInfoV3

Fields

dib3Size :: Word32
(+0) Size of the image header, in bytes.
dib3Width :: Word32
(+4) Width of the image, in pixels.
dib3Height :: Word32
(+8) Height of the image, in pixels.
dib3HeightFlipped :: Bool
If the height field in the file is negative then this is interpreted as an image with the rows flipped.
dib3Planes :: Word16
(+12) Number of color planes.
dib3BitCount :: Word16
(+14) Number of bits per pixel.
dib3Compression :: Compression
(+16) Image compression mode.
dib3ImageSize :: Word32
(+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.
dib3PelsPerMeterX :: Word32
(+24) Prefered resolution in pixels per meter, along the X axis.
dib3PelsPerMeterY :: Word32
(+28) Prefered resolution in pixels per meter, along the Y axis.
dib3ColorsUsed :: Word32
(+32) Number of color entries that are used.
dib3ColorsImportant :: Word32
(+36) Number of significant colors.

Instances

Show BitmapInfoV3 Source #
Instance details Defined in Codec.BMP.BitmapInfoV3 Methods showsPrec :: Int -> BitmapInfoV3 -> ShowS # show :: BitmapInfoV3 -> String # showList :: [BitmapInfoV3] -> ShowS #
Binary BitmapInfoV3 Source #
Instance details Defined in Codec.BMP.BitmapInfoV3 Methods put :: BitmapInfoV3 -> Put # get :: Get BitmapInfoV3 # putList :: [BitmapInfoV3] -> Put #

data BitmapInfoV4 Source #

Device Independent Bitmap (DIB) header for Windows V4 (95 and newer)

Constructors

BitmapInfoV4

Fields

dib4InfoV3 :: BitmapInfoV3
Size of the image header, in bytes.
dib4RedMask :: Word32
Color masks specify components of each pixel. Only used with the bitfields compression mode.
dib4GreenMask :: Word32
dib4BlueMask :: Word32
dib4AlphaMask :: Word32
dib4ColorSpaceType :: Word32
The color space used by the image.
dib4Endpoints :: (CIEXYZ, CIEXYZ, CIEXYZ)
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.
dib4GammaRed :: Word32
Toned response curves for each component. Only used when the ColorSpaceType specifies a calibrated image.
dib4GammaGreen :: Word32
dib4GammaBlue :: Word32

Instances

Show BitmapInfoV4 Source #
Instance details Defined in Codec.BMP.BitmapInfoV4 Methods showsPrec :: Int -> BitmapInfoV4 -> ShowS # show :: BitmapInfoV4 -> String # showList :: [BitmapInfoV4] -> ShowS #
Binary BitmapInfoV4 Source #
Instance details Defined in Codec.BMP.BitmapInfoV4 Methods put :: BitmapInfoV4 -> Put # get :: Get BitmapInfoV4 # putList :: [BitmapInfoV4] -> Put #

data BitmapInfoV5 Source #

Device Independent Bitmap (DIB) header for Windows V5 (98/2000 and newer)

Constructors

BitmapInfoV5
Fields dib5InfoV4 :: BitmapInfoV4 dib5Intent :: Word32 Rendering intent for the bitmap. dib5ProfileData :: Word32 Offset (in bytes) from the beginning of the header to the start of the profile data. dib5ProfileSize :: Word32 Size (in bytes) of embedded profile data. dib5Reserved :: Word32 Reserved, should be zero.

Instances

Show BitmapInfoV5 Source #
Instance details Defined in Codec.BMP.BitmapInfoV5 Methods showsPrec :: Int -> BitmapInfoV5 -> ShowS # show :: BitmapInfoV5 -> String # showList :: [BitmapInfoV5] -> ShowS #
Binary BitmapInfoV5 Source #
Instance details Defined in Codec.BMP.BitmapInfoV5 Methods put :: BitmapInfoV5 -> Put # get :: Get BitmapInfoV5 # putList :: [BitmapInfoV5] -> Put #

data Compression Source #

The Compression mode says how the image data is encoded in the file.

Constructors

CompressionRGB
CompressionRLE8
CompressionRLE4
CompressionBitFields
CompressionJPEG
CompressionPNG
CompressionUnknown Word32

Instances

Eq Compression Source #
Instance details Defined in Codec.BMP.Compression Methods (==) :: Compression -> Compression -> Bool # (/=) :: Compression -> Compression -> Bool #
Show Compression Source #
Instance details Defined in Codec.BMP.Compression Methods showsPrec :: Int -> Compression -> ShowS # show :: Compression -> String # showList :: [Compression] -> ShowS #
Binary Compression Source #
Instance details Defined in Codec.BMP.Compression Methods put :: Compression -> Put # get :: Get Compression # putList :: [Compression] -> Put #

data CIEXYZ Source #

Contains the XYZ coordinates of a specific color in a specified color space.

Constructors

CIEXYZ Word32 Word32 Word32

Instances

Show CIEXYZ Source #
Instance details Defined in Codec.BMP.CIEXYZ Methods showsPrec :: Int -> CIEXYZ -> ShowS # show :: CIEXYZ -> String # showList :: [CIEXYZ] -> ShowS #
Binary CIEXYZ Source #
Instance details Defined in Codec.BMP.CIEXYZ Methods put :: CIEXYZ -> Put # get :: Get CIEXYZ # putList :: [CIEXYZ] -> Put #

data Error Source #

Things that can go wrong when loading a BMP file.

Constructors

ErrorBadMagic	Magic number was not at the start of the file, so this probably isn't a BMP file.
Fields errorMagic :: Word16
ErrorFileHeaderTruncated	File is too short to contain a file header.
ErrorImageHeaderTruncated	File is too short to contain an image header.
ErrorImageDataTruncated	File is too short to contain the image data.
Fields errorBytesNeeded :: Int errorBytesAvailable :: Int
ErrorReservedFieldNotZero	Reserved fields should be zero.
ErrorDodgyFileHeaderFieldOffset	The offset to the image data from the file header doesn't point anywhere sensible.
Fields errorFileHeaderOffset :: Word32
ErrorUnhandledBitmapHeaderSize	We handle V3 V4 and V5 image headers, but the size of the header indicates it has some other format.
Fields errorBitmapHeaderSize :: Word32
ErrorUnhandledPlanesCount	We only handle single color planes.
Fields errorPlanesCount :: Word16
ErrorUnhandledColorDepth	We only handle 24 and 32 bit images.
Fields errorColorDepth :: Word16
ErrorUnhandledCompressionMode	We only handle uncompressed images.
Fields errorCompression :: Compression
ErrorImagePhysicalSizeMismatch	Mismatch between the image size stated in the header and that which is calculuated from the other fields.
Fields errorImageSizeFromHeader :: Word32 errorImageSizeOfBuffer :: Word32
ErrorInternalErrorPleaseReport	Something went wrong in the library.

Instances

Eq Error Source #
Instance details Defined in Codec.BMP.Error Methods (==) :: Error -> Error -> Bool # (/=) :: Error -> Error -> Bool #
Show Error Source #
Instance details Defined in Codec.BMP.Error Methods showsPrec :: Int -> Error -> ShowS # show :: Error -> String # showList :: [Error] -> ShowS #

Reading

readBMP :: FilePath -> IO (Either Error BMP) Source #

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 Error instead.

hGetBMP :: Handle -> IO (Either Error BMP) Source #

Get a BMP image from a file handle.

parseBMP :: ByteString -> Either Error BMP Source #

Parse a BMP image from a lazy ByteString

Writing

writeBMP :: FilePath -> BMP -> IO () Source #

Wrapper for hPutBMP

hPutBMP :: Handle -> BMP -> IO () Source #

Put a BMP image to a file handle.

renderBMP :: BMP -> ByteString Source #

Render a BMP image to a lazy ByteString.

Pack and Unpack

packRGBA32ToBMP Source #

Arguments

:: Int	Width of image (must be positive).
-> Int	Height of image (must be positive).
-> ByteString	A string of RGBA component values. Must have length (`width * height * 4`)
-> BMP

Pack a string of RGBA component values into a 32-bit BMP image.

Alias for packRGBA32ToBMP32.

packRGBA32ToBMP32 Source #

Arguments

:: Int	Width of image (must be positive).
-> Int	Height of image (must be positive).
-> ByteString	A string of RGBA component values. Must have length (`width * height * 4`)
-> BMP

Pack a string of RGBA component values into a 32-bit BMP image.

If the given dimensions don't match the input string then error.
If the width or height fields are negative then error.

packRGBA32ToBMP24 Source #

Arguments

:: Int	Width of image (must be positive).
-> Int	Height of image (must be positive).
-> ByteString	A string of RGBA component values. Must have length (`width * height * 4`)
-> BMP

Pack a string of RGBA component values into a 24-bit BMP image, discarding the alpha channel of the source data.

If the given dimensions don't match the input string then error.
If the width or height fields are negative then error.

unpackBMPToRGBA32 :: BMP -> ByteString Source #

Unpack a BMP image to a string of RGBA component values.

bmpDimensions :: BMP -> (Int, Int) Source #

Get the width and height of an image. It's better to use this function than to access the headers directly.