home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / demos / proart24 / PCA / TBoxLibs / h / sprite
Text File  |  1996-04-26  |  18KB  |  529 lines
  1. /****************************************************************************
  2.  * This source file was written by Acorn Computers Limited. It is part of   *
  3.  * the RISCOS library for writing applications in C for RISC OS. It may be  *
  4.  * used freely in the creation of programs for Archimedes. It should be     *
  5.  * used with Acorn's C Compiler Release 3 or later.                         *
  6.  *                                                                          *
  7.  ***************************************************************************/
  8.  
  9. /*
  10.  * Title  : sprite.h
  11.  * Purpose: provide access to RISC OS sprite facilities
  12.  *          
  13.  */
  14.  
  15. # ifndef __sprite_h
  16. # define __sprite_h
  17.  
  18. #ifndef __kernel_h
  19. #include "kernel.h"
  20. #endif            
  21.  
  22. #ifndef BOOL
  23. #define BOOL int
  24. #endif
  25.  
  26.  
  27. /* 
  28.  * This file contains functions for performing operations on sprites.
  29.  * For brevity only a brief description is given for each call. More details
  30.  * can be found in the Programmer's Reference manual under the section on
  31.  * Sprite SWIs.
  32.  *
  33.  */
  34.  
  35.  
  36.  
  37. /******** Simple operations, use no sprite area, no name/sprite pointer ***/
  38.  
  39. typedef enum
  40. {
  41.   sprite_nopalette  = 0,
  42.   sprite_haspalette = 1
  43. } sprite_palflag;
  44.  
  45. typedef struct
  46. {
  47.   int xmag,ymag,xdiv,ydiv;
  48. } sprite_factors;
  49.  
  50. typedef char sprite_pixtrans; 
  51.  
  52.  
  53.  
  54.  
  55. /* ----------------------------- sprite_screensave -------------------------
  56.  * Save the current graphics window as a sprite file, with optional palette.
  57.  * Equivalent to *ScreenSave.
  58.  *
  59.  */
  60. extern _kernel_oserror * sprite_screensave(const char *filename, sprite_palflag);
  61.  
  62. /* ---------------------------- sprite_screenload --------------------------
  63.  * Load a sprite file onto the screen. Equivalent to *ScreenLoad.
  64.  *
  65.  */
  66. extern _kernel_oserror * sprite_screenload(const char *filename);
  67.  
  68.  
  69.  
  70. /****** Operations on either system/user area, no name/sprite pointer *****/
  71.  
  72. typedef struct /* Format of a sprite area control block */
  73. {
  74.   int size;
  75.   int number;
  76.   int sproff;
  77.   int freeoff;
  78. } sprite_area;
  79.  
  80. typedef struct /* Format of a sprite header */
  81. {
  82.   int  next;      /*  Offset to next sprite                */
  83.   char name[12];  /*  Sprite name                          */
  84.   int  width;     /*  Width in words-1      (0..639)       */
  85.   int  height;    /*  Height in scanlines-1 (0..255/511)   */
  86.   int  lbit;      /*  First bit used (left end of row)     */
  87.   int  rbit;      /*  Last bit used (right end of row)     */
  88.   int  image;     /*  Offset to sprite image               */
  89.   int  mask;      /*  Offset to transparency mask          */
  90.   int  mode;      /*  Mode sprite was defined in           */
  91.                   /*  Palette data optionally follows here */
  92.                   /*  in memory                            */
  93. } sprite_header;
  94.  
  95. #define sprite_mainarea ((sprite_area *) 0)
  96.  
  97. typedef void * sprite_ptr;
  98.  
  99.  
  100. /* ------------------------ sprite_area_initialise -------------------------
  101.  * Initialise an area of memory as a sprite area 
  102.  *
  103.  */
  104. void sprite_area_initialise(sprite_area *, int size);
  105.  
  106. /* ----------------------- sprite_area_readinfo ----------------------------
  107.  * Read information from a sprite area control block
  108.  *
  109.  */
  110. extern _kernel_oserror * sprite_area_readinfo(sprite_area *, sprite_area *resultarea);
  111.  
  112. /* --------------------------- sprite_area_reinit --------------------------
  113.  * Reinitialise a sprite area.
  114.  * If system area, then equivalent to *SNew
  115.  *
  116.  */
  117. extern _kernel_oserror * sprite_area_reinit(sprite_area *);
  118.  
  119. /* --------------------------- sprite_area_load ----------------------------
  120.  * Load a sprite file into a sprite area.
  121.  * If system area, then equivalent to *SLoad
  122.  *
  123.  */
  124. extern _kernel_oserror * sprite_area_load(sprite_area *, const char *filename);
  125.  
  126. /* ---------------------------- sprite_area_merge --------------------------
  127.  * Merge a sprite file with a sprite area.
  128.  * If system area, then equivalent to *SMerge
  129.  *
  130.  */
  131. extern _kernel_oserror * sprite_area_merge(sprite_area *, const char *filename);
  132.  
  133. /* ---------------------------- sprite_area_save ---------------------------
  134.  * Saves a sprite area as a sprite file.
  135.  * If system area, then equivalent to *SSave
  136.  *
  137.  */
  138. extern _kernel_oserror * sprite_area_save(sprite_area *, const char *filename);
  139.  
  140. /* ---------------------------- sprite_getname -----------------------------
  141.  * Return the name and length of name of the n'th sprite in a sprite area into 
  142.  * a buffer.
  143.  *
  144.  */
  145. extern _kernel_oserror * sprite_getname(sprite_area *, void *buffer, int *length, int index);
  146.  
  147. /* ---------------------------- sprite_get ---------------------------------
  148.  * Copy a rectangle of screen delimited by the last pair of graphics cursor
  149.  * positions as a named sprite in a sprite area, optionally storing the
  150.  * palette with the sprite.
  151.  *
  152.  */
  153. extern _kernel_oserror * sprite_get(sprite_area *, char *name, sprite_palflag);
  154.  
  155. /* ---------------------------- sprite_get_rp ------------------------------
  156.  * Copy a rectangle of screen delimited by the last pair of graphics cursor
  157.  * positions as a named sprite in a sprite area, optionally storing the
  158.  * palette with the sprite. Address of sprite returned in resultaddress.
  159.  *
  160.  */
  161. extern _kernel_oserror * sprite_get_rp(sprite_area *, char *name, sprite_palflag,
  162.                          sprite_ptr *resultaddress);
  163.  
  164. /* ---------------------------- sprite_get_given ---------------------------
  165.  * Copy a rectangle of screen delimited by the given pair of graphics
  166.  * coordinates as a named sprite in a sprite area, optionally storing the
  167.  * palette with the sprite.
  168.  *
  169.  */
  170. extern _kernel_oserror * sprite_get_given(sprite_area *, char *name, sprite_palflag,
  171.                             int x0, int y0, int x1, int y1);
  172.  
  173. /* --------------------------- sprite_get_given_rp -------------------------
  174.  * Copy a rectangle of screen delimited by the given pair of graphics
  175.  * coordinates as a named sprite in a sprite area, optionally storing the
  176.  * palette with the sprite. Address of sprite returned in resultaddress.
  177.  *
  178.  */
  179. extern _kernel_oserror * sprite_get_given_rp(sprite_area *, char *name, sprite_palflag,
  180.                                int x0, int y0, int x1, int y1,
  181.                                sprite_ptr *resultaddress);
  182.  
  183. /* ------------------------------ sprite_create ----------------------------
  184.  * Create a named sprite in a sprite area of specified size and screen mode,
  185.  * optionally reserving space for palette data with the sprite.
  186.  *
  187.  */
  188. extern _kernel_oserror * sprite_create(sprite_area *, char *name, sprite_palflag,
  189.                          int width, int height, int mode);
  190.  
  191. /* ------------------------------ sprite_create_rp -------------------------
  192.  * Create a named sprite in a sprite area of specified size and screen mode,
  193.  * optionally reserving space for palette data with the sprite.Address of
  194.  * sprite returned in resultaddress.
  195.  *
  196.  */
  197. extern _kernel_oserror * sprite_create_rp(sprite_area *, char *name, sprite_palflag,
  198.                             int width, int height, int mode,
  199.                             sprite_ptr *resultaddress);
  200.  
  201.  
  202. /*********** Operations on system/user area, name/sprite pointer **********/
  203.  
  204. typedef enum
  205. {
  206.   sprite_id_name = 0,
  207.   sprite_id_addr = 0x74527053 /* 'Magic' number ("SpRt") to test against */
  208. } sprite_type;
  209.  
  210. typedef struct
  211. {
  212.   union
  213.   {
  214.     char *     name; /* Can use either name of sprite or address (faster) */
  215.     sprite_ptr addr;
  216.   } s;
  217.   sprite_type tag;   /* User must tag the use of this structure manually */
  218. } sprite_id;
  219.  
  220.  
  221. /* ----------------------------- sprite_select -----------------------------
  222.  * Select the specified sprite for plotting using plot(0xed,x,y).
  223.  *
  224.  */
  225. extern _kernel_oserror * sprite_select(sprite_area *, sprite_id *);
  226.  
  227. /* ----------------------------- sprite_select_rp --------------------------
  228.  * Select the specified sprite for plotting using plot(0xed,x,y). Address of
  229.  * sprite returned in resultaddress.
  230.  *
  231.  */ 
  232. extern _kernel_oserror * sprite_select_rp(sprite_area *, sprite_id *,
  233.                             sprite_ptr *resultaddress);
  234.  
  235. /* ----------------------------- sprite_delete -----------------------------
  236.  * Delete the specified sprite.
  237.  *
  238.  */
  239. extern _kernel_oserror * sprite_delete(sprite_area *, sprite_id *);
  240.  
  241. /*