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


-- | Read and write Accelerate arrays in various formats
--   
--   This package provides efficient conversion routines between a range of
--   array types and Accelerate arrays.
--   
--   Refer to the main <i>Accelerate</i> package for more information:
--   <a>http://hackage.haskell.org/package/accelerate</a>
@package accelerate-io
@version 1.0.0.1


-- | This module provides efficient conversion routines between different
--   array types and Accelerate arrays.
module Data.Array.Accelerate.IO

-- | The representation tag for manifest arrays based on
--   Data.Array.Accelerate.
--   
--   The Accelerate array implementation is based on type families and
--   picks an efficient, unboxed representation for every element type.
--   Moreover, these arrays can be handed efficiently (without copying) to
--   Accelerate programs for further computation.
data A

-- | Index conversion and equivalence statement between Repa and Accelerate
--   array shapes. That is, a n-dimensional Repa array will produce an
--   n-dimensional Accelerate array of the same extent, and vice-versa.
class (Shape r, Shape a) => Shapes r a | a -> r, r -> a

-- | <i>O(1)</i>. Unpack to an Accelerate array.
fromRepa :: (Shapes sh sh', Elt e) => Array A sh e -> Array sh' e

-- | <i>O(1)</i>. Wrap an Accelerate array.
toRepa :: Shapes sh sh' => Array sh' e -> Array A sh e

-- | Sequential computation of array elements
computeAccS :: (Load r sh e, Elt e) => Array r sh e -> Array A sh e

-- | Parallel computation of array elements
computeAccP :: (Load r sh e, Elt e, Monad m) => Array r sh e -> m (Array A sh e)

-- | A family of types that represents a collection of storable
--   <a>Vector</a>s. The structure of the collection depends on the element
--   type <tt>e</tt>.
--   
--   For example:
--   
--   <ul>
--   <li>if <tt>e :: Int</tt>, then <tt>Vectors (EltRepr e) :: ((), Vector
--   Int)</tt></li>
--   <li>if <tt>e :: (Double, Float)</tt>, then <tt>Vectors (EltRepr e) ::
--   (((), Vector Double), Vector Float)</tt></li>
--   </ul>

-- | <i>O(1)</i>. Turn the Accelerate array into a collection of storable
--   <a>Vector</a>s. The element type of the array <tt>e</tt> will
--   determine the structure of the output collection. See <a>Vectors</a>.
--   
--   Data will be output in row-major order.
toVectors :: (Shape sh, Elt e) => Array sh e -> Vectors (EltRepr e)

-- | <i>O(1)</i>. Treat a set of storable vectors as Accelerate arrays. The
--   type of elements <tt>e</tt> in the output Accelerate array determines
--   the structure of the collection that will be required as the second
--   argument. See <a>Vectors</a>.
--   
--   Data will be consumed from the vector in row-major order. You must
--   make sure that each of the input vectors contains the right number of
--   elements
fromVectors :: (Shape sh, Elt e) => sh -> Vectors (EltRepr e) -> Array sh e

-- | Convert an <a>IArray</a> to an accelerated array.
--   
--   While the type signature mentions Accelerate internals that are not
--   exported, in practice satisfying the type equality is straight
--   forward. The index type <tt>ix</tt> must be the unit type <tt>()</tt>
--   for singleton arrays, or an <tt>Int</tt> or tuple of <tt>Int</tt>'s
--   for multidimensional arrays.
fromIArray :: (IxShapeRepr (EltRepr ix) ~ EltRepr sh, IArray a e, Ix ix, Shape sh, Elt ix, Elt e) => a ix e -> Array sh e

-- | Convert an accelerated array to an <a>IArray</a>.
toIArray :: (IxShapeRepr (EltRepr ix) ~ EltRepr sh, IArray a e, Ix ix, Shape sh, Elt ix) => Array sh e -> a ix e

-- | Packed RGBA pixel data
type RGBA32 = Word32

-- | Read RGBA components from a BMP file.
readImageFromBMP :: FilePath -> IO (Either Error (Array DIM2 RGBA32))

-- | Write the image data to a file.
writeImageToBMP :: FilePath -> Array DIM2 RGBA32 -> IO ()

-- | A family of types that represents a collection of <a>ByteString</a>s.
--   They are the source data for function <tt>fromByteString</tt> and the
--   result data for <tt>toByteString</tt>

-- | Block copies bytes from a collection of <tt>ByteString</tt>s to
--   freshly allocated Accelerate array.
--   
--   The type of elements (<tt>e</tt>) in the output Accelerate array
--   determines the structure of the collection of <tt>ByteString</tt>s
--   that will be required as the second argument to this function. See
--   <a>ByteStrings</a>
fromByteString :: (Shape sh, Elt e) => sh -> ByteStrings (EltRepr e) -> IO (Array sh e)

-- | Block copy from an Accelerate array to a collection of freshly
--   allocated <tt>ByteString</tt>s.
--   
--   The type of elements (<tt>e</tt>) in the input Accelerate array
--   determines the structure of the collection of <tt>ByteString</tt>s
--   that will be output. See <a>ByteStrings</a>
toByteString :: (Shape sh, Elt e) => Array sh e -> IO (ByteStrings (EltRepr e))

-- | A family of types that represents a collection of pointers that are
--   the source/destination addresses for a block copy. The structure of
--   the collection of pointers depends on the element type <tt>e</tt>.
--   
--   e.g.
--   
--   If <tt>e :: Int</tt>, then <tt>BlockPtrs (EltRepr e) :: ((), Ptr
--   Int)</tt>
--   
--   If <tt>e :: (Double, Float)</tt> then <tt>BlockPtrs (EltRepr e) ::
--   (((), Ptr Double), Ptr Float)</tt>

-- | Block copy regions of memory into a freshly allocated Accelerate
--   array. The type of elements (<tt>e</tt>) in the output Accelerate
--   array determines the structure of the collection of pointers that will
--   be required as the second argument to this function. See
--   <a>BlockPtrs</a>
--   
--   Each one of these pointers points to a block of memory that is the
--   source of data for the Accelerate array (unlike function
--   <a>toArray</a> where one passes in function which copies data to a
--   destination address.).
fromPtr :: (Shape sh, Elt e) => sh -> BlockPtrs (EltRepr e) -> IO (Array sh e)

-- | Block copy from Accelerate array to pre-allocated regions of memory.
--   The type of element of the input Accelerate array (<tt>e</tt>)
--   determines the structure of the collection of pointers that will be
--   required as the second argument to this function. See <a>BlockPtrs</a>
--   
--   The memory associated with the pointers must have already been
--   allocated.
toPtr :: (Shape sh, Elt e) => Array sh e -> BlockPtrs (EltRepr e) -> IO ()

-- | Functions of this type are passed as arguments to <tt>toArray</tt>. A
--   function of this type should copy a number of bytes (equal to the
--   value of the parameter of type <a>Int</a>) to the destination memory
--   pointed to by <tt>Ptr e</tt>.
type BlockCopyFun e = Ptr e -> Int -> IO ()

-- | Represents a collection of "block copy functions" (see
--   <a>BlockCopyFun</a>). The structure of the collection of
--   <a>BlockCopyFun</a>s depends on the element type <tt>e</tt>.
--   
--   e.g.
--   
--   If <tt>e :: Float</tt> then <tt>BlockCopyFuns (EltRepr e) :: ((), Ptr
--   Float -&gt; Int -&gt; IO ())</tt>
--   
--   If <tt>e :: (Double, Float)</tt> then <tt>BlockCopyFuns (EltRepr e) ::
--   (((), Ptr Double -&gt; Int -&gt; IO ()), Ptr Float -&gt; Int -&gt; IO
--   ())</tt>

-- | Copy values from an Accelerate array using a collection of functions
--   that have type <a>BlockCopyFun</a>. The argument of type <tt>Ptr
--   e</tt> in each of these functions refers to the address of the
--   <i>source</i> block of memory in the Accelerate Array. The
--   <i>destination</i> address is implicit. e.g. the <a>BlockCopyFun</a>
--   could be the result of partially application to a <tt>Ptr e</tt>
--   pointing to the destination block.
--   
--   The structure of this collection of functions depends on the elemente
--   type <tt>e</tt>. Each function (of type <a>BlockCopyFun</a>) copies
--   data to a destination address (pointed to by the argument of type
--   <tt>Ptr ()</tt>).
--   
--   Unless there is a particularly pressing reason to use this function,
--   the <a>fromPtr</a> function is sufficient as it uses an efficient
--   low-level call to libc's <tt>memcpy</tt> to perform the copy.
fromArray :: (Shape sh, Elt e) => Array sh e -> BlockCopyFuns (EltRepr e) -> IO ()

-- | Copy values to a freshly allocated Accelerate array using a collection
--   of functions that have type <a>BlockCopyFun</a>. The argument of type
--   <tt>Ptr e</tt> in each of these functions refers to the address of the
--   <i>destination</i> block of memory in the Accelerate Array. The
--   <i>source</i> address is implicit. e.g. the <a>BlockCopyFun</a> could
--   be the result of a partial application to a <tt>Ptr e</tt> pointing to
--   the source block.
--   
--   The structure of this collection of functions depends on the elemente
--   type <tt>e</tt>. Each function (of type <a>BlockCopyFun</a>) copies
--   data to a destination address (pointed to by the argument of type
--   <tt>Ptr ()</tt>).
--   
--   Unless there is a particularly pressing reason to use this function,
--   the <a>fromPtr</a> function is sufficient as it uses an efficient
--   low-level call to libc's <tt>memcpy</tt> to perform the copy.
toArray :: (Shape sh, Elt e) => sh -> BlockCopyFuns (EltRepr e) -> IO (Array sh e)
