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. *
7 ***************************************************************************/
9 /*----- Licensing note ----------------------------------------------------*
11 * This file is part of Straylight's Steel library.
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)
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.
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.
30 * Purpose: provide access to RISC OS sprite facilities
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
51 /******** Simple operations, use no sprite area, no name/sprite pointer ***/
61 int xmag,ymag,xdiv,ydiv;
64 typedef char sprite_pixtrans;
69 /* ----------------------------- sprite_screensave -------------------------
70 * Save the current graphics window as a sprite file, with optional palette.
71 * Equivalent to *ScreenSave.
74 extern os_error * sprite_screensave(const char *filename, sprite_palflag);
76 /* ---------------------------- sprite_screenload --------------------------
77 * Load a sprite file onto the screen. Equivalent to *ScreenLoad.
80 extern os_error * sprite_screenload(const char *filename);
84 /****** Operations on either system/user area, no name/sprite pointer *****/
86 typedef struct /* Format of a sprite area control block */
94 typedef struct /* Format of a sprite header */
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 */
109 #define sprite_mainarea ((sprite_area *) 0)
111 typedef void * sprite_ptr;
114 /* ------------------------ sprite_area_initialise -------------------------
115 * Initialise an area of memory as a sprite area
118 void sprite_area_initialise(sprite_area *, int size);
120 /* ----------------------- sprite_area_readinfo ----------------------------
121 * Read information from a sprite area control block
124 extern os_error * sprite_area_readinfo(sprite_area *, sprite_area *resultarea);
126 /* --------------------------- sprite_area_reinit --------------------------
127 * Reinitialise a sprite area.
128 * If system area, then equivalent to *SNew
131 extern os_error * sprite_area_reinit(sprite_area *);
133 /* --------------------------- sprite_area_load ----------------------------
134 * Load a sprite file into a sprite area.
135 * If system area, then equivalent to *SLoad
138 extern os_error * sprite_area_load(sprite_area *, const char *filename);
140 /* ---------------------------- sprite_area_merge --------------------------
141 * Merge a sprite file with a sprite area.
142 * If system area, then equivalent to *SMerge
145 extern os_error * sprite_area_merge(sprite_area *, const char *filename);
147 /* ---------------------------- sprite_area_save ---------------------------
148 * Saves a sprite area as a sprite file.
149 * If system area, then equivalent to *SSave
152 extern os_error * sprite_area_save(sprite_area *, const char *filename);
154 /* ---------------------------- sprite_getname -----------------------------
155 * Return the name and length of name of the n'th sprite in a sprite area into
159 extern os_error * sprite_getname(sprite_area *, void *buffer, int *length, int index);
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.
167 extern os_error * sprite_get(sprite_area *, char *name, sprite_palflag);
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.
175 extern os_error * sprite_get_rp(sprite_area *, char *name, sprite_palflag,
176 sprite_ptr *resultaddress);
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.
184 extern os_error * sprite_get_given(sprite_area *, char *name, sprite_palflag,
185 int x0, int y0, int x1, int y1);
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.
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);
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.
202 extern os_error * sprite_create(sprite_area *, char *name, sprite_palflag,
203 int width, int height, int mode);
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.
211 extern os_error * sprite_create_rp(sprite_area *, char *name, sprite_palflag,
212 int width, int height, int mode,
213 sprite_ptr *resultaddress);
216 /*********** Operations on system/user area, name/sprite pointer **********/
221 sprite_id_addr = 0x74527053 /* 'Magic' number ("SpRt") to test against */
228 char * name; /* Can use either name of sprite or address (faster) */
231 sprite_type tag; /* User must tag the use of this structure manually */
235 /* ----------------------------- sprite_select -----------------------------
236 * Select the specified sprite for plotting using plot(0xed,x,y).
239 extern os_error * sprite_select(sprite_area *, sprite_id *);
241 /* ----------------------------- sprite_select_rp --------------------------
242 * Select the specified sprite for plotting using plot(0xed,x,y). Address of
243 * sprite returned in resultaddress.
246 extern os_error * sprite_select_rp(sprite_area *, sprite_id *,
247 sprite_ptr *resultaddress);
249 /* ----------------------------- sprite_delete -----------------------------
250 * Delete the specified sprite.
253 extern os_error * sprite_delete(sprite_area *, sprite_id *);
255 /* ----------------------------- sprite_rename -----------------------------
256 * Rename the specified sprite within the same sprite area.
259 extern os_error * sprite_rename(sprite_area *, sprite_id *, char *newname);
261 /* ----------------------------- sprite_copy -------------------------------
262 * Copy the specified sprite as another named sprite in the same sprite area.
265 extern os_error * sprite_copy(sprite_area *, sprite_id *, char *copyname);
267 /* ----------------------------- sprite_put --------------------------------
268 * Plot the specified sprite using the given GCOL action.
271 extern os_error * sprite_put(sprite_area *, sprite_id *, int gcol);
273 /* ----------------------------- sprite_put_given --------------------------
274 * Plot the specified sprite at (x,y) using the given GCOL action.
277 extern os_error * sprite_put_given(sprite_area *, sprite_id *, int gcol,
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.
285 extern os_error * sprite_put_scaled(sprite_area *, sprite_id *, int gcol,
287 sprite_factors *factors,
288 sprite_pixtrans pixtrans[]);
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.
295 extern os_error * sprite_put_greyscaled(sprite_area *, sprite_id *,
297 sprite_factors *factors,
298 sprite_pixtrans pixtrans[]);
300 /* ----------------------------- sprite_put_mask ---------------------------
301 * Plot the specified sprite mask in the background colour.
304 extern os_error * sprite_put_mask(sprite_area *, sprite_id *);
306 /* ----------------------------- sprite_put_mask_given ---------------------
307 * Plot the specified sprite mask at (x,y) in the background colour.
310 extern os_error * sprite_put_mask_given(sprite_area *, sprite_id *, int x, int y);
312 /* --------------------------- sprite_put_mask_scaled ----------------------
313 * Plot the sprite mask at (x,y) scaled, using the background colour/action
316 extern os_error * sprite_put_mask_scaled(sprite_area *, sprite_id *,
318 sprite_factors *factors);
320 /* ----------------------------- sprite_put_char_scaled --------------------
321 * Paint char scaled at (x,y)
324 extern os_error * sprite_put_char_scaled(char ch,
326 sprite_factors *factors);
328 /* ---------------------------- sprite_create_mask -------------------------
329 * Create a mask definition for the specified sprite.
332 extern os_error * sprite_create_mask(sprite_area *, sprite_id *);
334 /* ---------------------------- sprite_remove_mask -------------------------
335 * Remove the mask definition from the specified sprite.
338 extern os_error * sprite_remove_mask(sprite_area *, sprite_id *);
340 /* ---------------------------- sprite_insert_row --------------------------
341 * Insert a row into the specified sprite at the given row.
344 extern os_error * sprite_insert_row(sprite_area *, sprite_id *, int row);
346 /* ---------------------------- sprite_delete_row --------------------------
347 * Delete the given row from the specified sprite.
350 extern os_error * sprite_delete_row(sprite_area *, sprite_id *, int row);
352 /* ---------------------------- sprite_insert_column -----------------------
353 * Insert a column into the specified sprite at the given column.
356 extern os_error * sprite_insert_column(sprite_area *, sprite_id *, int column);
358 /* ---------------------------- sprite_delete_column -----------------------
359 * Delete the given column from the specified sprite.
362 extern os_error * sprite_delete_column(sprite_area *, sprite_id *, int column);
364 /* ----------------------------- sprite_flip_x -----------------------------
365 * Flip the specified sprite about the x axis
368 extern os_error * sprite_flip_x(sprite_area *, sprite_id *);
370 /* ----------------------------- sprite_flip_y -----------------------------
371 * Flip the specified sprite about the y axis
374 extern os_error * sprite_flip_y(sprite_area *, sprite_id *);
385 /* -------------------------------- sprite_readsize ------------------------
386 * Read the size information for the specified sprite_id
389 extern os_error * sprite_readsize(sprite_area *, sprite_id *,
390 sprite_info *resultinfo);
399 /* ----------------------------- sprite_readpixel --------------------------
400 * Read the colour of a given pixel in the specified sprite_id
403 extern os_error * sprite_readpixel(sprite_area *, sprite_id *,
404 int x, int y, sprite_colour *resultcolour);
406 /* ----------------------------- sprite_writepixel -------------------------
407 * Write the colour of a given pixel in the specified sprite_id
410 extern os_error * sprite_writepixel(sprite_area *, sprite_id *,
411 int x, int y, sprite_colour *colour);
416 sprite_masktransparent = 0,
420 /* ------------------------------- sprite_readmask -------------------------
421 * Read the state of a given pixel in the specified sprite mask
424 extern os_error * sprite_readmask(sprite_area *, sprite_id *,
425 int x, int y, sprite_maskstate *resultmaskstate);
427 /* ------------------------------- sprite_writemask ------------------------
428 * Write the state of a given pixel in the specified sprite mask
431 extern os_error * sprite_writemask(sprite_area *, sprite_id *,
432 int x, int y, sprite_maskstate *maskstate);
439 /* ----------------------------- sprite_restorestate -----------------------
440 * Restores the old state after one of the sprite redirection calls
443 extern os_error *sprite_restorestate(sprite_state state);
446 /* ---------------------------- sprite_outputtosprite ----------------------
447 * Redirect VDU output to a sprite, saving old state
450 extern os_error *sprite_outputtosprite(sprite_area *area, sprite_id *id,
451 int *save_area, sprite_state *state);
453 /* ----------------------- sprite_outputtomask -----------------------------
454 * Redirects output to a sprite's transparency mask, saving old state
457 extern os_error *sprite_outputtomask(sprite_area *area, sprite_id *id,
458 int *save_area, sprite_state *state);
460 /* --------------------------- sprite_outputtoscreen -----------------------
461 * Redirect output back to screen, saving old state
464 extern os_error *sprite_outputtoscreen(int *save_area, sprite_state *state);
466 /* --------------------------- sprite_sizeof_spritecontext -----------------
467 * Get size of save area needed to save sprite context.
470 extern os_error *sprite_sizeof_spritecontext(sprite_area *area, sprite_id *id,
473 /* ------------------------- sprite_sizeof_screencontext -------------------
474 * Get size of save area needed to save screen context.
477 extern os_error *sprite_sizeof_screencontext(int *size);
479 /* ------------------------ sprite_removewastage ---------------------------
480 * Removes left hand wastage from a sprite
483 extern os_error *sprite_removewastage(sprite_area *area, sprite_id *id);
488 /* ------------------------ sprite_change_size -----------------------------
489 * General insert/delete rows/columns operations
494 (sprite_area *area, sprite_id *id, BOOL rows, int at, int number);
496 /* Typedefs and functions for rotating sprites. */
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;
502 /* ------------------------ sprite_put_mask_trans ---------------------
503 * Put a box from the mask in background colours through a transformation matrix
507 *sprite_put_mask_trans
508 (sprite_area *, sprite_id *, sprite_box *, sprite_transmat *);
510 /* ------------------------ sprite_put_mask_pgm -----------------------
511 * Put a box from the mask in background colours to a parallelogram
516 (sprite_area *, sprite_id *, sprite_box *, sprite_pgm *);
518 /* ------------------------ sprite_put_trans --------------------------
519 * Put a box from the sprite through a transformation matrix
524 (sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_transmat *, sprite_pixtrans *);
526 /* ------------------------ sprite_put_pgm ----------------------------
527 * Put a box from the sprite to a parallelogram
532 (sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_pgm *, sprite_pixtrans *);
536 /* end of sprite.h */