################################################################################
    Gfx 2D
################################################################################


Modu do rysowania grafiki 3D - prostoktw i tekstu. Gwnie do rysowania GUI.
Uywa i wcza: "ResMngr.hpp", "Res_d3d.hpp". Wszystko zgromadzone jest
w przestrzeni nazw gfx2d.


Canvas
================================================================================

Gwnym obiektem jest singleton Canvas. Za jego pomoc rysuje si to wszystko.
Trzeba go powiadamia o zdarzeniach urzdzenia - OnDeviceCreate,
OnDeviceDestroy, OnDeviceRestore, OnDeviceInvalidate.

Rysowanie jest wygodne. Polega na swobodnym przestawianiu opcji takich jak:
SetColor (do obydwu - spritw i tekstu), SetSprite (do spritw), SetFont
(do tekstu).

Funkcja DrawRect rysuje prostokt (sprita). Funkcja DrawText rysuje tekst.
Mona te rysowa prostokty wypenione jednolitym kolorem. W tym celu ustawiamy
SetSprite na 0 i rysujemy DrawRect.

Ponadto do ustawiania s w postaci stosu (operacje Push i Pop): Translation
(przesunicie pocztku ukadu - 0,0), ClipRect (prostokt obcinajcy - wzgldem
biecego pocztku ukadu) i Alpha (przezroczysto). W kolorze nie dziaa
skadowa Alpha - przezroczysto trzeba robi za pomoc PushAlpha/PopAlpha.

Mona swobodnie wywoywa funkcje rysujce i przestawia stany canvasa nie
martwic si o to jak on uywa D3D. Jedynie na kocu (kiedy koczymy klatk lub
zamierzamy rysowa co innego, samemu) trzeba nie zapomnie wywoa Flush.

Canvas do rysowania wymaga ustawionego (sam sobie nie ustawi): Lighting=false,
Zenable=false, AlphaBlendEnable, SrcBlend, DestBlend i macierzy (gwnie macierz
rzutowania - pobieramy j z frame::GetMouseCoordsProjection).

Po dostosowaniu Canvas do uycia nowego font managera res::Font w wersji 1.1
moduu Gfx2d, podczas rysowania tekstu dziaa ju wszystko - translacja, kana
alfa oraz nawet prostokt obcinajcy.


Sprite
================================================================================

Sprite to obiekt klasy Sprite. Jest czym wicej ni parametrami podawanymi do
konkretnego rysowania prostokta, ale czym mniej ni zasobem. S pamitane w
singletonie SpriteRepository, ktry dziaa podobnie jak manager zasobw dla
zasobw. Definicje spritw mona wczytywa hurtem z pliku tekstowego XNL2,
pojedynczo z acucha XNL2 lub tworzy cakowicie z kodu. Mona je tworzy i
usuwa dynamicznie w czasie pracy.

Sprite czy zasoby tekstury, efektu oraz przechowuje dodatkowe informacje na
temat fragmentw tej tekstury, ktre maj by uywane do rysowania prostoktw
2D. Jego czas ycia musi by pozbiorem czasu ycia tych dwch zasobw.

Po co spritowi efekt? Sprawa nie jest jednoznaczna, ale jednak si przyda, bo
sprity mog si rni, np. ustawieniami samplera (clamp, filtrowanie liniowe
lub punktowe), wczonym alfa-testem itp.

Modu Gfx2D umoliwia rysowanie fragmentw tekstury sprita jako prostoktw
na ekranie. W tym celu przechowuje definicje elementw na tej teksturze, wyraon
w pikselach (a wic uzalenion od rozmiaru tej tektsury):

1. Elementy proste
   - Sprite moe by albo w trybie, w ktrym elementy proste s macierz.
     Wwczas definiuje si ilo kolumn, szeroko i wysoko pojedynczego
     elementu oraz dodatkowe odstpy.
   - Albo w trybie wasnym prostoktw, w ktrym kady prosty element jest
     opisany rcznie przez wsprzdne prostokta ne teksturze.
2. Elementy zoone
   cz elementy proste w wiksz cao umoliwiajc rysowanie rozcigajcych
   si lub rozkadanych ssiadujco (powtarzajcych si) wzorw wraz z ramkami
   po wybranych bokach czy dookoa.

Elementy s indeksowane jak tablica, wic naley uywa niskich indeksw,
najlepiej kolejnych (0, 1, 2 itd...). Indeks specjalny INDEX_ALL oznacza cao
tekstury sprita. Indeks INDEX_NONE oznacza nie rysowanie niczego. Indeksy
elementw zoonych budujemy uywajc na indeksie funkcji ComplexElement.
Indeksy elementw prostych wpisujemy po prostu.

Skadnia definicji sprita
-------------------------

W jzyku parsowanym przez Tokenizer z z CommonLib

  <nazwa> { <parametry> }

nazwa (string) - nazwa sprita

parametry:

  effect <nazwa>
  texture <nazwa>
  [elementy-proste]
  [elementy-zoone]

elementy-proste:

  matrix {
    <col-count>
    <element-width> <element-height>
    [ <space-x> <space-y>
    [ <start-x> <start-y> ] ]
  }

  lub:

  rects {
    <index> <prostokt>
    <index> <prostokt>
    ...
  }

prostokt:

  { left=<left> top=<top> right=<right> bottom=<bottom> }

  lub

  { left=<left> top=<top> width=<right> height=<bottom> }

elementy-zoone:

  complex {
    <index> <element-zoony>
    <index> <element-zoony>
    ...
  }

element-zoony:

  {
    center = <index> <szeroko> <wysoko> [flagi]
    [ left = <index> <szeroko> <wysoko> [flagi] ]
    [ right = <index> <szeroko> <wysoko> [flagi] ]
    [ top = <index> <szeroko> <wysoko> [flagi] ]
    [ bottom = <index> <szeroko> <wysoko> [flagi] ]
    [ left_top = <index> [flagi] ]
    [ right_top = <index> [flagi] ]
    [ left_bottom = <index> [flagi] ]
    [ right_bottom = <index> [flagi] ]
  }

szeroko, wysoko:

  <float>

  lub:

  <float> %

flagi (identyfikatory):

  ( CW | CCW | UD ) [H] [V]


Przykady
---------

Prosty sprite do rysowania wycznie jako cao z uyciem indeksu INDEX_ALL.

  "Sprite01" {
    effect "SpriteEffect01.fxo"
    texture "SpriteTexture01.png"
  }

Sprite do rysowania przycisku, w ktrym wasne prostokty opisuj trzy obszary
przedstawiajce kolejno: lewy brzeg, rodek i prawy brzeg przycisku. Na wysoko
cao si rozciga, na szeroko rodek si rozciga, a brzegi maj sta
szeroko.

  "Sprite03" {
    effect "SpriteEffect01.fxo"
    texture "SpriteTexture04.png"
    rects {
      0 { left=0, top=0, right=3, bottom=21 }
      1 { left=3, top=0, right=26, bottom=21 }
      2 { left=26, top=0, right=29, bottom=21 }
    }
    complex {
      0 {
        center = 1 100% 100%
        left = 0 3 100%
        right = 2 3 100%
      }
    }
  }

Sprite, na ktrym w macierzy 4x4, w jej lewym grnym obszarze 3x3 s wyrysowane
odpowiednio rogi, boki i rodek rameczki, ktra ma si automatycznie powtarza
(domylnie) lub rozciga bdc powtrzon zawsze 2 razy (fragment
zakomentowany) podczas rysowania jako jeden prostokt.

  "Sprite02" {
    effect "SpriteEffect01.fxo"
    texture "SpriteTexture03.png"
    matrix { 4, 8, 8, 0, 0, 0, 0 }
    complex {
      0 {
        center = 5 32 32
        left = 4 32 32
        right = 6 32 32
        top = 1 32 32
        bottom = 9 32 32
  {/      center = 5 50% 50%
        left = 4 25% 50%
        right = 6 25% 50%
        top = 1 50% 25%
        bottom = 9 50% 25% /}
        left_top = 0
        right_top = 2
        left_bottom = 8
        right_bottom = 10
      }
    }
  }


Techniczne
================================================================================

Quad sprita jest rysowany tak:

  0-------1
  |     / |
  |   /   |       0-1-2, 2-1-3
  | /     |
  2-------3

Przy rysowaniu tak spritw jak i tekstu uywany bdzie zawsze format wierzchoka:
- D3DFVF_XYZ
  z = 1.0f
  Pozycja w jednoskach ukadu 2D frameworka
- D3DFVF_DIFFUSE
  Alfa-blending zawsze wczony
  Kana alfa uywany do rekurencyjnej przezroczystoci
  Kolor uywany lub nie przy blendingu w efekcie
- D3DFVD_TEX1
  Wsprzdne tekstury, uywane lub nie przy blendingu w efekcie
Efekt musi mie parametry:
- Texture : texture

Musi te istnie efekt o nazwie "PlainColor2d.fxo" (bezparametrowy).

