{ MANUAL1.TXT                                     Copyright (c) Martin Kolecek }
{                                                                              }
{ Author: Martin Kolecek                                                       }
{ Datum: 01.05.2011                                      http://www.trsek.com  }
 
{XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
SLOVO UVODEM
 
Unit Engine.pas je urceny pro DOS, pro Borland Pascal 7.0 realny rezim, nebo
freepascal. Ma za cil vytvareni jednoduchych 2D her s podporou slozitych zvuku 
pres PC-Speaker na pozadi behu programu, drzeni nekolika klaves na klavesnici
najednou, BMP soubory a grafika podobna na 8mi-bitove NINTENDO. Plati zde 
limit 640KB takze pri pouziti vsech hlavnich funkci enginu vytvorite program
velky maximalne 90KB (samozrejme se nepocitaji data externich souboru) pak
dojde k chybe "heap overflow" (naraz na limit 640KB), takze je to vhodne spis
na male projekty jako je ukazkova hra milknuts. Ovsem je treba uvest ze o
vsechno je uz postarano v enginu od grafiky pres zvuky az po mapu takze se
muzete soustredit hlavne na hru samotnou. Verze pro freepascal limitem 640KB
samozrejme netrpi.
 
Pokud nechcete do knihovny zasahovat pouzijte jiz hotovy unit. Pro pripad ze
chcete do knihovny zasahovat: 4 soubory obj ktere se nachazeji ve slozce
NETWIDE je treba prilinkovat ke knihovne, zmente si v souboru engine.pas
nasledujici radky:
 
{$L C:\ENGINE\BP7\SOURCES\NETWIDE\blok.obj}
{$L C:\ENGINE\BP7\SOURCES\NETWIDE\writeblk.obj}
{$L C:\ENGINE\BP7\SOURCES\NETWIDE\flippage.obj}
{$L C:\ENGINE\BP7\SOURCES\NETWIDE\clearpag.obj}
 
tak aby odpovidaly vasemu umisteni na harddisku a spravne ukazovaly na obj.
 
Verze pro freepascal nevyzaduje zadne externi soubory.
 
{XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
O DOSBOXU
 
Pokud chcete engine provozovat pod DOSBoxem tak problemy by nastat nemely u
hotovych programu vytvorenych s verzi knihovny pro BP7, az na editory
datovych souboru (gra,snd,map). Editory jsou v DOSBoxu tak pomale, ze jejich
pouziti je nemozne. Budete potrebovat cisty DOS nebo Win9x rezim DOSu. Stejne
tak verze knihovny pro freepascal je v DOSBoxu prilis pomala (asi 35-40 fps).
Verze pro Borland Pascal 7.0 navic obsahuje funkce na XMS. Tyto funkce mi
nefungovaly a zastavovaly program kdyz jsem ho spoustel z editoru BP7 pod
DOSBoxem ovsem zkompilovat to slo a spoustet pak jiz hotovy program mimo
editor Borland Pascalu fungovalo pod DOSBoxem taky bez problemu. XMS se v
enginu pouziva pouze na prehravani zvuku raw, takze kdyz nebudete chtit hrat
rawy nebo pouzivat XMS na neco jineho, muzete pouzivat klidne Borland Pascal
7.0 s touto knihovnou pod DOSBoxem. Ve verzi pro freepascal funkce XMS nejsou
treba. Pomohlo by kdyby DOSBox vyrazne zrychlil svou emulaci v nektere z
pristich verzi nebo prepsani grafickych funkci ve freepascalske verzi do
nejake rychlejsi podoby. Samozrejme ze pro DOSBox plati nastavit hodnotu
cycles na cycles=max v konfiguracnim souboru. (V cistem DOSu vykazuje
freepascalska verze rychlost 175 fps a ma jeste rezervu v podobe cekani
nekolika milisekund za kazdym vykreslenym snimkem a funkce XMS ve verzi pro
Borland Pascal 7.0 jsou plne funkcni).
 
{XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
KNIHOVNA
 
Var
  Key: array[0..127] of Boolean;
  - stavy jednotlivych klaves, cislo predstavuje klavesu viz. konec
  zdrojoveho souboru engine.pas a hodnota boolean pak jestli je klavesa
  stisknuta nebo ne. True=stisknuto a prave drzeno , False=nestisknuto
  priklady: Repeat Until Key[1]=True; ... cekani na stisk ESC
            If Key[28]=True then Begin End; kdyz je stisknut Enter proved ...
 
Var
  Buffer: array[0..4] of Word;
  - V programu se pracuje se 4mi Buffery jako s parametry pro graficke funkce
  Buffer[4] predstavuje to co je na obrazovce ostatni 3 Buffery pak virtualni
  obrazovky 320x200x256 ktere mohou obsahovat zdrojovou grafiku nebo
  Buffer ktery se v nasledujicim okamziku cely najednou vlozi na obrazovku.
  Buffer[0] slouzi pro nahravani ze souboru do pameti a rozbalovani dat.
  Buffer[0] je velky 160x200 B, Buffery[1] [2] a [3] 320x200 B
 
Var
  xmsCelkem,xmsMaxBlok: Word;
  - promenne ktere hraji roli pri praci s XMS. Prvni je hodnota kolik je
  celkem XMS k dispozici a druha jak velky maximalne muze byt blok XMS pameti
  Naplneny jsou az po detekci XMS a volani procedury
  GetSizeXMS(var celkemXMS,blokXMS: Word);
 
Var
  xmsChyba: Byte;
  - promenna ktera se naplnuje kdyz dojde k nejake chybe pri praci s XMS
 
Procedure Init320x200;
  - inicializuje graficky rezim 320x200x256
 
Procedure Init80x25;
  - inicializuje zpet textovy rezim
 
Procedure WaitRetrace;
  - cekani na vykreslovaci paprsek az bude vlevo nahore, pouziva se aby se
  animace netrhala cenou je vsak zpomaleni vykreslovani na frekvenci monitoru
 
Procedure InitBuffers;
  - inicializuje Buffery viz. vyse a dalsi nutne vnitrni pameti, naprosto
  nezbytne zavolat na zacatku programu, nezapomente zase pamet uvolnit
  volanim ShutdownBuffers na konci programu.
 
Procedure ShutdownBuffers
  - uvolni alokovanou pamet pro dalsi pouziti jinymi programy a systemem
 
Procedure GetPal(Color:Byte; Var R,G,B:Byte);
  - naplni R,G,B prvky palety cervene zelene a modre pro barvu "Color"
 
Procedure SetPal(Color:Byte; R,G,B:Byte);
  - nastavi paletu barvy Color(0.255) prvky R,G,B (rozsah 0..63)
 
Procedure LoadGRPage(JmenoSouboru:string;Pozice:LongInt);
  - nacte z harddisku soubor 'JmenoSouboru.gra' od pozice seek(Pozice) do
  pameti Buffer[0] pro dalsi nahrani do bufferu [1] [2] nebo [3] prikazy
  LoadBlok nebo LoadSprite
  -Pozice se zadava 0 jen v pripade ze prilinkovavate data na konec exe pak
  se jako jmeno souboru vyplni soubor.exe a pozice se nastavi na misto kde
  zacinaji prilinkovana data
 
Procedure LoadBmpFile(JmenoSouboru: string; pozice: LongInt; StartColor: Byte);
  - nacte BMP soubor 'JmenoSouboru.bmp' s paletou 16 barev a s rozmery o
  nasobcich 4 od pozice seek(Pozice) do Bufferu[0] pro dalsi nahrani do
  bufferu [1] [2] nebo [3] prikazem LoadBitMap, StartColor je cislo barvy od
  ktere se v palete nahraje 16 barev bmp souboru napr. StartColor=240 tzn.
  barvy bmp souboru se nastavi na poslednich 16 barev palety.
  Obrazek BMP se nahraje do Bufferu[0] na souradnice 0,0 levy horni roh
 
Procedure LoadBlok(x1,y1,x2,y2,x3,y3,BufferTo: Word);
  - nacte z Bufferu[0] z pozice kde x2,y2 je levy horni roh a x3,y3 pravy
  dolni roh na strance 160x200 tento obdelnik na pozici x1,y1 na stranku
  BufferTo levym hornim rohem, priklad:
  LoadBlok(0,0,0,0,159,199,Buffer[1]) nacte na pozici 0,0 do rohu na stranku
  Buffer[1] data z obdelniku 0,0 159,199 z Bufferu[0] tj. cely Buffer[0]
 
Procedure LoadSprite(x1,y1,x2,y2,x3,y3,BufferTo: Word);
 - jako LoadBlok jen s tim rozdilem ze tam kde je barva 0 se neprovede
 nacteni daneho bajtu
 
Procedure LoadBlokM(x1,y1,x2,y2,x3,y3,BufferTo: Word); (M=Mirrored)
 - uplne jako LoadBlok jen s tim rozdilem ze nacteni se provede zrcadlove,
 vhodne tam kde potrebujeme aby panacek chodil nejen doleva ale i zrcadlove
 vykresleny doprava, muzeme tak v souboru gra mit jen jednu verzi a pak v
 bufferu s grafikou nacteme LoadBlok a LoadBlokM jen s rozdilem x1 a y1 a se
 zachovanim x2,y2,x3,y3, ziskame dva obrazky jeden pro kazdy smer pohybu
 
Procedure LoadSpriteM(x1,y1,x2,y2,x3,y3,BufferTo: Word);
 - jako LoadBlokM jen nacita sprajt
 
Procedure LoadBitMap(X,Y: Word; BufferTo: Word);
 - pouziva se po volani LoadBMPFile, nacte z Bufferu[0] do Bufferu "BufferTo"
 na souradnici X,Y obrazek BMP, rozmery BMP obrazku jsou automaticky
 nastaveny po volani LoadBMPFile. BufferTo = Buffer[1] [2] nebo [3]
 
Procedure LoadBitMapM(X,Y: Word; BufferTo: Word);
 - jako LoadBitMap jen s tim rozdilem ze nahraje obrazek zrcadlove otoceny
 
Procedure WritePixel(X:Word;Y,Color:Byte;Buffer:Word);
 - nakresli pixel na souradnice X,Y barvou "Color" do Bufferu "Buffer"
 Buffer[1] [2] nebo [3] = 320x200 v pameti, Buffer[4]=screen
 
Procedure Blok(x1,y1,x2,y2,Color,Buffer:Word);
 - nakresli plny obdelnik kde levy horni roh je urcen souradnicemi x1,y1
 pravy dolni roh pak souradnicemi x2,y2 , vyplni barvou "Color" v Bufferu
 "Buffer" (Buffer[1] [2] [3] nebo [4])
 
Procedure Ramecek(X1,Y1,X2,Y2:Word;Color:Byte;Buffer:Word);
 - nakresli do bufferu "Buffer" ramecek tloustkou jeden pixel barvou "Color"
 levy horni roh je urcen souradnicemi X1,Y1 pravy dolni roh pak souradnicemi
 X2,Y2
 
Procedure WriteBlok(x1,y1,x2,y2,x3,y3,BufferFrom,BufferTo: Word);
 - zkopiruje obdelnik grafiky z Bufferu "BufferFrom" do Bufferu "BufferTo"
 na pozici x1,y1 do Bufferu "BufferTo" z obdelniku x2,y2 x3,y3 z Bufferu
 "BufferFrom" priklad: WriteBlok(X,Y,0,0,15,15,Buffer[1],Buffer[3]);
 zkopiruje graficky obdelnik z Bufferu[1] ze souradnic 0,0 15,15 do bufferu
 Buffer[3] na pozici urcenou souradnicemi X,Y
 
Procedure WriteSprite(x1,y1,x2,y2,x3,y3,BufferFrom,BufferTo: Word);
 - jako WriteBlok jen s tim rozdilem ze bajty s hodnotou nula se nevykresluji
 
Procedure FlipPage(BufferFrom,BufferTo: Word);
 - zkopiruje obsah Bufferu "BufferFrom" do Bufferu "BufferTo"
 priklad: FlipPage(Buffer[1],Buffer[4]); zkopiruje obsah bufferu[1] na screen
 
Procedure ClearPage(Buffer:Word);
 - vymaze Buffer napr. ClearPage(Buffer[1]); vymaze Buffer[1] nulami.
 
Procedure InitTexter(Barva:Byte);
 - inicializuje moznost vypisovat texty na obrazovku, je nutne byt nejprve v
 grafickem rezimu, Barva urcuje jakou barvu budou mit vysledne texty (0..255)
 nezapomente opet uvolnit pamet texteru volanim procedury ShutdownTexter
 na konci programu
 
Procedure ShutdownTexter;
 - uvolni alokovanou pamet texteru pro pouziti dalsimi programy a systemem.
 Ve verzi pro freepascal neni treba tuto proceduru volat.
 
Procedure ChangeTexterColor(Barva:Byte);
 - zmeni barvu texteru (pozn. u BP7 verze pomala procedura)
 
Procedure WriteText(X,Y:Word;retezec:string;BufferTo:Word);
 - vypise do Bufferu "BufferTo" na souradnici X,Y textovy retezec je nutne
 aby byl inicializovany texter, priklad:
 WriteText(150,97,'Hallo World',Buffer[4]); vypise zhruba do prostred
 obrazovky text "Hallo World"
 
Procedure WriteNumber(x,y:Word;Cislo:Longint;Small:Boolean;BufferTo:Word);
 - vypise do Bufferu "BufferTo" na pozici X,Y cislo "Cislo" (rozsah cisel je
 0..9999999) Small=True znamena ze cislo bude malym fontem, Small=False
 znamena velikost cifer 5 pixelu do delky 7 pixelu na vysku
 
Procedure LoadMapFile(soubor:string; pozice:Longint);
 - Nacte do pameti soubor mapy z programu editmap, pozice je parametr pro
 seek(pozice) pri nacitani ze souboru
 
Procedure SetMapByte(MapOffset:Word;bajt:Byte);
 - na pozici MapOffset v mape nahraje bajt, mapa je velka 64000B takze rozsah
 MapOffsetu je 0 .. 63999, pouzivejte rovnici pro offset Y * delka radku + X
 kde X a Y jsou souradnice ctverce na mape
 
Function  GetMapByte(MapOffset:Word): Byte;
 - vraci hodnotu bajtu z mapy z pozice urcene MapOffsetem
 
Procedure InitKeyboard;
 - inicializuje klavesnici (nezapomente zase klavesnici vratit do puvodniho
 stavu volanim ShutdownKeyboard na konci programu)
 
Procedure ShutdownKeyboard;
 - vrati klavesnici do puvodniho stavu
 Pokud na konci programu zustane vlivem stisku CTRL+F9 pro spusteni nefunkcni
 klavesnice, stisknete CTRL+ESC pro navrat normalni funkcnosti
 
Function  DetekujXms: Word;
 - vrati 0, pokud je ovladac XMS nainstalovany.
 u freepascalske verze funkce XMS nejsou treba a proto v unitu pro freepascal nejsou
 
Procedure GetSizeXms(var celkemXMS,blokXMS: Word);
 - v celkemXMS vraci celkovou (volnou?) velikost XMS a v blokXMS kolik si
 maximalne muzeme alokovat pro 1 blok. Vetsinou jsou obe velikosti shodne.
 
Function  AlokujXms(kolik: Word): word;
 - "kolik" je v Kb. Vraci handle (rukojet) alokovaneho bloku.
 
Procedure UvolniXms(handle: Word);
 - vsechny bloky, ktere jsme si alokovali bychom meli uvolnit, jinak budou az
 do restartu systemu nepouzitelne pro jine aplikace.
 
Procedure MoveToXMS(Handle: Word; XMSOffset: LongInt; Var Source; BlockLength: LongInt);
 - Source je promenna ze ktere se bude kopirovat do XMS na offset "XMSOffset"
 pocet bajtu BlockLength (pocet bajtu BlockLength musi byt sude cislo)
 
Procedure MoveFromXMS(Handle: Word; XMSOffset: LongInt; Var Dest; BlockLength: LongInt);
 - Dest je promenna do ktere se bude kopirovat z XMS z Offsetu XMSOffset
 pocet bajtu BlockLength (pocet bajtu BlockLength musi byt sude cislo)
 
Procedure InitTimer;
 - zapne casovac pro pouzivani funkce wait, Stopky, FPS2s a zvukovych funkci
 nezapomente opet casovac uvest do puvodniho stavu volanim ShutdownTimer na
 konci programu
 
Procedure ShutdownTimer;
 - uvede casovac do puvodniho stavu
 
Procedure Wait(ms: Word);
 - ceka "ms" milisekund, nahrada prikazu delay z jednotky CRT
 
Procedure Sound(Hertz: Word);
 - nahrada prikazu Sound z jednotky CRT
 
Procedure Silence;
 - nahrada prikazu NoSound z jednotky CRT
 
Procedure Stopky_Start;
 - zapne mereni stopkami
 
Procedure Stopky_Stop;
 - zastavi mereni stopkami
 
Function  Stopky_GetNumber: LongInt;
 - vraci namerene cislo po mereni stopkami v milisekundach
 
Procedure LoadSNDFile(Filename:String;Pozice:LongInt);
 - nacte 'soubor.snd' z harddisku do pameti, pozice se pouziva pro
 seek(pozice) pri nacitani
 
Procedure LoadRAWFile(filename:String;Pozice:LongInt;N:Byte);
 - nacte 'soubor.raw' seek(pozice) z harddisku, N je poradove cislo rawu
 (cislujte rawy od nuly pro spravne automaticke uvolneni pameti na konci
 programu)
 Soubory RAW nemaji hlavicku a je treba si je predem pripravit utilitou
 wav2raw pro windows. Vemte WAV s delkou max 4 sekundy a nejakym programem si
 ho prevedte do formatu PCM 8bit unsigned mono a potom na nej aplikujte
 utilitu wav2raw. Tato utilita prevede wav na raw a nastavi do prvnich ctyr
 bajtu souboru delku dat. (nutne pro nacitani v enginu)
 
Procedure PlaySound(Sample:Byte);
 - prehraje zvuk ze souboru.snd, Sample je cislo zvuku
 
Procedure PlayRaw(Cislo:Byte);
 - prehraje zvuk raw , Cislo je poradove cislo rawu
 v DOSBoxu zni rawy obzvlast pekne protoze DOSBox hraje PC Speaker pres
 reproduktory pocitace, V cistem DOSu kde PC Spaker hraje z bedny to zni
 nic moc extra spis skrceni nez zvuky
 
Procedure StopPlay;
 - zastavi prehravani zvuku
 
Function  FPS2s: Boolean;
 - strida stav co jednu vterinu, v jedne vterine vraci True a v druhe False
 pouziva se pro vypocet fps
 
{XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}