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


-- | A library for handling and manipulating bitmaps.
--   
--   A library for handling and manipulating bitmaps (that is, rectangular
--   pixel arrays).
@package bitmap
@version 0.0.1

module Data.Bitmap.Base
class (Num t, Storable t) => PixelComponent t
data PixelComponentType
PctWord8 :: PixelComponentType
PctWord16 :: PixelComponentType
PctWord32 :: PixelComponentType
PctFloat :: PixelComponentType
pixelComponentSize :: PixelComponentType -> Int
pixelComponentType :: PixelComponent t => t -> PixelComponentType

-- | 8-bit unsigned integer type
data Word8 :: *

-- | 16-bit unsigned integer type
data Word16 :: *

-- | 32-bit unsigned integer type
data Word32 :: *
type Size = (Int, Int)
type Offset = (Int, Int)
type NChn = Int
type Alignment = Int
type Padding = Int
data Bitmap t

-- | (width,height)
bitmapSize :: Bitmap t -> Size

-- | number of channels (eg. 3 for RGB)
bitmapNChannels :: Bitmap t -> NChn

-- | the padding of the rows, measured in <i>bytes</i>
bitmapRowPadding :: Bitmap t -> Padding

-- | the alignment of the rows (in bytes)
bitmapRowAlignment :: Bitmap t -> Alignment

-- | The width divided by the height.
bitmapAspect :: Fractional a => Bitmap t -> a
bitmapComponentSizeInBytes :: PixelComponent t => Bitmap t -> Int
bitmapPixelSizeInBytes :: PixelComponent t => Bitmap t -> Int
bitmapPaddedRowSizeInBytes :: PixelComponent t => Bitmap t -> Int
bitmapUnpaddedRowSizeInBytes :: PixelComponent t => Bitmap t -> Int
bitmapSizeInBytes :: PixelComponent t => Bitmap t -> Int


-- | The full, mutable API in the IO monad.
module Data.Bitmap.IO

-- | Note: we <i>cannot</i> guarantee the alignment of the memory block
--   (but typically it is aligned at least to machine word boundary), but
--   what we <i>can</i> guarantee is that the rows are properly padded.
--   
--   At the moment, the default alignment is 4, valid alignments are 1, 2,
--   4, 8 and 16, and the padding method is compatible with the OpenGL one
--   (that is, the padding is the smallest multiple of a component size
--   such that the next row is aligned).
--   
--   The resulting new bitmap is filled with zeros.
newBitmap :: PixelComponent t => Size -> NChn -> Maybe Alignment -> IO (Bitmap t)
newBitmapUninitialized :: PixelComponent t => Size -> NChn -> Maybe Alignment -> IO (Bitmap t)

-- | Creates a new single-channel bitmap, using the given function to
--   compute the pixel values. Warning, this is probably slow!
createSingleChannelBitmap :: PixelComponent t => Size -> Maybe Alignment -> (Int -> Int -> t) -> IO (Bitmap t)
copyBitmapFromPtr :: PixelComponent t => Size -> NChn -> Padding -> Ptr t -> Maybe Alignment -> IO (Bitmap t)
bitmapFromForeignPtrUnsafe :: PixelComponent t => Size -> NChn -> Alignment -> Padding -> ForeignPtr t -> Bitmap t

-- | <pre>
--   withBitmap bitmap $ \(w,h) nchn padding ptr -&gt; ...
--   </pre>
withBitmap :: PixelComponent t => Bitmap t -> (Size -> NChn -> Padding -> Ptr t -> IO a) -> IO a

-- | Maps a function over each component of each pixel. Warning: this is
--   probably slow! Use a specialized function if there is one for your
--   task.
componentMap :: PixelComponent s => (s -> s) -> Bitmap s -> IO (Bitmap s)
componentMap' :: (PixelComponent s, PixelComponent t) => (s -> t) -> Bitmap s -> Maybe Alignment -> IO (Bitmap t)
componentMapInPlace :: PixelComponent s => (s -> s) -> Bitmap s -> IO ()

-- | Copies a subrectangle of the source image into a new image.
copySubImage :: PixelComponent t => Bitmap t -> Offset -> Size -> IO (Bitmap t)

-- | Copy into a new "black" bitmap; common generalization of crop and
--   extend.
copySubImage' :: PixelComponent t => Bitmap t -> Offset -> Size -> Size -> Offset -> IO (Bitmap t)

-- | The source rectangle may be arbitrary, may or may not intersect the
--   source image in any way. We only copy the intersection of the
--   rectangle with the image.
copySubImageInto :: PixelComponent t => Bitmap t -> Offset -> Size -> Bitmap t -> Offset -> IO ()
combineChannels :: PixelComponent t => [Bitmap t] -> Maybe Alignment -> IO (Bitmap t)
extractChannels :: PixelComponent t => Bitmap t -> Maybe Alignment -> IO [Bitmap t]
extractSingleChannel :: PixelComponent t => Bitmap t -> Maybe Alignment -> Int -> IO (Bitmap t)
extractChannelInto :: PixelComponent t => Bitmap t -> Int -> Bitmap t -> Int -> IO ()
bilinearResample :: PixelComponent t => Bitmap t -> Size -> Maybe Alignment -> IO (Bitmap t)
bilinearResampleChannel :: PixelComponent t => Bitmap t -> Int -> Size -> Maybe Alignment -> IO (Bitmap t)
bilinearResampleChannelInto :: PixelComponent t => Bitmap t -> Int -> Bitmap t -> Int -> IO ()

-- | Blends two bitmaps with the given weights; that is, the result is the
--   specified linear combination. If the values are outside the allowed
--   range (this can happen with the Word8, Word16, Word32 types and
--   weights whose sum is bigger than 1, or with a negative weight), then
--   they are clipped. The clipping <i>does not</i> happen with the Float
--   component type.
blendBitmaps :: PixelComponent t => Float -> Float -> Bitmap t -> Bitmap t -> Maybe Alignment -> IO (Bitmap t)
blendChannels :: PixelComponent t => Float -> Float -> Bitmap t -> Int -> Bitmap t -> Int -> Maybe Alignment -> IO (Bitmap t)
blendChannelsInto :: PixelComponent t => Float -> Float -> Bitmap t -> Int -> Bitmap t -> Int -> Bitmap t -> Int -> IO ()

-- | This is equivalent to <tt>componentMap (c -&gt; c^gamma)</tt>, except
--   that <tt>(^)</tt> is defined only for integral exponents; but should
--   be faster anyway.
powerlawGammaCorrection :: PixelComponent t => Float -> Bitmap t -> Maybe Alignment -> IO (Bitmap t)
powerlawGammaCorrectionChannel :: PixelComponent t => Float -> Bitmap t -> Int -> Maybe Alignment -> IO (Bitmap t)
powerlawGammaCorrectionChannelInto :: PixelComponent t => Float -> Bitmap t -> Int -> Bitmap t -> Int -> IO ()

-- | The data is copied, not shared. Note that the resulting ByteString is
--   encoded using the host machine's endianness, so it may be not
--   compatible across different architectures!
copyBitmapToByteString :: PixelComponent t => Bitmap t -> IO ByteString

-- | The data is copied, not shared. Note that we expect the ByteString to
--   be encoded encoded using the host machine's endianness.
copyBitmapFromByteString :: PixelComponent t => ByteString -> Size -> NChn -> Padding -> IO (Bitmap t)

-- | Note that the resulting pointer is valid only within a line (because
--   of the padding)
withComponentPtr :: PixelComponent t => Bitmap t -> Offset -> Int -> (Ptr t -> IO a) -> IO a

-- | It is not very efficient to read/write lots of pixels this way.
unsafeReadComponent :: PixelComponent t => Bitmap t -> Offset -> Int -> IO t
unsafeWriteComponent :: PixelComponent t => Bitmap t -> Offset -> Int -> t -> IO ()

-- | Please note that the component array to read shouldn't cross the
--   boundary between lines.
unsafeReadComponents :: PixelComponent t => Bitmap t -> Offset -> Int -> Int -> IO [t]

-- | Please note that the component array to write shouldn't cross the
--   boundary between lines.
unsafeWriteComponents :: PixelComponent t => Bitmap t -> Offset -> Int -> [t] -> IO ()
unsafeReadPixel :: PixelComponent t => Bitmap t -> Offset -> IO [t]

-- | These functions assume that the number of channels of the bitmap
--   agrees with the number suffix of the function.
--   
--   (Maybe I should put the number of components into the Bitmap type? But
--   that would cause different problems...)
unsafeReadPixel1 :: PixelComponent t => Bitmap t -> Offset -> IO t
unsafeReadPixel2 :: PixelComponent t => Bitmap t -> Offset -> IO (t, t)
unsafeReadPixel3 :: PixelComponent t => Bitmap t -> Offset -> IO (t, t, t)
unsafeReadPixel4 :: PixelComponent t => Bitmap t -> Offset -> IO (t, t, t, t)
unsafeWritePixel1 :: PixelComponent t => Bitmap t -> Offset -> t -> IO ()
unsafeWritePixel2 :: PixelComponent t => Bitmap t -> Offset -> (t, t) -> IO ()
unsafeWritePixel3 :: PixelComponent t => Bitmap t -> Offset -> (t, t, t) -> IO ()
unsafeWritePixel4 :: PixelComponent t => Bitmap t -> Offset -> (t, t, t, t) -> IO ()

module Data.Bitmap.Pure

-- | A bitmap filled with zero values. Note: we <i>cannot</i> guarantee the
--   alignment of the memory block (but typically it is aligned at least to
--   machine word boundary), but what we <i>can</i> guarantee is that the
--   rows are properly padded.
emptyBitmap :: PixelComponent t => Size -> NChn -> Maybe Alignment -> Bitmap t

-- | Creates a single channel bitmap from a function. This is probably a
--   bit slow.
createSingleChannelBitmap :: PixelComponent t => Size -> Maybe Alignment -> (Int -> Int -> t) -> Bitmap t

-- | Warning: this is probably slow.
componentMap :: PixelComponent s => (s -> s) -> Bitmap s -> Bitmap s

-- | Warning: this is probably slow.
componentMap' :: (PixelComponent s, PixelComponent t) => (s -> t) -> Bitmap s -> Maybe Alignment -> Bitmap t

-- | Copies a subrectangle of the source image into a new image.
copySubImage :: PixelComponent t => Bitmap t -> Offset -> Size -> Bitmap t

-- | Copy into a new "black" bitmap; common generalization of crop and
--   extend.
copySubImage' :: PixelComponent t => Bitmap t -> Offset -> Size -> Size -> Offset -> Bitmap t
combineChannels :: PixelComponent t => [Bitmap t] -> Maybe Alignment -> Bitmap t
extractChannels :: PixelComponent t => Bitmap t -> Maybe Alignment -> [Bitmap t]
extractSingleChannel :: PixelComponent t => Bitmap t -> Maybe Alignment -> Int -> Bitmap t
bilinearResample :: PixelComponent t => Bitmap t -> Size -> Maybe Alignment -> Bitmap t
bilinearResampleChannel :: PixelComponent t => Bitmap t -> Int -> Size -> Maybe Alignment -> Bitmap t

-- | Blends two bitmaps with the given weights; that is, the result is the
--   specified linear combination. If the values are outside the allowed
--   range (this can happen with the Word8, Word16, Word32 types and
--   weights whose sum is bigger than 1, or with a negative weight), then
--   they are clipped. The clipping <i>does not</i> happen with the Float
--   component type.
blendBitmaps :: PixelComponent t => Float -> Float -> Bitmap t -> Bitmap t -> Maybe Alignment -> Bitmap t
blendChannels :: PixelComponent t => Float -> Float -> Bitmap t -> Int -> Bitmap t -> Int -> Maybe Alignment -> Bitmap t

-- | This is equivalent to <tt>componentMap (c -&gt; c^gamma)</tt>, except
--   that <tt>(^)</tt> is defined only for integral exponents; but should
--   be faster anyway.
powerlawGammaCorrection :: PixelComponent t => Float -> Bitmap t -> Maybe Alignment -> Bitmap t
powerlawGammaCorrectionChannel :: PixelComponent t => Float -> Bitmap t -> Int -> Maybe Alignment -> Bitmap t

-- | Note that the data is <i>shared</i>; and also that the resulting
--   ByteString is encoded using the host machine's endianness.
bitmapToByteString :: PixelComponent t => Bitmap t -> ByteString


-- | A library to handle bitmaps (uncompressed pixel rectangles). The
--   smallest storage unit is 1 byte (thus <i>bit</i>maps, in the literal
--   sense of the word, are not supported).
--   
--   For loading JPEG/PNG images into <a>Bitmap</a>s, see the
--   <tt>stb-image</tt> library (version 0.2 or newer):
--   <a>http://hackage.haskell.org/package/stb-image</a>.
--   
--   Terminology: Pixels are made out of one or more "components". These
--   components are also referred as "channels"; for example a color image
--   could be made out of three channels, the red, green and blue one. The
--   components can be unsigned bytes, words, dwords, or floats. The pixels
--   are stored in horizontal order, and the channels are interleaved: That
--   is, the structure of an RGB image is <tt>R0 G0 B0 R1 G1 B1 ...</tt>.
--   Most of the library is indifferent to the meaning of different
--   channels.
--   
--   "Padding" refers to unused bytes at the end of each row. This is
--   sometimes necessary because other software components want the rows
--   aligned to machine word boundary, for example.
--   
--   The library should be relatively fast (except where noted), but
--   performance is not the primary goal (thus there is no inline assembly,
--   no SSE, etc.; but the critical functions are coded in C).
--   
--   There are both pure and IO versions of the API; you shouldn't mix the
--   two without taking special care. This module re-exports the pure
--   interface; if you want the IO one, import <tt>Data.Bitmap.IO</tt>
--   instead.
module Data.Bitmap