diff options
Diffstat (limited to 'trunk/librosprite.h')
-rw-r--r-- | trunk/librosprite.h | 89 |
1 files changed, 84 insertions, 5 deletions
diff --git a/trunk/librosprite.h b/trunk/librosprite.h index bbe7f7d..442163c 100644 --- a/trunk/librosprite.h +++ b/trunk/librosprite.h @@ -1,3 +1,21 @@ +/** + * \mainpage + * + * librosprite is a library for reading RISC OS sprite files. The following subformats are supported: + * <ul> + * <li>1-bit and 8-bit transparency masks</li> + * <li>Sprites with custom palettes</li> + * <li>Standard RISC OS 1-bit, 2-bit palettes, and 4-bit and 8-bit colour palettes</li> + * <li>Old-style sprites with most screen modes from 0-49 supported</li> + * <li>32bpp CMYK</li> + * <li>Inline alpha channel, as used by Photodesk and Tinct</li> + * </ul> + */ + +/** + * \file librosprite.h + */ + #ifndef ROSPRITE_H #define ROSPRITE_H @@ -7,12 +25,18 @@ typedef enum { ROSPRITE_OK, ROSPRITE_NOMEM, ROSPRITE_EOF, ROSPRITE_BADMODE } rosprite_error; -typedef enum { rosprite_rgb, rosprite_cmyk } rosprite_color_model; +typedef enum { ROSPRITE_RGB, ROSPRITE_CMYK } rosprite_color_model; +/** + * A reader interface used to load sprite files. + */ typedef int (*reader)(uint8_t* buf, size_t count, void* ctx); struct rosprite_file_context; +/** + * A sprite area comprises zero more rosprites. Optionally, it may also have an extension_words block. + */ struct rosprite_area { uint32_t extension_size; /* size of extension_words in bytes */ uint8_t* extension_words; @@ -20,7 +44,13 @@ struct rosprite_area { struct rosprite** sprites; /* array of length sprite_count */ }; +/** + * A sprite mode defines the colour depth, colour model and bitmap resolution of a sprite. + */ struct rosprite_mode { + /** + * The bits per colour channel. Legal values are 1, 2, 4, 8, 16, 24 and 32. + */ uint32_t colorbpp; /* maskbpp denotes the amount of alpha bpp used * while mask_width is the bits used to store the mask. @@ -30,7 +60,15 @@ struct rosprite_mode { */ uint32_t maskbpp; uint32_t mask_width; /* in pixels */ + + /** + * Horizontal dots per inch. Typical values are 22, 45, 90 and 180. + */ uint32_t xdpi; + + /** + * Vertical dots per inch. Typical values are 22, 45, 90 and 180. + */ uint32_t ydpi; rosprite_color_model color_model; }; @@ -40,15 +78,35 @@ struct rosprite_palette { uint32_t* palette; }; +/** + * A sprite is a bitmap image which has a mode, width and height. + */ struct rosprite { - unsigned char name[13]; /* last byte for 0 terminator */ + + /** + * The sprite name. This may be up to 12 characters long, and must be zero terminated. + */ + unsigned char name[13]; struct rosprite_mode mode; bool has_mask; bool has_palette; uint32_t palettesize; /* in number of entries (each entry is a word) */ uint32_t* palette; - uint32_t width; /* width in pixels */ - uint32_t height; /* height in pixels */ + + /** + * Width in pixels + */ + uint32_t width; + + /** + * Height in pixels + */ + uint32_t height; + + /** + * Image data is a series of words, appearing on screen left-to-right, top-to-bottom. + * Each word takes the form 0xRRGGBBAA. A is the alpha channel, where 0 is transparent, and 255 is opaque. + */ uint32_t* image; /* image data in 0xRRGGBBAA words */ }; @@ -62,11 +120,32 @@ rosprite_error rosprite_create_mem_context(uint8_t* p, unsigned long total_size, void rosprite_destroy_mem_context(struct rosprite_mem_context* ctx); int rosprite_mem_reader(uint8_t* buf, size_t count, void* ctx); +/** + * Load a rosprite_area using the reader provided. + * Clients must call rosprite_destroy_sprite_area() to dispose of the rosprite_area. + * \param[out] result The pointer to be populated by this function. + */ rosprite_error rosprite_load(reader reader, void* ctx, struct rosprite_area** result); + +/** + * Dispose of a rosprite_area and its children. + */ void rosprite_destroy_sprite_area(struct rosprite_area *); +/** + * Load a RISC OS palette file. A palette file has RISC OS filetype 0xFED, + * and is a series of VDU 19 Set Palette commands, each command being 6 bytes long. + * + * Clients must call rosprite_destroy_palette() to dispose of the rosprite_palette. + * + * \param[out] result The pointer to be populated by this function. + * \see http://www.drobe.co.uk/show_manual.php?manual=/sh-cgi?manual=Vdu%26page=19 + */ rosprite_error rosprite_load_palette(reader reader, void* ctx, struct rosprite_palette** result); -void rosprite_destroy_palette(struct rosprite_palette *); +/** + * Dispose of a rosprite_palette and its children. + */ +void rosprite_destroy_palette(struct rosprite_palette *); #endif |