/* Copyright 1996 Acorn Computers Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/****************************************************************************
* This source file was written by Acorn Computers Limited. It is part of *
* the RISCOS library for writing applications in C for RISC OS. It may be *
* used freely in the creation of programs for Archimedes. It should be *
* used with Acorn's C Compiler Release 3 or later. *
* *
***************************************************************************/
/*
* Title : sprite.h
* Purpose: provide access to RISC OS sprite facilities
*
*/
# ifndef __sprite_h
# define __sprite_h
# ifndef __os_h
# include "os.h"
# endif
/*
* This file contains functions for performing operations on sprites.
* For brevity only a brief description is given for each call. More details
* can be found in the Programmer's Reference manual under the section on
* Sprite SWIs.
*
*/
/******** Simple operations, use no sprite area, no name/sprite pointer ***/
typedef enum
{
sprite_nopalette = 0,
sprite_haspalette = 1
} sprite_palflag;
typedef struct
{
int xmag,ymag,xdiv,ydiv;
} sprite_factors;
typedef char sprite_pixtrans;
/* ----------------------------- sprite_screensave -------------------------
* Save the current graphics window as a sprite file, with optional palette.
* Equivalent to *ScreenSave.
*
*/
extern os_error * sprite_screensave(const char *filename, sprite_palflag);
/* ---------------------------- sprite_screenload --------------------------
* Load a sprite file onto the screen. Equivalent to *ScreenLoad.
*
*/
extern os_error * sprite_screenload(const char *filename);
/****** Operations on either system/user area, no name/sprite pointer *****/
typedef struct /* Format of a sprite area control block */
{
int size;
int number;
int sproff;
int freeoff;
} sprite_area;
typedef struct /* Format of a sprite header */
{
int next; /* Offset to next sprite */
char name[12]; /* Sprite name */
int width; /* Width in words-1 (0..639) */
int height; /* Height in scanlines-1 (0..255/511) */
int lbit; /* First bit used (left end of row) */
int rbit; /* Last bit used (right end of row) */
int image; /* Offset to sprite image */
int mask; /* Offset to transparency mask */
int mode; /* Mode sprite was defined in */
/* Palette data optionally follows here */
/* in memory */
} sprite_header;
#define sprite_mainarea ((sprite_area *) 0)
typedef void * sprite_ptr;
/* ------------------------ sprite_area_initialise -------------------------
* Initialise an area of memory as a sprite area
*
*/
void sprite_area_initialise(sprite_area *, int size);
/* ----------------------- sprite_area_readinfo ----------------------------
* Read information from a sprite area control block
*
*/
extern os_error * sprite_area_readinfo(sprite_area *, sprite_area *resultarea);
/* --------------------------- sprite_area_reinit --------------------------
* Reinitialise a sprite area.
* If system area, then equivalent to *SNew
*
*/
extern os_error * sprite_area_reinit(sprite_area *);
/* --------------------------- sprite_area_load ----------------------------
* Load a sprite file into a sprite area.
* If system area, then equivalent to *SLoad
*
*/
extern os_error * sprite_area_load(sprite_area *, const char *filename);
/* ---------------------------- sprite_area_merge --------------------------
* Merge a sprite file with a sprite area.
* If system area, then equivalent to *SMerge
*
*/
extern os_error * sprite_area_merge(sprite_area *, const char *filename);
/* ---------------------------- sprite_area_save ---------------------------
* Saves a sprite area as a sprite file.
* If system area, then equivalent to *SSave
*
*/
extern os_error * sprite_area_save(sprite_area *, const char *filename);
/* ---------------------------- sprite_getname -----------------------------
* Return the name and length of name of the n'th sprite in a sprite area into
* a buffer.
*
*/
extern os_error * sprite_getname(sprite_area *, void *buffer, int *length, int index);
/* ---------------------------- sprite_get ---------------------------------
* Copy a rectangle of screen delimited by the last pair of graphics cursor
* positions as a named sprite in a sprite area, optionally storing the
* palette with the sprite.
*
*/
extern os_error * sprite_get(sprite_area *, char *name, sprite_palflag);
/* ---------------------------- sprite_get_rp ------------------------------
* Copy a rectangle of screen delimited by the last pair of graphics cursor
* positions as a named sprite in a sprite area, optionally storing the
* palette with the sprite. Address of sprite returned in resultaddress.
*
*/
extern os_error * sprite_get_rp(sprite_area *, char *name, sprite_palflag,
sprite_ptr *resultaddress);
/* ---------------------------- sprite_get_given ---------------------------
* Copy a rectangle of screen delimited by the given pair of graphics
* coordinates as a named sprite in a sprite area, optionally storing the
* palette with the sprite.
*
*/
extern os_error * sprite_get_given(sprite_area *, char *name, sprite_palflag,
int x0, int y0, int x1, int y1);
/* --------------------------- sprite_get_given_rp -------------------------
* Copy a rectangle of screen delimited by the given pair of graphics
* coordinates as a named sprite in a sprite area, optionally storing the
* palette with the sprite. Address of sprite returned in resultaddress.
*
*/
extern os_error * sprite_get_given_rp(sprite_area *, char *name, sprite_palflag,
int x0, int y0, int x1, int y1,
sprite_ptr *resultaddress);
/* ------------------------------ sprite_create ----------------------------
* Create a named sprite in a sprite area of specified size and screen mode,
* optionally reserving space for palette data with the sprite.
*
*/
extern os_error * sprite_create(sprite_area *, char *name, sprite_palflag,
int width, int height, int mode);
/* ------------------------------ sprite_create_rp -------------------------
* Create a named sprite in a sprite area of specified size and screen mode,
* optionally reserving space for palette data with the sprite.Address of
* sprite returned in resultaddress.
*
*/
extern os_error * sprite_create_rp(sprite_area *, char *name, sprite_palflag,
int width, int height, int mode,
sprite_ptr *resultaddress);
/*********** Operations on system/user area, name/sprite pointer **********/
typedef enum
{
sprite_id_name = 0,
sprite_id_addr = 0x74527053 /* 'Magic' number ("SpRt") to test against */
} sprite_type;
typedef struct
{
union
{
char * name; /* Can use either name of sprite or address (faster) */
sprite_ptr addr;
} s;
sprite_type tag; /* User must tag the use of this structure manually */
} sprite_id;
/* ----------------------------- sprite_select -----------------------------
* Select the specified sprite for plotting using plot(0xed,x,y).
*
*/
extern os_error * sprite_select(sprite_area *, sprite_id *);
/* ----------------------------- sprite_select_rp --------------------------
* Select the specified sprite for plotting using plot(0xed,x,y). Address of
* sprite returned in resultaddress.
*
*/
extern os_error * sprite_select_rp(sprite_area *, sprite_id *,
sprite_ptr *resultaddress);
/* ----------------------------- sprite_delete -----------------------------
* Delete the specified sprite.
*
*/
extern os_error * sprite_delete(sprite_area *, sprite_id *);
/* ----------------------------- sprite_rename -----------------------------
* Rename the specified sprite within the same sprite area.
*
*/
extern os_error * sprite_rename(sprite_area *, sprite_id *, char *newname);
/* ----------------------------- sprite_copy -------------------------------
* Copy the specified sprite as another named sprite in the same sprite area.
*
*/
extern os_error * sprite_copy(sprite_area *, sprite_id *, char *copyname);
/* ----------------------------- sprite_put --------------------------------
* Plot the specified sprite using the given GCOL action.
*
*/
extern os_error * sprite_put(sprite_area *, sprite_id *, int gcol);
/* ----------------------------- sprite_put_given --------------------------
* Plot the specified sprite at (x,y) using the given GCOL action.
*
*/
extern os_error * sprite_put_given(sprite_area *, sprite_id *, int gcol,
int x, int y);
/* --------------------------- sprite_put_scaled ---------------------------
* Plot the specified sprite at (x,y) using the given GCOL action, and scaled
* using the given scale factors.
*
*/
extern os_error * sprite_put_scaled(sprite_area *, sprite_id *, int gcol,
int x, int y,
sprite_factors *factors,
sprite_pixtrans pixtrans[]);
/* ---------------------------- sprite_put_greyscaled ----------------------
* Plot the specified sprite at (x,y) using the given GCOL action, and
* greyscaled using the given scale factors.
*
*/
extern os_error * sprite_put_greyscaled(sprite_area *, sprite_id *,
int x, int y,
sprite_factors *factors,
sprite_pixtrans pixtrans[]);
/* ----------------------------- sprite_put_mask ---------------------------
* Plot the specified sprite mask in the background colour.
*
*/
extern os_error * sprite_put_mask(sprite_area *, sprite_id *);
/* ----------------------------- sprite_put_mask_given ---------------------
* Plot the specified sprite mask at (x,y) in the background colour.
*
*/
extern os_error * sprite_put_mask_given(sprite_area *, sprite_id *, int x, int y);
/* --------------------------- sprite_put_mask_scaled ----------------------
* Plot the sprite mask at (x,y) scaled, using the background colour/action
*
*/
extern os_error * sprite_put_mask_scaled(sprite_area *, sprite_id *,
int x, int y,
sprite_factors *factors);
/* ----------------------------- sprite_put_char_scaled --------------------
* Paint char scaled at (x,y)
*
*/
extern os_error * sprite_put_char_scaled(char ch,
int x, int y,
sprite_factors *factors);
/* ---------------------------- sprite_create_mask -------------------------
* Create a mask definition for the specified sprite.
*
*/
extern os_error * sprite_create_mask(sprite_area *, sprite_id *);
/* ---------------------------- sprite_remove_mask -------------------------
* Remove the mask definition from the specified sprite.
*
*/
extern os_error * sprite_remove_mask(sprite_area *, sprite_id *);
/* ---------------------------- sprite_insert_row --------------------------
* Insert a row into the specified sprite at the given row.
*
*/
extern os_error * sprite_insert_row(sprite_area *, sprite_id *, int row);
/* ---------------------------- sprite_delete_row --------------------------
* Delete the given row from the specified sprite.
*
*/
extern os_error * sprite_delete_row(sprite_area *, sprite_id *, int row);
/* ---------------------------- sprite_insert_column -----------------------
* Insert a column into the specified sprite at the given column.
*
*/
extern os_error * sprite_insert_column(sprite_area *, sprite_id *, int column);
/* ---------------------------- sprite_delete_column -----------------------
* Delete the given column from the specified sprite.
*
*/
extern os_error * sprite_delete_column(sprite_area *, sprite_id *, int column);
/* ----------------------------- sprite_flip_x -----------------------------
* Flip the specified sprite about the x axis
*
*/
extern os_error * sprite_flip_x(sprite_area *, sprite_id *);
/* ----------------------------- sprite_flip_y -----------------------------
* Flip the specified sprite about the y axis
*
*/
extern os_error * sprite_flip_y(sprite_area *, sprite_id *);
typedef struct
{
int width;
int height;
int mask;
int mode;
} sprite_info;
/* -------------------------------- sprite_readsize ------------------------
* Read the size information for the specified sprite_id
*
*/
extern os_error * sprite_readsize(sprite_area *, sprite_id *,
sprite_info *resultinfo);
typedef struct
{
int colour;
int tint;
} sprite_colour;
/* ----------------------------- sprite_readpixel --------------------------
* Read the colour of a given pixel in the specified sprite_id
*
*/
extern os_error * sprite_readpixel(sprite_area *, sprite_id *,
int x, int y, sprite_colour *resultcolour);
/* ----------------------------- sprite_writepixel -------------------------
* Write the colour of a given pixel in the specified sprite_id
*
*/
extern os_error * sprite_writepixel(sprite_area *, sprite_id *,
int x, int y, sprite_colour *colour);
typedef enum
{
sprite_masktransparent = 0,
sprite_masksolid = 1
} sprite_maskstate;
/* ------------------------------- sprite_readmask -------------------------
* Read the state of a given pixel in the specified sprite mask
*
*/
extern os_error * sprite_readmask(sprite_area *, sprite_id *,
int x, int y, sprite_maskstate *resultmaskstate);
/* ------------------------------- sprite_writemask ------------------------
* Write the state of a given pixel in the specified sprite mask
*
*/
extern os_error * sprite_writemask(sprite_area *, sprite_id *,
int x, int y, sprite_maskstate *maskstate);
typedef struct
{ int r[4];
} sprite_state;
/* ----------------------------- sprite_restorestate -----------------------
* Restores the old state after one of the sprite redirection calls
*
*/
extern os_error *sprite_restorestate(sprite_state state);
/* ---------------------------- sprite_outputtosprite ----------------------
* Redirect VDU output to a sprite, saving old state
*
*/
extern os_error *sprite_outputtosprite(sprite_area *area, sprite_id *id,
int *save_area, sprite_state *state);
/* ----------------------- sprite_outputtomask -----------------------------
* Redirects output to a sprite's transparency mask, saving old state
*
*/
extern os_error *sprite_outputtomask(sprite_area *area, sprite_id *id,
int *save_area, sprite_state *state);
/* --------------------------- sprite_outputtoscreen -----------------------
* Redirect output back to screen, saving old state
*
*/
extern os_error *sprite_outputtoscreen(int *save_area, sprite_state *state);
/* --------------------------- sprite_sizeof_spritecontext -----------------
* Get size of save area needed to save sprite context.
*
*/
extern os_error *sprite_sizeof_spritecontext(sprite_area *area, sprite_id *id,
int *size);
/* ------------------------- sprite_sizeof_screencontext -------------------
* Get size of save area needed to save screen context.
*
*/
extern os_error *sprite_sizeof_screencontext(int *size);
/* ------------------------ sprite_removewastage ---------------------------
* Removes left hand wastage from a sprite
*
*/
extern os_error *sprite_removewastage(sprite_area *area, sprite_id *id);
/* ------------------------ sprite_change_size -----------------------------
* General insert/delete rows/columns operations
*
*/
extern os_error
*sprite_change_size
(sprite_area *area, sprite_id *id, BOOL rows, int at, int number);
/* Typedefs and functions for rotating sprites. */
typedef struct {int p0 [2], p1 [2], p2 [2], p3 [2];} sprite_pgm;
typedef int sprite_transmat [6];
typedef struct {int x0, y0, x1, y1;} sprite_box;
/* ------------------------ sprite_put_mask_trans ---------------------
* Put a box from the mask in background colours through a transformation matrix
*
*/
extern os_error
*sprite_put_mask_trans
(sprite_area *, sprite_id *, sprite_box *, sprite_transmat *);
/* ------------------------ sprite_put_mask_pgm -----------------------
* Put a box from the mask in background colours to a parallelogram
*
*/
extern os_error
*sprite_put_mask_pgm
(sprite_area *, sprite_id *, sprite_box *, sprite_pgm *);
/* ------------------------ sprite_put_trans --------------------------
* Put a box from the sprite through a transformation matrix
*
*/
extern os_error
*sprite_put_trans
(sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_transmat *, sprite_pixtrans *);
/* ------------------------ sprite_put_pgm ----------------------------
* Put a box from the sprite to a parallelogram
*
*/
extern os_error
*sprite_put_pgm
(sprite_area *, sprite_id *, int gcol_action, sprite_box *, sprite_pgm *, sprite_pixtrans *);
# endif
/* end of sprite.h */