home *** CD-ROM | disk | FTP | other *** search
/ Garbo / Garbo.cdr / pc / progrmng / stk110.lzh / STKSRC.COM / SPR_ANIM.H < prev    next >
Encoding:
C/C++ Source or Header  |  1991-02-25  |  8.9 KB  |  207 lines
  1. /**********************************************************************
  2. * spr_anim.h
  3. * 
  4. * Routines for automatic sprite animation and movement.
  5. **********************************************************************
  6.                     This file is part of
  7.  
  8.           STK -- The sprite toolkit -- version 1.1
  9.  
  10.               Copyright (C) Jari Karjala 1991
  11.  
  12. The sprite toolkit (STK) is a FreeWare toolkit for creating high
  13. resolution sprite graphics with PCompatible hardware. This toolkit 
  14. is provided as is without any warranty or such thing. See the file
  15. COPYING for further information.
  16.  
  17. **********************************************************************
  18. **********************************************************************/
  19.  
  20. #ifndef __SPR_ANIM_H_
  21. #define __SPR_ANIM_H_
  22.  
  23. #include "grtypes.h"
  24.  
  25. /***** Datatypes *****/
  26.  
  27. #ifndef __ANIM_SPRITE_
  28. typedef void *ANIM_SPRITE;
  29. #endif
  30. /**********************************************************************
  31. * The animated sprite type is private. The handle must be void pointer 
  32. * due to the TC which does not allow "struct _anim_sprite *ANIM_SPRITE"  
  33. * without a "struct _anim_sprite" defined in the same file.
  34. **********************************************************************/
  35.  
  36. /**********************************************************************
  37. * The information structure returned by the spr_anim_get_info():
  38. **********************************************************************/
  39. typedef struct _anim_spr_info {
  40.     int     x,y;                            /** location        **/
  41.     int     dx,dy;                          /** movement vector **/
  42.     int     lef, top, rig, bot;             /** limits          **/
  43.     WORD    frame, frame_delay, timeout;    /** time info       **/
  44.     WORD    id;     /** the user spesified id of current sprite **/
  45.     int     w,h;                            /** width&height    **/
  46. } ANIM_SPR_INFO;
  47.  
  48. /***** Literal defines *****/
  49.  
  50. /**********************************************************************
  51. * The values for fx_mode and fx_type: (See spr_anim_set_fx_handler)
  52. **********************************************************************/
  53. #define SPR_ANIM_FX_ALL         (0x0F) /** all fx       **/
  54. #define SPR_ANIM_FX_TIMEOUT     (1<<0) /** timeout      **/
  55. #define SPR_ANIM_FX_HIT_X_LIMIT (1<<1) /** hit x limit  **/
  56. #define SPR_ANIM_FX_HIT_Y_LIMIT (1<<2) /** hit y limit  **/
  57. #define SPR_ANIM_FX_HIT_SPRITE  (1<<3) /** hit other spr**/
  58.  
  59. /**********************************************************************
  60. *
  61. * The FX_RET values for the fx_handler return codes:
  62. **********************************************************************/
  63. #define SPR_ANIM_FX_RET_NOTHING (0)     /** continue normally       **/
  64. #define SPR_ANIM_FX_RET_RE_PUT  (1)     /** put the sprite again    **/
  65. #define SPR_ANIM_FX_RET_STOP    (2)     /** stop the animation      **/
  66. #define SPR_ANIM_FX_RET_DELETE  (3)     /** delete the anim.sprite  **/
  67. #define SPR_ANIM_FX_RET_DESTROY (4)     /** destroy the anim.sprite **/
  68.  
  69. /***** Function prototypes *****/
  70.  
  71. ANIM_SPRITE spr_anim_create(WORD count, ...);
  72. /**********************************************************************
  73. * Create an animated sprite from the given simple sprites.
  74. * The sprites must have the same width and height.
  75. * Set the following defaults:
  76. *   x,y = 0,0
  77. *   dx,dy = 0,0
  78. *   lef,top,rig,bot = 0,0,spr_max_x,spr_max_y
  79. *   frame_delay, timeout = 0,0
  80. *   fx_mode = FX_ALL 
  81. *   fx_handler = default_fx (TIMEOUT & HIT_SPRITE delete, LIMITs bounce.)
  82. *
  83. * count The number of simple sprites, at most 20.
  84. * ...   The simple sprites
  85. *
  86. * Return: ANIM_SPRITE if no errors or 
  87. *          NULL if memory allocation error, count>20
  88. *           or ... contains a NULL sprite.
  89. **********************************************************************/
  90.  
  91. void spr_anim_start(ANIM_SPRITE aspr);
  92. /**********************************************************************
  93. * Start the sprite animation. 
  94. *
  95. * aspr  The animated sprite to use
  96. **********************************************************************/
  97.  
  98. void spr_anim_stop(ANIM_SPRITE aspr);
  99. /**********************************************************************
  100. * Stop the animation of the given sprite. This means that after the 
  101. * next pass this sprite will not be shown nor updated. Sprite can
  102. * be restarted with the function spr_anim_start.
  103. *
  104. * aspr  The animated sprite to stop
  105. **********************************************************************/
  106.  
  107. void spr_anim_delete(ANIM_SPRITE aspr);
  108. /**********************************************************************
  109. * Delete the given animated sprite. The simple sprites it contains are 
  110. * NOT deleted.
  111. *
  112. * aspr  The animated sprite to use
  113. **********************************************************************/
  114.  
  115. void spr_anim_destroy(ANIM_SPRITE aspr);
  116. /**********************************************************************
  117. * Delete the given animated sprite. The simple sprites it contains are 
  118. * ALSO deleted.
  119. *
  120. * aspr  The animated sprite to destroy
  121. **********************************************************************/
  122.  
  123. WORD spr_anim_next_pass(void);
  124. /**********************************************************************
  125. * This function handles the sprite animation and display.
  126. * 1. Spr_put all animated sprites.
  127. * 2. Check for special effects.
  128. *   a. Call fx_handlers if necessary.
  129. *   b. Act according to the fx_handler return values.
  130. * 3. Call spr_next_pass.
  131. * 4. Update frame indices and locations of all animated sprites.
  132. *
  133. * Return: The current visual page number
  134. **********************************************************************/
  135.  
  136.  
  137.  
  138. ANIM_SPR_INFO *spr_anim_get_info(ANIM_SPRITE aspr);
  139. /**********************************************************************
  140. * Return a pointer into a static info structure of the sprite.
  141. *
  142. * NOTE: the structure is only a copy which is overwritten by the 
  143. *       next call to this function.
  144. **********************************************************************/
  145.  
  146. void spr_anim_set_location(ANIM_SPRITE aspr, WORD x, WORD y);
  147. /**********************************************************************
  148. * Set the location of the animated sprite.
  149. **********************************************************************/
  150.  
  151. void spr_anim_set_vector(ANIM_SPRITE aspr, int dx, int dy);
  152. /**********************************************************************
  153. * Set the movement vector of the animated sprite. The (dx,dy) are added
  154. * to the (x,y) attributes of the sprite during every pass. Negative
  155. * values mean left and up directions in screen.
  156. **********************************************************************/
  157.  
  158. void spr_anim_set_limits(ANIM_SPRITE aspr,
  159.                          WORD lef, WORD top, WORD rig, WORD bot);
  160. /**********************************************************************
  161. * Set the limits for the animated sprite. The function takes care
  162. * of the bottom/right adjustments due to the size of the sprite.
  163. * The fx_handler will be triggered by these limits, if allowed.
  164. *
  165. * Note again, that all simple sprites belonging to the animated sprite
  166. * must have the same width & heigth or the limit checking will not work.
  167. **********************************************************************/
  168.  
  169. void spr_anim_set_time(ANIM_SPRITE aspr,
  170.                        int frame, int frame_delay, int timeout);
  171. /**********************************************************************
  172. * Set the frame delay and timeout values. (-1 means no change for
  173. * that value). 
  174. *
  175. * NOTE: The 'frame' MUST NOT be changed from an fx_handler!!
  176. *
  177. * frame         The current animation frame number (0..nr of frames-1)
  178. * frame_delay   The number of passes for each frame change (0=no change)
  179. * timeout       The number of passes before timeout action (0=infinite)
  180. **********************************************************************/
  181.  
  182. void spr_anim_set_fx_handler(ANIM_SPRITE aspr, 
  183.                              WORD fx_mask, 
  184.                              WORD (fx_handler)(ANIM_SPRITE,WORD,SPRITE));
  185. /**********************************************************************
  186. * Sets the special effects handler function for the given ANIM_SPRITE.
  187. *
  188. * The function should have the following prototype:
  189. *
  190. *   WORD handler_name(ANIM_SPRITE aspr, WORD fx_type, SPRITE spr);
  191. *
  192. * The function will be called with the following parameters:
  193. * aspr      the animated sprite whose handler this is, 
  194. * fx_type   the type of the effect which caused this call,
  195. * spr       the colliding sprite (if fx_type was HIT_SPRITE). 
  196. *
  197. * The function must return one of the SPR_ANIM_FX_RET values defined above.
  198. *
  199. * A NULL handler means that all special effects cause spr_anim_delete.
  200. *
  201. * fx_mask     The types of effects which cause a call to the handler,
  202. *             for example: SPR_ANIM_FX_HIT_Y_LIMIT|SPR_ANIM_FX_HIT_X_LIMIT
  203. * fx_handler  The handler function.
  204. **********************************************************************/
  205. #endif
  206.  
  207.