Utility library for DirectX 9.0 – Technická dokumentace
Úvod Dokumentace je určena pro programátory, kteří chtějí knihovnu používat ve svých programech, vysvětluje, co knihovna umí, jak se jednotlivé části používají, a rozebírá konceptuální strukturu knihovny. Zahrnuje také srovnání celkové struktury s knihovnou XNA, což je jedna z nejvýznamnějších dostupných knihoven postavených nad DirectX (pro jazyk C#). Pro správné pochopení vyžaduje znalost jazyka C++ a počítačové grafiky (alespoň na konceptuální úrovni), výhodou je také znalost samotného DirectX. Dokumentace se nezabývá vnitřní implementací a strukturou tříd, funkcí a modulů DirectX, k tomu slouží vlastní dokumentace knihovny. U některých částí ale podává základní nástin jejich funkce. Názvy uvedené v hranatých závorkách v jednotlivých částech jsou jména metod, které rozebíraný problém řeší. Tyto vysvětlivky jsou uváděny, jen pokud má objekt mnoho různých metod, pro zpřehlednění.
Technické požadavky K tvorbě a překladu knihovny bylo použito Microsoft Visual Studio 2008 a pro její použití je vyžadována stejná nebo novější verze. Pro ostatní překladače není správné fungování zajištěno. Dále potřeba nainstalovaná Microsoft DirectX SDK (verze August 2009), nebo novější. Knihovna pro rozumné využití vyžaduje grafickou kartu, která umožňuje hardwarovou akceleraci s použitím shaderů (alespoň verze 2).
Konceptuální struktura Knihovnu tvoří široká škála managerů (správců), které zajišťují všechny důležité služby, hlavně komunikaci s uživatelem a grafickým hardwarem. Managery jsou tvořené jako singletony a je tedy možné k nim přistupovat z jakéhokoliv místa aplikace a používat jejich metody. Mezi managery je přísná hierarchie, proto je nutné přesně dodržovat postup jejich vytváření a používání (mnohé managery sami používají jiné jim nadřazené). Pro usnadnění tvorby managerů obsahuje knihovna několik tříd pro jejich tvorbu, tyto třídy při správném použití vytvoří kompletní hierarchii a tím tedy celý runtime k následnému použití. Po vytvoření celé hierarchie (nebo jen potřebné části), je možné jednoduše z kteréhokoliv místa přistupovat k potřebným službám, aniž by jednotlivé objekty museli nějak složitě získávat adresy jednotlivých managerů. Nemusí je také dále předávat volaným metodám či objektům, protože ty se k nim dostanou stejně jako oni. Tento postup má své výhody i nevýhody. Mezi hlavní výhody patří snížení počtu argumentů mnoha metod a konstruktorů objektů, dále také snížení počtu proměnných objektů, sloužících k uchovávání těchto parametrů. Některé vlastnosti DirectX dělají z tohoto postupu navíc ještě bezpečnostní opatření, například je rozumné, aby grafické zařízení (softwarové rozhraní pro grafický hardware) existovalo v jednu chvíli jen jedno, téměř všechny metody toto rozhraní potřebují. Díky tomu, že toto rozhraní spravuje manager, existuje vždy právě jedno a všechny metody k němu mohou přistupovat, aniž by museli mít o argument více. Právě počítačová grafika, která má takovýchto objektů (musí být jen jeden a všichni ho potřebují) více je pro tuto architekturu velmi vhodná. Tento postup s sebou také nese několik nepříjemných nevýhod, takto tvořené třídy (hlavně ty knihovní) jsou mnohem méně průhledné a není na nic vidět, co ke své
funkci potřebují. Dále je potřeba dávat pozor, aby se managery správně vytvořili, správné pořadí a data jsou nutností. Také je potřeba dávat pozor, aby nebyl některý manager smazán (kromě konečného úklidu), managery je možné si ukládat do lokálních proměnných a ty potom v rámci automatického rušení na konci bloku nám mohou zrušit také managery do nich přiřazené! Knihovna XNA je naopak postavena podle klasického objektového modelu. Všechny důležité součásti grafického runtime jsou normální objekty, a aby k nim mohli metody vlastních tříd přistupovat, musí je odněkud dostat jako parametr, nebo je musí třída mít jako datovou položku. To vede k narůstání počtu parametrů a položek tříd a metod. Obzvlášť nepříjemný je tento fakt, pokud několik negrafických (které nic sami nekreslí, nebo neupravují) metod nakonec volá nějakou grafickou metodu. Všechny nadřazené metody musí tedy mít jako parametr rozhraní k hardwaru a musí si ho vzájemně předávat, a až poslední (grafická) metoda toto rozhraní skutečně využívá. Xna se dělí na obal DirectX a poměrně silný herní framework. Herní framework má pro řešení problému s předáváním managerů vytvořen registr serivic (aplikace tam postupně zařazuje důležité objekty) ve třídě Game. Seznam, kde je možné jednotlivé potřebné objekty zaregistrovat a přistupovat k nim přes třídu Game (základní třída herního frameworku). Toto použití ovšem vyžaduje použití implicitního frameworku (často má uživatel příliš specifické požadavky a není to možné) a také předávání odkazu na třídu Game (jen jeden parametr, ale to zase vede ke špatné průhlednosti tříd, které takto fungují). Knihovna (StarLib) dále obsahuje mnohá užitečná rozhraní (kamera, registr…) a k nim většinou nějakou rozumnou základní implementaci, která pomůže snadnému začátku práce. Další poměrně rozsáhlou částí je knihovna ladicích nástrojů. Obsahuje několik druhů vylepšených maker Assert, která jsou rozšířena o některé možnosti, nebo o spolupráci s grafickým systémem. Sem právě patří i profiler, jedná se o jednoduchý grafický profiler umožňující zobrazování běhových informací na obrazovku, nebo do souboru. Profiler je navržen, tak aby při správném použití byl viditelný jen v debug modu, při překladu do release modu se volání profileru smažou. Posední velkou částí je inicializační systém. Knihovna obsahuje třídy pro načítání a procházení souborů SML (podmnožina XML), ve kterých mohou být setupové informace. Pro použití připravených tříd je třeba zapsat inicializační informace speciálním způsobem, tyto třídy pak dokážou sestavit v podstatě kompletní runtime úplně bez práce (chybějící informace nahradí default hodnotami – rozumnými). Definice formátu souborů a popis jak musí bít specifikované inicializační informace (pro použití knihovních tříd) je v poslední části dokumentu.
Managery (popis a hierarchie) Managery jsou uspořádány do velmi jednoduché, stromové hierarchie (logicky odvoditelné – bez manageru grafiky nejde vytvořit grafický font). -
FileManager (závislost: - ) Jedná se o jednoduchého správce souborů, který kontroluje přístupová práva. Drží seznam právě otevřených souborů a ke každému si pamatuje ukazatel na vlastníka a při žádání o zdroj, žadatel předá svůj ukazatel (většinou this), manager zkontroluje otevřené soubory a předaný ukazatel a buď soubor vydá, nebo žádost zamítne [OpenFile, GetFile]. Manager toho nedělá příliš mnoho, jen otevírá a zavírá soubory a kontroluje práva přístupu. Ale umožňuje také soubor otevřít soubor a pak ho kontrolovaně sdílet napříč celou aplikací. Umožňuje také nastavení výchozích cest a pak hledá požadované soubory na těchto cestách [OpenFileInPath].
- smlParser / smlTree (závislosti: FileManager) Parser a tree slouží k načítání a zpracování inicializačních souborů SML. Parser načítá soubory a ukládá je do tree, kde jsou uloženy ve stromové struktuře a jsou rychle dostupné [ParseSML]. Pro přístup se používá jméno žádaného elementu kvalifikované jménem nadřízených elementů (spojené tečkou) [operator[]]. - Timer (závislost: - ) Timer je jednoduchý časovač, pro získávání časových informací používá api funkci QueryPerformanceCounter, která vrací čas v milisekundách a je velmi přesná. Časovač umožňuje výpočet uplynulého času, ale sám si žádné takové informace neuchovává. -
MainWindow (závislost: - ) Toto je správce hlavního okna, zajišťuje jeho vytvoření a stará se o správu základních událostí (ukončení aplikace, resize okna, minimalizace/maximalizace). Manager se nezabývá zpracováním vstupu od uživatele. -
Direct3D (závislost: smlTree/smlParser, MainWindow) Správce grafického zařízení a rozhraní, nejdůležitější správce v celém systému. Pomocí dat ze sml souborů, nebo parametrů (získaných jinak) je možné bezpečně vytvořit grafické zařízení, které bude vyhovovat požadavkům a respektovat hardware. Manager přijme požadované vlastnosti pro budoucí rozhraní, zkontroluje, zda jsou kompatibilní s hardwarem a vytvoří rozhraní (pro hardware). V případě že některé nastavení není kompatibilní, nic neudělá a oznámí to volajícímu. Knihovní engine umožňuje pohodlné načítání parametrů ze souboru, včetně několika alternativních nastavení, pokud některá konfigurace není realizovatelná na hardwaru. Manager také zajišťuje bezpečnou správu grafických zdrojů, zařizuje vyřizování OnLost a OnReset událostí (vyvolávají se např., pokud je okno zvětšeno). Třídy, které jsou potomkem rozhraní Registered jsou zaregistrovány automaticky a nemusí již řešit nic víc [OnLost/OnReset, AddListener]. Poslední jsou metody Reset a Resize, které je nutné zavolat hlavně, po změně nastavení zařízení (aby se změny projevili). -
Font (závislost: Direct3D) Správce fontů, usnadňuje výpis informací na obrazovku, uchovává seznam vytvořených fontů (jen std 2D fonty, žádné prostorové). Pokud je nastaven, tak si drží také jeden default font, který předává na požádání bez složitého volání. Jména fontů jsou shodná se jmény používanými v celých windows (třeba ve Wordu). Jednotlivé objekty postupně mohou žádat o registraci fontů, pak získat jejich popis a použít je k vypisování informací na obrazovku. -
Profile (závislost: Direct3D, Font, Timer) Správce knihovního profileru, který umožňuje volání v kódu obalovat profilovacími značkami (PROFILEBEGIN a PROFILEEND + jméno značky) a potom sledovat průběh těchto volání (délka volání, počet volání za frame,…). Profiler umožňuje výstup do souboru, nebo na obrazovku (nastavuje se při vytváření). Nakonec je potřeba na konci každého framu zavolat uložení nasbíraných informací*PROFILEDUMB+ a vykreslit je podle nastavení*PROFILEPRINT]. -
DirectInput (závislost: Direct3D) Manager spravuje vstup od uživatele (klávesnice a myš), pro získávání změn stavu vstupu vytváří nové vlákno a v něm provádí periodické dotazování (perioda je možná nastavit, lze i načíst ze souboru). Kontrolu stavu vstupu (hardwarově) provádí tedy automaticky, ale pro zjištění stavu (toho
co manager načetl z hardwaru) žádá aplikace manager nezávisle na jeho vlastní práci, volají metodu. Metody pro získávání informací o tlačítkách klávesnice a myši, či poloze myši lze volat ze kteréhokoliv místa aplikace bez dalších opatření. -
AnimationEffect (závislost: Direct3D) Správce hlavního knihovního efektu (vertex a pixel shaderů), pomáhá efekt sestavit, nastavit parametry shaderů a aplikovat je na modely. Manager předpokládá efekt určitého tvaru (jména parametrů, shaderů), standardně používá přiložený effect - vblend2.fx (v něm se dá inspirovat při návrhu vlastního). Při kreslení modelu je potřeba efekt explicitně inicializovat, zapnout a použít (nejde automaticky). V principu se jedná jen o obal standardního Effectu DirectX, používá se téměř totožně. - MgrFactory / SetupFactory Hlavní sestavovací manager, v podstatě se jedná jen o správce tvorby runtimu. MgrFactory sestavuje požadované managery, bez jakékoliv další úpravy (zvolený manager se vybírá předaným číslem, které je vysvětleno u metody v komentáři). SetupFactory managery vytvoří, ale navíc se pokusí načíst inicializační soubory a použít nastavení v nich uvedené. Pokud je hlavní metoda ConstructObject použita v cyklu 0,1,..n, pak se správnými inicializačními soubory vytvoří sama celý runtime. Obě verze navíc kontrolují vzájemné závislosti managerů a nedovolí vytvořit managery, které nemají splněné předpoklady. SetupFactory nabízí navíc velmi užitečnou metodu GetConst, která umožňuje získat text libovolného elementu kdekoliv v smlTree (pokud není v prostoru konstant, je potřeba plná kvalifikace), navíc je jí možné předat parametr, který vrátí, pokud daný element nenajde (default hodnotu).
Model (popis třídy) Implementace modelu je třída SkinnedMesh. Dále k ní patří třída AllocMeshHierarchy, která je jen pomocný objekt pro načítání modelu ze souborů X. SkinnedMesh je třída, k jejímu vytvoření je třebas jen jméno souboru X v němž je model uložen (takový soubor je možné získat třeba pomocí 3DS Max). Při vytváření si model sestaví definici vertexů (pozice, normál, textura), načte mesh, kostru a animace ze souboru. U meshe si poznamená informace o skinu (rozložení a váhu kostí), kostru si rozloží (jednotlivé matice na posun a rotaci, kvůli animování) a animace nahraje do AnimationContoleru (vnitřní struktura DirectX). Hlavní metody jsou update (vytvoření současného stavu animace) a draw (alikace animované kostry). Update vezme kostru, a rekurzivně násobí kosti maticemi animace a převádí je, aby působili vzhledem k centru modelu, ne vzhledem k nadřazené kosti. Výsledkem je seznam matic, které je možné aplikovat podle váhy přímo na vrcholy modelu. V metodě draw se použije AnimationEffect (managerem spravovaný efekt), kterému se předá animací upravená kostra a model se vykreslí.
StarDebug (popis ladicí části knihovny) Ladicí část knihovny obsahuje několik vylepšených verzí makra Assert, některé základní funkce (parsování řetězců, konvertování) a základní definici funkce okna pro MainWindow manager (není zajímavá pro vývoj a neměla by se měnit).
Assert Základní makro Assert funguje stejně, jako skoro standardní assert. Navíc umí kopírovat svůj text (jako Ctrl+C), breanknout aplikaci v místě, kde chyba nastala (ne v knihovně obsahující Assert) a ještě má tlačítko IgnoraAlways, které umožňuje tento konkrétní assert po zbytek běhu aplikace ignorovat (hodí se například v cyklu, pokud je tam jako nějaká kontrolní hláška). Navíc, pokud by se měla vyhodit chyba, tak také vrátí false (používá se ve funkcích, aby zjistili, že nastala chyba). cAssert je stejný jako Assert, jenom nevrací false (používá se v konstruktorech, nebo procedurách). PersistentAssert je zvláštní druh Assertu,který nezmizí v release modu, ale nadále funguje jako Assert. CommonUtils Soubor obsahuje některé konverzní funkce a klonování řetězců bez mezer. Hlavní je ladicí makro HR a cHR (assert pro DirectX), která fungují jako Assert a cAssert, akorát umožňují lepší spolupráci s objekty DirectX.
Inicializační soubory (popis struktury a formát SML) Standardní formát pro inicializační soubory knihovny je formát SML, pro správnou inicializaci je třeba alespoň soubor Setup.sml, umístěný, tak aby k němu aplikace mohla. Všechny další části inicializace jsou už závislé na definicích uvedených v tomto souboru. Zabudovaný parser umožňuje jen úplné (načte najednou celý soubor) načítání, a není vhodné pro příliš veliké soubory (navrženo je na malé inicializační soubory). SML SML znamená “simple markup language” a jedná se o podmnožinu jazyka XML. Formát dovoluje jen elementy a komentáře. Dokument musí mít jeden hlavní element (obsahující všechny ostatní). Elementy mohou obsahovat text, elementy, nebo komentáře. Komentář je při parsování kompletně vymazán z načteného textu. Elementy a komentáře se nesmějí překrývat ( { [ } ] ). Jména elementů nejsou nijak omezená (jen musí být bez mezer). Setup.sml Hlavní inicializační soubor, obsahuje jména dalších souborů, jméno hlavních dvou prostorů – grafického (definice startovního nastavení grafického rozhraní) a prostoru konstant (obsahuje hlavní konstanty programu). Všechny prostory se hledají buď v samotném Setup.sml, nebo v některém ze souborů načtených díky elementu files. -
files : středníkem zakončená jména inicializačních souborů, které se mají při startu načíst (jejich obsah bude možné dále používat) graphics : kvalifikované jméno elementu, ve kterém je uloženo nastavení grafického rozhraní const: kvalifikované jméno elementu, ve kterém jsou uloženy hlavní konstanty (používané runtimem, aplikace může používat vlastní prostory)
Grafické nastavení je definováno v elementu (v jednom z načtených souborů) a definuje základní vlastnosti celého zařízení. Umožňuje také definovat další verze prostoru, pokud použití tohoto skončí s chybou. Přípustné a defaultní hodnoty jsou uvedeny v knihovní verzi souboru.
-
adapter : definuje grafickou kartu, která se má použít pixel : definuje pixelformat pro obrazovku device : určuje, jaká se použije verze zařízení (akcelerovaná, nebo simulovaná) rasterization : určuje, zda použít akceleraci při vykreslování antialiasing : definuje požadovaný antialiasing shader : definuje minimální požadovanou verzi shaderů, které musí hardware podporovat fullcreenResolution : startovní rozlišení okna aplikace při celé obrazovce windowedResolution : startovní rozlišení okna aplikace při běhu v okně window : určuje, zda má aplikace běžet v okně, nebo přes celou obrazovku při startu error : definuje alternativní prostor (obsahující grafické nastavení), pro případ že by toto nastavení nešlo použít, případně může obsahovat pokyn skončit aplikaci s fatální chybou (pokud už není žádné nastavení, které by se dalo použít).
Konstanty jsou standardní elementy (obsahují jen text), které jsou obsaženy v lementu definovaném v Setup.sml pomocí elementu const.
