@node csGeom, csUtil, Libraries, Libraries
@subsection Geometry Library (@code{csGeom})
@cindex csGeom
@cindex Module, csGeom
@cindex Geometry Module
@cindex Geometry Library

This library is used to perform any calculations dealing with 2D or 3D
geometry. It contains several more or less independent classes. The most
important classes are:

@itemize @bullet
@item
@emph{Geometric Functionality}

These are functions that do not fit in one of the following classes, for
example to calculate intersections. They are grouped as static member
functions of one class. (It does not make sense to create objects of this
class, as it only contains these static member functions).

@item
@emph{Vectors}

These classes represent 2D and 3D vectors.  There is also a variant of the 3D
vector class which uses double precision numbers to represent its elements,
rather than the single precision numbers used by the standard 3D vector class.
These classes supply specially overloaded operators so you can use them in
calculations as you can use integer or float values.  The possible operators
are:

@itemize @bullet
@item
Add two vectors
@item
Subtract two vectors
@item
Multiply a vector and a scalar
@item
Divide a vector by a scalar
@item
Dot product (uses @samp{*} operator)
@item
Cross product (uses @samp{%} operator)
@item
Comparison of two vectors (@samp{==} and @samp{!=})
@item
Projecting one vector on another (@samp{<<} and @samp{>>})
@item
Inverting a vector (@samp{-} operator)
@item
Comparing all components with a small epsilon value (@samp{<} and @samp{>})
@end itemize

They also contain some functions to normalize the vector or return its length.
Single and double precision vectors can be mixed in calculations.

@item
@emph{Matrices}

These are 2D and 3D matrices. They are used to transform (rotate, scale etc.)
vectors. They also use their own operators for easier usage (for example to
multiply a matrix and a vector).

@item
@emph{Transforms}

A transformation consists of a matrix and a vector. In contrast to just a
matrix you can also include movement in a transform. It also uses its own
operators.

@item
@emph{Quaternions}

Encapsulation of quaternion functionality.

@item
@emph{Planes}

These classes represent 2D and 3D planes. They can, for example, be used to
split polygons or to calculate the distance of a point from a polygon (or
line segments instead of polygons for 2D planes).

@item
@emph{Line Segments}

A line segment is a straight line between two points, which ends at these
points. It could for example be used to define start and finish point of
straight movement. There are 2D and 3D segments.

@item
@emph{Polygons}

Polygons are an important class used heavily in the 3D engine. A polygon is
built from at least three points, called @dfn{vertices}. All vertices must
be on the same plane in space. The polygons outline consists of all line
segments from one vertex to the next one, including the segment from the last
vertex to the first one. These segments may not cross. Also, the polygon
must be convex, which means that if you take two arbitrary points inside the
polygon and draw a straight line between them, it may not cross any of the
polygon's edges.  A polygon has two faces, defined by the order of the
vertices: If you count through all vertices, and from your position they appear
in clockwise order, then you are viewing the front face, otherwise you are
viewing the back face.  The @dfn{normal} vector of the polygon always points
out perpendicular from the front face.

There are different types of polygons concerning management of the vertices
and how they can be used. First, there are the basic 2D and 3D polygons that
store their vertices as 3D vectors. The clippers are similar to this but
they are specialized on clipping other polygons (you lay the clipper somewhere
on a polygon and cut everything away of the polygon that is outside the
clipper, resulting in a new, smaller polygon). Then there is a 2D polygon
that stores its sides as line segments, not its vertices as vectors.
The most important type for the engine is the indexed polygon, which does not
store its vertices as 3D vectors but only as indices in a table.
@end itemize

There are also other classes that are mostly used inside the engine, such as
bounding boxes, frustums, polygon pools, etc.
