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


-- | Small geometry library for dealing with vectors and collision detection
--   
--   A small geometry library for dealing with vectors, points, lines,
--   simple shapes, and their various intersection tests. See also the
--   SGdemo project
--   (<a>http://hackage.haskell.org/cgi-bin/hackage-scripts/package/SGdemo</a>)
--   for an example of using the module.
@package SG
@version 1.0


-- | The module with all the different type-classes for vectors. Generally,
--   the main functions you might need from this function are:
--   
--   <ul>
--   <li><a>magSq</a> and <a>mag</a> (defined for all vectors).</li>
--   <li><a>getX</a> and <a>getY</a> (defined for all vectors) as well as
--   <a>getZ</a> (defined for all vectors with 3 or more dimensions).</li>
--   <li><a>dotProduct</a>, <a>unitVector</a>, <a>averageVec</a>,
--   <a>averageUnitVec</a>, <a>sameDirection</a>, <a>projectOnto</a>,
--   <a>projectPointOnto</a>, <a>distFrom</a> (defined for all
--   vectors).</li>
--   <li><a>iso</a>, which is defined for all combinations of vectors with
--   the same number of dimensions.</li>
--   </ul>
--   
--   The rest of the functions are mainly just wiring necessary for other
--   functions, but must be exported.
--   
--   As to the vector types, there are two methods to use this library. One
--   is to use the types from the <a>Data.SG.Vector.Basic</a> library,
--   which support basic vector operations. The other is to use the types
--   from the <a>Data.SG.Geometry.TwoDim</a> and
--   <a>Data.SG.Geometry.ThreeDim</a> modules, where a position vector is
--   differentiated from a relative vector (to increase clarity of code,
--   and help prevent errors such as adding two points together). Both
--   systems can be used with various useful functions (involving lines
--   too) from <a>Data.SG.Geometry</a>.
module Data.SG.Vector

-- | An isomorphism amongst vectors. Allows you to convert between two
--   vectors that have the same dimensions. You will notice that all the
--   instances reflect this.
class IsomorphicVectors from to
iso :: (IsomorphicVectors from to, Num a) => from a -> to a

-- | The class that is implemented by all vectors.
--   
--   Minimal implementation: fromComponents
class Foldable p => Coord p
getComponents :: (Coord p, Num a) => p a -> [a]
fromComponents :: (Coord p, Num a) => [a] -> p a
magSq :: (Coord p, Num a) => p a -> a
dotProduct :: (Coord p, Num a) => p a -> p a -> a

-- | This class is implemented by all 2D and 3D vectors, so <a>getX</a>
--   gets the X co-ordinate of both 2D and 3D vectors.
class Coord p => Coord2 p
getX :: Coord2 p => p a -> a
getY :: Coord2 p => p a -> a

-- | This class is implemented by all 3D vectors. To get the X and Y
--   components, use <a>getX</a> and <a>getY</a> from <a>Coord2</a>.
class Coord2 p => Coord3 p
getZ :: Coord3 p => p a -> a

-- | The origin/all-zero vector (can be used with any vector type you like)
origin :: (Coord p, Num a) => p a

-- | Gets the magnitude of the given vector.
mag :: (Coord p, Floating a) => p a -> a

-- | Scales the vector so that it has length 1. Note that due to
--   floating-point inaccuracies and so on, mag (unitVector v) will not
--   necessarily equal 1, but it should be very close. If an all-zero
--   vector is passed, the same will be returned.
--   
--   This function should be very fast when called on
--   <tt>Data.SG.Geometry.TwoDim.Rel2'</tt> and
--   <tt>Data.SG.Geometry.ThreeDim.Rel3'</tt>; vectors that are already
--   unit vectors (no processing is done).
unitVector :: (Coord p, VectorNum p, Ord a, Floating a) => p a -> p a

-- | Gets the average vector of all the given vectors. Essentially it is
--   the sum of the vectors, divided by the length, so <tt>averageVec
--   [Point2 (-3, 0), Point2 (5,0)]</tt> will give <tt>Point2 (1,0)</tt>.
--   If the list is empty, the all-zero vector is returned.
averageVec :: (Fractional a, VectorNum p, Num (p a)) => [p a] -> p a

-- | Like averageVec composed with unitVector -- gets the average of the
--   vectors in the list, and normalises the length. If the list is empty,
--   the all-zero vector is returned (which is therefore not a unit
--   vector). Similarly, if the average of all the vectors is all-zero, the
--   all-zero vector will be returned.
averageUnitVec :: (Floating a, Ord a, Coord p, VectorNum p, Num (p a)) => [p a] -> p a

-- | Works out if the two vectors are in the same direction (to within a
--   small tolerance).
sameDirection :: (VectorNum rel, Coord rel, Ord a, Floating a) => rel a -> rel a -> Bool

-- | Gives back the vector (first parameter), translated onto given axis
--   (second parameter). Note that the scale is always distance, <i>not</i>
--   related to the size of the axis vector.
projectOnto :: (Floating a, Ord a, VectorNum rel, Coord rel) => rel a -> rel a -> a

-- | Projects the first parameter onto the given axes (X, Y), returning a
--   point in terms of the new axes.
projectOnto2 :: (Floating a, Ord a, VectorNum rel, Coord rel) => rel a -> (rel a, rel a) -> rel a

-- | Gives back the point (first parameter), translated onto given axis
--   (second parameter). Note that the scale is always distance, <i>not</i>
--   related to the size of the axis vector.
projectPointOnto :: (Floating a, Ord a, VectorNum rel, Coord rel, IsomorphicVectors pt rel) => pt a -> rel a -> a

-- | Projects the point (first parameter) onto the given axes (X, Y),
--   returning a point in terms of the new axes.
projectPointOnto2 :: (Floating a, Ord a, VectorNum rel, Coord rel, IsomorphicVectors pt rel, Coord pt) => pt a -> (rel a, rel a) -> pt a

-- | Works out the distance between two points.
distFrom :: (VectorNum pt, Coord pt, Floating a) => pt a -> pt a -> a

-- | A modified version of <a>Functor</a> and
--   <tt>Control.Applicative.Applicative</tt> that adds the <a>Num</a>
--   constraint on the result. You are unlikely to need to use this class
--   much directly. Some vectors have <a>Functor</a> and
--   <tt>Control.Applicative.Applicative</tt> instances anyway.
class VectorNum f
fmapNum1 :: (VectorNum f, Num b) => (a -> b) -> f a -> f b
fmapNum2 :: (VectorNum f, Num c) => (a -> b -> c) -> f a -> f b -> f c
fmapNum1inv :: (VectorNum f, Num a) => (a -> a) -> f a -> f a
simpleVec :: (VectorNum f, Num a) => a -> f a
instance IsomorphicVectors v v


-- | Some types that are very basic vectors. Most of the use that can be
--   made of the vectors is in their type-class instances, which support a
--   powerful set of operations. For example:
--   
--   <pre>
--   fmap (*3) v -- Scales vector v by 3
--   pure 0 -- Creates a vector filled with zeroes
--   v + w -- Adds two vectors (there is a 'Num' instance, basically)
--   </pre>
--   
--   Plus all the instances for the classes in <a>Data.SG.Vector</a>, which
--   allows you to use <a>getX</a> and so on.
--   
--   You will probably want to create more friendly type synonyms, such as:
--   
--   <pre>
--   type Vector2 = Pair Double
--   type Vector3 = Triple Double
--   type Line2 = LinePair Double
--   type Line3 = LineTriple Double
--   </pre>
module Data.SG.Vector.Basic

-- | A pair, which acts as a 2D vector.
newtype Pair a
Pair :: (a, a) -> Pair a

-- | A triple, which acts as a 3D vector.
newtype Triple a
Triple :: (a, a, a) -> Triple a

-- | A quad, which acts as a 4D vector.
newtype Quad a
Quad :: (a, a, a, a) -> Quad a

-- | A pair of (position vector, direction vector) to be used as a 2D line.
newtype LinePair a
LinePair :: (Pair a, Pair a) -> LinePair a

-- | A pair of (position vector, direction vector) to be used as a 3D line.
newtype LineTriple a
LineTriple :: (Triple a, Triple a) -> LineTriple a
instance Eq a => Eq (Pair a)
instance Ord a => Ord (Pair a)
instance Show a => Show (Pair a)
instance Read a => Read (Pair a)
instance Eq a => Eq (Triple a)
instance Ord a => Ord (Triple a)
instance Show a => Show (Triple a)
instance Read a => Read (Triple a)
instance Eq a => Eq (Quad a)
instance Ord a => Ord (Quad a)
instance Show a => Show (Quad a)
instance Read a => Read (Quad a)
instance Eq a => Eq (LinePair a)
instance Ord a => Ord (LinePair a)
instance Show a => Show (LinePair a)
instance Read a => Read (LinePair a)
instance Eq a => Eq (LineTriple a)
instance Ord a => Ord (LineTriple a)
instance Show a => Show (LineTriple a)
instance Read a => Read (LineTriple a)
instance Coord3 Quad
instance Coord2 Quad
instance Coord Quad
instance Coord3 Triple
instance Coord2 Triple
instance Coord Triple
instance Coord2 Pair
instance Coord Pair
instance Functor Quad
instance Functor Triple
instance Functor Pair
instance Traversable Quad
instance Foldable Quad
instance Applicative Quad
instance Traversable Triple
instance Foldable Triple
instance Applicative Triple
instance Traversable Pair
instance Foldable Pair
instance Applicative Pair
instance (Show a, Eq a, Num a) => Num (Quad a)
instance (Show a, Eq a, Num a) => Num (Triple a)
instance (Show a, Eq a, Num a) => Num (Pair a)
instance VectorNum Quad
instance VectorNum Triple
instance VectorNum Pair


-- | This module has the type-class (and associated functions) for dealing
--   with geometric systems of 2 or 3 dimensions.
module Data.SG.Geometry

-- | A geometry system, parameterised over points, relative (free) vectors,
--   and lines. There are separate instances for two dimensions and for
--   three dimensions. Each pair of type-class parameters is uniquely
--   determined by the other parameter (i.e. by the dimensionality, and
--   which vector type you are using).
--   
--   Minimal implementation: everything but scaleRel.
class (VectorNum rel, Coord rel, Coord pt, IsomorphicVectors rel pt, IsomorphicVectors pt rel) => Geometry rel pt ln | rel -> pt ln, pt -> rel ln, ln -> rel pt
scaleRel :: (Geometry rel pt ln, Num a) => a -> rel a -> rel a
plusDir :: (Geometry rel pt ln, Num a) => pt a -> rel a -> pt a
fromPt :: (Geometry rel pt ln, Num a) => pt a -> pt a -> rel a
getLineVecs :: (Geometry rel pt ln, Num a) => ln a -> (pt a, rel a)
makeLine :: (Geometry rel pt ln, Num a) => pt a -> rel a -> ln a

-- | Adds the negation of the relative (free) vector to the point.
minusDir :: (Num a, Geometry rel pt ln) => pt a -> rel a -> pt a

-- | The flipped version of <a>fromPt</a>.
toPt :: (Geometry rel pt ln, Num a) => pt a -> pt a -> rel a

-- | Gets the line <i>from</i> the first point, <i>to</i> the second point.
lineTo :: (Num a, Geometry rel pt ln) => pt a -> pt a -> ln a

-- | The flipped version of <a>lineTo</a>.
lineFrom :: (Num a, Geometry rel pt ln) => pt a -> pt a -> ln a

-- | Gets the point at the start of the line.
getLineStart :: (Num a, Geometry rel pt ln) => ln a -> pt a

-- | Gets the direction vector of the line.
getLineDir :: (Num a, Geometry rel pt ln) => ln a -> rel a

-- | Gets the point at the end of the line.
getLineEnd :: (Geometry rel pt ln, Num a) => ln a -> pt a

-- | Alters the line to the given length, but with the same start point and
--   direction.
makeLength :: (Floating a, Ord a, Geometry rel pt ln) => a -> ln a -> ln a

-- | Given a multiple of the <i>direction vector</i> (this is <i>not</i>
--   distance unless the direction vector is a unit vector), calculates
--   that point.
alongLine :: (Num a, Geometry rel pt ln) => a -> ln a -> pt a

-- | Checks if the given point is on the given line (to within a small
--   epsilon-tolerance). If it is, gives back the distance along the line
--   (as a multiple of its direction vector) to the point in a Just
--   wrapper. If the point is not on the line, Nothing is returned.
distAlongLine :: (Geometry rel pt ln, Ord a, Floating a) => pt a -> ln a -> Maybe a

-- | Checks if the given point is on the given line (to within a small
--   epsilon-tolerance).
isOnLine :: (Geometry rel pt ln, Ord a, Floating a) => pt a -> ln a -> Bool

-- | Finds the nearest point on the line to the given point, and gives back
--   its distance along the line (as a multiple of the direction vector).
--   Since the nearest distance will be at a right-angle to the point, this
--   is the same as projecting the point onto the line.
nearestDistOnLine :: (Geometry rel pt ln, Ord a, Floating a) => pt a -> ln a -> a

-- | Finds the nearest point on the line to the given point, and gives back
--   the point.
nearestPointOnLine :: (Geometry rel pt ln, Ord a, Floating a) => pt a -> ln a -> pt a

-- | Gives the distance along the line (2D or 3D) at a given X value.
--   Returns Nothing if the line is parallel to the YZ plane (in 2D, if the
--   X component of the line is zero). The value returned is a multiple of
--   the direction vector of the line, which will only be the same as
--   distance if the direction vector is a unit vector.
valueAtX :: (Geometry rel pt ln, Coord2 rel, Coord2 pt, Fractional a) => ln a -> a -> Maybe a

-- | Gives the distance along the line (2D or 3D) at a given Y value.
--   Returns Nothing if the line is parallel to the XZ plane (in 2D, if the
--   Y component of the line is zero). The value returned is a multiple of
--   the direction vector of the line, which will only be the same as
--   distance if the direction vector is a unit vector.
valueAtY :: (Geometry rel pt ln, Coord2 rel, Coord2 pt, Fractional a) => ln a -> a -> Maybe a

-- | Gives the distance along the 3D line at a given Z value. Returns
--   Nothing if the line is parallel to the XY plane. The value returned is
--   a multiple of the direction vector of the line, which will only be the
--   same as distance if the direction vector is a unit vector.
valueAtZ :: (Geometry rel pt ln, Coord3 rel, Coord3 pt, Fractional a) => ln a -> a -> Maybe a

-- | pointAtX (and the Y and Z equivalents) are wrappers around
--   <a>valueAtX</a> (and similar) that give back the point rather than
--   distance along the line.
pointAtX, pointAtY :: (Geometry rel pt ln, Coord2 rel, Coord2 pt, Fractional a) => ln a -> a -> Maybe (pt a)
pointAtZ :: (Geometry rel pt ln, Coord3 rel, Coord3 pt, Fractional a) => ln a -> a -> Maybe (pt a)
instance Geometry Triple Triple LineTriple
instance Geometry Pair Pair LinePair


-- | A module with types to use in a 2D system, and various helper
--   functions. Several more functions are available for use in the
--   <a>Data.SG.Geometry</a> module.
module Data.SG.Geometry.TwoDim

-- | A point in 2D space.
newtype Point2' a
Point2 :: (a, a) -> Point2' a

-- | A relative vector (free vector) in 2D space. The pair are the x and y
--   components, and the last item is the <i>squared magnitude</i> of the
--   vector, which is stored with it to speed up various operations. It is
--   suggested you use <a>makeRel2</a> to create one of these, unless the
--   square magnitude is easily apparent, e.g. <tt>Rel2 (0, 2) 4</tt>
data Rel2' a
Rel2 :: (a, a) -> a -> Rel2' a

-- | Constructs a Rel2' vector.
makeRel2 :: Num a => (a, a) -> Rel2' a

-- | A line in 2D space. A line is a point, and a free vector indicating
--   direction. A line may be treated by a function as either finite
--   (taking the magnitude of the free vector as the length) or infinite
--   (ignoring the magnitude of the direction vector).
data Line2' a
Line2 :: (Point2' a) -> (Rel2' a) -> Line2' a
getLineStart2 :: Line2' a -> (Point2' a)
getLineDir2 :: Line2' a -> (Rel2' a)

-- | Gets the angle, in <i>radians</i>, anti-clockwise from the x-axis. If
--   you pass the all-zero vector, the return value will be zero.
toAngle :: RealFloat a => Rel2' a -> a

-- | Gets the vector perpendicular to the given 2D vector. If you pass it a
--   vector that is in a clockwise direction around a polygon, the result
--   will always face away from the polygon.
perpendicular2 :: Num a => Rel2' a -> Rel2' a

-- | Reflects the first direction vector against the given surface normal.
--   The resulting direction vector should have the same magnitude as the
--   original first parameter. An example:
--   
--   <pre>
--   makeRel2 (-3, -4) `reflectAgainst2` makeRel2 (0,1) == makeRel2 (-3, 4)
--   </pre>
reflectAgainst2 :: (Floating a, Ord a) => Rel2' a -> Rel2' a -> Rel2' a

-- | Reflects the first direction vector against the given surface normal.
--   The resulting direction vector should have the same magnitude as the
--   original first parameter.
--   
--   The reflection is not performed if the given vector points along the
--   same direction as the normal, that is: if once projected onto the
--   normal vector, the component is positive, the original first parameter
--   is returned unmodified. Examples:
--   
--   <pre>
--   makeRel2 (-3, -4) `reflectAgainstIfNeeded2` makeRel2 (0,1) == makeRel2 (-3, 4)
--   makeRel2 (-3, 4) `reflectAgainstIfNeeded2` makeRel2 (0,1) == makeRel2 (-3, 4)
--   </pre>
reflectAgainstIfNeeded2 :: (Floating a, Ord a) => Rel2' a -> Rel2' a -> Rel2' a

-- | Given two 2D lines, finds out their intersection. The first part of
--   the result pair is how much to multiply the direction vector of the
--   first line by (and add it to the start point of the first line) to
--   reach the intersection, and the second part is the corresponding item
--   for the second line. So given <tt>Just (a, b) = intersectLines2 la
--   lb</tt>, it should be the case (minus some possible precision loss)
--   that <tt>alongLine a la == alongLine b lb</tt>. If the lines are
--   parallel, Nothing is returned.
--   
--   Note that this function assumes the lines are infinite. If you want to
--   check for the intersection of two finite lines, check if the two parts
--   of the result pair are both in the range 0 to 1 inclusive.
intersectLines2 :: Fractional a => Line2' a -> Line2' a -> Maybe (a, a)

-- | Finds all the intersections between a line from the first list and a
--   line from the second list, and how far along that is each line. That
--   is, this is a bit like mapMaybe composed with intersectLines2 on all
--   pairings of a line from the first list and a line from the second
--   list.
findAllIntersections2 :: Fractional a => ([Line2' a], [Line2' a]) -> [((Line2' a, a), (Line2' a, a))]

-- | Given a line, and a circle (defined by a point and a radius), finds
--   the points of intersection.
--   
--   If the line does not intersect the circle, Nothing is returned. If
--   they do intersect, two values are returned that are distances along
--   the line. That is, given <tt>Just (a, b) = intersectLineCircle l
--   c</tt>, the two points of intersection are <tt>(alongLine l a,
--   alongLine l b)</tt>.
--   
--   The ordering of the two items in the pair is arbitrary, and if the
--   line is a tangent to the circle, the values will be the same.
intersectLineCircle :: (Ord a, Floating a) => Line2' a -> (Point2' a, a) -> Maybe (a, a)

-- | Like <a>pointAtZ</a>, but returns a 2D vector instead of a 3D vector
point2AtZ :: (Geometry rel pt ln, Coord3 rel, Coord3 pt, Fractional a) => ln a -> a -> Maybe (Point2' a)
instance Eq a => Eq (Point2' a)
instance Ord a => Ord (Point2' a)
instance Show a => Show (Point2' a)
instance Read a => Read (Point2' a)
instance Eq a => Eq (Rel2' a)
instance Ord a => Ord (Rel2' a)
instance Show a => Show (Rel2' a)
instance Read a => Read (Rel2' a)
instance Eq a => Eq (Line2' a)
instance Show a => Show (Line2' a)
instance Read a => Read (Line2' a)
instance Geometry Rel2' Point2' Line2'
instance Coord Rel2'
instance Coord2 Rel2'
instance Coord Point2'
instance Coord2 Point2'
instance Traversable Point2'
instance Foldable Rel2'
instance Foldable Point2'
instance Applicative Point2'
instance Functor Point2'
instance (Show a, Eq a, Num a) => Num (Rel2' a)
instance VectorNum Point2'
instance VectorNum Rel2'
instance IsomorphicVectors Pair Point2'
instance IsomorphicVectors Point2' Pair
instance IsomorphicVectors Pair Rel2'
instance IsomorphicVectors Rel2' Pair
instance IsomorphicVectors Point2' Rel2'
instance IsomorphicVectors Rel2' Point2'


-- | A module with types to use in a 3D system, and various helper
--   functions. Several more functions are available for use in the
--   <a>Data.SG.Geometry</a> module.
module Data.SG.Geometry.ThreeDim

-- | A point in 3D space.
newtype Point3' a
Point3 :: (a, a, a) -> Point3' a

-- | A relative vector (free vector) in 3D space. The triple is the x, y, z
--   components, and the last item is the <i>squared magnitude</i> of the
--   vector, which is stored with it to speed up various operations. It is
--   suggested you use <a>makeRel3</a> to create one of these, unless the
--   magnitude is easily apparent, e.g. <tt>Rel3 (0, 1, 1) 2</tt>
data Rel3' a
Rel3 :: (a, a, a) -> a -> Rel3' a

-- | Constructs a Rel3' vector
makeRel3 :: Num a => (a, a, a) -> Rel3' a

-- | A line in 3D space. A line is a point and a free vector indicating
--   direction. A line may be treated by a function as either finite
--   (taking the magnitude of the free vector as the length) or infinite
--   (ignoring the magnitude of the direction vector).
data Line3' a
Line3 :: (Point3' a) -> (Rel3' a) -> Line3' a
getLineStart3 :: Line3' a -> (Point3' a)
getLineDir3 :: Line3' a -> (Rel3' a)
instance Eq a => Eq (Point3' a)
instance Ord a => Ord (Point3' a)
instance Show a => Show (Point3' a)
instance Read a => Read (Point3' a)
instance Eq a => Eq (Rel3' a)
instance Ord a => Ord (Rel3' a)
instance Show a => Show (Rel3' a)
instance Read a => Read (Rel3' a)
instance Eq a => Eq (Line3' a)
instance Show a => Show (Line3' a)
instance Read a => Read (Line3' a)
instance Geometry Rel3' Point3' Line3'
instance Coord Rel3'
instance Coord Point3'
instance Coord3 Rel3'
instance Coord2 Rel3'
instance Coord3 Point3'
instance Coord2 Point3'
instance Traversable Point3'
instance Foldable Rel3'
instance Foldable Point3'
instance Applicative Point3'
instance Functor Point3'
instance (Show a, Eq a, Num a) => Num (Rel3' a)
instance VectorNum Point3'
instance VectorNum Rel3'
instance IsomorphicVectors Triple Point3'
instance IsomorphicVectors Point3' Triple
instance IsomorphicVectors Triple Rel3'
instance IsomorphicVectors Rel3' Triple
instance IsomorphicVectors Point3' Rel3'
instance IsomorphicVectors Rel3' Point3'


-- | A module with various simple matrix operations to augment the vector
--   stuff.
--   
--   The Num instances implement proper matrix multiplication as you would
--   expect (not element-wise multiplication).
module Data.SG.Matrix

-- | A 2x2 matrix. Primarily useful via its instances, such as
--   <a>Functor</a>, <a>Num</a>, and <a>Matrix</a>.
type Matrix22' a = SquareMatrix Pair a

-- | A 3x3 matrix. Primarily useful via its instances, such as
--   <a>Functor</a>, <a>Num</a>, and <a>Matrix</a>.
type Matrix33' a = SquareMatrix Triple a

-- | A 4x4 matrix. Primarily useful via its instances, such as
--   <a>Functor</a>, <a>Num</a>, and <a>Matrix</a>.
type Matrix44' a = SquareMatrix Quad a

-- | A square matrix. You will almost certainly want to use
--   <a>Matrix22'</a> and similar instead of this directly. It does have a
--   variety of useful instances though, especially <a>Functor</a>,
--   <a>Num</a> and <a>Matrix</a>.
--   
--   Its definition is based on a square matrix being, for example, a pair
--   of pairs or a triple of triples.
newtype SquareMatrix c a
SquareMatrix :: (c (c a)) -> SquareMatrix c a

-- | The class that all matrices belong to.
class Matrix m
matrixComponents :: Matrix m => m a -> [[a]]
fromMatrixComponents :: (Matrix m, Num a) => [[a]] -> m a
transpose :: Matrix m => m a -> m a

-- | The identity matrix.
identityMatrix :: (Num a, Matrix m) => m a

-- | Matrix multiplication where the size of the vector matches the
--   dimensions of the matrix. The complicated type just means that this
--   function will work for any combination of matrix types and vectors
--   where the width of the square matrix is the same as the number of
--   dimensions in the vector.
multMatrix :: (Foldable c, Applicative c, Num a, IsomorphicVectors c p, IsomorphicVectors p c) => SquareMatrix c a -> p a -> p a

-- | Matrix multiplication. There is no requirement that the size of the
--   matrix matches the size of the vector:
--   
--   <ul>
--   <li>If the vector is too small for the matrix (e.g. multiplying a 4x4
--   matrix by a 3x3 vector), 1 will be used for the missing vector
--   entries.</li>
--   <li>If the matrix is too small for the vector (e.g. multiplying a 2x2
--   matrix by a 3x3 vector), the other components of the vector will be
--   left untouched.</li>
--   </ul>
--   
--   This allows you to do tricks such as multiplying a 4x4 matrix by a 3D
--   vector, and doing translation (a standard 3D graphics trick).
multMatrixGen :: (Coord p, Matrix m, Num a) => m a -> p a -> p a

-- | Given a 2D relative vector, produces a matrix that will translate by
--   that much (when you multiply a 2D point with it using multMatrixGen)
translate2D :: (Num a, IsomorphicVectors p Pair) => p a -> Matrix33' a

-- | Given a 3D relative vector, produces a matrix that will translate by
--   that much (when you multiply a 3D point with it using multMatrixGen)
translate3D :: (Num a, IsomorphicVectors p Triple) => p a -> Matrix44' a

-- | Given an angle in <i>radians</i>, produces a matrix that rotates
--   anti-clockwise by that angle around the X axis. Note that this can be
--   used to produce a 2x2, 3x3 or 4x4 matrix, but if you produce a 2x2
--   matrix, odd things will happen!
rotateXaxis :: (Floating a, Matrix m) => a -> m a

-- | Given an angle in <i>radians</i>, produces a matrix that rotates
--   anti-clockwise by that angle around the Y axis. Note that this can be
--   used to produce a 2x2, 3x3 or 4x4 matrix, but if you produce a 2x2
--   matrix, odd things will happen!
rotateYaxis :: (Floating a, Matrix m) => a -> m a

-- | Given an angle in <i>radians</i>, produces a matrix that rotates
--   anti-clockwise by that angle around the Z axis. Note that this can be
--   used to produce a 2x2 (in which case it is a rotation around the
--   origin), 3x3 or 4x4 matrix.
rotateZaxis :: (Floating a, Matrix m) => a -> m a
instance (Num a, Traversable c, Foldable c, Functor c, Applicative c) => Num (SquareMatrix c a)
instance (Applicative c, Foldable c, Traversable c, Functor c) => Matrix (SquareMatrix c)
instance (Read a, Num a, Applicative c, Traversable c) => Read (SquareMatrix c a)
instance (Applicative c, Foldable c, Traversable c, Functor c, Show a) => Show (SquareMatrix c a)
instance Traversable c => Traversable (SquareMatrix c)
instance Foldable c => Foldable (SquareMatrix c)
instance (Foldable c, Applicative c, Eq a) => Eq (SquareMatrix c a)
instance Applicative c => Applicative (SquareMatrix c)
instance Functor c => Functor (SquareMatrix c)


-- | This module has types and functions for dealing with collision
--   detection on simple 2D shapes.
module Data.SG.Shape

-- | A type for simple 2D convex shapes. It is expected that you will
--   define a synonym in your own application such as <tt>type Shape =
--   Shape' Double</tt>, hence the funny name.
data Shape' a

-- | A rectangle with a centre, and a width (distance from the centre to
--   the left or right side of the rectangle) and a height (distance from
--   the centre to the top or bottom side of the rectangle. So the
--   rectangle with corners (1,1) and (3,2) is <tt>Rectangle (Point2
--   (2,1.5)) (1, 0.5)</tt>. Technically a rectangle is a polygon, of
--   course, but a rectangle (which is axis-aligned) can be processed
--   faster by most algorithms.
Rectangle :: Point2' a -> (a, a) -> Shape' a
shapeCentre :: Shape' a -> Point2' a
rectSize :: Shape' a -> (a, a)

-- | A circle with a centre and a radius.
Circle :: Point2' a -> a -> Shape' a
shapeCentre :: Shape' a -> Point2' a
circSize :: Shape' a -> a

-- | A polygon with a centre, and a list of points. The points are relative
--   vectors from the centre of the polygon, and are expected to be in
--   clockwise order. For example, the triangle with corners (1,1) (3,3)
--   and (3,1) could be <tt>Polygon (Point2 (2.5, 1.5)) [Rel2 (-1.5,-0.5),
--   Rel2 (0.5,1.5), Rel2 (-1.5, 1.5)]</tt>.
--   
--   Note that whereabouts the centre is inside the polygon is up to you
--   (it does not <i>have to be</i> the geometric average of the points),
--   but it should at least be inside the polygon, or else some algorithms
--   will behave strangely with it.
--   
--   The list of points should have at least 3 points in it, or else some
--   algorithms will behave strangely.
--   
--   If your points are not in clockwise order (with the X-Y axes being how
--   they are in graphs, not on screens), funny things will happen with the
--   collision detection.
Polygon :: Point2' a -> [Rel2' a] -> Shape' a
shapeCentre :: Shape' a -> Point2' a
polyPoints :: Shape' a -> [Rel2' a]

-- | Moves a shape by a given vector (by moving the centre).
moveShape :: Num a => Rel2' a -> Shape' a -> Shape' a

-- | Given an angle in <i>radians</i>, rotates the shape by that angle in
--   an anti-clockwise direction. A circle will remain untouched, a polygon
--   will have its points rotated, and a rectangle will become a polygon
--   and get rotated (even if you pass 0 as the angle).
rotateShape :: Floating a => a -> Shape' a -> Shape' a

-- | Scales the size of the shape (for all edges, from the centre) by the
--   given factor.
scaleShape :: Num a => a -> Shape' a -> Shape' a

-- | Given a shape, gets a list of points that make up the vertices of the
--   shape. For circles, this list will be empty.
shapePoints :: Num a => Shape' a -> [Point2' a]

-- | Gives back the bounding box of a shape in terms of the minimum X-Y and
--   the maximum X-Y corners of the bounding box.
boundingBox :: (Num a, Ord a) => Shape' a -> (Point2' a, Point2' a)

-- | Checks for overlap between the two shapes. If they do not collide,
--   returns Nothing. If they do collide, gives back suggested angles away
--   from each other. These are not necessarily the shortest direction to
--   separate the two shapes, but should be decent for doing collision
--   resolution (by using them as surface normals, or push-away vectors)
--   
--   The first vector returned is the direction in which the first shape
--   should head (or the surface normal to bounce the first shape off),
--   whereas the second vector returned is the direction in which the
--   second shape should head (or the surface normal to bounce the second
--   shape off).
--   
--   This function includes an initial quick test, followed by a more
--   detailed test if necessary.
overlap :: (Floating a, Ord a) => Shape' a -> Shape' a -> Maybe (Rel2' a, Rel2' a)

-- | Given a line and a shape, finds all possible intersections of the line
--   with the shape. Since the shapes are convex, continuous 2D shapes,
--   there will either be no intersections or two (which could be the same
--   point). The returned value is distance along the line in multiples of
--   the direction vector (the return value is the same idea as
--   <a>intersectLineCircle</a>).
intersectLineShape :: (Floating a, Ord a) => Line2' a -> Shape' a -> Maybe (a, a)
instance Show a => Show (Shape' a)
instance Read a => Read (Shape' a)
instance Eq a => Eq (Shape' a)
instance Ord a => Ord (Shape' a)


-- | A small geometry library, with vectors, matrices and simple shape
--   collision detection that is intended to be straightforward in two and
--   three dimensions.
--   
--   The basics of vectors are in the <a>Data.SG.Vector</a> module, the
--   basics of lines and geometry tests (e.g. testing whether a point is on
--   a line) are in <a>Data.SG.Geometry</a>, with further specialised tests
--   in <a>Data.SG.Geometry.TwoDim</a> and
--   <a>Data.SG.Geometry.ThreeDim</a>. Matrix transformations are in
--   <a>Data.SG.Matrix</a> and shapes (with collision detection) are in
--   <a>Data.SG.Shape</a>.
--   
--   The names for most of the types in this library end with a prime. This
--   is because it is intended that you specialise these types (usually to
--   Float or Double) in your application as follows:
--   
--   <pre>
--   type Point2 = Point2' Double
--   type Rel2 = Rel2' Double
--   type Line2 = Line2' Double
--   type Matrix22 = Matrix22' Double
--   </pre>
--   
--   Much of the use of the types (especially vectors) in this library is
--   made using type-classes such as Num, Functor, Applicative and so on.
--   For more explanation on some of the less well-known type-classes, see
--   either the article Typeclassopedia in The Monad Reader
--   (<a>http://www.haskell.org/haskellwiki/The_Monad.Reader</a>) issue 13
--   (<a>http://www.haskell.org/sitewiki/images/8/85/TMR-Issue13.pdf</a>),
--   or my own notes at <a>http://www.twistedsquare.com/haskell.html</a>.
--   
--   To understand what various functions will actually do, look at the
--   SGdemo project
--   (<a>http://hackage.haskell.org/cgi-bin/hackage-scripts/package/SGdemo</a>)
--   on Hackage (and its code) which provides a visual demonstration of
--   several of the functions.
module Data.SG