summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2016-08-11 12:16:12 (GMT)
committer Vincent Sanders <vince@kyllikki.org>2016-08-11 12:16:12 (GMT)
commitb0e4d39dc3be430670148262efbc0226b97448a6 (patch)
tree70d474a838c2b7c9f8fcd1156656dacba16ae057
parenta44819c36f45f3a0a2d387210d0c2f6b5eb577d9 (diff)
downloadlibnsbmp-b0e4d39dc3be430670148262efbc0226b97448a6.tar.gz
libnsbmp-b0e4d39dc3be430670148262efbc0226b97448a6.tar.bz2
move library usage documentation into a README file
-rw-r--r--src/README57
-rw-r--r--src/libnsbmp.c63
2 files changed, 62 insertions, 58 deletions
diff --git a/src/README b/src/README
new file mode 100644
index 0000000..19b75e7
--- a/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
diff --git a/src/libnsbmp.c b/src/libnsbmp.c
index 123ed9e..d4e4b08 100644
--- a/src/libnsbmp.c
+++ b/src/libnsbmp.c
@@ -7,6 +7,11 @@
* http://www.opensource.org/licenses/mit-license.php
*/
+/**
+ * \file
+ * BMP decoding implementation
+ */
+
#include <assert.h>
#include <stdbool.h>
#include <stdio.h>
@@ -18,64 +23,6 @@
#include "utils/log.h"
-/* The functions provided by this file 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'.
-
- [dynis] - Tue 1st July 2008
-*/
-
/* squashes unused variable compiler warnings */
#define UNUSED(x) ((x)=(x))