Garbo

home *** CD-ROM | disk | FTP | other *** search

/ Garbo / Garbo.cdr / pc / progrmng / stk110.lzh / STKREF.DOC < prev next >

Wrap

Text File | 1991-02-25 | 22.2 KB | 793 lines

********************************************************************** This file is part of STK -- The sprite toolkit -- version 1.1 Copyright (C) Jari Karjala 1991 The sprite toolkit (STK) is a FreeWare toolkit for creating high resolution sprite graphics with PCompatible hardware. This toolkit is provided as is without any warranty or such thing. See the file COPYING for further information. ********************************************************************** GRTYPES --------------------------------------------------------------------------- Common type definitions for the graphics and sprite routines #define NULL ((void*)0) typedef unsigned char BYTE; typedef unsigned int WORD; typedef BYTE *BITMAP; --------------------------------------------------------------------------- The SPR functions --------------------------------------------------------------------------- The basic sprite support system prototypes and structures. extern int spr_pass_delay; The delay after setvisualpage() before removing old objects in the funtion spr_next_pass(). Many EGA/VGA cards need some milliseconds to switch pages, the sprites flicker if this delay is too short. If someone has better solutions in dealing with this problem, I sure would like to know about them. Time is given in milliseconds and the default is 10 ms for EGA and 0 ms for Hercules (use spr_regulate_speed to balance the frame rate with different display adapters). #define spr_max_x gr_max_x #define spr_max_y gr_max_y The maximum coordinate values for current graphics adapter. Variables defined in module gr.c, and initialized in gr_start. (It is faster to use variables instead of getmaxx() and getmaxy()); typedef void *SPRITE; The sprite type is private. The handle must be void pointer due to the Turbo C which does not allow "struct _sprite *SPRITE" without struct _sprite definition in the same file. void spr_initialize(int graphicsdriver); Initialize the sprite system to the given display hardware. Supported graphicsdrivers: EGA (only two colors), EGAMONO and HERCMONO. The visual page is set to 0. NOTE: This function must be called before any other sprite funtions and the graphics mode must have been set before this call. graphicsdriver The BGI identifier for the graphics driver used. SPRITE spr_create(WORD w, WORD h, BITMAP pic, BITMAP mask, BYTE res, WORD ID); Create a sprite from the given bitmaps. w,h Width (must be < 512) and height (<256) of sprite in pixels pic The picture bitmap for the sprite mask The mask bitmap for the sprite res The number of steps wanted per 8 bit interval in horizontal direction (1,2,4,8). For example, the value 8 gives one pixel resolution in X-direction. ID The user supplied ID for the sprite (usually index into an array and/or sprite type identifier). Return: the newly created sprite or NULL if parameter error, sprite too big or out-of-memory SPRITE spr_share(SPRITE spr, BYTE n); Create a shared version of the given sprite. This allows at most n spr_copies which all share the shape data thus saving quite much memory. spr The sprite to share n The maximum number of shared copies Return: New SPRITE or NULL if error (out of memory, spr==NULL) SPRITE spr_copy(SPRITE spr, WORD id); Create a copy of the given sprite. If the sprite was shared with spr_share then a shared copy is created. spr The sprite to share id The ID for the new sprite Return: New SPRITE or NULL if error (out of memory, spr was NULL, no more shared copies) void spr_put(SPRITE spr, WORD x, WORD y); Put the sprite into the given position in the display. Actually the call has no effect on screen until spr_next_pass() is called next time and the sprite will disappear after the next spr_next_pass() call after that. NOTE: Cannot be called twice for the same sprite before spr_hide() or spr_next_pass(). spr The sprite to put x The X coordinate y The Y coordinate void spr_hide(SPRITE spr); Undo a spr_put for the sprite. This function only removes the sprite from internal display list since the spr_put did not actually put the sprite into the screen. spr The sprite to hide void spr_delete(SPRITE spr); Delete the given sprite and release associated memory buffers. Also spr_hides the sprite. spr The sprite to delete WORD spr_next_pass(void); 1. Draw all sprites into the hidden screen page. 2. Make the hidden screen page visible. 3. Delete old sprites from the new hidden page. Return: The current visual page number void spr_regulate_speed(void); This function tries to regulate the frame speed by delaying if we are doing more frames per second than we should. The target speed is 1 frame per one clock tick (about 18 frames per second). This is a reasonable target speed for 286 machines. This function should be called after each spr_next_pass() call. /***** Information retrieving functions *****/ WORD spr_get_id(SPRITE spr); Return the user supplied identifier of the sprite WORD spr_get_x(SPRITE spr); Return the X coordinate of the sprite in pixels from top-left WORD spr_get_y(SPRITE spr); Return the Y coordinate of the sprite in pixels from top-left WORD spr_get_width(SPRITE spr); Return the width of the sprite in pixels WORD spr_get_height(SPRITE spr); Return the height of the sprite in pixels --------------------------------------------------------------------------- The SPR_FIO functions --------------------------------------------------------------------------- The functions for reading sprites from a file. SPRITE spr_fio_read_smp(char *smpfile, BYTE res, WORD ID); Create a sprite from the given SMP file. smpfile The sprite bitmap file name. res The number of steps wanted per 8 bit interval in horizontal direction (1,2,4,8). For example, the value 8 gives one pixel resolution in X-direction. ID The user supplied ID for the sprite (not obligatory) Return: the newly created sprite or NULL if file not found, read error or out-of-memory --------------------------------------------------------------------------- The SPR_HIT functions --------------------------------------------------------------------------- The sprite collision detection routines. Collisions may be checked only for the sprites which have been spr_put() since the last call to spr_next_pass(). All checks are made against the mask-bitmaps of the sprites. int spr_hit_with_point(SPRITE spr, WORD x, WORD y); Check whether the given point is inside the given sprite. Return: 0 if no collision, negative otherwise. int spr_hit(SPRITE spr1, SPRITE spr2); Check whether the given sprites collide against each other. Return: 0 if no collision, negative otherwise. SPRITE spr_hit_first(SPRITE spr); Find the first sprite colliding the given sprite. Use spr_hit_next to get the next sprites. Return: Sprite or NULL if no collision SPRITE spr_hit_next(SPRITE spr); Find the next sprite colliding with the given sprite. Return: Sprite or NULL if no collision --------------------------------------------------------------------------- The SPR_ANIM functions --------------------------------------------------------------------------- Routines for automatic sprite animation and movement. /***** Datatypes *****/ typedef void *ANIM_SPRITE; The animated sprite type is private. The handle must be void pointer due to the TC which does not allow "struct _anim_sprite *ANIM_SPRITE" without a "struct _anim_sprite" defined in the same file. The information structure returned by the spr_anim_get_info(): typedef struct _anim_spr_info { int x,y; /** location **/ int dx,dy; /** movement vector **/ int lef, top, rig, bot; /** limits **/ WORD frame, frame_delay, timeout; /** time info **/ WORD id; /** the user spesified id of current sprite **/ int w,h; /** width&height **/ } ANIM_SPR_INFO; /***** Literal defines *****/ The values for fx_mode and fx_type: (See spr_anim_set_fx_handler) #define SPR_ANIM_FX_ALL (0x0F) /** all fx **/ #define SPR_ANIM_FX_TIMEOUT (1<<0) /** timeout **/ #define SPR_ANIM_FX_HIT_X_LIMIT (1<<1) /** hit x limit **/ #define SPR_ANIM_FX_HIT_Y_LIMIT (1<<2) /** hit y limit **/ #define SPR_ANIM_FX_HIT_SPRITE (1<<3) /** hit other spr**/ The FX_RET values for the fx_handler return codes: #define SPR_ANIM_FX_RET_NOTHING (0) /** continue normally **/ #define SPR_ANIM_FX_RET_RE_PUT (1) /** put the sprite again **/ #define SPR_ANIM_FX_RET_STOP (2) /** stop the animation **/ #define SPR_ANIM_FX_RET_DELETE (3) /** delete the anim.sprite **/ #define SPR_ANIM_FX_RET_DESTROY (4) /** destroy the anim.sprite **/ /***** Function prototypes *****/ ANIM_SPRITE spr_anim_create(WORD count, ...); Create an animated sprite from the given simple sprites. The sprites must have the same width and height. Set the following defaults: x,y = 0,0 dx,dy = 0,0 lef,top,rig,bot = 0,0,spr_max_x,spr_max_y frame_delay, timeout = 0,0 fx_mode = FX_ALL fx_handler = default_fx (TIMEOUT & HIT_SPRITE delete, LIMITs bounce.) count The number of simple sprites, at most 20. ... The simple sprites Return: ANIM_SPRITE if no errors or NULL if memory allocation error, count>20 or ... contains a NULL sprite. void spr_anim_start(ANIM_SPRITE aspr); Start the sprite animation. aspr The animated sprite to use void spr_anim_stop(ANIM_SPRITE aspr); Stop the animation of the given sprite. This means that after the next pass this sprite will not be shown nor updated. Sprite can be restarted with the function spr_anim_start. aspr The animated sprite to stop void spr_anim_delete(ANIM_SPRITE aspr); Delete the given animated sprite. The simple sprites it contains are NOT deleted. aspr The animated sprite to use void spr_anim_destroy(ANIM_SPRITE aspr); Delete the given animated sprite. The simple sprites it contains are ALSO deleted. aspr The animated sprite to destroy WORD spr_anim_next_pass(void); This function handles the sprite animation and display. 1. Spr_put all animated sprites. 2. Check for special effects. a. Call fx_handlers if necessary. b. Act according to the fx_handler return values. 3. Call spr_next_pass. 4. Update frame indices and locations of all animated sprites. Return: The current visual page number ANIM_SPR_INFO *spr_anim_get_info(ANIM_SPRITE aspr); Return a pointer into a static info structure of the sprite. NOTE: the structure is only a copy which is overwritten by the next call to this function. void spr_anim_set_location(ANIM_SPRITE aspr, WORD x, WORD y); Set the location of the animated sprite. void spr_anim_set_vector(ANIM_SPRITE aspr, int dx, int dy); Set the movement vector of the animated sprite. The (dx,dy) are added to the (x,y) attributes of the sprite during every pass. Negative values mean left and up directions in screen. void spr_anim_set_limits(ANIM_SPRITE aspr, WORD lef, WORD top, WORD rig, WORD bot); Set the limits for the animated sprite. The function takes care of the bottom/right adjustments due to the size of the sprite. The fx_handler will be triggered by these limits, if allowed. Note again, that all simple sprites belonging to the animated sprite must have the same width & heigth or the limit checking will not work. void spr_anim_set_time(ANIM_SPRITE aspr, int frame, int frame_delay, int timeout); Set the frame delay and timeout values. (-1 means no change for that value). NOTE: The 'frame' MUST NOT be changed from an fx_handler!! frame The current animation frame number (0..nr of frames-1) frame_delay The number of passes for each frame change (0=no change) timeout The number of passes before timeout action (0=infinite) void spr_anim_set_fx_handler(ANIM_SPRITE aspr, WORD fx_mask, WORD (fx_handler)(ANIM_SPRITE,WORD,SPRITE)); Sets the special effects handler function for the given ANIM_SPRITE. The function should have the following prototype: WORD handler_name(ANIM_SPRITE aspr, WORD fx_type, SPRITE spr); The function will be called with the following parameters: aspr the animated sprite whose handler this is, fx_type the type of the effect which caused this call, spr the colliding sprite (if fx_type was HIT_SPRITE). The function must return one of the SPR_ANIM_FX_RET values defined above. A NULL handler means that all special effects cause spr_anim_delete. fx_mask The types of effects which cause a call to the handler, for example: SPR_ANIM_FX_HIT_Y_LIMIT|SPR_ANIM_FX_HIT_X_LIMIT fx_handler The handler function. --------------------------------------------------------------------------- The GR functions --------------------------------------------------------------------------- Support routines for graphics mode. /***** Variables *****/ extern int gr_max_x; extern int gr_max_y; The maximum coordinate values for current graphics adapter. (It is faster to use variables instead of getmaxx() and getmaxy()); extern int gr_text_mode; #define GR_MODE_OR (1<<0) /* OR the text over previous graphics */ #define GR_MODE_CLEAR (1<<1) /* Clear the backgroud before print */ #define GR_MODE_CLEAR_FAST (1<<2) /* Clear the bg before print FAST */ This variable defines the text writing mode when using gr_* functions (default GR_MODE_CLEAR) The GR_MODE_CLEAR_FAST is limited to 8 pixel horizontal resolution, i.e. coordinate positions (1,0) and (5,0) are considered to be same. extern unsigned char far *gr_font_addr; Pointer into an byte array containing the character font for 8x8 pixel fixed point font. Initialized to ROM font (FFA6:000E). Used only with GR_MODE_CLEAR_FAST in those graphics modes which are supported by the sprite functions. extern int gr_visualpage; extern int gr_activepage; The current visual page and active drawing page, provided that they have been changed only with gr_*page functions. extern char gr_keys[128]; Array of booleans for each key of the keyboard (indexed by the scan code value). Non-zero if key is depressed, zero otherwise. The array is updated during the kbd_grab, see the function gr_start_kbd_grab below. For example gr_keys[GR_KEY_ESC] is 1 if Esc is currently depressed and 0 if not. Multiple simultaneous keyspresses are detected correctly. /***** Function prototypes *****/ void gr_detect(int type, int *graphdriver, int *graphmode); #define GR_TYPE_ANY 0 /* Any mode will do */ #define GR_TYPE_SPR 1 /* The best possible mode for the sprite toolkit */ Detect the graphics card and mode of the system. The type parameter can be used to specify special requests. graphdriver and graphmode parameters are returned. These values can be used with the gr_start function. They contain the value -1 if some error occured (cannot find requested mode, etc) void gr_start(int *graphdriver, int *graphmode); Initializes the graphics system. Search BGI drivers from the path defined in the enviroment variable BGIDIR or current directory. Set videomode into the BIOS to fool mouse drivers with Hercules graphics. Set gr_end at exit and ctrl-C signals. Terminate with error message if initialization fails. graphdriver pointer to the driver ID (or DETECT) graphmode pointer to the mode ID void gr_end(void); Returns to the text mode void gr_setactivepage(int page); Set the active graphics page for writing and reading (0/1). Also set the 'gr_activepage' variable void gr_setvisualpage(int page); Set the visual graphics page Also set the 'gr_visualpage' variable void gr_putch(char ch); void gr_puts(char *s); void gr_printf(char *s,...); #define gr_gotoxy(x, y) moveto(x*8, y*8) gr_putch, gr_puts, gr_printf work as the as in text modes. '\n', '\r' are handled as in standard text modes. The string to be output must not exceed 100 characters. Scrolling or backspacing not implemented. void gr_center_printf(int y, char *s,...); Print text horizontally centered. (x centered, at given y in pixels). The string to be output must not exceed 100 characters. void gr_xy_printf(int x, int y, char *s,...); printf at the given position. (x and y in pixels) The string to be output must not exceed 100 characters. void gr_dual_center_printf(int y, char *s,...); Print text into both graphics pages at the given position. (x centered, at given y in pixels) The string to be output must not exceed 100 characters. void gr_dual_xy_printf(int x, int y, char *s,...); printf into both graphics pages at the given position. (x and y in pixels) The string to be output in gr_printf must not exceed 100 characters. int gr_inkey(void); Return a keypress if one pending, otherwise 0. Extended codes contain 0 in the low byte. Keyboard buffer head and tail are set equal to disable auto-repeat, but it doesn't always work... char *gr_gets(char *cpdest, int max_len); Read a string from screen in graphics mode. The result is placed into cpdest, at most max_len characters are read (max_len must be less than 80). Return cpdest of NULL Backspace deletes characters, Esc returns a NULL pointer. void gr_start_kbd_grab(void); Set a new handler for the keyboard. This handler sets and resets the gr_keys array values for each scancode received, then flushes the keyboard buffer, and after that calls the old handler. void gr_end_kbd_grab(void); End the kbd grab, ie restore the original keyboard handler. Defines for the scan codes of some keys. See others from some book, for example Peter Norton's Programmers guide or perhaps you could figure them out just by counting keycaps... #define GR_KEY_ESC 1 #define GR_KEY_1 2 #define GR_KEY_2 3 #define GR_KEY_3 4 #define GR_KEY_4 5 #define GR_KEY_5 6 #define GR_KEY_6 7 #define GR_KEY_7 8 #define GR_KEY_8 9 #define GR_KEY_9 10 #define GR_KEY_0 11 #define GR_KEY_TAB 15 #define GR_KEY_Q 16 #define GR_KEY_W 17 #define GR_KEY_E 18 #define GR_KEY_R 19 #define GR_KEY_T 20 #define GR_KEY_Y 21 #define GR_KEY_U 22 #define GR_KEY_I 23 #define GR_KEY_O 24 #define GR_KEY_P 25 #define GR_KEY_A 30 #define GR_KEY_S 31 #define GR_KEY_D 32 #define GR_KEY_F 33 #define GR_KEY_G 34 #define GR_KEY_H 35 #define GR_KEY_J 36 #define GR_KEY_K 37 #define GR_KEY_L 38 #define GR_KEY_Z 44 #define GR_KEY_X 45 #define GR_KEY_C 46 #define GR_KEY_V 47 #define GR_KEY_B 48 #define GR_KEY_N 49 #define GR_KEY_M 50 #define GR_KEY_COMMA 51 #define GR_KEY_DOT 52 #define GR_KEY_SPACE 57 #define GR_KEY_ARROW_UP 72 #define GR_KEY_ARROW_DOWN 80 #define GR_KEY_ARROW_LEFT 75 #define GR_KEY_ARROW_RIGHT 77 --------------------------------------------------------------------------- The MOUSE functions --------------------------------------------------------------------------- The mouse interface through INT 33. NOTE: The pointer is not visible in the 2nd page of a Hercules card Codes for mouse button presses: #define BUTTON_LEFT 1 #define BUTTON_RIGHT 2 #define BUTTON_MS_MIDDLE (BUTTON_RIGHT | BUTTON_LEFT) #define BUTTON_MIDDLE 4 typedef unsigned int MOUSE_POINTER[2][16]; The mouse cursor datatype. First mask and then shape bitmap (must be WORDs) Predefined mouse cursor shapes: extern MOUSE_POINTER mouse_pointer_arrow; /* HotSpot 1,1 */ extern MOUSE_POINTER mouse_pointer_hourglass;/* HotSpot 7,7 */ extern MOUSE_POINTER mouse_pointer_cross; /* HotSpot 7,7 */ /***** Function prototypes *****/ int mouse_initialize(void); Initialize the mouse driver, set the pointer shape to arrow, set pointer window to full screen and enable cursor. Return: the number of buttons or 0 if no mouse driver detected For the following functions, see the mouse documention int mouse_driver_init(void); /** 0 **/ void mouse_show_pointer(void); /** 1 **/ void mouse_hide_pointer(void); /** 2 **/ void mouse_get_pointer_xy(int *x, int *y); /** 3 **/ void mouse_get_rel_pointer_xy(int *x, int *y); /** 11 **/ int mouse_get_buttons(void); /** 3 **/ int mouse_get_presses(int buttons); /** 5 **/ int mouse_get_releases(int buttons); /** 6 **/ void mouse_set_pointer_xy(int x, int y); /** 4 **/ void mouse_set_sensitivity(int x, int y); /** 15 **/ void mouse_set_pointer_shape(int HotX, int HotY, MOUSE_POINTER shape); void mouse_set_pointer_window(int a, int b, int c, int d); /** 7 **/ void mouse_disable_pointer_window(int a, int b, int c, int d);/** 16 **/ void mouse_set_light_pen(int a); /** 13 & 14 **/