home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / demos / proart24 / PCA / TBoxLibs / h / sprite
Encoding:
Text File  |  1996-04-26  |  17.6 KB  |  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. /* ----------------------------- sprite_rename -----------------------------
  242.  * Rename the specified sprite within the same sprite area.
  243.  *
  244.  */
  245. extern _kernel_oserror * sprite_rename(sprite_area *, sprite_id *, char *newname);
  246.  
  247. /* ----------------------------- sprite_copy -------------------------------
  248.  * Copy the specified sprite as another named sprite in the same sprite area.
  249.  *
  250.  */
  251. extern _kernel_oserror * sprite_copy(sprite_area *, sprite_id *, char *copyname);
  252.  
  253. /* ----------------------------- sprite_put --------------------------------
  254.  * Plot the specified sprite using the given GCOL action.
  255.  *
  256.  */
  257. extern _kernel_oserror * sprite_put(sprite_area *, sprite_id *, int gcol);
  258.  
  259. /* ----------------------------- sprite_put_given --------------------------
  260.  * Plot the specified sprite at (x,y) using the given GCOL action.
  261.  *
  262.  */
  263. extern _kernel_oserror * sprite_put_given(sprite_area *, sprite_id *, int gcol,
  264.                             int x, int y);
  265.  
  266.  
  267. _kernel_oserror * sprite_put_in_current(sprite_area *area, sprite_id *spr,
  268.                              int gcol_action,
  269.                              int x, int y);
  270.  
  271.  
  272. /* --------------------------- sprite_put_scaled ---------------------------
  273.  * Plot the specified sprite at (x,y) using the given GCOL action, and scaled
  274.  * using the given scale factors.
  275.  *
  276.  */
  277. extern _kernel_oserror * sprite_put_scaled(sprite_area *, sprite_id *, int gcol,
  278.                             int x, int y,
  279.                             sprite_factors *factors,
  280.                             sprite_pixtrans pixtrans[]);
  281.  
  282. /* ---------------------------- sprite_put_greyscaled ----------------------
  283.  * Plot the specified sprite at (x,y) using the given GCOL action, and 
  284.  * greyscaled using the given scale factors.
  285.  *
  286.  */
  287. extern _kernel_oserror * sprite_put_greyscaled(sprite_area *, sprite_id *,
  288.                             int x, int y,
  289.                             sprite_factors *factors,
  290.                             sprite_pixtrans pixtrans[]);
  291.  
  292. /* ----------------------------- sprite_put_mask ---------------------------
  293.  * Plot the specified sprite mask in the background colour.
  294.  *
  295.  */
  296. extern _kernel_oserror * sprite_put_mask(sprite_area *, sprite_id *);
  297.  
  298. /* ----------------------------- sprite_put_mask_given ---------------------
  299.  * Plot the specified sprite mask at (x,y) in the background colour. 
  300.  *
  301.  */
  302. extern _kernel_oserror * sprite_put_mask_given(sprite_area *, sprite_id *, int x, int y);
  303.  
  304. /* --------------------------- sprite_put_mask_scaled ----------------------
  305.  * Plot the sprite mask at (x,y) scaled, using the background colour/action
  306.  *
  307.  */
  308. extern _kernel_oserror * sprite_put_mask_scaled(sprite_area *, sprite_id *,
  309.                             int x, int y,
  310.                             sprite_factors *factors);
  311.  
  312. /* ----------------------------- sprite_put_char_scaled --------------------
  313.  * Paint char scaled at (x,y)
  314.  *
  315.  */
  316. extern _kernel_oserror * sprite_put_char_scaled(char ch,
  317.                                   int x, int y,
  318.                                   sprite_factors *factors);
  319.  
  320. /* ---------------------------- sprite_create_mask -------------------------
  321.  * Create a mask definition for the specified sprite.
  322.  *
  323.  */
  324. extern _kernel_oserror * sprite_create_mask(sprite_area *, sprite_id *);
  325.  
  326. /* ---------------------------- sprite_remove_mask -------------------------
  327.  * Remove the mask definition from the specified sprite.
  328.  *
  329.  */
  330. extern _kernel_oserror * sprite_remove_mask(sprite_area *, sprite_id *);
  331.  
  332. /* ---------------------------- sprite_insert_row --------------------------
  333.  * Insert a row into the specified sprite at the given row.
  334.  *
  335.  */
  336. extern _kernel_oserror * sprite_insert_row(sprite_area *, sprite_id *, int row);
  337.  
  338. /* ---------------------------- sprite_delete_row --------------------------
  339.  * Delete the given row from the specified sprite.
  340.  *
  341.  */
  342. extern _kernel_oserror * sprite_delete_row(sprite_area *, sprite_id *, int row);
  343.  
  344. /* ---------------------------- sprite_insert_column -----------------------
  345.  * Insert a column into the specified sprite at the given column. 
  346.  *
  347.  */
  348. extern _kernel_oserror * sprite_insert_column(sprite_area *, sprite_id *, int column);
  349.  
  350. /* ---------------------------- sprite_delete_column -----------------------
  351.  * Delete the given column from the specified sprite.
  352.  *
  353.  */
  354. extern _kernel_oserror * sprite_delete_column(sprite_area *, sprite_id *, int column);
  355.  
  356. /* ----------------------------- sprite_flip_x -----------------------------
  357.  * Flip the specified sprite about the x axis
  358.  *
  359.  */
  360. extern _kernel_oserror * sprite_flip_x(sprite_area *, sprite_id *);
  361.  
  362. /* ----------------------------- sprite_flip_y -----------------------------
  363.  * Flip the specified sprite about the y axis
  364.  *
  365.  */
  366. extern _kernel_oserror * sprite_flip_y(sprite_area *, sprite_id *);
  367.  
  368.  
  369. typedef struct
  370. {
  371.  int width;
  372.  int height;
  373.  int mask;
  374.  int mode;
  375. } sprite_info;
  376.  
  377. /* -------------------------------- sprite_readsize ------------------------
  378.  * Read the size information for the specified sprite_id
  379.  *
  380.  */
  381. extern _kernel_oserror * sprite_readsize(sprite_area *, sprite_id *,
  382.                            sprite_info *resultinfo);
  383.  
  384.  
  385. typedef struct
  386. {
  387.   int colour;
  388.   int tint;
  389. } sprite_colour;
  390.  
  391. /* ----------------------------- sprite_readpixel --------------------------
  392.  * Read the colour of a given pixel in the specified sprite_id
  393.  *
  394.  */
  395. extern _kernel_oserror * sprite_readpixel(sprite_area *, sprite_id *,
  396.                             int x, int y, sprite_colour *resultcolour);
  397.  
  398. /* ----------------------------- sprite_writepixel -------------------------
  399.  * Write the colour of a given pixel in the specified sprite_id
  400.  *
  401.  */
  402. extern _kernel_oserror * sprite_writepixel(sprite_area *, sprite_id *,
  403.                              int x, int y, sprite_colour *colour);
  404.  
  405.  
  406. typedef enum
  407. {
  408.   sprite_masktransparent = 0,
  409.   sprite_masksolid       = 1
  410. } sprite_maskstate;
  411.  
  412. /* ------------------------------- sprite_readmask -------------------------
  413.  * Read the state of a given pixel in the specified sprite mask
  414.  *
  415.  */
  416. extern _kernel_oserror * sprite_readmask(sprite_area *, sprite_id *,
  417.                            int x, int y, sprite_maskstate *resultmaskstate);
  418.  
  419. /* ------------------------------- sprite_writemask ------------------------
  420.  * Write the state of a given pixel in the specified sprite mask
  421.  *
  422.  */
  423. extern _kernel_oserror * sprite_writemask(sprite_area *, sprite_id *,
  424.                             int x, int y, sprite_maskstate *maskstate);
  425.  
  426.  
  427. typedef struct
  428.         { int r[4];
  429.         } sprite_state;
  430.  
  431. /* ----------------------------- sprite_restorestate -----------------------
  432.  * Restores the old state after one of the sprite redirection calls
  433.  *
  434.  */
  435. extern _kernel_oserror *sprite_restorestate(sprite_state state);
  436.  
  437.  
  438. /* ---------------------------- sprite_outputtosprite ----------------------
  439.  * Redirect VDU output to a sprite, saving old state 
  440.  *
  441.  */
  442. extern _kernel_oserror *sprite_outputtosprite(sprite_area *area, sprite_id *id,
  443.                                 int *save_area, sprite_state *state);
  444.  
  445. /* ----------------------- sprite_outputtomask -----------------------------
  446.  * Redirects output to a sprite's transparency mask, saving old state
  447.  *
  448.  */
  449. extern _kernel_oserror *sprite_outputtomask(sprite_area *area, sprite_id *id,
  450.                               int *save_area, sprite_state *state);
  451.  
  452. /* --------------------------- sprite_outputtoscreen -----------------------
  453.  * Redirect output back to screen, saving old state
  454.  *
  455.  */
  456. extern _kernel_oserror *sprite_outputtoscreen(int *save_area, sprite_state *state);
  457.  
  458. /* --------------------------- sprite_sizeof_spritecontext -----------------
  459.  * Get size of save area needed to save sprite context.
  460.  *
  461.  */
  462. extern _kernel_oserror *sprite_sizeof_spritecontext(sprite_area *area, sprite_id *id,
  463.                                       int *size);
  464.  
  465. /* ------------------------- sprite_sizeof_screencontext -------------------
  466.  * Get size of save area needed to save screen context.
  467.  *
  468.  */
  469. extern _kernel_oserror *sprite_sizeof_screencontext(int *size);
  470.  
  471. /* ------------------------ sprite_removewastage ---------------------------
  472.  * Removes left hand wastage from a sprite
  473.  *
  474.  */
  475. extern _kernel_oserror *sprite_removewastage(sprite_area *area, sprite_id *id);
  476.  
  477.  
  478. /* new SWIs */
  479.  
  480. /* ------------------------ sprite_change_size -----------------------------
  481.  * General insert/delete rows/columns operations
  482.  *
  483.  */
  484. extern _kernel_oserror
  485.   *sprite_change_size
  486.   (sprite_area *area, sprite_id *id, BOOL rows, int at, int number);
  487.  
  488. /* Typedefs and functions for rotating sprites. */
  489.  
  490. typedef struct {int p0 [2], p1 [2], p2 [2], p3 [2];} sprite_pgm;
  491. typedef int sprite_transmat [6];
  492. typedef struct {int x0, y0, x1, y1;} sprite_box;
  493.  
  494. /* ------------------------ sprite_put_mask_trans ---------------------
  495.  * Put a box from the mask in background colours through a transformation matrix
  496.  *
  497.  */
  498. extern _kernel_oserror
  499.   *sprite_put_mask_trans
  500.   (sprite_area *, sprite_id *, sprite_box *, sprite_transmat *);
  501.  
  502. /* ------------------------ sprite_put_mask_pgm -----------------------
  503.  * Put a box from the mask in background colours to a parallelogram
  504.  *
  505.  */
  506. extern _kernel_oserror
  507.   *sprite_put_mask_pgm
  508.   (sprite_area *, sprite_id *, sprite_box *, sprite_pgm *);
  509.  
  510. /* ------------------------ sprite_put_trans --------------------------
  511.  * Put a box from the sprite through a transformation matrix
  512.  *
  513.  */
  514. extern _kernel_oserror
  515.   *sprite_put_trans
  516.   (sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_transmat *, sprite_pixtrans *);
  517.  
  518. /* ------------------------ sprite_put_pgm ----------------------------
  519.  * Put a box from the sprite to a parallelogram
  520.  *
  521.  */
  522. extern _kernel_oserror
  523.   *sprite_put_pgm
  524.   (sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_pgm *, sprite_pixtrans *);
  525.  
  526. # endif
  527.  
  528. /* end of sprite.h */
  529.