-- 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.2 -- | A Camera represents a coordinate frame into which 3D points may -- be transformed. For rendering purposes, it is often helpful to combine -- a transformation matrix computed from a Camera by -- camMatrix -- that transforms points into the camera's -- coordinate frame -- with a perspective projection matrix, as created -- by projectionMatrix. module Graphics.GLUtil.Camera3D -- | A Camera may be translated and rotated to provide a coordinate -- frame into which 3D points may be transformed. data Camera a -- | Pan a camera view (turn side-to-side) by an angle given in radians. -- Panning is about the world's up-axis as captured by the initial camera -- state (e.g. the positive Y axis for fpsCamera). panRad :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Pan a camera view (turn side-to-side) by an angle given in degrees. -- Panning is about the world's up-axis as captured by the initial camera -- state (e.g. the positive Y axis for fpsCamera). pan :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Tilt a camera view (up-and-down) by an angle given in radians. Tilting -- is about the camera's horizontal axis (e.g. the positive X axis for -- fpsCamera). tiltRad :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Tilt a camera view (up-and-down) by an angle given in degrees. Tilting -- is about the camera's horizontal axis (e.g. the positive X axis for -- fpsCamera). tilt :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Roll a camera view about its view direction by an angle given in -- radians. Rolling is about the camera's forward axis (e.g. the negative -- Z axis for fpsCamera). rollRad :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Roll a camera view about its view direction by an angle given in -- degrees. Rolling is about the camera's forward axis (e.g. the negative -- Z axis for fpsCamera). roll :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Translate a camera's position by the given vector. dolly :: (Conjugate a, Epsilon a, RealFloat a) => V3 a -> Camera a -> Camera a -- | A camera at the origin with its up-axis coincident with the positive Z -- axis. This is the convention used by the ROS robotics platform. rosCamera :: (Epsilon a, RealFloat a) => Camera a -- | A camera at the origin with its up-axis coincident with the positive Y -- axis. This is the convention used by first-person shooter (fps) -- video games. fpsCamera :: (Epsilon a, RealFloat a) => Camera a -- | projectionMatrix fov aspect near far produces a perspective -- projection matrix with the specified vertical field of view (FOV), -- given in radians, aspect ratio, and near and far clipping planes. projectionMatrix :: (Conjugate a, Epsilon a, RealFloat a) => a -> a -> a -> a -> M44 a -- | Produce a transformation matrix from a Camera. This matrix -- transforms homogenous points into the camera's coordinate frame. camMatrix :: (Conjugate a, Epsilon a, RealFloat a) => Camera a -> M44 a -- | Convert degrees to radians. deg2rad :: RealFloat a => a -> a -- | A camera designed for 2D viewing. The camera may be translated -- perpendicular to its view direction, or rolled about its view -- direction. module Graphics.GLUtil.Camera2D -- | A Camera may be translated and rotated to provide a coordinate -- frame into which 3D points may be transformed. data Camera a -- | Move the camera side-to-side or up-and-down as in a tracking shot. track :: (Conjugate a, Epsilon a, RealFloat a) => V2 a -> Camera a -> Camera a -- | Roll a camera view about its view direction by an angle given in -- degrees. roll :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Roll a camera view about its view direction by an angle given in -- radians. rollRad :: (Epsilon a, RealFloat a) => a -> Camera a -> Camera a -- | Initialize a camera for 2D rendering. camera2D :: (Epsilon a, RealFloat a) => Camera a -- | Produce a matrix that transforms homogenous 2D points into the -- camera's coordinate frame. camMatrix :: (Conjugate a, Epsilon a, RealFloat a) => Camera a -> M33 a -- | Convert degrees to radians. deg2rad :: RealFloat a => a -> a -- | Helpers for working with OpenGL viewports. module Graphics.GLUtil.Viewport -- | withViewport pos sz m runs the action m after -- setting the viewport with the given Position and Size. -- The viewport is reset to its original state after the action is run, -- and the result of the action is returned. withViewport :: Position -> Size -> IO a -> IO a -- | Support for writing Linear 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 -- | A mapping from Haskell types to values of VariableType. This -- defines how Haskell values may be mapped to values that may be bound -- to GLSL variables. class HasVariableType a variableType :: HasVariableType a => a -> VariableType -- | Maps each VariableType to its corresponding DataType. -- Typically this indicates the element type of composite variable types -- (e.g. variableDataType FloatVec2 = Float). 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 VertexArrayObject, 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 VertexArrayObject bound. withVAO :: VertexArrayObject -> IO r -> IO r -- | Short alias for VertexArrayObject. type VAO = VertexArrayObject -- | Miscellaneous utilities for dealing with OpenGL errors. module Graphics.GLUtil.GLError -- | Check OpenGL error flags and print them on stderr. printError :: IO () -- | Check OpenGL error flags and print them on stderr 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 String. 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 TexInfo using Haskell Ints 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 IsPixelData instance treats the pointer -- underlying a ByteString as an array of Word16s. newtype ShortString ShortString :: ByteString -> ShortString -- | Create a new 2D texture with data from a TexInfo. loadTexture :: IsPixelData a => TexInfo a -> IO TextureObject -- | Replace a 2D texture's pixel data with data from a TexInfo. reloadTexture :: IsPixelData a => TextureObject -> TexInfo a -> IO () -- | Set texture coordinate wrapping options for both the S and -- T dimensions of a 2D texture. texture2DWrap :: StateVar (Repetition, Clamping) -- | Set texture coordinate wrapping options for the S, T, -- and R dimensions of a 3D texture. texture3DWrap :: StateVar (Repetition, Clamping) -- | Bind each of the given textures to successive texture units at the -- given TextureTarget. 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] -- | Uses the JuicyPixels package to load images that are then -- used to create OpenGL textuers. module Graphics.GLUtil.JuicyTextures -- | Load a TexInfo value from an image file, and supply it to a -- user-provided function. Supported image formats include png, -- jpeg, bmp, and gif. See readTexture -- for most uses. readTexInfo :: FilePath -> (forall a. IsPixelData a => TexInfo a -> IO b) -> IO (Either String b) -- | Load a TextureObject from an image file. Supported formats -- include png, jpeg, bmp, and gif. 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 Program. linkShaderProgram :: [VertexShader] -> [FragmentShader] -> IO Program -- | Link vertex and fragment shaders into a Program. The supplied -- IO action is run after attaching shader objects to the new -- program, but before linking. This supports the use of -- bindFragDataLocation to map fragment shader outputs. linkShaderProgramWith :: [VertexShader] -> [FragmentShader] -> (Program -> IO ()) -> IO Program -- | Link vertex, geometry, and fragment shaders into a Program. linkGeoProgram :: [VertexShader] -> [GeometryShader] -> [FragmentShader] -> IO Program -- | Link vertex, geometry, and fragment shaders into a Program. The -- supplied IO action is run after attaching shader objects to the -- new program, but before linking. This supports the use of -- bindFragDataLocation 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 -- UniformLocation. namedUniform :: Uniform a => String -> StateVar a -- | Set a UniformLocation to a scalar value. uniformScalar :: UniformComponent a => UniformLocation -> SettableStateVar a -- | Set a UniformLocation from a list representation of a -- low-dimensional vector of GLfloats. 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 GLmatrix. 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 ShaderProgram 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 ShaderProgram. loadShaderProgram :: FilePath -> FilePath -> IO ShaderProgram -- | Load a ShaderProgram 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 ShaderProgram. The supplied -- IO function is applied to the new program after shader objects -- are attached to the program, but before linking. This supports the use -- of bindFragDataLocation to map fragment shader outputs. loadShaderProgramWith :: FilePath -> FilePath -> (Program -> IO ()) -> IO ShaderProgram -- | Load a ShaderProgram 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 ShaderProgram. loadGeoProgram :: FilePath -> FilePath -> FilePath -> IO ShaderProgram -- | Load a ShaderProgram 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 ShaderProgram. The supplied IO function is applied -- to the new program after shader objects are attached to the program, -- but before linking. This supports the use of -- bindFragDataLocation to map fragment shader outputs. loadGeoProgramWith :: FilePath -> FilePath -> FilePath -> (Program -> IO ()) -> IO ShaderProgram -- | Load a ShaderProgram 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 loadShaderProgram. loadShaderExplicit :: FilePath -> FilePath -> ([String], [String]) -> IO ShaderProgram -- | Get the AttribLocation associated with a named vertex -- attribute. getAttrib :: ShaderProgram -> String -> AttribLocation -- | Enable a named vertex attribute. enableAttrib :: ShaderProgram -> String -> IO () -- | Set a named vertex attribute's IntegerHandling and -- VertexArrayDescriptor. setAttrib :: ShaderProgram -> String -> IntegerHandling -> VertexArrayDescriptor a -> IO () -- | Set a named uniform parameter associated with a particular shader -- program. setUniform :: Uniform a => ShaderProgram -> String -> a -> IO () -- | Get the UniformLocation associated with a named uniform -- parameter. getUniform :: ShaderProgram -> String -> UniformLocation -- | Simplify common drawing commands. module Graphics.GLUtil.Drawing -- | drawIndexedTris n draws n Triangles using -- vertex data from the currently bound ArrayBuffer and indices -- from the beginning of the currently bound ElementArrayBuffer. -- Note that there must be at least n * 3 indices in the -- ElementArrayBuffer! drawIndexedTris :: GLsizei -> IO () -- | Utilities for filling BufferObjects. module Graphics.GLUtil.BufferObjects -- | Allocate and fill a BufferObject from a list of -- Storables. makeBuffer :: Storable a => BufferTarget -> [a] -> IO BufferObject -- | Allocate and fill a BufferObject from a list of -- Storables 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 -- | replaceBuffer target elements replaces the buffer data -- attached to the buffer object currently bound to target with -- the supplied list. Any previous data is deleted. replaceBuffer :: Storable a => BufferTarget -> [a] -> IO () -- | Allocate and fill a BufferObject with the given number of bytes -- from the supplied pointer. fromPtr :: BufferTarget -> Int -> Ptr a -> IO BufferObject -- | Fill a buffer with a ByteString. fromByteString :: BufferTarget -> ByteString -> IO BufferObject -- | Fill a buffer with data from a ForeignPtr. The application -- fromForeignPtr target len fptr fills a target -- BufferTarget with len elements starting from -- fptr. fromForeignPtr :: Storable a => BufferTarget -> Int -> ForeignPtr a -> IO BufferObject -- | Fill a buffer with data from a Vector. fromVector :: Storable a => BufferTarget -> Vector a -> IO BufferObject -- | replaceVector target v replaces the buffer data attached to -- the buffer object currently bound to target with the supplied -- Vector. Any previous data is deleted. replaceVector :: Storable a => BufferTarget -> Vector a -> IO () -- | Produce a Ptr value to be used as an offset of the given number -- of bytes. offsetPtr :: Int -> Ptr a -- | A zero-offset Ptr. offset0 :: Ptr a -- | A class for things we know how to serialize into an OpenGL buffer. class BufferSource v fromSource :: BufferSource v => BufferTarget -> v -> IO BufferObject -- | Create an ElementArrayBuffer from a source of Word32s. bufferIndices :: BufferSource (v Word32) => v Word32 -> IO BufferObject instance Storable a => BufferSource (Vector a) instance Storable a => BufferSource [a] -- | The main import that simply re-exports the various modules that make -- up the GLUtil library. module Graphics.GLUtil -- | Load a TextureObject from an image file. Supported formats -- include png, jpeg, bmp, and gif. readTexture :: FilePath -> IO (Either String TextureObject)