HGamer3D-API 0.1.1 → 0.1.2

raw patch · 2 files changed

+120/−20 lines, 2 files

Files

• HGamer3D-API.cabal +1/−1
• HGamer3D/APIs/One.hs +119/−19

@@ -1,5 +1,5 @@ Name:                HGamer3D-API
-Version:             0.1.1
+Version:             0.1.2
 Synopsis:            Library to enable 3D game development for Haskell - API
 Description:         
 	Library, to enable 3D game development for Haskell,

@@ -18,8 +18,16 @@ 
 -- One.hs
 
--- This module provides a simple, generic API into the HGamer3D functionality.
-
+-- |This module is the first attempt, to provide an abstracted interface
+-- to the HGamer3D API Bindings. It is named 'One' on purpose, since it is
+-- assumed, that there will be additional APIs in the future, which then 
+-- might be named 'APIs.Two', 'APIs.Three' and so on. Also note the plural
+-- in 'APIs'!
+--
+-- It should be possible, to write 3D applications, by using the API of 
+-- this module alone. Anyhow, to enable a mixture also with the code
+-- of the underlying bindings, the constructors of the data types are made
+-- public.
 module HGamer3D.APIs.One
 
 (
@@ -55,6 +63,7 @@ 	--------
 	
 	module HGamer3D.Bindings.OIS.EnumKeyCode,
+	module HGamer3D.Bindings.Ogre.EnumTransformSpace,
 	
 	-- Functions
 	------------
@@ -77,6 +86,13 @@ 
 
 	-- Graphics Object Functions
+	scale,
+	translate,
+	roll,
+	pitch,
+	yaw,
+	rotate,
+	
 	getPosition,
 	setPosition,
 	getOrientation,
@@ -125,6 +141,7 @@ import HGamer3D.Bindings.Ogre.TypeVector3
 
 import HGamer3D.Bindings.Ogre.EnumSceneType
+import HGamer3D.Bindings.Ogre.EnumTransformSpace
 
 import HGamer3D.Bindings.Ogre.ClassCamera
 import HGamer3D.Bindings.Ogre.ClassRoot
@@ -167,21 +184,21 @@ ---
 
 
--- Input System
+-- |The encapsulation of the state of input devices, like keyboard, mouse, ...
 data InputSystem = InputSystem {
-	isMouse::HG3DClass,
+	isMouse::HG3DClass, 
 	isKeyboard::HG3DClass,
 	isInputManager::HG3DClass
 } deriving (Show, Eq)
 
--- View System
+-- |The encapsulation of the state of the view, camera, window and viewport
 data ViewSystem = ViewSystem {
 	vsCamera::HG3DClass,
 	vsRenderWindow::HG3DClass,
 	vsViewport::HG3DClass
 } deriving (Show, Eq)
 
--- Engine System
+-- |The encapsulation of the state of the graphics engine
 data EngineSystem = EngineSystem {
 	esRoot::HG3DClass,
 	esSceneManager::HG3DClass,
@@ -192,21 +209,38 @@ 
 
 -- common 3D objects, internal data objects (to get typesafety, later to be done with typed pointers)
+
+-- | Encapsulation of a Light Object
 data Light = Light HG3DClass
-data Object = ManualObject HG3DClass | Mesh HG3DClass
+-- | An Object is a basic graphical structure, without connection to a position
+data Object = ManualObject HG3DClass -- ^The Ogre ManualObject, which is an Object, drawn by single statements
+			  | Mesh HG3DClass -- ^A 3D Mesh
+			  
+-- | A Node gives position, rotation and connection to other nodes and child parent relationships
+-- this is a Ogre abstration, which is used in the One API, to generate the 'GraphicsObject' below
 data Node = Node HG3DClass
+
+-- | The time as abstracted type, to recognize it in the api
 data Time = Time Float
+
+-- | An Animation, the encapsulation of simple types has the usual reason, to
+-- get a better type checking in the API
 data Animation = Animation HG3DClass
 
--- common 3D Objects
+-- | The graphics object
 data GraphicsObject = GraphicsObject Object Node | LightObject Light | CombinedObject Node
 
 --
 
 
 -- basic initialize function
---
-initializeHG3D :: String -> String -> IO (EngineSystem, ViewSystem, InputSystem)
+
+-- | With this function, the graphics system is being initialized. The return 
+-- value consists of the three state types, which carry the state for 
+-- the graphics engine, the input system and the view
+initializeHG3D :: String -- ^Name of the window, displayed
+			-> String  -- ^SceneManager type used
+			-> IO (EngineSystem, ViewSystem, InputSystem)
 initializeHG3D windowName sceneManagerType = do
 
 		root <- cRNew
@@ -249,10 +283,12 @@ 
 -- camera functions
 
+-- |Postions the camera
 setCameraPos :: ViewSystem -> Vector3 -> IO ()
 setCameraPos vs pos = do
 	cCSetPosition2 (vsCamera vs)  pos
 
+-- |Sets the camera view direction
 setCameraLookAt :: ViewSystem -> Vector3 -> IO ()
 setCameraLookAt vs vec3 = do
 	cCLookAt (vsCamera vs) vec3
@@ -260,13 +296,17 @@ 
 -- light functions
 
+-- | creates a light, which fills all the room with similar strength
 createAmbientLight :: EngineSystem -> ColourValue -> IO () 
 createAmbientLight es colour = do
 	cSmSetAmbientLight (esSceneManager es) colour
 	return ()
 	
-	
-createLight :: EngineSystem -> String -> ColourValue -> Vector3 -> IO (GraphicsObject) 
+-- | creates a point light at a specific location
+createLight :: EngineSystem -> String -- ^Name of the light
+		-> ColourValue -- ^Color of the light
+		-> Vector3 -- ^Position, where light is created
+		-> IO (GraphicsObject) -- ^Return value is a graphics object
 createLight es lightName colour (Vector3 x y z) = do
 	cSmSetAmbientLight (esSceneManager es) colour
 	light <- cSmCreateLight (esSceneManager es) lightName
@@ -305,7 +345,14 @@ 
 -- use "BaseWhiteNoLighting" Material
 
-createLine :: EngineSystem -> String -> String -> ColourValue -> Vector3 -> Vector3 -> IO (GraphicsObject)
+-- |Creates a line by using the ManualObject functionality of Ogre
+createLine :: EngineSystem -- ^The engine system
+		-> String -- ^The name of the line object
+		-> String -- ^The material used for the line
+		-> ColourValue -- ^The color of the line
+		-> Vector3 -- ^The start point of the line
+		-> Vector3 -- ^The end point of the line
+		-> IO (GraphicsObject) -- ^Return value is a graphics object
 createLine es lineName materialName colour vStart vEnd = do
 	mo <- cSmCreateManualObject (esSceneManager es) lineName
 	cMnoBegin mo materialName OtLineList "General"
@@ -318,8 +365,14 @@ 	go <- getGraphicsObject es (ManualObject mo)
 	return (go)
 
-
-createCube :: EngineSystem -> String -> String -> ColourValue -> Vector3 -> IO (GraphicsObject)
+-- |Creates a cube by using the ManualObject functionality of Ogre
+createCube :: EngineSystem -- ^The engine system 
+		-> String -- ^The name of the cube object 
+		-> String -- ^The material used for the cube 
+		-> ColourValue -- ^The color of the line 
+		-> Vector3 -- ^The initial position, where the cube is created
+				   -- it is measured to the center of the cube
+		-> IO (GraphicsObject) -- ^Return value is a graphics object
 createCube es cubeName materialName colour pos = do
 	mo <- cSmCreateManualObject (esSceneManager es) cubeName
 	-- set Dynamic to false
@@ -371,8 +424,11 @@ 	setPosition go pos
 	return (go)
 
-
-createMesh :: EngineSystem -> String -> String -> IO (GraphicsObject)
+-- |This function creates a graphics object, by loading a mesh
+createMesh :: EngineSystem -- ^The engine system
+		-> String -- ^The name of the created mesh object
+		-> String -- ^The filename of the mesh, from the resources
+		-> IO (GraphicsObject) -- ^Return value is a graphics object
 createMesh es meshName meshFile = do
 
 	entity <- cSmCreateEntity (esSceneManager es) meshName meshFile "General"
@@ -380,8 +436,12 @@ 	return (go)
 	
 
--- combine objects into new one
-combineGraphicsObjects :: EngineSystem -> [GraphicsObject] -> IO (GraphicsObject)
+-- |This function groups objects into a new object
+-- it is not perfoming any geometric operations, it just groups the 
+-- input objects. Can be used, to move and rotate a group.
+combineGraphicsObjects :: EngineSystem -- ^The engine system
+		-> [GraphicsObject] -- ^A list of objects, to be grouped
+		-> IO (GraphicsObject) -- ^The return value is a new GraphicsObject
 combineGraphicsObjects es listObjects = do
 
 	node <- getNewNode es
@@ -402,6 +462,46 @@ --
 -- GraphicsObject functions
 --
+
+--	scale
+
+-- |Scales a GraphicsObject by multiplying a scale to the existing one
+scale :: GraphicsObject -> Vector3 -> IO ()
+scale go sc  = do
+	cNScale (getNodeFromGraphicsObject go) sc
+	return () 
+
+--	| Translate a GraphicsObject from its current position
+translate :: GraphicsObject -> Vector3 -> EnumTransformSpace -> IO ()
+translate go v ets = do
+	cNTranslate (getNodeFromGraphicsObject go) v ets
+	return () 
+
+--	roll
+roll :: GraphicsObject -> Radian -> EnumTransformSpace -> IO ()
+roll go r ets = do
+	cNRoll (getNodeFromGraphicsObject go) r ets
+	return () 
+
+--	pitch
+pitch :: GraphicsObject -> Radian -> EnumTransformSpace -> IO ()
+pitch go r ets = do
+	cNPitch (getNodeFromGraphicsObject go) r ets
+	return () 
+
+--	yaw
+yaw :: GraphicsObject -> Radian -> EnumTransformSpace -> IO ()
+yaw go r ets = do
+	cNYaw (getNodeFromGraphicsObject go) r ets
+	return () 
+
+--	rotate
+rotate :: GraphicsObject -> Vector3 -> Radian -> EnumTransformSpace -> IO ()
+rotate go v r ets = do
+	cNRotate (getNodeFromGraphicsObject go) v r ets
+	return () 
+
+	
 
 getPosition :: GraphicsObject -> IO (Vector3)
 getPosition go = do