home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / desklib / !DeskLib / h_doc / Sprite < prev    next >
Encoding:
Text File  |  1996-05-21  |  13.8 KB  |  418 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    Sprite.h
  12.     Author:  Copyright © 1992, 1993, 1994 John Winters, Jason Williams, 
  13.                                           Jason Howat
  14.              and sundry contributors
  15.     Version: 0.29 (02 Sep 1995)
  16.     Purpose: Sprite-SWI interfaces.
  17.              This version of the Sprite library only includes the most common
  18.              sprite operations, and only on "user" sprite areas, and "named"
  19.              sprites. (i.e. not pointers-to-sprites)
  20.              More Sprite operations may appear as the moderator gets time
  21.              to include them into the library.
  22.     
  23.     Mods:    02 Sep 1995 JH Desk_Sprite_MemorySize now works in 'double pixel' 
  24.                             modes (see 'Libraries.Sprite.c.MemSize' for the 
  25.                             details).
  26.                             Added Desk_Sprite_Select.
  27. */
  28.  
  29.  
  30. #ifndef __Desk_Sprite_h
  31. #define __Desk_Sprite_h
  32.  
  33. #ifdef __cplusplus
  34.     extern "C" {
  35. #endif
  36.  
  37. #include <stdarg.h>
  38.  
  39. #ifndef __Desk_Core_h
  40.     #include "Desk.Core.h"
  41. #endif
  42.  
  43. #ifndef __Desk_Wimp_h
  44.     #include "Desk.Wimp.h"
  45. #endif
  46.  
  47. #ifndef __Desk_Coord_h
  48.     #include "Desk.Coord.h"
  49. #endif
  50.  
  51.  
  52.  
  53. #define Desk_sprite_MAXNAME    12
  54.  
  55. #define Desk_spritepool_SYSTEM 0
  56. #define Desk_spritepool_WIMP   1
  57.  
  58.  
  59. typedef struct {
  60.     unsigned int areasize ;
  61.     unsigned int numsprites ;
  62.     unsigned int firstoffset ;
  63.     unsigned int freeoffset ;
  64. } Desk_sprite_areainfo ;
  65.  
  66. typedef Desk_sprite_areainfo *Desk_sprite_area;
  67.  
  68. typedef struct {
  69.     unsigned int width ;
  70.     unsigned int height ;
  71.     unsigned int maskstatus ;
  72.     unsigned int mode ;
  73. } Desk_sprite_info ;
  74.  
  75. typedef Desk_sprite_info *sprite;
  76.  
  77.  
  78. typedef struct {
  79.     int          callno ;
  80.     Desk_sprite_area  spritearea ;
  81.     sprite       sprite ;
  82.     void         *savearea ;
  83. } Desk_sprite_outputstate ;
  84.  
  85.  
  86. typedef struct
  87. {
  88.   int  Desk_offset_next;
  89.   char name[Desk_sprite_MAXNAME];
  90.   int  width;
  91.   int  height;
  92.   int  leftbit;
  93.   int  rightbit;
  94.   int  imageoffset;
  95.   int  maskoffset;
  96.   int  screenmode;
  97. } Desk_sprite_header;
  98.  
  99.  
  100. typedef struct
  101. {
  102.   Desk_wimp_point multiply;
  103.   Desk_wimp_point divide;
  104. } Desk_sprite_scalefactors;
  105.  
  106.  
  107. extern void    Desk_Sprite_ScreenSave(const char *filename, Desk_bool savepalette);
  108.  /* Save the screen as a sprite file - SpriteOp 2 */
  109.  
  110.  
  111. extern void    Desk_Sprite_ScreenLoad(const char *filename);
  112.  /* ScreenLoad a sprite file - SpriteOp 3 */
  113.  
  114. extern void    Desk_Sprite_InitArea(Desk_sprite_area area);
  115.  /* Initialise a sprite area - SpriteOp 9 */
  116.  
  117. extern void    Desk_Sprite_Load(Desk_sprite_area area, const char *filename) ;
  118.  /* Load a file into a sprite area - SpriteOp 10 */
  119.  
  120. extern void    Desk_Sprite_Merge(Desk_sprite_area area, const char *filename);
  121.  /* Merge a file into a sprite area - SpriteOp 11 */
  122.  
  123. extern void    Desk_Sprite_Save(Desk_sprite_area area, const char *filename);
  124.  /* Save a sprite area into a file - SpriteOp 12 */
  125.  
  126.  
  127. extern void    Desk_Sprite_Create(Desk_sprite_area area, const char *name, int haspalette,
  128.                                int width, int height, int screenmode);
  129. /*
  130.  *  Desk_Sprite_Create() - SpriteOp 15
  131.  *    Creates a sprite according to the parameters.
  132.  */
  133.  
  134. extern void    Desk_Sprite_Select(Desk_sprite_area area, const char *name,
  135.                                Desk_sprite_header **spriteptr);
  136. /*
  137.  *  Desk_Sprite_Select() - SpriteOp 24
  138.  *    Selects the given sprite.
  139.  */
  140.  
  141. extern void    Desk_Sprite_Delete(Desk_sprite_area area, const char *name);
  142. /*
  143.  *  Desk_Sprite_Delete() - SpriteOp 25
  144.  *    Deletes the given sprite
  145.  */
  146.  
  147.  
  148. extern void    Desk_Sprite_Rename(Desk_sprite_area area, const char *oldname, const char *newname);
  149. /*
  150.  *  Desk_Sprite_Rename() and Desk_Sprite_Copy() - SpriteOps 25, 26
  151.  *    Unsurprisingly, these rename and copy a sprite, respectively.
  152.  */
  153.  
  154. extern void    Desk_Sprite_Copy(Desk_sprite_area area, const char *oldname, const char *newname);
  155. /*
  156.  *  Desk_Sprite_Rename() and Desk_Sprite_Copy() - SpriteOps 25, 26
  157.  *    Unsurprisingly, these rename and copy a sprite, respectively.
  158.  */
  159.  
  160.  
  161.  
  162. extern void    Desk_Sprite_Get(Desk_sprite_area area, const char *name, int Desk_with_palette,
  163.                             int left, int bottom, int right, int top,
  164.                             sprite *Desk_sprite_ptr);
  165. /*
  166.  *  Desk_Sprite_Get() - SpriteOp 16
  167.  *    Gets (creates and copies) a sprite from the given screen rectangle
  168.  */
  169.  
  170.  
  171.  
  172. extern void    Desk_Sprite_Plot(Desk_sprite_area area, const char *name,  /* "PutUser" */
  173.                              int x, int y, int Desk_plot_action);
  174. /*
  175.  *  Desk_Sprite_Plot() - SpriteOp 34
  176.  *    Plots a sprite with it's bottom-left corners at the given coordinate,
  177.  *    using the given GCOL plot action (see GFX.h for plot actions)
  178.  */
  179.  
  180.  
  181. extern void    Desk_Sprite_ReadInfo(Desk_sprite_area area, const char *name,
  182.                                  Desk_sprite_info *info);
  183.  /* Reads sprite information - SpriteOp 40 */
  184.  
  185.  
  186. extern void    Desk_Sprite_Redirect(Desk_sprite_area area, const char *name,
  187.                                  void *savearea, Desk_sprite_outputstate *oldstate);
  188.  /* redirects VDU output into the named sprite - SpriteOp 60 */
  189.  
  190.  
  191. extern void    Desk_Sprite_UnRedirect(Desk_sprite_outputstate *oldstate);
  192.  /* Un-redirects VDU output back to the saved state - SpriteOp 60 */
  193.  
  194.  
  195.  
  196. extern void    Desk_Sprite_ReadSaveAreaSize(Desk_sprite_area area, const char *name,
  197.                                          int *saveareasize);
  198.  /*  Desk_Sprite_ReadSaveAreaSize
  199.   *  Given a sprite area and a sprite name, returns the save area size needed
  200.   *  for the given sprite. (SpriteOp 62 veneer)
  201.   */
  202.  
  203.  
  204. /* Desk_Sprite_ReadControl (8)
  205.  * Read information about sprite area
  206.  * Returns number of sprites in area
  207.  * If you aren't interested in any of the returned variables, then put NULL
  208.  * pointers in
  209.  */
  210. extern int Desk_Sprite_ReadControl(Desk_sprite_area area, int *size, sprite *firstsprite,
  211.                               void *firstfree);
  212.  
  213. extern int Desk_Sprite_GetName(Desk_sprite_area area, char *name, int spritenumber);
  214. /* Desk_Sprite_GetName (13)
  215.  * Read name of sprite, given number (starts from 1)
  216.  * Buffer passed in 'name' must be at least 13 chars long
  217.  * Returns length of name.
  218.  */
  219.  
  220. extern void    Desk_Sprite_CreateMask(Desk_sprite_area area, const char *name);
  221. /* Desk_Sprite_CreateMask (29)
  222.  * Creates a mask for a sprite
  223.  */
  224.  
  225. extern void    Desk_Sprite_RemoveMask(Desk_sprite_area area, const char *name);
  226. /* Desk_Sprite_RemoveMask (30)
  227.  * Removes a mask from a sprite
  228.  */
  229.  
  230. extern void    Desk_Sprite_InsertRow(Desk_sprite_area area, const char *name, int pos);
  231. /* Desk_Sprite_InsertRow (31)
  232.  * Inserts a row at the specified row, and shuffles the rest on
  233.  */
  234.  
  235. extern void    Desk_Sprite_DeleteRow(Desk_sprite_area area, const char *name, int pos);
  236. /* Desk_Sprite_DeleteRow (32)
  237.  * Deletes a row at the specified row, and shuffles the rest on
  238.  */
  239.  
  240. extern void    Desk_Sprite_FlipX(Desk_sprite_area area, const char *name);
  241. /* Desk_Sprite_FlipX (33)
  242.  * Flips sprite about x axis (top<>bottom)
  243.  */
  244.  
  245. extern void    Desk_Sprite_Append(Desk_sprite_area area, const char *name1, const char *name2,
  246.                                int dir);
  247. /* Desk_Sprite_Append (35)
  248.  * Glues two sprites together
  249.  * Sprite 2 is deleted, and sprite 1 becomes them both added together
  250.  * Sprites must be the same width if appending vertically, or the same height if
  251.  * appending horizontally
  252.  * 'dir' is 0 for horizontal, 1 for vertical
  253.  */
  254.  
  255. extern int Desk_Sprite_CreatePalette(Desk_sprite_area area, const char *name, Desk_bool big);
  256. /* Desk_Sprite_CreatePalette (37)
  257.  * Returns size of palette created
  258.  * If 'big' is true, then a 256 entry palette is created (RO3 only)
  259.  */
  260.  
  261. extern void    Desk_Sprite_RemovePalette(Desk_sprite_area area, const char *name);
  262. /* Desk_Sprite_RemovePalette (37)
  263.  */
  264.  
  265. extern int Desk_Sprite_ReadPixel(Desk_sprite_area area, const char *name, const Desk_wimp_point *pos);
  266. /* Desk_Sprite_ReadPixel (41)
  267.  * Returns colour
  268.  * Tint is returned, so long as 'tint' isn't NULL (0)
  269.  */
  270.  
  271. extern void    Desk_Sprite_WritePixel(Desk_sprite_area area, const char *name,
  272.                                    const Desk_wimp_point *pos, int colour, int tint);
  273. /* Desk_Sprite_WritePixel (42)
  274.  */
  275.  
  276. extern Desk_bool Desk_Sprite_ReadMask(Desk_sprite_area area, const char *name, const Desk_wimp_point *pos);
  277. /* Desk_Sprite_ReadMask (43)
  278.  * Returns Desk_bool_TRUE if solid
  279.  */
  280.  
  281. extern void    Desk_Sprite_WriteMask(Desk_sprite_area area, const char *name, const Desk_wimp_point *pos,
  282.                                   Desk_bool solid);
  283. /* Desk_Sprite_WriteMask (43)
  284.  */
  285.  
  286. extern void    Desk_Sprite_InsertColumn(Desk_sprite_area area, const char *name, int pos);
  287. /* Desk_Sprite_InsertColumn (45)
  288.  * Inserts a column at the specified column, and shuffles the rest on
  289.  */
  290.  
  291. extern void    Desk_Sprite_DeleteColumn(Desk_sprite_area area, const char *name, int pos);
  292. /* Desk_Sprite_DeleteColumn (46)
  293.  * Deletes a column at the specified column, and shuffles the rest on
  294.  */
  295.  
  296. extern void    Desk_Sprite_FlipY(Desk_sprite_area area, const char *name);
  297. /* Desk_Sprite_FlipY (47)
  298.  * Flips sprite about y axis (left<>right)
  299.  */
  300.  
  301. extern void    Desk_Sprite_PlotMask(Desk_sprite_area area, const char *name, const Desk_wimp_point *pos);
  302. /* Desk_Sprite_PlotMask (49)
  303.  */
  304.  
  305. extern void    Desk_Sprite_PlotMaskScaled(Desk_sprite_area area, const char *name,
  306.                                        const Desk_wimp_point *pos, Desk_sprite_scalefactors sc);
  307. /* Desk_Sprite_PlotMaskScaled (50)
  308.  */
  309.  
  310. extern void    Desk_Sprite_PlotScaled(Desk_sprite_area area, const char *name,
  311.                                    const Desk_wimp_point *pos, const Desk_sprite_scalefactors *scale,
  312.                                    const void *pixtrans);
  313. /* Desk_Sprite_PlotScaled (52)
  314.  * pixtrans can be up to 16 bytes long, it's left as a void * so that you can
  315.  * use a char *, or a pixtrans * if one gets defined in the future
  316.  */
  317.  
  318. extern void    Desk_Sprite_PlotGrey(Desk_sprite_area area, const char *name,
  319.                                  const Desk_wimp_point *pos, Desk_sprite_scalefactors scale,
  320.                                  const void *pixtrans);
  321. /* Desk_Sprite_PlotGrey (53)
  322.  * pixtrans should be a greyscale for the antialiasing to work properly
  323.  * (or a blue scale or whatever)
  324.  */
  325.  
  326. extern void    Desk_Sprite_WimpPlot(Desk_sprite_area area, const char *name, const Desk_wimp_point *pos,
  327.                                  const Desk_convert_block *convert, int Desk_plot_action);
  328. /* Desk_Sprite_WimpPlot
  329.  * Plots a sprite in a window.
  330.  * 'pos' should be work area coordinates, and convert is the convert block for
  331.  * the window.
  332.  * All relevant scaling/colour translating is taken to plot the sprite at 1:1 in
  333.  * the current mode
  334.  */
  335.  
  336.  
  337. /* Sprite manipulation functions ------------------------------------------ */
  338.  
  339. typedef enum
  340. {
  341.   Desk_sprite_HASNOMASKPAL = 0x00,             /* Sprite has no mask or palette */
  342.   Desk_sprite_HASNOPALMASK = 0x00,
  343.   Desk_sprite_HASMASK      = 0x01,             /* Sprite has a mask only        */
  344.   Desk_sprite_HASPAL       = 0x02,             /* Sprite has a palette only     */
  345.   Desk_sprite_HASMASKPAL   = 0x03,             /* Has both mask and palette     */
  346.   Desk_sprite_HASPALMASK   = 0x03
  347. } Desk_spritemem_flags;
  348.  
  349.  
  350. extern int Desk_Sprite_MemorySize(int width, int height, int mode,
  351.                              Desk_spritemem_flags flags);
  352.  /*  Desk_Sprite_MemorySize
  353.   *  Returns the amount of memory to malloc to hold the sprite
  354.   *  defined by the parameters.
  355.   *
  356.   *  -- Example, create sprite area large enough for 3 identical sprites
  357.   *     which are mode 12, 34x17, and have their own palettes.
  358.   *
  359.   *    Desk_sprite_areainfo *pUserSprites;
  360.   *
  361.   *    size = 3 * Desk_Sprite_MemorySize( 34, 17, 12, Desk_sprite_HASPAL );
  362.   *    size += sizeof( Desk_sprite_areainfo );
  363.   *    pUserSprites = (Desk_sprite_areainfo*) malloc( size );
  364.   */
  365.  
  366.  
  367. extern int Desk_Sprite_IconMemorySize(const Desk_window_block *pWinBlock, Desk_icon_handle icon,
  368.                                  int mode, Desk_spritemem_flags flags,
  369.                                  Desk_wimp_point *dimensions);
  370.  /*  Desk_Sprite_IconMemorySize
  371.   *  This takes the given WIMP icon, and calculates the size of the sprite
  372.   *  needed to exactly fill it, by calling Desk_Sprite_MemorySize for you.
  373.   *  If 'dimensions' is not NULL, then it will be filled in with the needed
  374.   *  size (width/height) of the sprite in pixels.
  375.   *
  376.   *  The window is passed in as a Desk_window_block so that this can be applied
  377.   *  to templates as well as open windows.
  378.   *
  379.   *  Example:
  380.   *  {
  381.   *    Desk_window_info winfo;
  382.   *    int         s;
  383.   *
  384.   *    Desk_Window_GetInfo(mainwindow, &winfo);
  385.   *    s = Desk_Sprite_IconMemorySize(&winfo.block, 5, |* Get info for icon 5    *|
  386.   *                          Desk_screen_mode,         |* in current screen mode *|
  387.   *                          Desk_sprite_HASNOMASKPAL, |* with no mask/palette   *|
  388.   *                          NULL);               |* Don't return dimensions*|
  389.   */
  390.  
  391.  
  392. extern Desk_sprite_area Desk_Sprite_LoadFile(const char *filename);
  393. /*  Desk_Sprite_LoadFile
  394.  *  This loads the given sprite file into a sprite area, & returns a pointer to
  395.  *  it.  The memory is automatically allocated with malloc(), so to free it
  396.  *  later, simply call free() on the returned pointer.
  397.  */
  398.  
  399.  
  400.  
  401. extern Desk_sprite_area Desk_Sprite_LoadFiles(int nooffiles, ...);
  402. /*
  403.   Purpose:  - Loads any number of sprite files into sprite area
  404.   Inputs:   - nooffiles - number of files to be loaded
  405.               ...       - pointers to pathnames of files to be loaded
  406.   Returns:  - pointer to sprite area
  407.   SeeAlso:  - Desk_Sprite_LoadFile
  408.  
  409. ****************************************************************************/
  410.  
  411.  
  412. #ifdef __cplusplus
  413. }
  414. #endif
  415.   
  416.  
  417. #endif
  418.