Document camera

README.md

@@ -6,10 +6,10 @@ __HUMP__ is a small collection of tools for developing games with LÖVE.
 Contents:
 ------------
 
-* *vector.lua*: powerful vector class (pure lua)
+*   *vector.lua*: powerful vector class (pure lua)
-* *class.lua*: "class" system supporting function inheritance
+*   *class.lua*: "class" system supporting function inheritance (pure lua)
-* *camera.lua*: translate-, zoom- and rotatable camera
+*   *camera.lua*: translate-, zoom- and rotatable camera
-* *gamestate.lua*: class to handle gamestates
+*   *gamestate.lua*: class to handle gamestates
 
 Documentation
 =============
@@ -19,14 +19,14 @@ vector.lua
 
 A vector class implementing everything you want to do with vectors, and some more.
 
-#### Basic ####
+### Basic ###
 
 **function vector(x,y)**<br />
 Creates a new vector. Element access with `v.x` and `v.y`.<br />
 *Parameters:*
 
-* `x` (_number_) - x coordinate
+*   `x` **[number]**: x coordinate
-* `y` (_number_) - y coordinate
+*   `y` **[number]**: y coordinate
 
 *Returns:* the vector
 
@@ -35,7 +35,7 @@ Creates a new vector. Element access with `v.x` and `v.y`.<br />
 Tests for vector type.<br />
 *Parameters:*
 
-* `v` - variable to test<br />
+*   `v`: variable to test<br />
 
 *Returns:* `true` if `v` is a vector
 
@@ -55,18 +55,20 @@ Unpacks the vector.<br />
 	print(v:unpack()) -- prints "1     2"
 
 
-#### Operators  ####
+### Operators  ###
 
 Arithmetic (`+`, `-`, `*`, `/`) and comparative operators (`==`, `<=`, `<`) are defined.
 
-* `+` and `-` _only_ work on vectors. `-` is also the unary minus (e.g. `print(-vector(1,0)) -- prints (-1,0)`
+*   `+` and `-` _only_ work on vectors. `-` is also the unary minus (e.g. `print(-vector(1,0)) -- prints (-1,0)`
-* `a * b` works on vectors and numbers: ==<br />==If `a` is a number and `b` is a vector (or vice versa), the result the scalar multiplication. If `a` and `b` are vectors, then the result is the _dot product_.|
+*   `a * b` works on vectors and numbers:<br />
-* `a / b` is only defined for `a` being a vector and `b` being a number. Result is the same as `a * 1/b`
+    -   If `a` is a number and `b` is a vector (or vice versa), the result the scalar multiplication.<br />
+    -   If `a` and `b` both are vectors, then the result is the _dot product_.
+*   `a / b` is only defined for `a` being a vector and `b` being a number. Result is the same as `a * 1/b`
 
-`<=` and `<` sort lexically, i.e. `a <= b` if it holds: `a.x < b.x` or `a.y < b.y` if `a.x == b.x`
+`<=` and `<` sort lexically, i.e. `a <= b` is true if it holds: `a.x < b.x` or `a.y < b.y` if `a.x == b.x`
 
 
-#### Even more! ####
+### Even more! ###
 
 **function vector:permul(other)**<br />
 Perform element-wise multiplication.
@@ -102,14 +104,13 @@ Normalize vector and return it.<br />
 Get rotated vector. The original vector remains unchanged.<br />
 *Parameters:*
 
-* `phi` - Rotation angle in radians.
+*   `phi` **[number]**: Rotation angle in radians.
 
 
 **function Vector:rotate_inplace(phi)**<br />
 Rotate the vector and return it.<br />
 *Warning:* This will change the state of all references to this vector.
 
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 class.lua
 ---------
@@ -117,11 +118,11 @@ class.lua
 Simple class-like system for Lua. Supports definition of class types and inheritance of functions.
 For an example how to use this, see below.
 
-**function Class([constructor])**<br/>
+**function Class(constructor)**<br/>
 Creates a new unnamed class.
 *Parameters:*
 
-* _optional_ `constructor` - A function used to construct the class. The first parameter of this function is the object, the others are parameters given upon construction.
+*   _(optional)_ `constructor`: A function used to construct the class. The first parameter of this function is the object, the others are parameters given upon construction.
 
 *Example:*
 
@@ -152,7 +153,7 @@ Great for debugging. Both `name` and `constructor` can be omitted (but why would
 	print(Feline) -- prints 'Feline'
 
 
-**function Interface([name])**<br />
+**function Interface(name)**<br />
 Shortcut to `Class{name = name}`, i.e. a possibly named class without constructor.
 
 
@@ -161,7 +162,7 @@ Add functions of `super` to `class`. Multiple interfaces can be defined.<br />
 `super`'s constructor can be accessed via super.construct(self). See example below.
 
 
-#### Example usage ####
+### Example usage ###
 
 	Feline = Class{name = "Feline", function(self, size, weight)
 		self.size = size self.weight = weight
@@ -199,15 +200,65 @@ Add functions of `super` to `class`. Multiple interfaces can be defined.<br />
 	felix:speak()
 	hobbes:speak()
 
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 camera.lua
 ----------
 _Depends on vector.lua_
 
-**TODO**
+Camera class to display only a certain zoomed and rotated region of the game.
+You can have multiple cameras in one game.
+
+**function Camera(pos, zoom, rotation)**<br />
+Create a new camera with position `pos`, zoom `zoom` and rotation `rotation`.
+**Parameters:**
+
+*   _(optional)_ `pos` **[vector]**: Initial position of the camera. Defaults to (0,0).
+*   _(optional)_ `zoom` **[number]**: Initial zoom. Defaults to 1.
+*   _(optional)_ `rotation` **[number]**: Initial rotation in radians. Defaults to 0.
+
+**Returns:** The new camera object.
+
+
+**function camera:rotate(phi)**<br />
+Rotate camera by `phi` radians. Same as `camera.rot = camera.rot + phi`.
+
+
+**function camera:translate(t)**<br />
+Translate (move) camera by vector `t`. Same as `camera.pos = camera.pos + t.
+
+**function camera:draw(func)**<br />
+Apply camera transformation to drawings in function `func`. Shortcut to
+`camera:apply()` and `camera:deapply()` (see below).
+
+*Example:*
+
+	cam:draw(function() love.graphics.rectangle('fill', -100,-100, 200,200) end)
+
+
+**function camera:apply()**<br />
+Apply camera transformations to every drawing operation until the next `camera:deapply()`.
+
+
+**function camera:deapply()**<br />
+Revert camera transformations for the rest of the drawing operations.
+
+*Example:* (equivalent to the `cam:draw()` example above)
+
+	camera:apply()
+	love.graphics.rectangle('fill', -100,-100, 200,200)
+	camera:deapply()
+
+
+**function camera:transform(p)**<br />
+Transform vector `p` from camera coordinates to world coordinates.
+You probably won't need this, but it is the basis to `camera:mousepos()`.
+
+
+**function camera:mousepos()**<br />
+Get mouse position in world coordinates, i.e. the position the users mouse
+is currently when camera transformations are applied. Use this for _any_
+mouse interaction with transformed objects in your game.
 
-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 
 gamestate.lua
 -------------