diff options
author | Vincent Sanders <vince@kyllikki.org> | 2016-08-11 13:16:12 +0100 |
---|---|---|
committer | Vincent Sanders <vince@kyllikki.org> | 2016-08-11 13:16:12 +0100 |
commit | b0e4d39dc3be430670148262efbc0226b97448a6 (patch) | |
tree | 70d474a838c2b7c9f8fcd1156656dacba16ae057 | |
parent | a44819c36f45f3a0a2d387210d0c2f6b5eb577d9 (diff) | |
download | libnsbmp-b0e4d39dc3be430670148262efbc0226b97448a6.tar.gz libnsbmp-b0e4d39dc3be430670148262efbc0226b97448a6.tar.bz2 |
move library usage documentation into a README file
-rw-r--r-- | src/README | 57 | ||||
-rw-r--r-- | src/libnsbmp.c | 63 |
2 files changed, 62 insertions, 58 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 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)) |