home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / CPROG / WGT_TC21.ZIP / WSPR.DOC < prev    next >
Text File  |  1992-07-17  |  10KB  |  334 lines

  1.             WSPR.LIB Documentation
  2.             ~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4.     The WordUp Graphics Toolkit Version 2.0 includes a special
  5. library for sprites.  The library allows you to edit sprites using 
  6. the WGT Sprite Creator, load them in your program, and display
  7. them on the screen.  The best part about the sprites is you can
  8. set up movement and animation sequences and the library will handle
  9. everything for you.  
  10.  
  11.  
  12. Using WSPR.LIB
  13. ~~~~~~~~~~~~~~
  14.     To use the library, you must also link wgt.lib, and include
  15. wgt.h and wspr.h.  The library needs a lot of memory so make sure
  16. you have lots, and set the program heap size in the Options\Debugger
  17. menu.
  18.  
  19.  
  20.  
  21.  
  22.             Sprite Procedures
  23.             ~~~~~~~~~~~~~~~~~
  24.  
  25. int wloadsprites(color *palette,char *filename,block sprites[201]);
  26.  
  27.  
  28.     Loads a sprite file created with the WGT Sprite Creator.
  29.     Returns -1 if unsuccessful or 0 if successful
  30.     Sprite files now contain 200 sprites instead of 100.
  31.     Remember to change this in your previous programs.
  32.     This command will load all sprites, as well as the colour
  33.     palette.  
  34.  
  35.     Example usage:
  36.         ok=wloadsprites(&palette,"game.spr",sprites);
  37.  
  38.  
  39. --------------------------------------------------------------------------
  40.  
  41.  
  42. void wfreesprites(block sprites[201]);
  43.     
  44.     Frees memory previously allocated from loadsprites.
  45.  
  46.     Example usage:
  47.         wfreesprites(sprites);
  48.  
  49.  
  50. --------------------------------------------------------------------------
  51.  
  52.  
  53. void initspr(void);
  54.  
  55.     Initializes sprite library.
  56.     Sets up internal variables, and makes a virtual screen
  57.     called 'spritescreen'.
  58.  
  59.     Assumes you have loaded sprites into an array called 'sprites'.
  60.     You must call it sprites for these routines to work.
  61.  
  62.     You must call this after you load in sprites using wloadsprites.
  63.     If you need to call this more than once in a program, you
  64.     must free the virtual screen by wfreeblock(spritescreen).
  65.  
  66.     Example usage:
  67.         initspr(sprites);
  68.  
  69.  
  70. --------------------------------------------------------------------------
  71.  
  72.  
  73. void spriteon(int number,int x coord,int y coord,int spritenum);
  74.  
  75.     Turns a sprite on at the coordinates, using the spritenum block
  76. from the sprites array.  Spritenum is the same as the sprite numbers in
  77. the WGT Sprite Creator.  Number can range from 1 to 40.  This means you
  78. can have 40 sprites on the screen at once.  
  79.     Each call to spriteon must be followed later in the program by
  80. a spriteoff.  Do not call spriteon using the same number twice in a row
  81. or the computer may hang. You must turn the sprite off and back on again.
  82.  
  83.     Example usage:
  84.         spriteon(1,160,100,3);
  85.  
  86.  
  87. --------------------------------------------------------------------------
  88.  
  89.  
  90. void spriteoff(int number);
  91.  
  92.     Turns off a sprite. See above.
  93.  
  94.     Example usage:
  95.         spriteoff(3);
  96.  
  97.  
  98. --------------------------------------------------------------------------
  99.  
  100.  
  101. void animate(int number,char *animation sequence);
  102.  
  103.     Sets up animation for a sprite.  Number is the sprite number
  104. to animate.  The string you must pass takes the following form:
  105.  
  106.     "(spritenum,delay)(spritenum2,delay2)R"
  107.  
  108. Between each set of brackets is the information required to animate the
  109. sprite.  The first number is the sprite number, and the second is how long
  110. that sprite number is displayed. You then make another set and use
  111. different sprite numbers and delays.  If you place a CAPITAL R at the end
  112. of the string, the animation will (R)epeat itself when it gets to the end.
  113. If you leave the R out, the animation will occur once, and stop.
  114. You can have 40 sets for animation.
  115.  
  116. For example: To animate sprite number one between two sprites, and repeat:
  117.  
  118.     Animate(1,"(1,0)(2,0)R");
  119.         ^   ^    ^   ^
  120.         |   |    |   | R repeats the sequence
  121.         |   |    |
  122.         |   |    |Second sprite shown is number 2, with no delay
  123.         |   |
  124. Sprite to animate   |First sprite shown is number 1, with no delay
  125.  
  126. After calling this procedure, you must turn the animation on with animon.
  127.  
  128.     Example usage:
  129.         Animate(4,"(5,12)(69,0)(200,100)");
  130.  
  131.  
  132. --------------------------------------------------------------------------
  133.  
  134.  
  135. void animon(int spritenum);
  136.  
  137.     Turns animation on for the sprite.  See above for setting animation.
  138.  
  139.     Example usage:
  140.         animon(3);
  141.  
  142.  
  143. --------------------------------------------------------------------------
  144.  
  145.  
  146. void animoff(int spritenum);
  147.  
  148.     Freezes animation for the sprite.
  149.  
  150.     Example usage:
  151.         animoff(3);
  152.  
  153.  
  154. --------------------------------------------------------------------------
  155.  
  156.  
  157. void movex(int spritenum,char *movement sequence);
  158.  
  159.     Sets up horizontal movement for a sprite.
  160.     Works the similar to animate only there are 3 numbers in each set.
  161.     You can have 15 sets for movement.
  162.  
  163.     movex(3,"(1,50,1)(-1,50,0)R");
  164.  
  165.     The first number in the set is added to the current x coordinate
  166. of the sprite.  Therefore if the sprite is at 100,50 on the screen, and
  167. you make the number a 5, the sprite will move to 105,50.  This number can
  168. be anything, so you can have the sprite move right (positive numbers),
  169. left (negative numbers) or nowhere (zero).
  170.  
  171.     The second number in the set is the number of times to move the
  172. sprite before going on to the next set.  Always >0!
  173.  
  174.     The third number in the set is the delay for each time the sprite
  175. moves. Try using 0 at first and increase it to slow the sprites down.
  176.  
  177.     If the set was (1,50,1), then the sprite would move to the right
  178. one pixel, 50 times, with a delay of 1 for each move.  Then the next set
  179. would be activated. If you have a CAPITAL R at the end of the string,
  180. the movement will repeat.
  181.  
  182.     For example, to make sprite 2 move back and forth on the screen
  183. continuously:
  184.     movex(2,"(1,200,0)(-1,200,0)R");
  185.  
  186.     To make a sprite move from the left side to the right, and jump
  187. back to the left again:
  188.  
  189.     movex(2,"(1,319,0)(-319,1,0)R");
  190.                ^
  191.                | This moves the sprite 319 pixels to the left!
  192.  
  193.  
  194. --------------------------------------------------------------------------
  195.  
  196.  
  197. void movey(int spritenum,char *movement sequence);
  198.  
  199.     Sets up vertical movement for a sprite.
  200.     Exactly the same a movex. See above.
  201.  
  202.  
  203. --------------------------------------------------------------------------
  204.  
  205.  
  206. void movexon(int spritenum);
  207.  
  208.     Turns horizontal movement for a sprite on.
  209.  
  210.     Example usage:
  211.         movexon(3);
  212.  
  213.  
  214. --------------------------------------------------------------------------
  215.  
  216.  
  217. void movexoff(int spritenum);
  218.  
  219.     Turns horizontal movement for a sprite off.
  220.  
  221.     Example usage:
  222.         movexoff(3);
  223.  
  224.  
  225. --------------------------------------------------------------------------
  226.  
  227.  
  228. void moveyon(int spritenum);
  229.  
  230.     Turns vertical movement for a sprite on.
  231.  
  232.     Example usage:
  233.         moveyon(3);
  234.  
  235.  
  236. --------------------------------------------------------------------------
  237.  
  238.  
  239. void moveyoff(int spritenum);
  240.  
  241.     Turns vertical movement for a sprite off.
  242.  
  243.     Example usage:
  244.         moveyoff(3);
  245.  
  246.  
  247. --------------------------------------------------------------------------
  248.  
  249.  
  250. int overlap(int spritenum 1,int spritenum 2);
  251.  
  252.     Tests if two sprites overlap each other on the screen.
  253.     They both must be turned on.
  254.     Returns 1 if they are overlapping.
  255.     (Used for detecting collisions)
  256.  
  257. --------------------------------------------------------------------------
  258.  
  259.  
  260.  
  261. **************************************************************************
  262.  
  263.  
  264. The sprite library uses the following variables:
  265.  
  266. int spon=15;        - the highest sprite number used in your program
  267.               (may be up to 40)
  268.  
  269. int spclip=1;        - 0 means sprite clipping is off
  270.              (might hang computer is it is off)
  271.  
  272. block spritescreen;        - the virtual screen used as a background
  273.  
  274.  
  275. A large structure contains all data about the sprites:
  276.  
  277. typedef struct {
  278.       unsigned char num;           // sprite number to show on screen
  279.       int x;                   // x coord
  280.       int y;                   // y coord
  281.       int ox;                   // last x coord
  282.       int oy;                   // last y coord
  283.       unsigned char on;               // sprite is on?
  284.       int maxx;                   // area on screen to copy
  285.       int maxy;                   // Upper left and
  286.       int minx;                        // Bottom right corners of box
  287.       int miny;                        // to copy.
  288.       block old;                       // old block (stores what was
  289.                               behind sprite)
  290.  
  291.       char animon;               // animation on?
  292.       int anm[41];                     // number of animation
  293.       unsigned char ans[41];           // delay for animations
  294.       char curan;               // current animation
  295.       unsigned char delcnt;           // delay count
  296.  
  297.       char movexon;               // x movement on?
  298.       int mvx[16];               // direction to move
  299.       int mvn[16];               // number of times to move
  300.       unsigned char mvxs[16];           // delay for movement
  301.       char curxmove;               // current x move
  302.       int curmnx;               // number of times moved already
  303.       unsigned char mvxcnt;           // delay count
  304.  
  305.       char moveyon;               // y movement on?
  306.       int mvy[16];               // direction to move
  307.       int mvny[16];               // number of times to move
  308.       unsigned char mvys[16];           // delay for movement
  309.       char curymove;               // current y move
  310.       int curmny;               // number of times moved already
  311.       unsigned char mvycnt;            // delay count
  312.  
  313.       } sprit;
  314. sprit s[40];
  315.  
  316. You will probably not need to change any of these.  There are a few
  317. applications however.  
  318.  
  319. If you need to store the movements or animations as integers, it will be
  320. a pain converting the numbers into a correct string to pass to the animate
  321. command, therefore you can just put them directly into the arrays yourself.
  322.  
  323. If you draw something other than a sprite on the spritescreen, you will
  324. need to copy more of the screen to the visual page.  Therefore change the
  325. minx,miny,maxx,maxy variables of a sprite that is on to the coordinates
  326. of the area you need to copy.  See breakout.c for an example of this.
  327. The sprite library is designed for use with non-changing backgrounds.
  328. If you need to change the background, you must use the above technique
  329. to copy the area modified.  Future versions will provide more control
  330. over this problem.
  331.  
  332.  
  333.  
  334.