The MidLevelRender (MLR)
========================

Its main task is to transform and light the geometry handed to it by a HighLevelRenderer and
to feed this transformed and lit data into a rasterizer. MLR is designed to work with different
HighLevelRender's or Rasterizers.

The MLR project contains several folders:

- Clipping		- define a view frustrum and perform clipping into it
- Geometry		- store geometry data
- Lighting		- lit geometry
- Sorting		- define a render state and how to sort after certain parameters
- Texture		- define a texture and a pool to handle textures
- Rasterizer	- define a proxy for the rasterizer
- Effects		- provides an extra API for effects (very special cases of geometry data)


Clipping
--------

The clipper is essentially the camera through which we see the world. Therefor it knows
how to transform the camera into world space and how to transform from world space into
clipping space. Clipping space is defined as a "cube in homogenious space from 0.0f - 1.0f
in x, y and z".
Clipper = class MLRClipper
The clipper works together with the culling routines from the Element renderer and reuses
the culling state. There is defined a MLRClippingState for an efficient way to clip object
with the 6 clipping planes.
The clipper also contains a pool of GOSVertices (see Rasterizer) in which transformed
geometry data ready for rendering is stored.

This is how a frame works:
- first the clipper get initialized with the new camera position
- then the element renderer gives sequentially the geometry data to the clipper.
  Therefor the clipper provides 4 interfaces:
  The first 3 provide a matrix describing the object location in world space.
  Screen quads are allready defined in screen space therefor dont need transformation
  or clipping.
  - shape (see geometry)
  - scalable shape (see effect)
  - effect (see effect)
  - screen quads
After concatination the matrices together the clipper will call
- the backface culling and mark backfacing geometry
- the lighting function for the shape's primitives
- the transform of the coordinates into clipping space if the object is clipped
- the clip function if clipped. the clip function also fills the GOSVertex pool
- the lightmap function


Geometry
--------

While the ElementRenderer on top of MLR cares about hierarchy MLR stores and manipulates
the geometry data. The basic geometry containing unit is a primitive.
Primitive == abstract class MLRPrimitve.
Any primitive has one render state (see MLRState). Derived from MLRPrimitve is
MLRIndexPrimitve. This abstract class provides an indexed storage of the geometry data.
The index points to a unique vertex which is defined by a unique combination of
coordinates, color, texture coordinates and normals.
The MLRPolyMesh class is a non-indexed case. The geometry data is stored as a chain of
polygones with variable vertex count. MLRIndexedPolyMesh covers the indexed case.

Lighting
--------

MLR supports to types of lighting:
- The so called 'classic lighting' on a per vertex basis using the vertex normals.
  For per vertex lighting is available:
  - ambient light
  - infinite light
  - infinite light with falloff
  - point light
  - spot light
- The so called 'lightmap lighting' in which an extra texture gets applied to an object.
  This texture contains radiosity lighting information.
For an object is also the combination of the both lighting types allowed.
MLRPrimitive (see Geometry) has a member function 'Lighting'.

Sorting
-------

Before rendering the geometry data it is useful to sort them after the render state.
All information how to render and how to process a primitive are stored in MLRState.
For easy sorting all render informations are stored in a DWORD including a texture
handle (which points into the texture pool (see Textures)). All informations about
how to process a primitve are also stored in a DWORD. This are informations like 
lighting on off, in which render pass to render, use backfacing or not.
The actual sorting takes place in a sorter. 
Sorter == abstract class MLRSorter
The sorter gets sequentialy all transformed geoemtry data and stores them recording
to its implemented sorting functions.
MLRSortByOrder for example puts all data into designated buckets in the order it gets
the data handed.  So far there are 16 buckets (subject of change) to reflect different
render passes like alpha, non-alpha, light maps, HUD etc. Before drawing the data gets
sorted by render state.

Textures
--------

Definitions:
An "image" is the representation of a picture in memory. Images are differ by names.
The GOSImagePool (see Rasterizer) should take care that every image is loaded only once.
Image == class GOSImage (see Rasterizer).

A "texture" is an instance of an "image". It has also a texture matrix which allows to
move an image relative to the texture coordinates of an object.
Texture == class MLRTexture.

MLRTexture contains a texture handle which is an integer. This integer is stored in the
render state of an object (see MLRState / Sorting). There are 12 bits (2^12 = 4096)
(subject to changes) reserved in the state for the texture handle. The 12 bit information
is divided in 12-X bit for an image handle and X bit for instancing. The handle is provided
by the texture pool. X is defined in the constructor of the texture pool.

The application has access to a global texture pool called "MLRTexturePool::Instance". The
application has to take care of creating this texture pool once. The application can add
textures to the texture pool by name and an integer defining the instance. This integer
has no order purposes. The application also can remove textures from the texture pool by 
MLRTexture - pointer.

Rasterizer
----------

This provides a proxy to the underlaying Rasterizer. It connects a GOSVertex, a GOSImage.
It also provides a GOSVertex pool to feed all the render data from one memory block.
It also provides a GOSImagePool to ensure that all textures are loaded only once and
get reused.