################################################################################
  Kodowanie Windows-1250, koniec wiersza CR+LF, test: Za gl ja
  Math - Modu matematyczny
  Copyleft (C) 2007 Adam Sawicki
  Licencja: GNU LGPL
  Kontakt: mailto:sawickiap@poczta.onet.pl , http://regedit.gamedev.pl/
################################################################################


Wstp
================================================================================

To jest zaanwasowana biblioteka matematyczna. Definiuje typu takie jak wektor
czy macierz. Elementy matematyczne nie wymagajce tych typw, a jedynie
operujce na zwykych liczbach, znajdziesz w module Base. Math to najwikszy z
moduw CommonLib. Zawarte w nim elementy przeznaczone s gwnie do
programowania gier. Math dubluje wikszo funkcjonalnoci biblioteki D3DX z
DirectX w zakresie matematyki, a take implementuje duo innych funkcji wyszego
poziomu, jak kolizje midzy rnymi obiektami geometrycznymi.


Zaoenia
================================================================================

- Przenona.

- Wszystko ma wasne, niezalena, korzystajca tylko z Base.

- Nie uywa wyjtkw moduu Error.

- Moliwoci:
Nie wszystko to co ma D3DX, ale dua cz z tego. Wszystko, co czsto uywane,
wane i potrzebne. Dodatkowo zaawansowane obliczenia typu kolizje midzy rnego
rodzaju obiektami.

- Nastawiona bardziej nia wspprac z DirectX ni OpenGL - ukad wsprzdnych
lewoskrtny, macierze w porzdku wierszowym, kolory w formacie A8R8G8B8 itp.

- W razie zdefiniowania USE_DIRECTX oferuje wygodn i szybk (0 narzutu)
konwersj midzy typami matematycznymi wasnymi a D3DX, poniewa wystpuje
zgodno bitowa.

- Funkcji generujcych czy przeliczajcych rne rzeczy nie s zdefiniowane
wewntrz klas jako metody statyczne ani tym bardziej jako zwyke (typu
obiekt1.ZrbCo(obiekt2)), tylko jako zwyke funkcje globalne, czsto
przecione.

- W funkcjach generujcych czy liczcych co wszelkie struktury bardziej zoone
ni pojedyncza liczba zwracane s przez pierwszy parametr wskanikowy, a nie
przez zwrcenie wartoci.

- Kady kolor reprezentowany jest przez skadowe ARGB, kana alfa jest tak samo
wany i nie jest nigdzie pomijany ani domylnie inicjalizowany. Domylny format
koloru to A8R8G8B8 (kompatybilny z uint4).

- DECYZJA: Jak zrobi operacje, np.:
1. dot3(v1, v2)
2. VEC3::dot(v1, v2)
3. v1.dot3(v2)
DECYZJA: 1
BO:
> Ta opcja jest najkrtsza
> Zapis 3 jest brzydki i nienaturalny, bo niesymetrynczy
> Zapis 2 jest duszy i niczego nie polepsza, bo nawet kiedy bdzie konflikt
  w przestrzeni globalnej to funkcja si przeaduje albo si j inaczej nazwie.

- DECYZJA: Jak zrobi inicjalizacj struktur, np.:
1. PLANE plane1(v1, v2, v3);
2. PLANE plane1; CreatePlane(&plane1, v1, v2, v3);
3. PLANE plane1; plane1.Fill(v1, v2, v3);
DECYZJA: 2, konstruktor tylko do bezporedniej inicjalizacji pl bez konwersji.
BO:
> Opcja 1 sama nie wystarczy, czasem chce si zmieni, wtedy trzebaby doda
  2 lub 3.
> Jest zgodna z konwencj funkcji wypeniajcych, konwertujcych itp.
  Rozrnienie midzy inicjalizacj a konwersj jest pynne.

- Nie ma kolizji odcinka z obiektami.
Dlaczego? Bo mona skorzysta z kolizji promienia i sprawdzi czy otrzymane t
nie przekracza dugoci odcinka (0..1 czy te 0..Dugo).


Skadniki
================================================================================

Modu definiuje nastpujce obiekty geometryczne jako struktury:

- POINT_ - punkt 2D (int)
- RECTI - prostokt 2D (int)
- RECTF - prostokt 2D (float)
- LINE2D - prosta 2D (float)
- VEC2 - wektor/punkt 2D (float)
- VEC3 - wektor/punkt 3D (float)
- VEC4 - wektor/punkt 4D (float)
- MATRIX - macierz 4x4 (float)
- PLANE - paszczyzna 3D (float)
- BOX - prostopadocian 3D (float)
- COLOR - kolor (4 x uint1)
- COLORF - kolor (4 x float)
- QUATERNION - kwaternion (float)

Wspierane s te nastpujce rodzaje obiektw nie majce swoich struktur:

- Trjkt
  Uywa si trzech punktw:
  VEC3 p0, p1, p2
- Promie/prosta 3D
  Uywa si pozycji punktu i wektora kierunku:
  VEC3 Orig, Dir
- Sfera
  Uuywa si pozycji rodka i dugoci promienia:
  VEC3 Center, float Radius


math_cast
================================================================================

To tak naprawd szablon funkcji, ktry w oglnym przypadku nie dziaa (rzuca
assertion failed), ale ma zdefiniowane specjalizacje. Suy do konwersji midzy
typami tego moduu math a typami innymi matematycznymi, np. z Win32API czy D3DX.
Ma zwykle zerowy narzut, bo dokonuje reinterpretacji, a nie adnej konwersji.
Uywa si go intuicyjnie, tak samo jak normalnego rzutowania, np.:

	math::POINT_ Pt(1, 2);
	POINT WinPt = math::math_cast<POINT>(Pt);

Zdefiniowane s nastpujce konwersje:

- midzy common::POINT_ a POINT z Win32API
- midzy common::RECTI a RECT z Win32API
- midzy common::VEC2 a D3DXVECTOR2 z D3DX
- midzy common::VEC3 a D3DXVECTOR3 z D3DX
- midzy common::VEC4 a D3DXVECTOR4 z D3DX
- midzy common::COLOR a uint4
- midzy common::COLOR a unsigned long == DWORD == D3DCOLOR z DirectX
- midzy common::COLORF a D3DXCOLOR z D3DX
- midzy common::PLANE a D3DXPLANE z D3DX
- midzy common::MATRIX a D3DXMATRIX z D3DX
- midzy common::QUATERNION a D3DXQUATERNION z D3DX


Kolizje
================================================================================

Punkt:
- Punkt
  - Czy nachodz na siebie - VecEqual
- Promie, prosta, odcinek
  - Odlego punktu od prostej - PointToLineDistance
  - Czy punkt ley na prostej - PointOnLine
  - Rzut punktu na prost - ClosestPointOnLine
  - Warto parametru t punktu lecego na prostej - PointToLine
  - Punkt naley od odcinka - PointInLineSegment
- Prostopadocian
  - Czy punkt naley do prostopadocianu - PointInBox
  - Odlego punktu od prostopadocianu - PointToBoxDistance
  - Najbliszy punkt z prostopadocianu - ClosestPointInBox
- Sfera
  - Czy punkt naley do sfery - PointInSphere
  - Odlego punktu od sfery - PointToSphereDistance
  - Najbliszy punkt ze sfery - ClosestPointOnSphere
- Paszczyzna
  - Czy punkt naley do paszczyzny - PointOnPlane
  - Odlego punktu od paszczyzny - abs(DotCoord)
  - Najbliszy punkt z paszczyzny (rzut) - ClosestPointOnPlane
  - Po ktrej stronie paszczyzny ley punkt - DotCoord
- Trjkt
  - Czy punkt naley do trjkta - PointOnTriangle
  - Najbliszy punkt z trjkta - (BRAK)
  - Wsprzdne barycentryczne punktu w trjkcie - CalculateBarycentric
- Frustum
  - Czy punkt naley do frustuma FRUSTUM_PLANES - PointInFrustum
  - Najbliszy punkt z frustuma - (BRAK)

Promie, prosta, odcinek:
- Promie, prosta, odcinek:
  - Parametry T najbliszych sobie punktw na prostych - ClosestPointsOnLines
- Prostopadocian
  - Kolizja promienia z prostopadocianem - RayToBox
- Sfera
  - Kolizja promienia ze sfer - RayToSphere
- Paszczyzna
  - Kolizja promienia z paszczyzn - RayToPlane
- Trjkt
  - Kolizja promienia z trjktem - RayToTriangle
- Frustum
  - Kolizja promienia z frustumem - RayToFrustum

Prostopadocian AABB:
- Prostopadocian:
  - Czy dwa prostopadociany koliduj - OverlapBox
  - Suma prostopadocianw - Union
  - Cz wsplna prostopadocianw - Intersection
- Sfera:
  - Kolizja prostopadocianu ze sfer - SphereToBox
  - Sfera w prostopadocianie - SphereInBox
  - Prostopadocian w sferze - BoxInSphere
- Paszczyzna:
  - Kolizja prostopadocianu z paszczyzn - PlaneToBox
  - Klasyfikacja prostopadocianu do paszczyzny - ClassifyBoxToPlane
- Trjkt:
  - Czy trjkt jest wewntrz prostopadocianu - TriangleInBox
  - Czy trjkat nachodzi na prostopadocian - TriangleToBox
- Frustum:
  - Czy AABB jest wewntrz frustuma - BoxInFrustum
  - Kolizja AABB z frustumem - BoxToFrustum_Fast, BoxToFrustum

Sfera:
- Sfera:
  - Kolizja sfery ze sfer - SphereToSphere
- Paszczyzna:
  - Kolizja sfery z paszczyzn - SphereToPlane
  - Klasyfikacja sfery do paszczyzny - SphereToPlane
- Trjkt: (BRAK)
- Frustum:
  - Sfera zawiera si we frustumie - SphereInFrustum
  - Kolizja sfery z frustumem - SphereToFrustum_Fast, SphereToFrustum

Paszczyzna:
- Paszczyzna:
  - Kolizja dwch paszczyzn - Intersect2Planes
  - Kolizja trzech paszczyzn - Intersect3Planes
- Trjkt:
  - Czy paszczyzna koliduje z trjktem - PlaneToTriangle
  - Klasyfikacja trjkta do paszczyzny - ClassifyPlaneToTriangle
- Frustum:
  - Czy paszczyzna koliduje z frustumem (klasyfikacja) - ClassifyFrustumToPlane

Trjkt:
- Trjkt:
  - Kolizja dwch trjktw: TriangleToTriangle
- Frustum:
  - Trjkt wewntrz frustuma: TriangleInFrustum
  - Kolizja trjkta z frustumem: TriangleToFrustum

Frustum:
- Frustum:
  - Kolizja dwch frustumw: FrustumToFrustum


Kolizj odcinka z dowolnym obiektem mona zrobi tak: Dany jest odcinek
o pocztku w punkcie SegOrig, kierunku SegDir i parametrze koca SegEndT oraz
obiekt Co, z ktrym testujemy kolizj. Uyjemy funkcji dla prostej i
niezalenie czy w przypadku kolizji z tyu punktu RayOrig (zwrcone T ujemne)
zwrci miejsce kolizji blisze czy dalsze, odcinek koliduje z obiektem, kiedy:

  float T;
  if (PointInCo(SegOrig, Co))
    return true;
  if (!LineToCo(SegOrig, SegDir, Co, &T))
    return false;
  if (T < 0 || T > SegEndT)
    return false;
  return true;


PoissonDisc
================================================================================

Dostpne s trzy tablice:

  const float POISSON_DISC_1D[];
  const VEC2  POISSON_DISC_2D[];
  const VEC3  POISSON_DISC_3D[];

Ich rozmiary to 100, a formalnie odpowiednio:

  const uint4 POISSON_DISC_1D_COUNT;
  const uint4 POISSON_DISC_2D_COUNT;
  const uint4 POISSON_DISC_3D_COUNT;

S to cigi punktw w przestrzeni 1D, 2D, 3D o skadowych z przedziau 0..1
odpowiadajce prbkowaniu losowemu wg tzw. Poisson Disc. Jest to taki rozkad,
ktry cho losowy to zachowuje okrelon minimaln odlego midzy prbkami,
eby nie skupiay si nadmiernie w jednych miejscach tylko byy rwnomiernie
rozoone w caej przestrzeni. Zastosowania s bardzo liczne.

Te prbki s PROGRESYWNE. To mj autorski pomys. Mona bra dowoln liczb
pierwszych elementw z takiej tablicy i nadal jest to poprawny rozkad Poisson
Disc, tyle e obowizuje dla nich wiksza minimalna odlego midzy punktami.


Czego nie ma
================================================================================

- Macierzy innych ni 4x4, np. 3x3, 3x4 itp.

- Penego wsparcia dla geometrii 2D (s wektory, prostokty i proste w 2D, ale
brakuje kolizji midzy nimi).

- Kolizji obiektw typu Swept - poruszajcych si (dynamicznych).

- Nastpujcych obiektw geometrycznych:
> Oriented Bounding Box (OBB)
> Dowolny wielocian wypuky opisany paszczyznami lub wierzchokami
> Siatka trjktw

- Zaawansowanych algorytmw, takich jak triangulacja, znajdowanie wypukej
otoczki czy Constructive Solid Geometry (CSG).

