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


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

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

-- | A bitmap.
data Bitmap t
bitmapSize :: BitmapClass bitmap => bitmap t -> Size
bitmapNChannels :: BitmapClass bitmap => bitmap t -> NChn
bitmapRowPadding :: BitmapClass bitmap => bitmap t -> Padding
bitmapRowAlignment :: BitmapClass bitmap => bitmap t -> Alignment

-- | The width divided by the height.
bitmapAspect :: (Fractional a, BitmapClass bitmap) => bitmap t -> a
bitmapComponentType :: (BitmapClass bitmap, PixelComponent t) => bitmap t -> PixelComponentType
bitmapComponentSizeInBytes :: (BitmapClass bitmap, PixelComponent t) => bitmap t -> Int
bitmapPixelSizeInBytes :: (BitmapClass bitmap, PixelComponent t) => bitmap t -> Int
bitmapPaddedRowSizeInBytes :: (BitmapClass bitmap, PixelComponent t) => bitmap t -> Int
bitmapUnpaddedRowSizeInBytes :: (BitmapClass bitmap, PixelComponent t) => bitmap t -> Int
bitmapSizeInBytes :: (BitmapClass bitmap, PixelComponent t) => bitmap t -> Int

-- | A class so that using newtypes is convenient.
class BitmapClass b
data BitmapChannel t
BmChn :: (Bitmap t) -> Int -> BitmapChannel t


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

-- | A mutable Bitmap in the IO Monad. Only the content is mutable, the
--   shape isn't.
data IOBitmap t
data IOBitmapChannel t
unsafeFreezeBitmap :: IOBitmap t -> Bitmap t
unsafeThawBitmap :: Bitmap t -> IOBitmap t

-- | Synonym for <a>newIOBitmap</a>
emptyBitmap :: PixelComponent t => Size -> NChn -> Maybe Alignment -> IO (IOBitmap t)

-- | Clones a bitmap.
cloneBitmap :: PixelComponent t => IOBitmap t -> Maybe Alignment -> IO (IOBitmap t)

-- | Creates an empty bitmap with the same properties as the source.
emptyCloneBitmap :: PixelComponent t => IOBitmap t -> Maybe Alignment -> IO (IOBitmap 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 (IOBitmap t)

-- | 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.
newIOBitmap :: PixelComponent t => Size -> NChn -> Maybe Alignment -> IO (IOBitmap t)
newIOBitmapUninitialized :: PixelComponent t => Size -> NChn -> Maybe Alignment -> IO (IOBitmap t)
copyBitmapFromPtr :: PixelComponent t => Size -> NChn -> Padding -> Ptr t -> Maybe Alignment -> IO (IOBitmap t)
ioBitmapFromForeignPtrUnsafe :: PixelComponent t => Size -> NChn -> Alignment -> Padding -> ForeignPtr t -> IOBitmap t

-- | <pre>
--   withIOBitmap bitmap $ \(w,h) nchn padding ptr -&gt; ...
--   </pre>
withIOBitmap :: PixelComponent t => IOBitmap 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) -> IOBitmap s -> IO (IOBitmap s)
componentMap' :: (PixelComponent s, PixelComponent t) => (s -> t) -> IOBitmap s -> Maybe Alignment -> IO (IOBitmap t)
componentMapInPlace :: PixelComponent s => (s -> s) -> IOBitmap s -> IO ()

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

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

-- | Flips the bitmap vertically.
flipBitmap :: PixelComponent t => IOBitmap t -> Maybe Alignment -> IO (IOBitmap t)
flipBitmapInPlace :: PixelComponent t => IOBitmap t -> IO ()

-- | Flips the bitmap horizontally.
mirrorBitmap :: PixelComponent t => IOBitmap t -> Maybe Alignment -> IO (IOBitmap t)
mirrorBitmapInPlace :: PixelComponent t => IOBitmap t -> IO ()

-- | Convert a bitmap to one with a different component type.
castBitmap :: (PixelComponent s, PixelComponent t) => IOBitmap s -> Maybe Alignment -> IO (IOBitmap t)
combineChannels :: PixelComponent t => [IOBitmap t] -> Maybe Alignment -> IO (IOBitmap t)
extractChannels :: PixelComponent t => IOBitmap t -> Maybe Alignment -> IO [IOBitmap t]
extractSingleChannel :: PixelComponent t => IOBitmap t -> Maybe Alignment -> Int -> IO (IOBitmap t)
extractChannelInto :: PixelComponent t => IOBitmap t -> Int -> IOBitmap t -> Int -> IO ()
bilinearResample :: PixelComponent t => IOBitmap t -> Size -> Maybe Alignment -> IO (IOBitmap t)
bilinearResampleChannel :: PixelComponent t => IOBitmap t -> Int -> Size -> Maybe Alignment -> IO (IOBitmap t)
bilinearResampleChannelInto :: PixelComponent t => IOBitmap t -> Int -> IOBitmap 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 -> IOBitmap t -> IOBitmap t -> Maybe Alignment -> IO (IOBitmap t)
blendChannels :: PixelComponent t => Float -> Float -> IOBitmap t -> Int -> IOBitmap t -> Int -> Maybe Alignment -> IO (IOBitmap t)
blendChannelsInto :: PixelComponent t => Float -> Float -> IOBitmap t -> Int -> IOBitmap t -> Int -> IOBitmap 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 -> IOBitmap t -> Maybe Alignment -> IO (IOBitmap t)
powerlawGammaCorrectionChannel :: PixelComponent t => Float -> IOBitmap t -> Int -> Maybe Alignment -> IO (IOBitmap t)
powerlawGammaCorrectionChannelInto :: PixelComponent t => Float -> IOBitmap t -> Int -> IOBitmap t -> Int -> IO ()


-- | The pure, inmutable API.
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

-- | Clones a bitmap. The only effect of this in the pure setting should be
--   that the alignment/padding can change. You shouldn't normally use this
--   function.
cloneBitmap :: PixelComponent t => Bitmap t -> Maybe Alignment -> Bitmap t

-- | Creates an empty bitmap with the same properties as the source.
emptyCloneBitmap :: PixelComponent t => Bitmap t -> 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
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

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

-- | Flips the bitmap vertically.
flipBitmap :: PixelComponent t => Bitmap t -> Maybe Alignment -> Bitmap t

-- | Flips the bitmap horizontally.
mirrorBitmap :: PixelComponent t => Bitmap t -> Maybe Alignment -> Bitmap t

-- | Converts between different component types.
castBitmap :: (PixelComponent s, PixelComponent t) => Bitmap s -> Maybe Alignment -> 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


-- | Saving and loading uncompressed bitmaps. For loading from compressed
--   formats, see the <tt>stb-image</tt> library:
--   <a>http://hackage.haskell.org/package/stb-image</a>.
--   
--   The goal of this module is to provide the simplest possible interface
--   for loading and saving bitmaps; so you can start experimenting without
--   much hassle.
--   
--   Note: Endianness is the endianness of the host, so the resulting file
--   is not portable across platforms with different endiannesses.
module Data.Bitmap.IO.File
readBitmap :: PixelComponent t => FilePath -> IO (IOBitmap t)
writeBitmap :: PixelComponent t => FilePath -> IOBitmap t -> IO ()
readRawData :: PixelComponent t => FilePath -> (Size, NChn, PixelComponentType) -> IO (IOBitmap t)

-- | Saves only the raw pixel data, no resolution etc.
writeRawData :: PixelComponent t => FilePath -> IOBitmap t -> IO ()

-- | Writes a 16 byte header in the following format:
--   
--   <pre>
--   dword xsize
--   dword ysize
--   dword nchn
--   dword pixelcomponent_type
--   </pre>
--   
--   Pixel component encoding is the following:
--   
--   <ul>
--   <li>1 = Word8</li>
--   <li>2 = Word16</li>
--   <li>3 = Word32</li>
--   <li>4 = Float</li>
--   </ul>
--   
--   Endianness is the endianness of the host, so the resulting file is not
--   portable across platform with different endiannesses.
hPutHeader :: PixelComponent t => Handle -> IOBitmap t -> IO ()

-- | Saves only the raw pixel data, no resolution etc.
hPutRawData :: PixelComponent t => Handle -> IOBitmap t -> IO ()
hGetHeader :: Handle -> IO (Size, NChn, PixelComponentType)
hGetRawData :: PixelComponent t => Handle -> (Size, NChn, PixelComponentType) -> IO (IOBitmap t)


-- | Saving and loading uncompressed bitmaps. For loading from compressed
--   formats, see the <tt>stb-image</tt> library:
--   <a>http://hackage.haskell.org/package/stb-image</a>.
--   
--   The goal of this module is to provide the simplest possible interface
--   for loading and saving bitmaps; so you can start experimenting without
--   much hassle.
--   
--   Note: Endianness is the endianness of the host, so the resulting file
--   is not portable across platforms with different endiannesses.
--   
--   See the module <a>Data.Bitmap.IO.File</a> for the file format.
module Data.Bitmap.Pure.File
readBitmap :: PixelComponent t => FilePath -> IO (Bitmap t)
writeBitmap :: PixelComponent t => FilePath -> Bitmap t -> IO ()
readRawData :: PixelComponent t => FilePath -> (Size, NChn, PixelComponentType) -> IO (Bitmap t)

-- | Saves only the raw pixel data, no resolution etc.
writeRawData :: PixelComponent t => FilePath -> Bitmap t -> IO ()


-- | Access to individual pixels. It isn't very efficient to handle bitmaps
--   this way.
module Data.Bitmap.Pure.Pixels

-- | Newtypes for bitmaps with a fixed number of channels (components per
--   pixel)
data Bitmap1 t
data Bitmap2 t
data Bitmap3 t
data Bitmap4 t
bitmap1 :: Bitmap t -> Bitmap1 t
bitmap2 :: Bitmap t -> Bitmap2 t
bitmap3 :: Bitmap t -> Bitmap3 t
bitmap4 :: Bitmap t -> Bitmap4 t

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

-- | Please note that the component array to read shouldn't cross the
--   boundary between lines.
unsafeReadComponents :: PixelComponent t => Bitmap t -> Offset -> Int -> Int -> [t]
unsafeReadPixel :: PixelComponent t => Bitmap t -> Offset -> [t]
unsafeReadPixel1 :: PixelComponent t => Bitmap1 t -> Offset -> t
unsafeReadPixel2 :: PixelComponent t => Bitmap2 t -> Offset -> (t, t)
unsafeReadPixel3 :: PixelComponent t => Bitmap3 t -> Offset -> (t, t, t)
unsafeReadPixel4 :: PixelComponent t => Bitmap4 t -> Offset -> (t, t, t, t)
instance BitmapClass Bitmap4
instance BitmapClass Bitmap3
instance BitmapClass Bitmap2
instance BitmapClass Bitmap1


-- | Accessing individual pixels.
module Data.Bitmap.IO.Pixels

-- | Newtypes for mutable bitmaps with a fixed number of channels
--   (components per pixel)
data IOBitmap1 t
data IOBitmap2 t
data IOBitmap3 t
data IOBitmap4 t
ioBitmap1 :: IOBitmap t -> IOBitmap1 t
ioBitmap2 :: IOBitmap t -> IOBitmap2 t
ioBitmap3 :: IOBitmap t -> IOBitmap3 t
ioBitmap4 :: IOBitmap t -> IOBitmap4 t
fromIOBitmap1 :: IOBitmap1 t -> IOBitmap t
fromIOBitmap2 :: IOBitmap2 t -> IOBitmap t
fromIOBitmap3 :: IOBitmap3 t -> IOBitmap t
fromIOBitmap4 :: IOBitmap4 t -> IOBitmap t

-- | Note that the resulting pointer is valid only within a line (because
--   of the padding)
withComponentPtr :: PixelComponent t => IOBitmap 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 => IOBitmap t -> Offset -> Int -> IO t
unsafeWriteComponent :: PixelComponent t => IOBitmap t -> Offset -> Int -> t -> IO ()

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

-- | Please note that the component array to write shouldn't cross the
--   boundary between lines.
unsafeWriteComponents :: PixelComponent t => IOBitmap t -> Offset -> Int -> [t] -> IO ()
unsafeReadPixel :: PixelComponent t => IOBitmap t -> Offset -> IO [t]
unsafeReadPixel1 :: PixelComponent t => IOBitmap1 t -> Offset -> IO t
unsafeReadPixel2 :: PixelComponent t => IOBitmap2 t -> Offset -> IO (t, t)
unsafeReadPixel3 :: PixelComponent t => IOBitmap3 t -> Offset -> IO (t, t, t)
unsafeReadPixel4 :: PixelComponent t => IOBitmap4 t -> Offset -> IO (t, t, t, t)
unsafeWritePixel1 :: PixelComponent t => IOBitmap1 t -> Offset -> t -> IO ()
unsafeWritePixel2 :: PixelComponent t => IOBitmap2 t -> Offset -> (t, t) -> IO ()
unsafeWritePixel3 :: PixelComponent t => IOBitmap3 t -> Offset -> (t, t, t) -> IO ()
unsafeWritePixel4 :: PixelComponent t => IOBitmap4 t -> Offset -> (t, t, t, t) -> IO ()
instance BitmapClass IOBitmap4
instance BitmapClass IOBitmap3
instance BitmapClass IOBitmap2
instance BitmapClass IOBitmap1


-- | This is the same as the pure API, without the annoying alignment
--   stuff. All functions use the default alignment.
module Data.Bitmap.Simple

-- | A bitmap filled with zero values.
emptyBitmap :: PixelComponent t => Size -> NChn -> Bitmap t

-- | Creates an empty bitmap with the same properties as the source.
emptyCloneBitmap :: PixelComponent t => Bitmap t -> Bitmap t

-- | Creates a single channel bitmap from a function. This is probably a
--   bit slow.
createSingleChannelBitmap :: PixelComponent t => Size -> (Int -> Int -> 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

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

-- | Flips the bitmap vertically.
flipBitmap :: PixelComponent t => Bitmap t -> Bitmap t

-- | Flips the bitmap horizontally.
mirrorBitmap :: PixelComponent t => Bitmap t -> Bitmap t

-- | Converts between different component types.
castBitmap :: (PixelComponent s, PixelComponent t) => Bitmap s -> Bitmap t
combineChannels :: PixelComponent t => [Bitmap t] -> Bitmap t
extractChannels :: PixelComponent t => Bitmap t -> [Bitmap t]
extractSingleChannel :: PixelComponent t => Bitmap t -> Int -> Bitmap t
bilinearResample :: PixelComponent t => Bitmap t -> Size -> Bitmap t
bilinearResampleChannel :: PixelComponent t => Bitmap t -> Int -> Size -> 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 -> Bitmap t
blendChannels :: PixelComponent t => Float -> Float -> Bitmap t -> Int -> Bitmap t -> Int -> 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 -> Bitmap t
powerlawGammaCorrectionChannel :: PixelComponent t => Float -> Bitmap t -> Int -> Bitmap t


-- | 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 mutable IO versions of the API (ST is also
--   planned). This module re-exports the simplified pure interface.
module Data.Bitmap