chiark - git - mdw - ssr/blob - StraySrc/Libraries/Steel/h/sprite

   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 /*----- Licensing note ----------------------------------------------------*
  10  *
  11  * This file is part of Straylight's Steel library.
  12  *
  13  * Steel is free software; you can redistribute it and/or modify
  14  * it under the terms of the GNU General Public License as published by
  15  * the Free Software Foundation; either version 2, or (at your option)
  16  * any later version.
  17  *
  18  * Steel is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU General Public License
  24  * along with Steel.  If not, write to the Free Software Foundation,
  25  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26  */
  27
  28 /*
  29  * Title  : sprite.h
  30  * Purpose: provide access to RISC OS sprite facilities
  31  *
  32  */
  33
  34 # ifndef __sprite_h
  35 # define __sprite_h
  36
  37 # ifndef __os_h
  38 # include "os.h"
  39 # endif
  40
  41 /*
  42  * This file contains functions for performing operations on sprites.
  43  * For brevity only a brief description is given for each call. More details
  44  * can be found in the Programmer's Reference manual under the section on
  45  * Sprite SWIs.
  46  *
  47  */
  48
  49
  50
  51 /******** Simple operations, use no sprite area, no name/sprite pointer ***/
  52
  53 typedef enum
  54 {
  55   sprite_nopalette  = 0,
  56   sprite_haspalette = 1
  57 } sprite_palflag;
  58
  59 typedef struct
  60 {
  61   int xmag,ymag,xdiv,ydiv;
  62 } sprite_factors;
  63
  64 typedef char sprite_pixtrans;
  65
  66
  67
  68
  69 /* ----------------------------- sprite_screensave -------------------------
  70  * Save the current graphics window as a sprite file, with optional palette.
  71  * Equivalent to *ScreenSave.
  72  *
  73  */
  74 extern os_error * sprite_screensave(const char *filename, sprite_palflag);
  75
  76 /* ---------------------------- sprite_screenload --------------------------
  77  * Load a sprite file onto the screen. Equivalent to *ScreenLoad.
  78  *
  79  */
  80 extern os_error * sprite_screenload(const char *filename);
  81
  82
  83
  84 /****** Operations on either system/user area, no name/sprite pointer *****/
  85
  86 typedef struct /* Format of a sprite area control block */
  87 {
  88   int size;
  89   int number;
  90   int sproff;
  91   int freeoff;
  92 } sprite_area;
  93
  94 typedef struct /* Format of a sprite header */
  95 {
  96   int  next;      /*  Offset to next sprite                */
  97   char name[12];  /*  Sprite name                          */
  98   int  width;     /*  Width in words-1      (0..639)       */
  99   int  height;    /*  Height in scanlines-1 (0..255/511)   */
 100   int  lbit;      /*  First bit used (left end of row)     */
 101   int  rbit;      /*  Last bit used (right end of row)     */
 102   int  image;     /*  Offset to sprite image               */
 103   int  mask;      /*  Offset to transparency mask          */
 104   int  mode;      /*  Mode sprite was defined in           */
 105                   /*  Palette data optionally follows here */
 106                   /*  in memory                            */
 107 } sprite_header;
 108
 109 #define sprite_mainarea ((sprite_area *) 0)
 110
 111 typedef void * sprite_ptr;
 112
 113
 114 /* ------------------------ sprite_area_initialise -------------------------
 115  * Initialise an area of memory as a sprite area
 116  *
 117  */
 118 void sprite_area_initialise(sprite_area *, int size);
 119
 120 /* ----------------------- sprite_area_readinfo ----------------------------
 121  * Read information from a sprite area control block
 122  *
 123  */
 124 extern os_error * sprite_area_readinfo(sprite_area *, sprite_area *resultarea);
 125
 126 /* --------------------------- sprite_area_reinit --------------------------
 127  * Reinitialise a sprite area.
 128  * If system area, then equivalent to *SNew
 129  *
 130  */
 131 extern os_error * sprite_area_reinit(sprite_area *);
 132
 133 /* --------------------------- sprite_area_load ----------------------------
 134  * Load a sprite file into a sprite area.
 135  * If system area, then equivalent to *SLoad
 136  *
 137  */
 138 extern os_error * sprite_area_load(sprite_area *, const char *filename);
 139
 140 /* ---------------------------- sprite_area_merge --------------------------
 141  * Merge a sprite file with a sprite area.
 142  * If system area, then equivalent to *SMerge
 143  *
 144  */
 145 extern os_error * sprite_area_merge(sprite_area *, const char *filename);
 146
 147 /* ---------------------------- sprite_area_save ---------------------------
 148  * Saves a sprite area as a sprite file.
 149  * If system area, then equivalent to *SSave
 150  *
 151  */
 152 extern os_error * sprite_area_save(sprite_area *, const char *filename);
 153
 154 /* ---------------------------- sprite_getname -----------------------------
 155  * Return the name and length of name of the n'th sprite in a sprite area into
 156  * a buffer.
 157  *
 158  */
 159 extern os_error * sprite_getname(sprite_area *, void *buffer, int *length, int index);
 160
 161 /* ---------------------------- sprite_get ---------------------------------
 162  * Copy a rectangle of screen delimited by the last pair of graphics cursor
 163  * positions as a named sprite in a sprite area, optionally storing the
 164  * palette with the sprite.
 165  *
 166  */
 167 extern os_error * sprite_get(sprite_area *, char *name, sprite_palflag);
 168
 169 /* ---------------------------- sprite_get_rp ------------------------------
 170  * Copy a rectangle of screen delimited by the last pair of graphics cursor
 171  * positions as a named sprite in a sprite area, optionally storing the
 172  * palette with the sprite. Address of sprite returned in resultaddress.
 173  *
 174  */
 175 extern os_error * sprite_get_rp(sprite_area *, char *name, sprite_palflag,
 176                          sprite_ptr *resultaddress);
 177
 178 /* ---------------------------- sprite_get_given ---------------------------
 179  * Copy a rectangle of screen delimited by the given pair of graphics
 180  * coordinates as a named sprite in a sprite area, optionally storing the
 181  * palette with the sprite.
 182  *
 183  */
 184 extern os_error * sprite_get_given(sprite_area *, char *name, sprite_palflag,
 185                             int x0, int y0, int x1, int y1);
 186
 187 /* --------------------------- sprite_get_given_rp -------------------------
 188  * Copy a rectangle of screen delimited by the given pair of graphics
 189  * coordinates as a named sprite in a sprite area, optionally storing the
 190  * palette with the sprite. Address of sprite returned in resultaddress.
 191  *
 192  */
 193 extern os_error * sprite_get_given_rp(sprite_area *, char *name, sprite_palflag,
 194                                int x0, int y0, int x1, int y1,
 195                                sprite_ptr *resultaddress);
 196
 197 /* ------------------------------ sprite_create ----------------------------
 198  * Create a named sprite in a sprite area of specified size and screen mode,
 199  * optionally reserving space for palette data with the sprite.
 200  *
 201  */
 202 extern os_error * sprite_create(sprite_area *, char *name, sprite_palflag,
 203                          int width, int height, int mode);
 204
 205 /* ------------------------------ sprite_create_rp -------------------------
 206  * Create a named sprite in a sprite area of specified size and screen mode,
 207  * optionally reserving space for palette data with the sprite.Address of
 208  * sprite returned in resultaddress.
 209  *
 210  */
 211 extern os_error * sprite_create_rp(sprite_area *, char *name, sprite_palflag,
 212                             int width, int height, int mode,
 213                             sprite_ptr *resultaddress);
 214
 215
 216 /*********** Operations on system/user area, name/sprite pointer **********/
 217
 218 typedef enum
 219 {
 220   sprite_id_name = 0,
 221   sprite_id_addr = 0x74527053 /* 'Magic' number ("SpRt") to test against */
 222 } sprite_type;
 223
 224 typedef struct
 225 {
 226   union
 227   {
 228     char *     name; /* Can use either name of sprite or address (faster) */
 229     sprite_ptr addr;
 230   } s;
 231   sprite_type tag;   /* User must tag the use of this structure manually */
 232 } sprite_id;
 233
 234
 235 /* ----------------------------- sprite_select -----------------------------
 236  * Select the specified sprite for plotting using plot(0xed,x,y).
 237  *
 238  */
 239 extern os_error * sprite_select(sprite_area *, sprite_id *);
 240
 241 /* ----------------------------- sprite_select_rp --------------------------
 242  * Select the specified sprite for plotting using plot(0xed,x,y). Address of
 243  * sprite returned in resultaddress.
 244  *
 245  */
 246 extern os_error * sprite_select_rp(sprite_area *, sprite_id *,
 247                             sprite_ptr *resultaddress);
 248
 249 /* ----------------------------- sprite_delete -----------------------------
 250  * Delete the specified sprite.
 251  *
 252  */
 253 extern os_error * sprite_delete(sprite_area *, sprite_id *);
 254
 255 /* ----------------------------- sprite_rename -----------------------------
 256  * Rename the specified sprite within the same sprite area.
 257  *
 258  */
 259 extern os_error * sprite_rename(sprite_area *, sprite_id *, char *newname);
 260
 261 /* ----------------------------- sprite_copy -------------------------------
 262  * Copy the specified sprite as another named sprite in the same sprite area.
 263  *
 264  */
 265 extern os_error * sprite_copy(sprite_area *, sprite_id *, char *copyname);
 266
 267 /* ----------------------------- sprite_put --------------------------------
 268  * Plot the specified sprite using the given GCOL action.
 269  *
 270  */
 271 extern os_error * sprite_put(sprite_area *, sprite_id *, int gcol);
 272
 273 /* ----------------------------- sprite_put_given --------------------------
 274  * Plot the specified sprite at (x,y) using the given GCOL action.
 275  *
 276  */
 277 extern os_error * sprite_put_given(sprite_area *, sprite_id *, int gcol,
 278                             int x, int y);
 279
 280 /* --------------------------- sprite_put_scaled ---------------------------
 281  * Plot the specified sprite at (x,y) using the given GCOL action, and scaled
 282  * using the given scale factors.
 283  *
 284  */
 285 extern os_error * sprite_put_scaled(sprite_area *, sprite_id *, int gcol,
 286                             int x, int y,
 287                             sprite_factors *factors,
 288                             sprite_pixtrans pixtrans[]);
 289
 290 /* ---------------------------- sprite_put_greyscaled ----------------------
 291  * Plot the specified sprite at (x,y) using the given GCOL action, and
 292  * greyscaled using the given scale factors.
 293  *
 294  */
 295 extern os_error * sprite_put_greyscaled(sprite_area *, sprite_id *,
 296                             int x, int y,
 297                             sprite_factors *factors,
 298                             sprite_pixtrans pixtrans[]);
 299
 300 /* ----------------------------- sprite_put_mask ---------------------------
 301  * Plot the specified sprite mask in the background colour.
 302  *
 303  */
 304 extern os_error * sprite_put_mask(sprite_area *, sprite_id *);
 305
 306 /* ----------------------------- sprite_put_mask_given ---------------------
 307  * Plot the specified sprite mask at (x,y) in the background colour.
 308  *
 309  */
 310 extern os_error * sprite_put_mask_given(sprite_area *, sprite_id *, int x, int y);
 311
 312 /* --------------------------- sprite_put_mask_scaled ----------------------
 313  * Plot the sprite mask at (x,y) scaled, using the background colour/action
 314  *
 315  */
 316 extern os_error * sprite_put_mask_scaled(sprite_area *, sprite_id *,
 317                             int x, int y,
 318                             sprite_factors *factors);
 319
 320 /* ----------------------------- sprite_put_char_scaled --------------------
 321  * Paint char scaled at (x,y)
 322  *
 323  */
 324 extern os_error * sprite_put_char_scaled(char ch,
 325                                   int x, int y,
 326                                   sprite_factors *factors);
 327
 328 /* ---------------------------- sprite_create_mask -------------------------
 329  * Create a mask definition for the specified sprite.
 330  *
 331  */
 332 extern os_error * sprite_create_mask(sprite_area *, sprite_id *);
 333
 334 /* ---------------------------- sprite_remove_mask -------------------------
 335  * Remove the mask definition from the specified sprite.
 336  *
 337  */
 338 extern os_error * sprite_remove_mask(sprite_area *, sprite_id *);
 339
 340 /* ---------------------------- sprite_insert_row --------------------------
 341  * Insert a row into the specified sprite at the given row.
 342  *
 343  */
 344 extern os_error * sprite_insert_row(sprite_area *, sprite_id *, int row);
 345
 346 /* ---------------------------- sprite_delete_row --------------------------
 347  * Delete the given row from the specified sprite.
 348  *
 349  */
 350 extern os_error * sprite_delete_row(sprite_area *, sprite_id *, int row);
 351
 352 /* ---------------------------- sprite_insert_column -----------------------
 353  * Insert a column into the specified sprite at the given column.
 354  *
 355  */
 356 extern os_error * sprite_insert_column(sprite_area *, sprite_id *, int column);
 357
 358 /* ---------------------------- sprite_delete_column -----------------------
 359  * Delete the given column from the specified sprite.
 360  *
 361  */
 362 extern os_error * sprite_delete_column(sprite_area *, sprite_id *, int column);
 363
 364 /* ----------------------------- sprite_flip_x -----------------------------
 365  * Flip the specified sprite about the x axis
 366  *
 367  */
 368 extern os_error * sprite_flip_x(sprite_area *, sprite_id *);
 369
 370 /* ----------------------------- sprite_flip_y -----------------------------
 371  * Flip the specified sprite about the y axis
 372  *
 373  */
 374 extern os_error * sprite_flip_y(sprite_area *, sprite_id *);
 375
 376
 377 typedef struct
 378 {
 379  int width;
 380  int height;
 381  int mask;
 382  int mode;
 383 } sprite_info;
 384
 385 /* -------------------------------- sprite_readsize ------------------------
 386  * Read the size information for the specified sprite_id
 387  *
 388  */
 389 extern os_error * sprite_readsize(sprite_area *, sprite_id *,
 390                            sprite_info *resultinfo);
 391
 392
 393 typedef struct
 394 {
 395   int colour;
 396   int tint;
 397 } sprite_colour;
 398
 399 /* ----------------------------- sprite_readpixel --------------------------
 400  * Read the colour of a given pixel in the specified sprite_id
 401  *
 402  */
 403 extern os_error * sprite_readpixel(sprite_area *, sprite_id *,
 404                             int x, int y, sprite_colour *resultcolour);
 405
 406 /* ----------------------------- sprite_writepixel -------------------------
 407  * Write the colour of a given pixel in the specified sprite_id
 408  *
 409  */
 410 extern os_error * sprite_writepixel(sprite_area *, sprite_id *,
 411                              int x, int y, sprite_colour *colour);
 412
 413
 414 typedef enum
 415 {
 416   sprite_masktransparent = 0,
 417   sprite_masksolid       = 1
 418 } sprite_maskstate;
 419
 420 /* ------------------------------- sprite_readmask -------------------------
 421  * Read the state of a given pixel in the specified sprite mask
 422  *
 423  */
 424 extern os_error * sprite_readmask(sprite_area *, sprite_id *,
 425                            int x, int y, sprite_maskstate *resultmaskstate);
 426
 427 /* ------------------------------- sprite_writemask ------------------------
 428  * Write the state of a given pixel in the specified sprite mask
 429  *
 430  */
 431 extern os_error * sprite_writemask(sprite_area *, sprite_id *,
 432                             int x, int y, sprite_maskstate *maskstate);
 433
 434
 435 typedef struct
 436         { int r[4];
 437         } sprite_state;
 438
 439 /* ----------------------------- sprite_restorestate -----------------------
 440  * Restores the old state after one of the sprite redirection calls
 441  *
 442  */
 443 extern os_error *sprite_restorestate(sprite_state state);
 444
 445
 446 /* ---------------------------- sprite_outputtosprite ----------------------
 447  * Redirect VDU output to a sprite, saving old state
 448  *
 449  */
 450 extern os_error *sprite_outputtosprite(sprite_area *area, sprite_id *id,
 451                                 int *save_area, sprite_state *state);
 452
 453 /* ----------------------- sprite_outputtomask -----------------------------
 454  * Redirects output to a sprite's transparency mask, saving old state
 455  *
 456  */
 457 extern os_error *sprite_outputtomask(sprite_area *area, sprite_id *id,
 458                               int *save_area, sprite_state *state);
 459
 460 /* --------------------------- sprite_outputtoscreen -----------------------
 461  * Redirect output back to screen, saving old state
 462  *
 463  */
 464 extern os_error *sprite_outputtoscreen(int *save_area, sprite_state *state);
 465
 466 /* --------------------------- sprite_sizeof_spritecontext -----------------
 467  * Get size of save area needed to save sprite context.
 468  *
 469  */
 470 extern os_error *sprite_sizeof_spritecontext(sprite_area *area, sprite_id *id,
 471                                       int *size);
 472
 473 /* ------------------------- sprite_sizeof_screencontext -------------------
 474  * Get size of save area needed to save screen context.
 475  *
 476  */
 477 extern os_error *sprite_sizeof_screencontext(int *size);
 478
 479 /* ------------------------ sprite_removewastage ---------------------------
 480  * Removes left hand wastage from a sprite
 481  *
 482  */
 483 extern os_error *sprite_removewastage(sprite_area *area, sprite_id *id);
 484
 485
 486 /* new SWIs */
 487
 488 /* ------------------------ sprite_change_size -----------------------------
 489  * General insert/delete rows/columns operations
 490  *
 491  */
 492 extern os_error
 493   *sprite_change_size
 494   (sprite_area *area, sprite_id *id, BOOL rows, int at, int number);
 495
 496 /* Typedefs and functions for rotating sprites. */
 497
 498 typedef struct {int p0 [2], p1 [2], p2 [2], p3 [2];} sprite_pgm;
 499 typedef int sprite_transmat [6];
 500 typedef struct {int x0, y0, x1, y1;} sprite_box;
 501
 502 /* ------------------------ sprite_put_mask_trans ---------------------
 503  * Put a box from the mask in background colours through a transformation matrix
 504  *
 505  */
 506 extern os_error
 507   *sprite_put_mask_trans
 508   (sprite_area *, sprite_id *, sprite_box *, sprite_transmat *);
 509
 510 /* ------------------------ sprite_put_mask_pgm -----------------------
 511  * Put a box from the mask in background colours to a parallelogram
 512  *
 513  */
 514 extern os_error
 515   *sprite_put_mask_pgm
 516   (sprite_area *, sprite_id *, sprite_box *, sprite_pgm *);
 517
 518 /* ------------------------ sprite_put_trans --------------------------
 519  * Put a box from the sprite through a transformation matrix
 520  *
 521  */
 522 extern os_error
 523   *sprite_put_trans
 524   (sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_transmat *, sprite_pixtrans *);
 525
 526 /* ------------------------ sprite_put_pgm ----------------------------
 527  * Put a box from the sprite to a parallelogram
 528  *
 529  */
 530 extern os_error
 531   *sprite_put_pgm
 532   (sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_pgm *, sprite_pixtrans *);
 533
 534 # endif
 535
 536 /* end of sprite.h */