summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJames Shaw <jshaw@netsurf-browser.org>2008-03-26 22:49:28 (GMT)
committer James Shaw <jshaw@netsurf-browser.org>2008-03-26 22:49:28 (GMT)
commit704f880692d5ac4597ec3cadbf3aeb48c8ba91cb (patch)
tree8c9d119ca743d935503985abe88bdd8eaf2a5cc6
parent9aa23badba0cb139ee23b696649dae67f0686805 (diff)
downloadlibrosprite-704f880692d5ac4597ec3cadbf3aeb48c8ba91cb.tar.gz
librosprite-704f880692d5ac4597ec3cadbf3aeb48c8ba91cb.tar.bz2
Start adding doxygen documentation to the library interface.
svn path=/import/jshaw/libsprite/; revision=10018
-rw-r--r--trunk/Makefile11
-rw-r--r--trunk/example.c2
-rw-r--r--trunk/librosprite.c117
-rw-r--r--trunk/librosprite.h89
4 files changed, 151 insertions, 68 deletions
diff --git a/trunk/Makefile b/trunk/Makefile
index 7f86a41..873f212 100644
--- a/trunk/Makefile
+++ b/trunk/Makefile
@@ -1,6 +1,7 @@
AR = ar
CC = gcc
LD = gcc
+DOXYGEN = doxygen
ARFLAGS = -cru
CFLAGS = -Wall -Wextra -Wundef -Wpointer-arith -Wcast-align \
-Wwrite-strings -Wstrict-prototypes \
@@ -9,7 +10,9 @@ CFLAGS = -Wall -Wextra -Wundef -Wpointer-arith -Wcast-align \
-Wmissing-format-attribute -Wunused -Wunreachable-code \
-Wformat=2 -Werror-implicit-function-declaration
LDFLAGS = -L./
-#-Wmissing-declarations -Wmissing-prototypes
+#-Wmissing-declarations -Wmissing-prototypes
+
+all: example palette2c
example: librosprite.a example.o
${LD} -g -o $@ example.o ${LDFLAGS} -lrosprite -lSDL
@@ -23,5 +26,9 @@ librosprite.a: librosprite.o
%.o: %.c
${CC} -c -g ${CFLAGS} -o $@ $<
+docs:
+ ${DOXYGEN}
+
clean:
- rm -f $(wildcard *.o) $(wildcard *.a) example palette \ No newline at end of file
+ rm -f $(wildcard *.o) $(wildcard *.a) example palette
+ rm -rf doc \ No newline at end of file
diff --git a/trunk/example.c b/trunk/example.c
index d0dad5e..5de3139 100644
--- a/trunk/example.c
+++ b/trunk/example.c
@@ -119,7 +119,7 @@ int main(int argc, char *argv[])
for (uint32_t i = 0; i < sprite_area->sprite_count; i++) {
struct rosprite* sprite = sprite_area->sprites[i];
printf("\nname %s\n", sprite->name);
- printf("color_model %s\n", sprite->mode.color_model == rosprite_rgb ? "RGB" : "CMYK");
+ printf("color_model %s\n", sprite->mode.color_model == ROSPRITE_RGB ? "RGB" : "CMYK");
printf("colorbpp %u\n", sprite->mode.colorbpp);
printf("xdpi %u\n", sprite->mode.xdpi);
printf("ydpi %u\n", sprite->mode.ydpi);
diff --git a/trunk/librosprite.c b/trunk/librosprite.c
index 5309488..fcea0d0 100644
--- a/trunk/librosprite.c
+++ b/trunk/librosprite.c
@@ -50,60 +50,60 @@ struct rosprite_mem_context {
};
static const struct rosprite_mode oldmodes[] = {
-/*0*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*1*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*2*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 22, .ydpi = 45, .color_model = rosprite_rgb },
-
-/*3*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0, .ydpi = 0, .color_model = rosprite_rgb },
-
-/*4*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*5*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 22, .ydpi = 45, .color_model = rosprite_rgb },
-
-/*6*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0, .ydpi = 0, .color_model = rosprite_rgb },
-/*7*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0, .ydpi = 0, .color_model = rosprite_rgb },
-
-/*8*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*9*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*10*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 22, .ydpi = 45, .color_model = rosprite_rgb },
-/*11*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*12*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*13*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*14*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*15*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*16*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*17*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*18*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*19*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*20*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*21*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*22*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi =180, .ydpi = 90, .color_model = rosprite_rgb },
-/*23*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*24*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*25*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*26*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*27*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*28*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*29*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*30*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*31*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*32*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = rosprite_rgb },
-/*33*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*34*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*35*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*36*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*37*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*38*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*39*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*40*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*41*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*42*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*43*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*44*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*45*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*46*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = rosprite_rgb },
-/*47*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = rosprite_rgb },
-/*48*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 90, .color_model = rosprite_rgb },
-/*49*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 90, .color_model = rosprite_rgb }
+/*0*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*1*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*2*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 22, .ydpi = 45, .color_model = ROSPRITE_RGB },
+
+/*3*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0, .ydpi = 0, .color_model = ROSPRITE_RGB },
+
+/*4*/{ .colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*5*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 22, .ydpi = 45, .color_model = ROSPRITE_RGB },
+
+/*6*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0, .ydpi = 0, .color_model = ROSPRITE_RGB },
+/*7*/{ .colorbpp = 0, .maskbpp = 0, .mask_width = 0, .xdpi = 0, .ydpi = 0, .color_model = ROSPRITE_RGB },
+
+/*8*/{ .colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*9*/{ .colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*10*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 22, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*11*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*12*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*13*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*14*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*15*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*16*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*17*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*18*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*19*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*20*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*21*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*22*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi =180, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*23*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*24*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*25*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*26*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*27*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*28*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*29*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*30*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*31*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*32*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*33*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*34*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*35*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*36*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*37*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*38*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*39*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*40*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*41*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*42*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*43*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*44*/{.colorbpp = 1, .maskbpp = 1, .mask_width = 1, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*45*/{.colorbpp = 2, .maskbpp = 1, .mask_width = 2, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*46*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 90, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*47*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 45, .color_model = ROSPRITE_RGB },
+/*48*/{.colorbpp = 4, .maskbpp = 1, .mask_width = 4, .xdpi = 45, .ydpi = 90, .color_model = ROSPRITE_RGB },
+/*49*/{.colorbpp = 8, .maskbpp = 1, .mask_width = 8, .xdpi = 45, .ydpi = 90, .color_model = ROSPRITE_RGB }
};
/* table for converting a 5bit channel into an 8bit channel (used for 16bpp to 32bpp conversion) */
@@ -279,7 +279,7 @@ static rosprite_error sprite_get_mode(uint32_t spriteMode, struct rosprite_mode*
mode.xdpi = (spriteMode & 0x07ffc000) >> 14; /* preserve bits 14-26 only */
mode.ydpi = (spriteMode & 0x00003ffe) >> 1; /* preserve bits 1-13 only */
- mode.color_model = rosprite_rgb;
+ mode.color_model = ROSPRITE_RGB;
switch (spriteType) {
case 1:
mode.colorbpp = 1; break;
@@ -295,7 +295,7 @@ static rosprite_error sprite_get_mode(uint32_t spriteMode, struct rosprite_mode*
mode.colorbpp = 32; break;
case 7:
mode.colorbpp = 32;
- mode.color_model = rosprite_cmyk;
+ mode.color_model = ROSPRITE_CMYK;
break;
case 8:
mode.colorbpp = 24; break;
@@ -375,7 +375,7 @@ static uint32_t sprite_upscale_color(uint32_t pixel, struct rosprite_mode* mode,
{
switch (mode->colorbpp) {
case 32:
- if (mode->color_model == rosprite_rgb) {
+ if (mode->color_model == ROSPRITE_RGB) {
/* swap from 0xAABBGGRR to 0xRRGGBBAA */
pixel = BSWAP(pixel);
@@ -730,9 +730,6 @@ void rosprite_destroy_sprite_area(struct rosprite_area* sprite_area)
rosprite_error rosprite_load_palette(reader reader, void* ctx, struct rosprite_palette** result)
{
- /* Palette file is in groups of 6 bytes, each is a VDU 19 (set palette)
- * http://www.drobe.co.uk/show_manual.php?manual=/sh-cgi?manual=Vdu%26page=19 */
-
/* TODO: currently assume palette has linear entries (2nd byte in is 00, 01, 02 etc) */
struct rosprite_palette* palette = malloc(sizeof(struct rosprite_palette));
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