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


-- | Miscellaneous OpenGL utilities.
--   
--   Helpers for working with shaders, buffer objects, and textures in
--   OpenGL.
@package GLUtil
@version 0.6.1

module Graphics.GLUtil.Viewport
withViewport :: Position -> Size -> IO a -> IO a


-- | Support for writing <a>Linear</a> types to uniform locations in shader
--   programs.
module Graphics.GLUtil.Linear

-- | A type class for things we can write to uniform locations in shader
--   programs.
class AsUniform t
asUniform :: AsUniform t => t -> UniformLocation -> IO ()
instance AsUniform [V4 GLfloat]
instance AsUniform [V4 GLuint]
instance AsUniform [V4 GLint]
instance AsUniform [V3 GLfloat]
instance AsUniform [V3 GLuint]
instance AsUniform [V3 GLint]
instance AsUniform [V2 GLfloat]
instance AsUniform [V2 GLuint]
instance AsUniform [V2 GLint]
instance AsUniform (M44 GLfloat)
instance AsUniform (M33 GLfloat)
instance AsUniform (M22 GLfloat)
instance AsUniform (V4 GLfloat)
instance AsUniform (V4 GLuint)
instance AsUniform (V4 GLint)
instance AsUniform (V3 GLfloat)
instance AsUniform (V3 GLuint)
instance AsUniform (V3 GLint)
instance AsUniform (V2 GLfloat)
instance AsUniform (V2 GLuint)
instance AsUniform (V2 GLint)
instance AsUniform GLfloat
instance AsUniform GLuint
instance AsUniform GLint


-- | This module contains classes and functions to relate Haskell types
--   with OpenGL DataTypes (typically used to describe the values stored in
--   arrays) and VariableTypes (used as attributes and uniforms in GLSL
--   programs).
module Graphics.GLUtil.TypeMapping
class HasVariableType a
variableType :: HasVariableType a => a -> VariableType

-- | Maps each <a>VariableType</a> to its corresponding <a>DataType</a>.
--   Typically this indicates the element type of composite variable types
--   (e.g. <tt>variableDataType FloatVec2 = Float</tt>). Note that this is
--   a partial mapping as we are primarily supporting the use of these
--   types as inputs to GLSL programs where types such as Bool are not
--   supported.
variableDataType :: VariableType -> DataType

-- | Open mapping from Haskell types to OpenGL types.
class Storable a => HasGLType a
glType :: HasGLType a => a -> DataType
instance HasGLType GLfloat
instance HasGLType Float
instance HasGLType GLuint
instance HasGLType Word32
instance HasGLType Word16
instance HasGLType Word8
instance HasGLType GLint
instance HasGLType Int
instance HasVariableType (M44 GLfloat)
instance HasVariableType (M33 GLfloat)
instance HasVariableType (M22 GLfloat)
instance HasVariableType (V4 GLuint)
instance HasVariableType (V3 GLuint)
instance HasVariableType (V2 GLuint)
instance HasVariableType (V4 Word32)
instance HasVariableType (V3 Word32)
instance HasVariableType (V2 Word32)
instance HasVariableType (V4 Int32)
instance HasVariableType (V3 Int32)
instance HasVariableType (V2 Int32)
instance HasVariableType (V4 GLint)
instance HasVariableType (V3 GLint)
instance HasVariableType (V2 GLint)
instance HasVariableType (V4 GLfloat)
instance HasVariableType (V3 GLfloat)
instance HasVariableType (V2 GLfloat)
instance HasVariableType GLuint
instance HasVariableType Word32
instance HasVariableType Int32
instance HasVariableType GLint
instance HasVariableType GLfloat
instance HasVariableType Float


-- | A thin layer over OpenGL 3.1+ vertex array objects.
module Graphics.GLUtil.VertexArrayObjects

-- | Allocate a <a>VertexArrayObject</a>, and initialize it with the
--   provided action. This action should bind the buffer data, index data
--   (if necessary), and setup vertex attributes.
makeVAO :: IO () -> IO VertexArrayObject

-- | Run an action with the given <a>VertexArrayObject</a> bound.
withVAO :: VertexArrayObject -> IO r -> IO r

-- | Short alias for <a>VertexArrayObject</a>.
type VAO = VertexArrayObject


-- | Miscellaneous utilities for dealing with OpenGL errors.
module Graphics.GLUtil.GLError

-- | Check OpenGL error flags and print them on <a>stderr</a>.
printError :: IO ()

-- | Check OpenGL error flags and print them on <a>stderr</a> with the
--   given message as a prefix. If there are no errors, nothing is printed.
printErrorMsg :: String -> IO ()

-- | Throw an exception if there is an OpenGL error.
throwError :: IO ()

-- | An exception type for OpenGL errors.
data GLError

-- | Throw an exception if there is an OpenGL error. The exception's error
--   message is prefixed with the supplied <a>String</a>.
throwErrorMsg :: String -> IO ()
instance Typeable GLError
instance Show GLError
instance Exception GLError


-- | Utilities for loading texture data.
module Graphics.GLUtil.Textures

-- | Pixel format of image data.
data TexColor
TexMono :: TexColor
TexRGB :: TexColor
TexBGR :: TexColor
TexRGBA :: TexColor

-- | A basic texture information record.
data TexInfo a
TexInfo :: GLsizei -> GLsizei -> TexColor -> a -> TexInfo a
texWidth :: TexInfo a -> GLsizei
texHeight :: TexInfo a -> GLsizei
texColor :: TexInfo a -> TexColor
texData :: TexInfo a -> a

-- | Helper for constructing a <a>TexInfo</a> using Haskell <a>Int</a>s for
--   image dimensions.
texInfo :: Int -> Int -> TexColor -> a -> TexInfo a

-- | Class for containers of texture data.
class HasGLType (Elem a) => IsPixelData a where type family Elem a
withPixels :: IsPixelData a => a -> (Ptr (Elem a) -> IO c) -> IO c

-- | Wrapper whose <a>IsPixelData</a> instance treats the pointer
--   underlying a <a>ByteString</a> as an array of <a>Word16</a>s.
newtype ShortString
ShortString :: ByteString -> ShortString

-- | Create a new 2D texture with data from a <a>TexInfo</a>.
loadTexture :: IsPixelData a => TexInfo a -> IO TextureObject

-- | Replace a 2D texture's pixel data with data from a <a>TexInfo</a>.
reloadTexture :: IsPixelData a => TextureObject -> TexInfo a -> IO ()

-- | Set texture coordinate wrapping options for both the <a>S</a> and
--   <a>T</a> dimensions of a 2D texture.
texture2DWrap :: StateVar (Repetition, Clamping)

-- | Set texture coordinate wrapping options for the <a>S</a>, <a>T</a>,
--   and <a>R</a> dimensions of a 3D texture.
texture3DWrap :: StateVar (Repetition, Clamping)

-- | Bind each of the given textures to successive texture units at the
--   given <a>TextureTarget</a>.
withTextures :: TextureTarget -> [TextureObject] -> IO a -> IO a

-- | Bind each of the given 2D textures to successive texture units.
withTextures2D :: [TextureObject] -> IO a -> IO a

-- | Generate a complete set of mipmaps for the currently bound texture
--   object.
generateMipmap' :: TextureTarget -> IO ()
instance IsPixelData ShortString
instance IsPixelData ByteString
instance HasGLType b => IsPixelData (Vector b)
instance HasGLType b => IsPixelData (StorableArray i b)
instance HasGLType b => IsPixelData (ForeignPtr b)
instance HasGLType b => IsPixelData (Ptr b)
instance HasGLType b => IsPixelData [b]

module Graphics.GLUtil.JuicyTextures
readTexInfo :: FilePath -> (forall a. IsPixelData a => TexInfo a -> IO b) -> IO (Either String b)
readTexture :: FilePath -> IO (Either String TextureObject)


-- | Utilities for working with fragment and vertex shader programs.
module Graphics.GLUtil.Shaders

-- | Load a shader program from a file.
loadShader :: Shader s => FilePath -> IO s

-- | Specialized loading for geometry shaders that are not yet fully
--   supported by the Haskell OpenGL package.
loadGeoShader :: FilePath -> IO GeometryShader

-- | Link vertex and fragment shaders into a <a>Program</a>.
linkShaderProgram :: [VertexShader] -> [FragmentShader] -> IO Program

-- | Link vertex and fragment shaders into a <a>Program</a>. The supplied
--   <a>IO</a> action is run after attaching shader objects to the new
--   program, but before linking. This supports the use of
--   <a>bindFragDataLocation</a> to map fragment shader outputs.
linkShaderProgramWith :: [VertexShader] -> [FragmentShader] -> (Program -> IO ()) -> IO Program

-- | Link vertex, geometry, and fragment shaders into a <a>Program</a>.
linkGeoProgram :: [VertexShader] -> [GeometryShader] -> [FragmentShader] -> IO Program

-- | Link vertex, geometry, and fragment shaders into a <a>Program</a>. The
--   supplied <a>IO</a> action is run after attaching shader objects to the
--   new program, but before linking. This supports the use of
--   <a>bindFragDataLocation</a> to map fragment shader outputs.
linkGeoProgramWith :: [VertexShader] -> [GeometryShader] -> [FragmentShader] -> (Program -> IO ()) -> IO Program

-- | Work with a named uniform shader parameter. Note that this looks up
--   the variable name on each access, so uniform parameters that will be
--   accessed frequently should instead be resolved to a
--   <a>UniformLocation</a>.
namedUniform :: Uniform a => String -> StateVar a

-- | Set a <a>UniformLocation</a> to a scalar value.
uniformScalar :: UniformComponent a => UniformLocation -> SettableStateVar a

-- | Set a <a>UniformLocation</a> from a list representation of a
--   low-dimensional vector of <a>GLfloat</a>s. Only 2, 3, and 4
--   dimensional vectors are supported.
uniformVec :: UniformLocation -> SettableStateVar [GLfloat]

-- | Set a uniform shader location from a nested list matrix
--   representation. Only 3x3 and 4x4 matrices are supported.
uniformMat :: UniformLocation -> SettableStateVar [[GLfloat]]

-- | Set a named uniform shader parameter from a nested list matrix
--   representation. Only 3x3 and 4x4 matrices are supported.
namedUniformMat :: String -> SettableStateVar [[GLfloat]]

-- | Set a uniform shader location with a 4x4 <a>GLmatrix</a>.
uniformGLMat4 :: UniformLocation -> SettableStateVar (GLmatrix GLfloat)
instance Eq GeometryShader
instance Ord GeometryShader
instance Show GeometryShader
instance ObjectName GeometryShader


-- | Convenience interface for working with GLSL shader programs. Provides
--   an interface for setting attributes and uniforms.
module Graphics.GLUtil.ShaderProgram

-- | Representation of a GLSL shader program that has been compiled and
--   linked.
data ShaderProgram
ShaderProgram :: Map String (AttribLocation, VariableType) -> Map String (UniformLocation, VariableType) -> Program -> ShaderProgram
attribs :: ShaderProgram -> Map String (AttribLocation, VariableType)
uniforms :: ShaderProgram -> Map String (UniformLocation, VariableType)
program :: ShaderProgram -> Program

-- | Load a <a>ShaderProgram</a> from a vertex shader source file and a
--   fragment shader source file. The active attributes and uniforms in the
--   linked program are recorded in the <a>ShaderProgram</a>.
loadShaderProgram :: FilePath -> FilePath -> IO ShaderProgram

-- | Load a <a>ShaderProgram</a> from a vertex shader source file and a
--   fragment shader source file. The active attributes and uniforms in the
--   linked program are recorded in the <a>ShaderProgram</a>. The supplied
--   <a>IO</a> function is applied to the new program after shader objects
--   are attached to the program, but before linking. This supports the use
--   of <a>bindFragDataLocation</a> to map fragment shader outputs.
loadShaderProgramWith :: FilePath -> FilePath -> (Program -> IO ()) -> IO ShaderProgram

-- | Load a <a>ShaderProgram</a> from a vertex shader source file, a
--   geometry shader source file, and a fragment shader source file. The
--   active attributes and uniforms in the linked program are recorded in
--   the <a>ShaderProgram</a>.
loadGeoProgram :: FilePath -> FilePath -> FilePath -> IO ShaderProgram

-- | Load a <a>ShaderProgram</a> from a vertex shader source file, a
--   geometry shader source file, and a fragment shader source file. The
--   active attributes and uniforms in the linked program are recorded in
--   the <a>ShaderProgram</a>. The supplied <a>IO</a> function is applied
--   to the new program after shader objects are attached to the program,
--   but before linking. This supports the use of
--   <a>bindFragDataLocation</a> to map fragment shader outputs.
loadGeoProgramWith :: FilePath -> FilePath -> FilePath -> (Program -> IO ()) -> IO ShaderProgram

-- | Load a <a>ShaderProgram</a> from a vertex and fragment shader source
--   files. the third argument is a tuple of the attribute names and
--   uniform names that will be set in this program. If all attributes and
--   uniforms are desired, consider using <a>loadShaderProgram</a>.
loadShaderExplicit :: FilePath -> FilePath -> ([String], [String]) -> IO ShaderProgram
getAttrib :: ShaderProgram -> String -> AttribLocation
enableAttrib :: ShaderProgram -> String -> IO ()
setAttrib :: ShaderProgram -> String -> IntegerHandling -> VertexArrayDescriptor a -> IO ()
setUniform :: Uniform a => ShaderProgram -> String -> a -> IO ()
getUniform :: ShaderProgram -> String -> UniformLocation


-- | Utilities for filling <a>BufferObject</a>s.
module Graphics.GLUtil.BufferObjects

-- | Allocate and fill a <a>BufferObject</a> from a list of
--   <a>Storable</a>s.
makeBuffer :: Storable a => BufferTarget -> [a] -> IO BufferObject

-- | Allocate and fill a <a>BufferObject</a> from a list of
--   <a>Storable</a>s whose length is explicitly given. This is useful when
--   the list is of known length, as it avoids a traversal to find the
--   length.
makeBufferLen :: Storable a => BufferTarget -> Int -> [a] -> IO BufferObject

-- | <tt>replaceBuffer target elements</tt> replaces the buffer data
--   attached to the buffer object currently bound to <tt>target</tt> with
--   the supplied list. Any previous data is deleted.
replaceBuffer :: Storable a => BufferTarget -> [a] -> IO ()

-- | Allocate and fill a <a>BufferObject</a> with the given number of bytes
--   from the supplied pointer.
fromPtr :: BufferTarget -> Int -> Ptr a -> IO BufferObject

-- | Fill a buffer with a <a>ByteString</a>.
fromByteString :: BufferTarget -> ByteString -> IO BufferObject

-- | Fill a buffer with data from a <a>ForeignPtr</a>. The application
--   <tt>fromForeignPtr target len fptr</tt> fills a <tt>target</tt>
--   <a>BufferTarget</a> with <tt>len</tt> elements starting from
--   <tt>fptr</tt>.
fromForeignPtr :: Storable a => BufferTarget -> Int -> ForeignPtr a -> IO BufferObject

-- | Fill a buffer with data from a <a>Vector</a>.
fromVector :: Storable a => BufferTarget -> Vector a -> IO BufferObject

-- | <tt>replaceVector target v</tt> replaces the buffer data attached to
--   the buffer object currently bound to <tt>target</tt> with the supplied
--   <a>Vector</a>. Any previous data is deleted.
replaceVector :: Storable a => BufferTarget -> Vector a -> IO ()

-- | Produce a <a>Ptr</a> value to be used as an offset of the given number
--   of bytes.
offsetPtr :: Int -> Ptr a

-- | A zero-offset <a>Ptr</a>.
offset0 :: Ptr a


-- | The main import that simply re-exports the various modules that make
--   up the <tt>GLUtil</tt> library.
module Graphics.GLUtil
readTexture :: FilePath -> IO (Either String TextureObject)