2ee739cc |
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 */ |