QDBMP

ABOUT

QDBMP (Quick n' Dirty BMP) is a minimalistic cross-platform C library for handling BMP image files. The library is extremely lightweight - it consists of just two small files and has no dependencies other than the standard C library. It is intended to provide small applications with basic image I/O capabilities by utilizing the widely used BMP image format.

The library is written entirely in C, and is highly portable. It explicitly handles endianness issues and uses no OS-specific code.

The library supports the following BMP variants:

Uncompressed 32 BPP (alpha values are ignored)
Uncompressed 24 BPP
Uncompressed 8 BPP (indexed color)

QDBMP is free and open source software, distributed under the MIT license.

DOWNLOAD

qdbmp_0.1.0.tar.gz - QDBMP version 1.0.0 (UNIX newlines) (2007-04-07, 8 KB)

qdbmp_0.1.0.zip - QDBMP version 1.0.0 (Windows newlines) (2007-04-07, 10 KB)

USING QDBMP

Add qdbmp.h and qdbmp.c to your project. Include qdbmp.h in your code.

SAMPLE PROGRAM

/* Creates a negative image of the input bitmap file */
#include "qdbmp.h"
#include <stdio.h>

int main( int argc, char* argv[] )
{
    BMP*    bmp;
    UCHAR   r, g, b;
    UINT    width, height;
    UINT    x, y;

    if ( argc != 3 )
    {
        fprintf( stderr, "Usage: %s <input file> <output file>\n", argv[ 0 ] );
        return 0;
    }

    /* Read an image file */
    bmp = BMP_ReadFile( argv[ 1 ] );
    BMP_CHECK_ERROR( stderr, -1 ); /* If an error has occurred, notify and exit */

    /* Get image's dimensions */
    width = BMP_GetWidth( bmp );
    height = BMP_GetHeight( bmp );

    /* Iterate through all the image's pixels */
    for ( x = 0 ; x < width ; ++x )
    {
        for ( y = 0 ; y < height ; ++y )
        {
            /* Get pixel's RGB values */
            BMP_GetPixelRGB( bmp, x, y, &r, &g, &b );

            /* Invert RGB values */
            BMP_SetPixelRGB( bmp, x, y, 255 - r, 255 - g, 255 - b );
        }
    }

    /* Save result */
    BMP_WriteFile( bmp, argv[ 2 ] );
    BMP_CHECK_ERROR( stderr, -2 );

    /* Free all memory allocated for the image */
    BMP_Free( bmp );

    return 0;
}

API REFERENCE

TYPES

BMP - Bitmap object instance

UINT - Unsigned long integer (DWORD)

USHORT - Unsigned short integer (WORD)

UCHAR - Unsigned char

ERROR HANDLING

QDBMP's functions do not return values indicating success. Instead, each library operation sets an internal flag that may be queried using BMP_GetError(). If the operation was successful the function returns BMP_OK. Otherwise, it returns an error code describing what went wrong. BMP_GetErrorDescription() may be used to get a textual description of the last error that has occurred.

The suggested style is checking for an error immediately after every error prone operation. The BMP_CHECK_ERROR macro may be used to simplify this process. To illustrate:

/* Perform a BMP operation */
bmp = BMP_ReadFile( "MyImage.bmp" );

/* Method 1: Manually check for an error */
if ( BMP_GetError() != BMP_OK )
{
    /* Print error info */
    printf( "An error has occurred: %s (code %d)\n", BMP_GetErrorDescription(), BMP_GetError() );
}

/* Method 2: Check for an error using the macro */
BMP_CHECK_ERROR( stdout, -1 );

FUNCTIONS

BMP_Create()

BMP* BMP_Create( UINT width, UINT height, USHORT depth )

Creates a blank BMP image with the specified dimensions and bit depth.

BMP_Free()

void BMP_Destroy( BMP* bmp )

Frees all memory used by the BMP image.

BMP_ReadFile()

BMP* BMP_ReadFile( const char* filename )

Reads the specified BMP image file.

BMP_WriteFile()

void BMP_WriteFile( BMP* bmp, const char* filename )

Writes the BMP image to the specified file.

BMP_GetWidth()

UINT BMP_GetWidth( BMP* bmp )

Returns the image's width.

BMP_GetHeight()

UINT BMP_GetHeight( BMP* bmp )

Returns the image's height.

BMP_GetDepth()

USHORT BMP_GetDepth( BMP* bmp )

Returns the image's color depth (number of bits per pixel).

BMP_GetPixelRGB()

void BMP_GetPixelRGB( BMP* bmp, UINT x, UINT y, UCHAR* r, UCHAR* g, UCHAR* b )

Populates the arguments with the specified pixel's RGB values.

BMP_SetPixelRGB()

void BMP_SetPixelRGB( BMP* bmp, UINT x, UINT y, UCHAR r, UCHAR g, UCHAR b )

Sets the specified pixel's RGB values.

BMP_GetPixelIndex()

void BMP_GetPixelIndex( BMP* bmp, UINT x, UINT y, UCHAR* val )

Gets the specified pixel's color index.

BMP_SetPixelIndex()

void BMP_SetPixelIndex( BMP* bmp, UINT x, UINT y, UCHAR val )

Sets the specified pixel's color index.

BMP_GetPaletteColor()

void BMP_GetPaletteColor( BMP* bmp, UCHAR index, UCHAR* r, UCHAR* g, UCHAR* b )

Populates the arguments with the RGB values for the specified palette index.

BMP_SetPaletteColor()

void BMP_SetPaletteColor( BMP* bmp, UCHAR index, UCHAR r, UCHAR g, UCHAR b )

Sets the RGB values for the specified palette index.

BMP_GetError()

BMP_STATUS BMP_GetError()

Returns the last error code.

BMP_GetErrorDescription()

const char* BMP_GetErrorDescription()

Returns a textual description of the last error.

MACROS

BMP_CHECK_ERROR

BMP_CHECK_ERROR( output_file, return_value )

May be used after each BMP operation to check for an error. If an error has occurred, its description is printed to the specified output file and the specified value is returned.

CONTACT

QDBMP is developed by Chai Braudo.