Tato skupina funkcí je určena pouze pro programátory dobře znalé problematiky Windows API. Umožňuje doplňování funkcí a vlastností, které programovací systém Petr přímo sám nepodporuje. Pomocí funkcí pro přístup k DLL je možné využívat všechny funkce operačního systému Windows a stejně tak i funkce doplňkových knihoven DLL. Funkce nejsou nijak systémem Petr kontrolovány (jako např. platnost ukazatele v paměti) a může proto nesprávným použitím funkcí dojít ke zhroucení programu, případně až k vážnému poškození dat. Podrobné popisy k systémovým funkcím Windows API SDK je možné získat z internetových stránek Microsoft (www.microsoft.com) v oddělení pro vývojáře.

 

načtení knihovny

 

Parametrem funkce je jméno souboru knihovny DLL (včetně přípony). Funkce zajistí načtení knihovny do paměti a navrátí číselný identifikátor knihovny. Není-li knihovna nalezena, je navráceno číslo 0. K načtení knihovny je využita systémová funkce LoadLibrary, navrácené číslo odpovídá handle načteného modulu.

 

uvolnění knihovny

 

Funkce uvolní z paměti knihovnu, jejíž identifikační číslo je zadáno jako parametr funkce. Je povoleno zadání neplatného čísla 0. K uvolnění knihovny je použita systémová funkce FreeLibrary, zadané číslo odpovídá handle modulu.

 

importování funkce

identifikátor knihovny

jméno funkce

počet parametrů

volací konvence C

 

Funkce importování funkce slouží k vyhledání funkce v knihovně. Je využita systémová funkce GetProcAddress. Jako první parametr se zadává identifikační číslo knihovny načtené v paměti (je povoleno zadání neplatného čísla 0). Druhým parametrem je jméno funkce (text). Není-li zadaná funkce nalezena, je proveden druhý pokus - ke jménu funkce je přidáno písmeno "A" (varianta pro 8-bitové textové parametry). Třetím parametrem je počet parametrů funkce (je kontrolován počet parametrů v rozsahu 0 až 65k). Bez zadání se uvažuje počet parametrů 0. Jedním parametrem se přitom rozumí jedna položka v zásobníku o velikosti 4 bajty (tj. dvouslovo). Poslední parametr je logický příznak udávající, že funkce je volána podle konvence C, tj. po návratu z funkce jsou zrušeny parametry ze zásobníku. Tato volací konvence je využívána např. u funkce printf a u dalších funkcí s proměnlivým počtem parametrů. Všechny ostatní funkce používají volací konvenci Pascal, tj. o zrušení parametrů ze zásobníku se stará volaná funkce (implicitní nastavení). Je-li funkce nalezena, je navrácen paměťový blok se strukturou popsanou dále. Při ukončení programu je nutno tento blok zrušit funkcí pro uvolnění paměťového bloku. Není-li funkce nalezena, je navráceno číslo 0. Všechny parametry funkce jsou při vytvoření paměťového bloku automaticky vynulovány.

 

provedení funkce

 

Prvek provedení funkce zajistí vyvolání a provedení funkce knihovny DLL. Jako parametr prvku se zadává adresa paměťového bloku navráceného předešlou funkcí pro importování funkce. Jedná se o běžný paměťový blok, který lze vytvářet, modifikovat či rušit operacemi pro obsluhu paměťových bloků. Lze si např. připravit několik paměťových bloků pro různé způsoby volání jedné funkce. Paměťový blok pro volání funkce má následující strukturu:

 

(4 bajty) adresa volané funkce

(2 bajty) N počet parametrů funkce (1 parametr je 4 bajtová položka v zásobníku)

(2 bajty) pomocné příznaky: je-li nastaven bit 0, je použita volací konvence C (po návratu z funkce jsou zrušeny parametry ze zásobníku) jinak se použije volací konvence Pascal (o zrušení parametrů ze zásobníku se stará volaná funkce)

(N * 4 bajtů) N parametrů funkce, první parametr je při volání funkce uložen na nejnižší adrese zásobníku

 

Před voláním funkce je nutno nastavit parametry funkce. Implicitně jsou všechny parametry při importování funkce inicializovány na nulu. Nastavení parametrů se provádí pomocí následujících operací pro manipulaci s paměťovými bloky. První parametr je umístěn na offsetu 8 od začátku paměťového bloku. Každý parametr je 4-bajtové číslo (dvouslovo). Pozor na předávání textového parametru - parametrem u převážné většiny funkcí je ukazatel na ASCIIZ text, ne přímo text samotný. Prvek pro provedení funkce může být použit buď jako příkaz nebo jako funkce navracející číselný parametr.

 

vytvoření paměťového bloku

 

Jako parametr prvku se zadává požadovaná velikost paměťového bloku. Prvek navrací adresu paměťového bloku. Při ukončení programu je nutno paměťový blok zrušit následující funkcí pro uvolnění paměťového bloku. Paměťové bloky do velikosti 4 KB jsou obsluhovány vnitřní efektivní obsluhou systému Petr, která zajišťuje rychlé vytváření bloků, modifikaci velikosti i rušení. Pro paměťové bloky o velikosti nad 4 KB je využita systémová funkce HeapAlloc se zarovnáváním bloků na hranici 256 bajtů.

 

uvolnění paměťového bloku

 

Prvek zajistí zrušení paměťového bloku, jehož adresa je zadána jako parametr. Je povoleno zadání neplatné adresy 0.

 

změna velikosti paměťového bloku

adresa paměťového bloku

nová velikost

 

Funkce zajistí změnu velikosti pamětového bloku. Prvním parametrem je adresa paměťového bloku, jehož velikost má být změněna. Zadáním nuly dojde k vytvoření nového paměťového bloku. Druhým parametrem je nová velikost paměťového bloku. Zadáním nuly dojde ke zrušení paměťového bloku. Funkce navrací adresu nového paměťového bloku. Díky vnitřní optimalizaci může být paměťový blok nezměněn (je navrácena stejná adresa bloku). Nevyhovuje-li velikost paměťového bloku, vytvoří funkce nový blok s požadovanou velikostí a obsah starého bloku do něj překopíruje.

 

ukazatel čtení

ukazatel zápisu

 

Prvky ukazatel čtení a ukazatel zápisu slouží k nastavení adresy v paměti, odkud nebo kam se budou ukládat data následujícími prvky pro čtení/zápis dat. Čtením hodnoty některého z následujících prvků dojde k posunu ukazatele čtení, zápisem hodnoty do prvku dojde k posunu ukazatele zápisu. Ukazatele čtení a zápisu nejsou nijak kontrolovány na platnost. Nesprávnou manipulací může dojít k nežádoucí modifikaci paměti systému nebo programu.

 

kopie dat

 

Prvek kopie dat zajistí kopírování bloku dat z adresy nastavené ukazatelem čtení na adresu udanou ukazatelem zápisu. Velikost dat je zadána jako parametr prvku. Ukazatele čtení i zápisu se operací posunou o zadanou velikost dat.

 

porovnání dat

 

Prvek porovnání dat zajistí porovnání bloku dat mezi adresou nastavenou ukazatelem čtení a adresou udanou ukazatelem zápisu. Velikost dat je zadána jako parametr prvku. Je-li nalezen rozdíl mezi daty, navrací prvek velikost zbývajících dat a ukazatele čtení a zápisu zůstanou nastavené na odlišných datech. Jsou-li data shodná, navrátí prvek nulu a ukazatele čtení a zápisu jsou nastaveny za koncem dat.

 

bajt se znaménkem (char) (posun ukazatele o 1)

bajt bez znaménka (BYTE) (posun ukazatele o 1)

slovo se znaménkem (short) (posun ukazatele o 2)

slovo bez znaménka (WORD) (posun ukazatele o 2)

3-bajt se znaménkem (posun ukazatele o 3)

3-bajt bez znaménka (posun ukazatele o 3)

dvouslovo se znaménkem (long) (posun ukazatele o 4)

dvouslovo bez znaménka (DWORD) (posun ukazatele o 4)

reálné číslo 4 bajty (float) (posun ukazatele o 4)

reálné číslo 8 bajtů (double) (posun ukazatele o 8)

logická hodnota (BOOL) (posun ukazatele o 4)

text zakončený nulou ASCIIZ (posun ukazatele o N+1)

ukazatel na text zakončený nulou ASCIIZ (posun ukazatele o 4)

text s pevnou délkou (posun ukazatele o N, kratší text doplněn mezerami)

délka textu s pevnou délkou N (nutno nastavit před použitím předešlého prvku)

 

Pomocí prvků pro přístup k datům lze číst nebo zapisovat do paměti. Čtením prvku je načtena hodnota z paměti, jejíž adresa je udána pomocí ukazatele čtení. Ukazatel čtení se posune o velikost prvku. Nastavením hodnoty prvku se hodnota uloží do paměti na adresu udanou ukazatelem zápisu. Ukazatel zápisu se posune o velikost prvku. U textových prvků jsou použity 8-bitové znaky. Je-li vyžadován text v kódu UNICODE, je nutná konverze textu pomocí systémových funkcí MultiByteToWideChar a WideCharToMultiByte. U převážné většiny funkcí Windows se předává jako parametr ukazatel na text zakončený nulou (typ parametru LPCTSTR) namísto textu samotného. Je-li prvek pro nastavení ukazatele na text zakončený nulou použit, nesmí být obsah použité textové proměnné až do chvíle vyvolání funkce DLL modifikován, jinak se může ukazatel stát neplatným (je předán pouze ukazatel na obsah textové proměnné).

 

čtení dat ze souboru

zápis dat do souboru

 

Prvky čtení dat ze souboru a zápis dat do souboru slouží ke čtení/zápisu bloku dat z/do souboru. Jako parametr prvku se zadává velikost dat ke čtení/zápisu. Paměťové ukazatele čtení a zápisu ukazují na data v paměti, souborové ukazatele ukazují na data v souboru.

 

identifikátor okenního prvku

 

Prvek překonvertovává identifikační číslo okenního prvku systému Petr na identifikační číslo Windows (HWND). Pro neplatný prvek je navrácena nula.

 

vytvoření 3D objektu z paměťových bloků

počet vrcholů

vrcholy

normály (0=auto)

mapování textur (0=není)

barvy (0=nejsou)

počet plošek

plošky

 

Prvek slouží k rychlému a efektivnímu vytvoření 3D objektu 3D grafiky např. pomocí výpočtu. Prvek navrací identifikační číslo vytvořeného objektu.

 

Jako první parametr je uveden počet vrcholů objektu. Druhým parametrem je adresa paměťového bloku, obsahujícího souřadnice jednotlivých vrcholů. Každý vrchol je určen pomocí 3 reálných 4-bajtových čísel představujících souřadnice X, Y a Z vrcholu.

 

Třetím parametrem je adresa paměťového bloku obsahujícího normály. Tento parametr může být buď neuveden nebo uvedena 0, v tom případě budou normály objektu vygenerovány automaticky s úhlem pro zjemnění 0.5. Jsou-li normály použity, musí jejich počet odpovídat počtu vrcholů. Normály jsou zadány stejným způsobem jako vrcholy (3 reálná 4-bajtová čísla).

 

Čtvrtým parametrem je adresa paměťového bloku obsahujícího definice mapování textur. Pro každý vrchol objektu je zadána dvojice reálných 4-bajtových čísel představujících horizontální a vertikální souřadnici bodu v textuře. Levý horní roh textury má souřadnici (0,0), pravý dolní roh souřadnici (1,1). Není-li potřeba mapování textury používat, lze parametr vynechat nebo uvést 0.

 

Pátým parametrem je adresa paměťového bloku obsahujícího definice barev jednotlivých vrcholů objektu. Barva pro každý vrchol je zadána jako 4 reálná 4-bajtová čísla představující barevné složky RGBA v pořadí červená, zelená, modrá a alfa složka. Každá ze složek má rozsah 0 (=černá) až 1 (=plný jas), hodnota 0 pro alfa složku představuje průhlednost a 1 plnou viditelnost. Počet barev musí souhlasit s počtem vrcholů objektu. Nejsou-li definice barev požadovány, lze namísto adresy zadat 0 nebo parametr vynechat, použije se jednotná barva pro celý objekt.

 

Šestý parametr udává počet trojúhelníkových plošek, ze kterých je objekt sestaven. Sedmým parametrem je adresa paměťového bloku obsahujícího definice jednotlivých plošek objektu. Každá z plošek je trojúhelník o 3 vrcholech. Jedna ploška je určena 3 celočíselnými 4-bajtovými čísly bez znaménka představujícími indexy vrcholů. Jeden vrchol může být sdílen více ploškami.

 

paměťový blok z 3D objektu

 

Prvek umožňuje zpřístupnění definice 3D objektu 3D grafiky pro účely exportování objektu nebo vytvoření modifikované verze objektu. Parametrem prvku je identifikační číslo objektu.

 

Prvek navrací adresu paměťového bloku obsahujícího definici objektu. Tento paměťový blok má velikost 32 bajtů a obsahuje osum 4-bajtových celočíselných položek bez znaménka. Význam jednotlivých položek odpovídá popisu předešlého prvku vytvoření 3D objektu z paměťových bloků.

 

offset 0: parametry, nyní rezervováno a nastaveno na 0

offset 4: počet vrcholů objektu

offset 8: adresa paměťového bloku obsahujícího souřadnice vrcholů

offset 12: adresa paměťového bloku obsahujícího normály

offset 16: adresa paměťového bloku obsahujícího mapování textur (0=není)

offset 20: adresa paměťového bloku obsahujícího barvy vrcholů (0=není)

offset 24: počet plošek objektu

offset 28: adresa paměťového bloku obsahujícího definice plošek

 

Důležité: Navrácený paměťový blok s definicí objektu stejně jako jednotlivé paměťové bloky s daty jsou nově vytvořené a musí být proto po ukončení práce s daty zrušeny.