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


-- | Haskell binding to the Cal3D animation library.
--   
--   Haskell binding to the Cal3D, a skeletal-based animation library
--   written in C++. See also the related packages cal3d-opengl and
--   cal3d-examples.
@package cal3d
@version 0.1

module Graphics.Animation.Cal3D.Error
type Fallible a = Either String a
type IOFallible a = IO (Fallible a)

-- | Compares the result of an action with a bad value, such as an error
--   code, returns (Left errormessage) if action value == bad, otherwise
--   (Right actionresult)
checkErrorValue :: (Eq a) => IO a -> a -> String -> IO (Either String a)

-- | Like checkError, but returns (Right ()) instead of an interesting
--   value.
checkError :: (Eq a) => IO a -> a -> String -> IO (Either String ())


-- | Most (possibly all) data type declarations are collected here, in
--   order to avoid mutually recursive modules, like where module Model
--   needs data <a>Mixer</a> from module Mixer, and module Mixer needs data
--   <a>Model</a> from module Model.
module Graphics.Animation.Cal3D.Types

-- | A CoreModel is a type which may have multiple instances
--   (<a>Model</a>s). See <a>Graphics.Animation.Cal3D.Model</a>.
data CoreModel

-- | LoadResult is (Left error_message) or (Right thing_loaded_from_file)
type LoadResult a = IO (Either String a)

-- | A function that loads something from a file.
type Loader a = CoreModel -> FilePath -> LoadResult a
type CLoader = CoreModel -> CString -> IO CInt

-- | Identifies an animation.
newtype AnimationId
AnimationId :: CInt -> AnimationId

-- | Identifies a mesh.
newtype MeshId
MeshId :: CInt -> MeshId

-- | Identifies a material.
newtype MaterialId
MaterialId :: CInt -> MaterialId

-- | Identifies a material thread.
data MaterialThreadId
MaterialThreadId :: Int -> MaterialThreadId

-- | Identifies a material set.
data MaterialSetId
MaterialSetId :: Int -> MaterialSetId

-- | A Model is an "instance" of a <a>CoreModel</a>. See
--   <a>Graphics.Animation.Cal3D.Model</a>.
data Model

-- | A Mixer can blend simultaneous animations and play them. See
--   <a>Graphics.Animation.Cal3D.Mixer</a>.
data Mixer

-- | A Renderer provides data needed for graphics rendering. Cal3D does no
--   rendering itself; the Renderer simply provides the needed information
--   for a graphics API such as OpenGL. See
--   <a>Graphics.Animation.Cal3D.Renderer</a>; also see the cal3d-opengl
--   package.
data Renderer
instance Show MeshId
instance Eq MeshId


-- | A Renderer provides information needed for graphics rendering; it does
--   not output any graphics by itself, but needs the cooperation of a
--   graphics API. Consider using Graphics.Animation.Cal3D.OpenGL from the
--   cal3d-opengl package.
module Graphics.Animation.Cal3D.Renderer

-- | Create a Renderer.
newRenderer :: Model -> IO Renderer

-- | Destroy a Renderer.
deleteRenderer :: Renderer -> IO ()

-- | Executes a rendering action.
--   
--   <pre>
--   renderAnimation renderer action
--   </pre>
--   
--   corresponds to
--   
--   <pre>
--   renderer-&gt;beginRendering();
--   action();
--   renderer-&gt;endRendering();
--   </pre>
--   
--   in the Cal3D C++ API.
renderAnimation :: Renderer -> IO () -> IO (Either String ())

-- | The number of meshes in the Renderer's <a>Model</a>.
getMeshCount :: Renderer -> IO Int

-- | The number of submeshes in the given mesh of the Renderer's
--   <a>Model</a>.
getSubmeshCount :: Renderer -> Int -> IO Int

-- | Selects a particular (mesh, submesh) so that all subsequent operations
--   refer to this (mesh, submesh) pair.
selectMeshSubmesh :: Renderer -> Int -> Int -> IO (Either String ())

-- | Used to index faces.
type CalIndex = CInt

-- | The number of faces in the current (mesh, submesh).
getFaceCount :: Renderer -> IO Int

-- | Fills a buffer with the face numbers.
getFaces :: Renderer -> Ptr CalIndex -> IO Int

-- | Calls an action with a pointer to the ambient color data. The color
--   data are four bytes (red, green, blue, alpha). If you are using
--   OpenGL, use Graphics.Animation.Cal3D.OpenGL.getAmbientColor instead.
--   You almost certainly don't want to use <tt>withAmbientColorPtr</tt>
--   directly, unless your are connecting Cal3D to a different graphics
--   API.
withAmbientColorPtr :: (Storable c) => (Ptr Word8 -> IO c) -> Renderer -> IO c

-- | Diffuse color, like <a>withAmbientColorPtr</a>.
withDiffuseColorPtr :: (Storable c) => (Ptr Word8 -> IO c) -> Renderer -> IO c

-- | Specular color, like <a>withAmbientColorPtr</a>.
withSpecularColorPtr :: (Storable c) => (Ptr Word8 -> IO c) -> Renderer -> IO c

-- | The shininess, which affects the extent of speculr effects.
getShininess :: Renderer -> IO Float

-- | The number of vertices, also the number of normals, in the current
--   (mesh, submesh).
getVertexCount :: Renderer -> IO Int

-- | Fills a buffer with the vertex data of the current (mesh, submesh).
getVertices :: Renderer -> Ptr Float -> Int -> IO Int

-- | Fills a buffer with the normal data for the current (mesh, submesh).
getNormals :: Renderer -> Ptr Float -> Int -> IO Int

module Graphics.Animation.Cal3D.Mixer

-- | Create a Mixer.
newMixer :: IO Mixer

-- | Destroy a Mixer.
deleteMixer :: Mixer -> IO ()

-- | Add an animation to be <a>cycled</a> (repeated) to the current mix.
--   The animation will continue playing until removed by
--   <a>clearCycle</a>.
blendCycle :: Mixer -> AnimationId -> Float -> Float -> IO (Either String ())

-- | Remove a <a>cycled</a> animation from the current mix.
clearCycle :: Mixer -> AnimationId -> Float -> IO (Either String ())

-- | Execute an animation once, instead of repeating it.
executeAction :: Mixer -> AnimationId -> Float -> Float -> Float -> Bool -> IO (Either String ())


-- | A <a>CoreModel</a> is a model type from which many instance
--   <a>Model</a>s can be created. For example, there could be a clown
--   CoreModel and many individual clown instances. The CoreModel contains
--   data shared by its instances:
--   
--   <ul>
--   <li>A single skeleton</li>
--   <li>One or more meshes, represented by <a>MeshId</a>s</li>
--   <li>One or more animations, represented by <a>AnimationId</a>s</li>
--   <li>One or more materials, represented by <a>MaterialId</a>s</li>
--   </ul>
--   
--   Each of these may be loaded from a file by the appropriate loader
--   function, for example, <a>loadCoreSkeleton</a>.
--   
--   Materials of the CoreModel are organized by <a>sets</a> and
--   <a>threads.</a> Within a material set, represented by a
--   <a>MaterialSetId</a>, all materials have the same appearance, such as
--   metal or wood. Each material thread, represented by a
--   <a>MaterialThreadId</a>, is associated with a particular part of the
--   model, such as head or arm. Changing material sets of a model
--   (instance) is a convenient way of changing the character's costume or
--   over-all look.
module Graphics.Animation.Cal3D.CoreModel

-- | Create a CoreModel
newCoreModel :: String -> IO CoreModel

-- | Destroy a CoreModel
deleteCoreModel :: CoreModel -> IO ()

-- | Load a core skeleton from a file.
loadCoreSkeleton :: CoreModel -> FilePath -> LoadResult ()

-- | Load a core animation from a file
loadCoreAnimation :: Loader AnimationId

-- | Load a core mesh from a file
loadCoreMesh :: Loader MeshId

-- | Load a core material from a file
loadCoreMaterial :: Loader MaterialId

-- | Create a core material thread.
createCoreMaterialThread :: CoreModel -> MaterialThreadId -> IO (Either String ())

-- | Apply the material identified by a material thread and material set.
setCoreMaterialId :: CoreModel -> MaterialThreadId -> MaterialSetId -> MaterialId -> IO (Either String ())

module Graphics.Animation.Cal3D.Model

-- | Create a new Model instance from a CoreModel.
newModel :: CoreModel -> IO Model

-- | Destroy a Model.
deleteModel :: Model -> IO ()

-- | Attach a mesh to a Model.
attachMesh :: Model -> MeshId -> IO (Either String ())

-- | Set the level of detail for a Model (between 0 and 1).
setLodLevel :: Model -> Float -> IO ()

-- | Apply a material set to a Model.
setMaterialSet :: Model -> MaterialSetId -> IO ()

-- | Get a Mixer which can animate the Model.
getMixer :: Model -> IO Mixer

-- | Let the current animations of a Model run for a specified time.
update :: Model -> Float -> IO ()

-- | Get a Renderer for the Model, which can provide information needed for
--   a graphics API.
getRenderer :: Model -> IO Renderer

module Graphics.Animation.Cal3D