----------------------------------------------------------------------------- -- | -- Copyright : (C) 2015, 2016 Dimitri Sabadie -- License : BSD3 -- -- Maintainer : Dimitri Sabadie <dimitri.sabadie@gmail.com> -- Stability : experimental -- Portability : portable -- -- = What are buffers? -- -- Buffers are like /GPU/ static arrays. They have a fixed size and a given -- type. But there’s more. A GPU buffer is more like an address on GPU and a -- size in raw machine units. By definition it’s then untyped continuous -- memory. For type safety, we expose them as typed arrays on steroids. -- -- = Creating buffers -- -- You can create buffers with the 'createBuffer' function: -- -- @ -- buf <- createBuffer (newRegion 10) -- @ -- -- The type of @buf@ is ambiguous in that case though because 'Buffer' is a -- very permissive type. You’ll almost always need to provide the type -- because one type parameter cannot be resolved by type inference: the -- buffer access type (read, write, read/write). However, you can store the -- buffer in a @data@ of your own so that you don’t have to explicitely give -- the type to the 'createBuffer' function. -- -- @ -- buf2 :: Buffer RW Int32 <- createBuffer (newRegion 10) -- @ -- -- Here, @buf2@ has type @'Buffer' 'RW' 'Int32'@ and can hold 10 'Int32'. -- -- @ -- data Foo = Foo { fooBuffer :: Buffer RW Float } -- -- foo <- fmap Foo $ createBuffer (newRegion 5) -- @ -- -- Here, you can see that we don’t need to provide the type anymore, because -- of type inference. Make sure to understand how the type system works so -- that you understand all those three examples. -- -- == A buffer is more than a typed array on GPU -- -- The cool stuff about 'Buffer' is that it doesn’t really represent a typed -- array on GPU. It represents a typed slice of an untyped continuous memory -- area on GPU! That means you can have several slices in the same continuous -- area with different types! -- -- @ -- data Slices = Slices { -- floats :: Buffer RW Float -- , ints :: Buffer RW Int32 -- } -- -- slices <- createBuffer $ -- Slices <$> newRegion 100 <*> newRegion 8 -- @ -- -- Here, we’ve just asked the GPU to allocate a continuous memory area to -- store two slices in there: 100 'Float' followed by 8 'Int32'. And we have -- @floats slices :: Buffer RW Float@ and @ints slices :: Buffer RW Int32@. -- Pretty simple, see? -- -- == More about the 'BuildBuffer' type -- -- 'BuildBuffer' is a type used to map the number of elements in the buffers -- you ask for into the number of bytes the GPU will actually need to allocate -- all of them. 'newRegion' is the function to ask for the creation of a new -- buffer in the continuous memory you’re building up! -- -- = I/O with buffers -- -- Buffers are used to customize and add information to your renderer. They -- have plenty of uses and in all cases you’ll need two kind of operations: -- -- * writes ; -- * reads. -- -- == Writing to buffers -- -- Once you have a 'Buffer', you can write values to it if it supports -- /write access/. Use 'W' or 'RW' as buffer access to enable writing to it. -- -- === Filling -- -- The moste simple operation on 'Buffer's is to clean all its memory to a -- certain value. That is done with the 'fill' function: -- -- @ -- buf :: Buffer W Float <- createBuffer (newBuffer 10) -- -- fill buf pi -- @ -- -- Here we’ll fill @buf@ with @pi@. Typical use is to fill it with zeros. -- -- === Writing the whole buffer -- -- You can fill the buffer with a different value for each index with the -- 'writeWhole' function. That function takes a 'Foldable' value and writes -- its content to the buffer. Typical use is to pass a list of values. -- -- @ -- buf :: Buffer W Float <- createBuffer (newBuffer 4) -- -- writeWhole buf [7, 3, -234, 34] -- @ -- -- Check 'writeWhole' documentation for further details on special cases. -- -- === Indexed write -- -- You can write a single element in a buffer by providing an index like you -- do with regular arrays: -- -- @ -- buf :: Buffer W Float <- createBuffer (newBuffer 10) -- -- writeAt buf 3 pi -- writeAt' buf 5 100 -- @ -- -- 'writeAt' is used to write a value at a given index in the buffer. -- 'writeAt'' is the unsafe version of 'writeAt'. -- -- == Reading from buffers -- -- You can read from a 'Buffer' if it supports /read access/. Use 'R' or 'RW' -- as buffer access to enable reads. -- -- === Reading the whole buffer -- -- You can retrieve all the elements in a buffer via the 'readWhole' function: -- -- @ -- buf :: Buffer R Float <- createBuffer (newBuffer 10) -- -- readWhole buf >>= print -- will print out the content as a @[Float]@ -- @ -- -- === Indexed read -- -- You can read a single element in a buffer by providing an index: -- -- @ -- buf :: Buffer R Float <- createBuffer (newBuffer 10) -- -- buf @? 8 >>= traverse_ print -- print the value only if it’s not out out bounds -- buf @! 5 >>= traverse_ print -- unsafe version -- @ -- -- The '(@?)' operator is the indexed read operator for 'Buffer' and '(@!)' -- is its unsafe version. ----------------------------------------------------------------------------- module Graphics.Luminance.Buffer ( -- * Buffer creation createBuffer -- * Buffer access , BufferRW -- * Buffer regions , Buffer , BuildBuffer , newRegion -- * Operations on buffer regions , readWhole , writeWhole , fill , (@?) , (@!) , writeAt , writeAt' ) where import Graphics.Luminance.Core.Buffer