From e51ea4e0ee3ec45de0c661abd8eb04d433cdbfdf Mon Sep 17 00:00:00 2001
From: John Mark Bell <jmb@netsurf-browser.org>
Date: Fri, 9 Jul 2010 21:11:06 +0000
Subject: Document the bitmap format properly.

svn path=/trunk/netsurf/; revision=10623
---
 image/bitmap.h | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

(limited to 'image')

diff --git a/image/bitmap.h b/image/bitmap.h
index 4a99de17e..ee837f5d7 100644
--- a/image/bitmap.h
+++ b/image/bitmap.h
@@ -22,7 +22,32 @@
  * This interface wraps the native platform-specific image format, so that
  * portable image convertors can be written.
  *
- * The bitmap format is ABGR.
+ * Bitmaps are required to be 32bpp with components in the order RR GG BB AA.
+ * 
+ * For example, an opaque 1x1 pixel image would yield the following bitmap 
+ * data:
+ * 
+ * Red  : 0xff 0x00 0x00 0x00
+ * Green: 0x00 0xff 0x00 0x00
+ * Blue : 0x00 0x00 0xff 0x00
+ *
+ * Any attempt to read pixels by casting bitmap data to uint32_t or similar
+ * will need to cater for the order of bytes in a word being different on
+ * big and little endian systems. To avoid confusion, it is recommended
+ * that pixel data is loaded as follows:
+ *
+ * uint32_t read_pixel(const uint8_t *bmp)
+ * {
+ *     //     red      green           blue              alpha
+ *     return bmp[0] | (bmp[1] << 8) | (bmp[2] << 16) | (bmp[3] << 24);
+ * }
+ *
+ * and *not* as follows:
+ *
+ * uint32_t read_pixel(const uint8_t *bmp)
+ * {
+ *     return *((uint32_t *) bmp);
+ * }
  */
 
 #ifndef _NETSURF_IMAGE_BITMAP_H_
-- 
cgit v1.2.3