################################################################################
    Framework
################################################################################
Autor  : Adam Sawicki
Wersja : 6.1
Data   : 8 lutego 2007



Framework to szkielet aplikacji Direct3D. Zakres odpowiedzialnoci:

- Tworzenie, usuwanie, zarzdzanie oknem Windows.
- Obsuga okna - sterowanie moliwociami, odbieranie komunikatw (skalowanie,
  minimalizacja, utrata aktywnoci itp.)
- Tworzenie, usuwanie, ponowne tworzenie i resetowanie obiektu Direct3D oraz
  urzdzenia Direct3D.
- Obsuga utraty urzdzenia.
- Udostpnianie do uytku obiektw: okna, obiektu D3D, urzdzenia D3D
- Zmiana ustawie graficznych.
  Jeli si nie uda, powrt do poprzednich.
- Przechwytywanie i obsuga bdw moduu Error.
- Obsuga pli komunikatw.
- Obsuga wejcia z klawiatury i z myszy.
- Pomiar czasu. Zliczanie FPS.
- Wczytywanie z pliku i zapisywanie do pliku ustawie graficznych.


Config.dat
==========

Wikszo opcji nie bya i nie jest opisana bo ich znaczenie i moliwe wartoci
s w miar oczywiste.

FlushMode = None, Event, Lock
Sposb, w jaki aplikacja ma oczekiwa na zakoczenie renderowania przed
zaprezentowaniem klatki.
None - brak oczekiwania. To jest warto domylna, najszybsza i zalecana o ile
nie wystpuj adne problemy. Jeli wystpuje zjawisko "rwania si" animacji
albo zjawisko nie-rysowania caej geometrii tylko czci, naley wczy Event,
a jeli to nie pomoe, najbrutalniejsz metod, czyli Lock.


LoopMode
========

Program moe pracowa w dwch trybach: "LoopMode" na true lub na false.

- true oznacza, e program cay czas ptli si na maxa wykonujc kolejne klatki
  animacji OnFrame
- false oznacza, e program nie wykonuje klatek, a jedynie czeka na komunikaty
  do okna i reaguje na polecenie odrysowania Redraw - tylko kiedy zachodzi
  potrzeba odrysowania okna wykonuje OnFrame

Tryb ten mona zmienia w dowolnej chwili funkcj SetLoopMode. Domylnie jest
true.


OnFrame
=======

Trzeba sobie samemu zrobi Clear, BeginScene i EndScene. Present jest robione
przez framework. W OnFrame lepiej najpierw narysowa, potem zostawi rysowanie i
policzy - wtedy dziaa szybciej.

UWAGA! Wywoywa Clear, BeginScene, EndScene i w ogle rysowa wolno tylko
po sprawdzeniu e (frame::Dev && !frame::GetDeviceLost()).


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

- Enumeracji trybw graficznych.
Framework jest przezroczysty - daje dostp do obiektw Direct3D i urzdzenia.
Enumeracja adapterw czy trybw to sprawa tak prosta i tak indywidualna, e
nie ma sensu zamyka jej we frameworku.

- DirectInput, obsugi joystickw i innych manipulatorw
Obsugiwane jest tylko wejcie z klawiatury i z myszy i wystarcza do tego
(a nawet najlepsze jest do tego) zwyke Windows API.


Zdarzenia
=========

Wywoania poszczeglnych funkcji / callbackw ukadaj si tak:

OnCreate()
  OnDeviceCreate()
    OnDeviceRestore()
	  OnFrame()
	OnDeviceInvalidate()
  OnDeviceDestroy()
OnDestroy()

Przy czym jeli pewna inicjalizacja zakoczy si bdem:

- adne funkcje wewntrzne nie s wywoywane.
- Komplementarna funkcja finalizujca zostanie wywoana.

Jak wida z poniszych scenariuszy, trudno okreli jasn zaleno w sekwencji
wywoa zdarze z pierwszej i z drugiej z tych grup:

OnCreate - OnDestroy
  Jednorazowo, inicjalizacja i finalizacja aplikacji.
OnDeviceCreate - OnDeviceDestroy
  Po utworzeniu i przed usuniciem urzdzenia.
OnDeviceRestore - OnDeviceInvalidate
  Po utworzeniu lub zresetowaniu oraz przed zresetowaniem lub usuniciem
  urzdzenia.

OnRestore - OnMinimize
  Podczas przywracania oraz minimalizacji lub Alt+Tab itp. kiedy na penym
  ekranie.
OnActivate - OnDeactivate
  Podczas uzyskiwania oraz utraty aktywnoci (ogniska) przez okno programu.
OnResume - OnPause
  Podczas odzyskiwania i utraty czasowej zdolnoci do ptlenia si.

Typowe scenariusze:

- Uruchomienie aplikacji:
    OnActivate - OnCreate - OnDeviceCreate - OnDeviceRestore
- Wyczenie aplikacji:
    OnDeviceInvalidate - OnDeviceDestroy - OnDestroy - OnDeactivate
- Przeczenie si na inne okno (program w oknie):
    OnDeactivate
  Powrt:
    OnActivate
- Skalowanie (program w oknie)
  Pocztek:
    OnPause
  Koniec:
    OnDeviceInvalidate - OnDeviceRestore, OnResume
- Przenoszenie
  Pocztek:
    OnPause
  Koniec:
    OnResume
- Wcinicie lewego Altu jako wejcie do menu okna
  Pierwsze nacinicie:
    OnPause
  Drugie nacinicie:
    OnResume
- Minimalizacja programu (program w oknie):
  Minimalizacja:
    OnMinimize - OnDeactivate
  Przywrcenie:
    OnActivate - OnRestore
- Alt+Tab na penym ekranie:
  Wyjcie:
    OnDeviceInvalidate - OnDeactivate
  Przywrcenie:
    OnActivate - OnRestore - OnPause - OnDeviceRestore - OnResume
- Maksymalizacja okna
    OnPause - OnDeviceInvalidate - OnDeviceRestore - OnResume
  Przywracanie okna ze zmaksymalizowanego:
    OnPause - OnDeviceInvalidate - OnDeviceRestore - OnResume


Ukad wsprzdnych
===================

Framework okrela tzw. ukad wsprzdnych myszy. Uywa go do podawania
wsprzdnych kursora myszy. Udostpnia te macierz rzutowania ortogonalnego
zbudowan na jego bazie. Dziki temu mona uywa go w caym systemie GUI i
caej grafice 2D w aplikacji.

Ukad okrelaj parametry podawane do funkcji Go:

- MouseCoords : MOUSE_COORDS
- MouseCoordsWidth, MouseCoordsHeight

Dostpne s trzy tryby - MC_PIXELS, MC_FIXED_HEIGHT, MC_FIXED. Po szczegy
patrz komentarze tego enuma we Framework.hpp.


Wielowtkowo
==============

Modu nie jest bezpieczny wtkowo. Naley go uywa tylko z jednego wtku.


Wyjtki
=======

Modu zajmuje si obsug wyjtkw. Wyjtki nigdy nie wylatuj z funkcji gwnej
Go, za to mona zgasza swoje w funkcjach callback wywoywanych przez framework
i on je przechwyci i obsuy.


Ustawienia graficzne i konfiguracja
===================================

Framework wczytuje konfiguracj gwn programu z pliku "Config.xnl" i umieszcza
w zmiennej globalnej g_Config z moduu Config. S tam ustawienia graficzne, ale
mog te by dowolne dodatkowe ustawienia dla warstw niszych aplikacji.

Zmiany w konfiguracji mona wprowadza w czasie pracy programu i mona j
zapisa do pliku (np. w zdarzeniu OnDestroy) uywajc funkcji:

- WriteSettingsToConfig - wpisuje biece ustawienia wywietlania
  do konfiguracji
- SaveConfig - zapisuje konfiguracj do pliku

Ustawienia mona zmienia w czasie pracy programu funkcj ChangeSettings. Jest
to tak naprawd danie zmiany trybu, ktore zostanie wykonane przed nastpn
klatk.

Uytkownikowi mona da do wyboru tryby, a te, ktre maj pozosta niedostpne
do zmiany pozostan po prostu z wartoci tak, jak maj zapisan w pliku
z ustawieniami.

Plik jest w formacie moduu Config opartym o jzyk XNL2. Poszczeglne klucze i
ich wartoci to:

- BackBufferWidth : uint4
- BackBufferHeight : uint4
- RefreshRate : uint4
- BackBufferFormat : D3DFORMAT
  Dostpne s stae D3DFMT_ bez tego przedrostka, pisane z duej litery, np.
  "A8R8G8B8", a take liczby uint4.
- BackBufferCount : uint4
- MultiSampleType : D3DMULTISAMPLE_TYPE
  Dostpne s stae D3DMULTISAMPLE_ bez tego przedrostka pisane z duej litery,
  np. "NONE", a take liczby typu uint4.
- MultiSampleQuality : uint4
- SwapEffect : D3DSWAPEFFECT
  Dostpne s stae D3DSWAPEFFECT_ bez tego przedrostka pisane z duej litery,
  np. "DISCARD", a take liczby typu uint4.
- FullScreen : bool
- EnableAutoDepthStencil : bool
- AutoDepthStencilFormat : D3DFORMAT
  Patrz wyej.
- DiscardDepthStencil : bool
- LockableBackBuffer : bool
- PresentationInverval : uint4 {Presentation Interval}
  Dostpne s stae D3DPRESENT_INTERVAL_ bez tego przedrostka z duej litery,
  np. "DEFAULT", a take liczby typu uint4.
- Adapter : uint4 {Adapter}
  Dostpne s liczby typu uint4, a take warto specjalna "DEFAULT".
- DeviceType : D3DDEVTYPE
  Dostpne s stae D3DDEVTYPE_ bez tego przedrostka z duej litery, np. "HAL",
  a take liczby typu uint4.
- VertexProcessing : uint4 {Vertex Processing}
  Dostpne s stae D3DCREATE_*_VERTEXPROCESSING bez tego przedrostka i
  przyrostka z duej litery, np. "HARDWARE", a take warto specjalna "AUTO"
  oraz liczby typu uint4.

