home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / maj / 678 / mcgalib.doc < prev    next >
Text File  |  1993-11-29  |  8KB  |  246 lines
  1. ┌──────────────────────┐
  2. │ THE MCGA-VGA LIBRARY │
  3. └──────────────────────┘
  4.  
  5. This  new  library  holds  and replaces now the SPRLIB library.
  6. These  functions  are  for  the  VGA  19, 320 x 200, 256 colors
  7. screen. To see how  using  the  sprite  functions,  look at the
  8. EXAMPLE.C listing, and read explanations on EXAMPLE program la-
  9. ter...
  10.  
  11. Functions supported are these:
  12. - Set a screen mode.
  13. - Display a text string.
  14. - Clear the screen.
  15. - Put a pixel.
  16. - Get a pixel color.
  17. - Draw a line.
  18. - Create a new color.
  19. - Using several palettes.
  20. - Set a window.
  21. - Get a block of screen.
  22. - Put a block on screen.
  23. - Fill a rectangle.
  24. - Put a 16 color icon on screen.
  25. - Put 256 color sprites:
  26.    * In XOR mode.
  27.    * In overwriting mode.
  28.    * In copy mode.
  29.  
  30.  
  31. The variables of the library:
  32.  
  33. VARIABLES FOR GRAPHICAL WINDOW
  34. unsigned int XL=0;
  35. unsigned int XR=319;
  36. unsigned int YB=0;
  37. unsigned int YT=199;
  38.  
  39. VARIABLE FOR REAL OR VIRTUAL SCREEN
  40. unsigned int VGASCREEN=0xA000;
  41.   The  default value (0xA000) is the segment adress of the real
  42. screen,  one  changes  segment  to use a virtual screen, offset
  43. must be 0.
  44.  
  45. extern unsigned char TEXTCOLOR;  Color for text display.
  46. extern unsigned long *SPVECTOR;  Pointer on sprites' addresses.
  47. extern char *SPCODE;             Pointer on start of sprites'
  48.    code.
  49.  
  50.  
  51. The functions of the library:
  52.  
  53. void selectscreen(int mode);
  54.   To change screen mode: 19 for MCGA screen, 3 for text screen.
  55.  
  56. char *getspadr(int number);
  57.   Returns  address of a sprite by sending its number in the ta-
  58. ble,  that  is in the range 1..N, N being number of sprites in
  59. the table.
  60.  
  61. void window19(int left, int bottom, int right, int top);
  62.   Set  a  graphical  window  inside the screen. Left = 0..319,
  63. right = 0..319, bottom = 0..199, top = 0..199.
  64.  
  65. void outtext(int column, int line, char *text);
  66.   Put a string on screen. Column = 1..40, line = 1..25.  Color
  67. according to the TEXTCOLOR variable.
  68.  
  69. void cls19(int color);
  70.   Clear the screen with a color among 256.
  71.  
  72. void sprite256(int x, int y, char *adr);
  73.   Put  a  256  colors sprite on scenery, without   erasing the
  74. background. Address is either an  absolute address or the GETS-
  75. PADR function with the sprite number as parameter.
  76.   Ex.:  sprite256( 5, 18, getspadr( 3 ));
  77. This displays the third sprite in table at x = 5, y = 18.
  78.  
  79. void csprite256(int x, int y, char *adr);
  80.   Put  a sprite with its background on the screen. That erases
  81. the scenery. It's very fast and serves to make scenery.
  82.  
  83. void xsprite256(int x, int y, char *adr);
  84.   Display  a  sprite in XOR mode, exclusive or. This change the
  85. colors. By  displaying  again the sprite one restore the back-
  86. ground.
  87.  
  88. void sprite(int number, int x, int y, unsigned char mode);
  89.   Generical function that calls other sprite functions accor-
  90. ding to the chosen mode:
  91.      0 = COPY.
  92.      4 = overwriting.
  93.  
  94. void  getblock(int  left,  int  bottom, int right, int top,
  95. char *adr);
  96.   Get a block of the screen to the adress This requires an even
  97. width.  And  one  must  first  allocate a memory buffer at  adr
  98. (with the malloc function in C language).
  99.  
  100. void putblock(int x, int y, char *adr);
  101.   Put a block saved with getblock on the screen.
  102.  
  103. void icon19(int x, int y, char *adr);
  104.   Put a 16 color icon on the screen. An icon displays color 0
  105. that  is the black color number, and don't display color 9 that
  106. serves to background. It can be made with the k, i or j command
  107. of MegaSprites.
  108.  
  109. void writeRGB(char *paladr);
  110.   Set  a  256 color palette from a file of 768 values, pre-
  111. viously loaded in memory at paladr.
  112.  
  113. void writecolor(int colnum, int r, int g, int b);
  114.   Create a new color # colnum with three red, green,  and blue
  115. values, that are in range 0..63.
  116.  
  117. void setpix256(int x, int y, unsigned char color);
  118.   Put a pixel at x, y.
  119.  
  120. int getpix256(int x, int y);
  121.   Get the color of pixel at x, y.
  122.  
  123. void  line256(int  x,  int y, int x2, int y2, unsigned char co-
  124. lor);
  125.  Draw a line from starting point at x, y to ending point at x2,
  126. y2.
  127.  
  128. void fillblock(int l, int b, int r, int h, int color);
  129.   Fill a rectangle defined by l, b, r, b (left, bottom, right,
  130. top) with a color among 256.
  131.  
  132.  
  133. MCGALIB.OBJ
  134.  
  135. MCGALIB.OBJ holds all the functions detailed above. It's an as-
  136. sembly  80286  set  of functions that can be used with any lan-
  137. guage and compiler.
  138. The way to use this assembly module depends of the compiler and
  139. must to be explained in its manual.
  140.  
  141. This  module  is assembled for LARGE MODEL, CASE-SENSITIVE, and
  142. symbols  are  prefixed  by the '_' letter, that requires either
  143. you  set  the appropriate option to your linker, or you prefixe
  144. the functions with '_' at the call.
  145.  
  146. For example:          sprite(x, y, adr)
  147. becomes              _sprite(x, y, adr).
  148.  
  149. The MCGALIB.H file can be included in C files, it is not requi-
  150. red however.
  151. The  source code MCGALIB.C or MCGALIB.ASM that is provided if a
  152. registered version can so be included in a C or assembly module
  153. or translated to another language.
  154.  
  155.  
  156. ┌─────────────────────┐
  157. │ THE EXAMPLE PROGRAM │
  158. └─────────────────────┘
  159.  
  160. Files used by the program:
  161.  
  162. DEMO2.SPR            File of sprites.
  163. DEMO2.AUT            File of an automaton.
  164. EXAMPLE.C            C ANSI source file for example of use.
  165. EXAMPLE.EXE          The executable.
  166. EXAMPLE.PRJ          A TC 2.0 project example.
  167. MCGALIB.OBJ          Assembly 80286 library of graphical and
  168.                      sprite functions.
  169. MCGALIB.H            Header file of MCGALIB.OBJ for C com-
  170. pilers.
  171.  
  172. The EXAMPLE program is a very simple program to show how to use
  173. sprites and automaton. It uses MCGALIB.OBJ and also it includes
  174. all necessary functions for sprite management: loading sprite,
  175. converting addresses after loading, making scenery, etc..
  176.  
  177.  
  178. Variables for sprite using:
  179.  
  180. FILE *FP;             Used by file functions.
  181. int *AUTOMATON;       Pointer on a buffer for automaton.
  182. char *BLOCKSAVE;      Pointer on a buffer for screen block.
  183. int AUTMAX;           Number of entries in automaton.
  184. int SPRMAX;           Number of sprites in table.
  185.  
  186.  
  187. Fonctions for sprite using:
  188.  
  189. void outtextf(int x,int y,char *fmt, ... );
  190.     Display a formatted text string at x, y. As printf for gra-
  191. phical screen.
  192.      x=0..40
  193.      y=0..24
  194.  
  195. int autread(int i);
  196.     Function  to  read  frame i of loaded automaton, return the
  197. sprite number to this frame.
  198.  
  199. int getcode(int n);
  200.     Function that returns code of format of sprite #n.
  201.  
  202.  
  203. Function for loading files:
  204.  
  205. void changext(char *name,char *ext);
  206.     Add  or  replace  extension  of filename by the proper one.
  207. Assume  size  of  variable names is large enough to handle a 13
  208. characters long string.
  209.  
  210. int bload(char *fname,char *adr,int siz);
  211.    Load any binary file. Return 1 if OK, 0 otherwise.
  212.  
  213. int autload(char *aname);
  214.    Load automaton "aname" at AUTOMATON location. Assume AUTOMA-
  215. TON  points  out a memory buffer allocated with function of the
  216. language.
  217.  
  218. int sprload(char *spname);
  219.   Load the file of sprites "spname", at SPVECTOR location.  SP-
  220. VECTOR  is a pointer defined in MCGALIB, and it must be alloca-
  221. ted before loading sprites into memory. The function is shorte-
  222. ned  to  load  file until 64 Kb long if a unregistered version,
  223. and it is the same as that of VTools if the registered version.
  224. It convert relative addresses to absolute ones.
  225.   Return 1 if OK, 0 otherwise.
  226.   When returning, SPVECTOR points out the table of adresses  of
  227. the sprites, and SPCODE points out the images.
  228.  
  229.  
  230. The main loop of the program:
  231.  
  232.  This  program  is  a  short example to show how to use 256 co-
  233. lor sprites on a scenery without erasing the scenery.
  234. The scenery is a single sprite that covers background. The main
  235. iteration  saves  the  block of screen where animation is done,
  236. puts the sprite, restores the screen, then one repeats the ope-
  237. ration  at  the  next  location, and so on... Even if it's very
  238. simple,  this example holds all that is required for a strategy
  239. or  role-playing game. To make an arcade game, the color planes
  240. principle  is required and that is for the PLIB library and its
  241. example...
  242.  
  243.  
  244.  
  245.  
  246.