summaryrefslogtreecommitdiff
path: root/src/README
diff options
context:
space:
mode:
Diffstat (limited to 'src/README')
-rw-r--r--src/README57
1 files changed, 57 insertions, 0 deletions
diff --git a/src/README b/src/README
new file mode 100644
index 0000000..19b75e7
--- /dev/null
+++ b/src/README
@@ -0,0 +1,57 @@
+NetSurf bitmap decoding library
+===============================
+
+The functions provided by this library allow for the decoding of
+Microsoft's BMP and ICO image file formats.
+
+READING BMP FILES
+=================
+
+To begin decoding a BMP, the caller should initialise a
+'bmp_bitmap_callback_vt' structure with the appropriate values necessary
+to handle bitmap images. Next, a 'bmp_image' structure should be
+initialised by calling bmp_create(). This structure should then be
+passed to bmp_analyse() along with the BMP data to process and the size
+of this data.
+
+Once the analysis has begun, the decoder completes the width and height
+variables.
+
+To decode the image, the caller must use bmp_decode() which selects the
+proper decoding method based on the BMP info header and assigns the
+decoded bitmap image to the 'bitmap' member of the 'bmp_image'
+structure. The bitmap image is stored with 4 bytes-per-pixel in RGBA
+format.
+
+It should be noted that bmp_finalise() should always be called, even if
+the image was never decoded. It is also the responsibility of the
+caller to free 'bmp_data'.
+
+READING ICO FILES
+=================
+
+To begin decoding an ICO, the caller should initialise a
+'bmp_bitmap_callback_vt' structure with the appropriate values necessary
+to handle bitmap images. Next, an 'ico_collection' structure should be
+initialised by calling ico_create(). This structure should then be
+passed to ico_analyse() along with the ICO data to process and the size
+of this data.
+
+Once the analysis has begun, the decoder completes the width and height
+variables. Because ICO collections contain multiple bitmap images, the
+width and height will contain the values of the largest available image.
+
+The caller then obtains a BMP from the ICO collection by calling
+ico_find() with the requested width and height.
+
+To decode the image, the caller must use bmp_decode() which selects the
+proper decoding method based on the BMP info header and assigns the
+decoded bitmap image to the 'bitmap' member of the 'bmp_image'
+structure. The bitmap image is stored with 4 bytes-per-pixel in RGBA
+format.
+
+It should be noted that ico_finalise() should always be called, even if
+no images were decoded. Because ico_finalise() calls bmp_finalise() for
+each bitmap within the collection, the caller is not required to perform
+this function. However, it is the responsibility of the caller to free
+'ico_data'. \ No newline at end of file