BitImageScan -- C API

Header Files

#include <basicInt.h>

Type Definitions

BitImageScan

	typedef struct BitImageScan {

	    char     *currByte;

	    int       currBit;

	    BitImage *region;

	    int       x, y;

	    int       regionSkip;

	    int       unitWidth;

	    int       byteWidth;

	    int       height;

	    int       lastBit;

	} BitImageScan;

    

currByte

The byte to scan on next GetExtent() call.

currBit

The bit to start scanning on next GetExtent() call. Ranges from 0 to 7.

region

The BitImage we are scanning on.

x

x-coordinate of currBit in region.

y

y-coordinate of currBit in region.

regionSkip

Precomputed values for offset to add when skipping to the next row.

unitWidth, byteWidth, height, lastBit

Since the region we want to mask may be smaller than the dimension of the BitImage, we have to "clip" the bitmask to the size of the region. The last four fields are attributes of the clipped BitImage and have the same semantics as the field in BitImage.

Operators

Scan

BitImageScan* BitImageOpenScan (BitImage *mask, int w, int h)

Allocate and initialize a pointer to a BitImageScan structure. This structure records the state of a scan using mask as the bit mask of size w x h. If mask is NULL, then the scan structure will be initialized such that each call to GetNextExtent will return extents equivalent to using a mask with all bits set to 1.

int BitImageGetNextExtent (BitImageScan *scan, int *x, int *y, int *len)

Take in a BitImageScan scan, and output an extent. An extent is a pair of coordinates (x1, y) and (x2, y) in the same row, with all bits between (x1, y) and (x2-1, y) is 1, and bits (x1-1, y) and (x2, y) are 0. GetNextExtent() output an extent in the form of (x1, x2 - x1, y). GetNextExtent() returns SCAN_NOT_DONE if it finds an extent. If an extent is found, it is returned. SCAN_DONE is returned if it cannot find anymore extent in the bitmap-region. If SCAN_DONE is returned, the output pointers are invalid.

void BitImageCloseScan (BitImageScan *scan)

Free the BitImageScan structure scan. After CloseScan() is called on a BitImageScan structure, the structure cannot be used any more.

This is a typical usage of BitImageScan structure;

       scan = BitImageOpenScan(bit, w, h);

       while (BitImageGetNextExtent(scan, &x1, &len, &y) != SCAN_DONE) {

           set curr to the byte at (x1, y)

           DO_N_TIMES(len,

               // do something with curr

               curr++;

           )

       }

       BitImageCloseScan(scan);