summaryrefslogtreecommitdiff
path: root/trunk/librosprite.h
diff options
context:
space:
mode:
Diffstat (limited to 'trunk/librosprite.h')
-rw-r--r--trunk/librosprite.h89
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