Dali: BitImage -- C API

Header Files

#include <dvmbasic.h>

Type Definitions

BitImage

A BitImage is a two dimensional array of pixels, where each pixel can take value of either 0 or 1. As with ByteImages, a BitImage can be either physical or virtual. A physical BitImage has memory allocated to it, while a virtual BitImage borrows its memory from a physical one.
BitImages are internally represented in a packed format (i.e., 8 bits are packed into one byte). This representation allows makes some operations very fast, but slows others down.
A byte in a BitImage bit is said to be a full byte if all 8 bits are part of the BitImage. Otherwise it is said to be partial.
A BitImage is said to be byte-aligned iff the left and right boundary of the BitImage is also at the byte-boundary. It is said to be left byte-aligned iff the left boundary is at the byte-boundary.

    typedef struct BitImage {
         int unitWidth;
         int byteWidth;
         int height;
         int x;
         int y;
         int parentWidth;
         unsigned char firstBit;
         unsigned char lastBit;
         unsigned char isVirtual;
         unsigned char *firstByte;
     } BitImage;

unitWidth

the width of the BitImage in bits.

byteWidth

The number of full bytes in the each row of the BitImage. If bits in the first byte (or last) byte are not in the BitImage, the first (or last) byte are considered as partial bytes and is not counted in byteWidth.

height

the height of the BitImage

x

the x-offset of the top-left corner of the BitImage from it's parent (in bits).

y

the y-offset of the top-left corner of the BitImage from it's parent (in bits).

parentWidth

For a physical buffer, parentWidth is the number of bytes allocated for the buffer. Note that this might be one more than byteWidth, since byteWidth does not include the last byte if it is partial.
For a virtual buffer, parentWidth is the parentWidth of the physical buffer it belongs to. (again, this should be called rootWidth since the parent of a BitImage may be a virtual image also.)

firstBit

The first valid bit in the first byte of the buffer. The sequence is 01234567. (First bit is 0, second bit is 1 ...) A physical buffer always has firstBit == 0.

lastBit

The last valid bit in the last byte of the buffer. The sequence is 12345670. (First bit is 1, second bit is 2 ...)

isVirtual

1 iff the BitImage is virtual. 0 otherwise.

firstByte

pointer to the first byte in the BitImage in the first row of BitImage

Constants

Return Code

Return code from various bit primitives. DVM_BIT_OK indicates the primitives executed succesfully. DVM_BIT_IS_BYTE_ALIGN indicates that the BitImage passed into a non-byte-aligned primitives is byte-aligned. DVM_BIT_NOT_BYTE_ALIGN indicates that the BitImage passed into a byte-aligned primitives is not byte-aligned.

     #define DVM_BIT_OK 0
     #define DVM_BIT_IS_BYTE_ALIGN -1
     #define DVM_BIT_NOT_BYTE_ALIGN -2

Operators

Allocation

BitImage *BitNew (int w, int h)

Create a new physical BitImage of size w x h bits and return a pointer to that BitImage.

void BitFree (BitImage *bitImage)

Deallocate the BitImage bitImage (used for both virtual physical BitImages).

BitImage *BitClip (BitImage *bitImage, int x, int y, int w, int h)

Create a virtual BitImage of size w x h bits, with bitImage as the parent, and offset (x, y) from bit. A pointer to the new BitImage is returned.

void BitReclip (BitImage *bitImage, int x, int y, int w, int h, BitImage *clipped)

Initialize the virtual BitImage clipped as if it is created by BitClip(bitImage, x, y, w, h).

Initialization

int BitCopy (BitImage *src, BitImage *dest)

Copy the top-left w x h area of BitImage src into BitImage dest, where w and h are minimum width and height of src and dest. Either one of both of src and dest should not be byte-aligned. BitCopy8 should be used instead if both are byte-aligned. Returns DVM_BIT_OK if copied succesfully, or DVM_BIT_IS_BYTE_ALIGN if both src and dest are found to be byte-aligned.

int BitCopy8 (BitImage *src, BitImage *dest)

Copy the top-left w x h area of BitImage src into BitImage dest, where w and h are minimum width and height of src and dest. Both src and dest should be byte-aligned. BitCopy should be used instead if either one is not byte-aligned. Returns DVM_BIT_OK if copied succesfully, or DVM_BIT_NOT_BYTE_ALIGN if either src or dest are found to be not byte-aligned.

int BitSet (BitImage *bitImage, unsigned char v)

Set the BitImage bit to the all 0 if v is 0, or 1 if v is non-zero. bit must not be byte-aligned. Returns DVM_BIT_OK if set is succesful, or DVM_BIT_IS_BYTE_ALIGN if bit is byte-aligned.

int BitSet8 (BitImage *bitImage, unsigned char v)

Set the BitImage bit to the all 0 if v is 0, or 1 if v is non-zero. bit must be byte-aligned. Returns DVM_BIT_OK if set is succesful, or DVM_BIT_NOT_BYTE_ALIGN if bit is not byte-aligned.

void BitMakeFromKey (ByteImage *byteImage, unsigned char low, unsigned char high, BitImage *bitImage)
Initialize the content of bitImage as follows :
  if (low <= byte(x,y) <= high) {
      bit(x,y) = 1
  } else {
      bit(x,y) = 0
  }
      

Set Operations

int BitUnion (BitImage *src1, BitImage *src2, BitImage *dest)

Union the top-left w x h area of BitImage src1 and BitImage src2 and store the result into the top-left w x h area of dest, where w and h are the minimum width and height among src1, src2 and dest. Either one of src1, src2 and dest must be non-byte-aligned. Returns DVM_BIT_OK if union is succesful, or DVM_BIT_IS_BYTE_ALIGN if all three input are byte-aligned.

int BitUnion8 (BitImage *src1, BitImage *src2, BitImage *dest)

Union the top-left w x h area of BitImage src1 and BitImage src2 and store the result into the top-left w x h area of dest, where w and h are the minimum width and height among src1, src2 and dest. All three src1, src2 and dest must be byte-aligned. Returns DVM_BIT_OK if union is succesful, or DVM_BIT_NOT_BYTE_ALIGN if one of the three input is not byte-aligned.

int BitIntersect (BitImage *src1, BitImage *src2, BitImage *dest)

Intersect the top-left w x h area of BitImage src1 and BitImage src2 and store the result into the top-left w x h area of dest, where w and h are the minimum width and height among src1, src2 and dest. Either one of src1, src2 and dest must be non-byte-aligned. Returns DVM_BIT_OK if intersect is succesful, or DVM_BIT_IS_BYTE_ALIGN if all three input are byte-aligned.

int BitIntersect8 (BitImage *src1, BitImage *src2, BitImage *dest)

Intersect the top-left w x h area of BitImage src1 and BitImage src2 and store the result into the top-left w x h area of dest, where w and h are the minimum width and height among src1, src2 and dest. All three src1, src2 and dest must be byte-aligned.
Returns DVM_BIT_OK if intersect is succesful, or DVM_BIT_NOT_BYTE_ALIGN if one of the three input is not byte-aligned.

Queries

int BitIsAligned(BitImage *bitImage)

Returns non-zero value iff BitImage bitImage is byte-aligned.

int BitIsLeftAligned(BitImage *bitImage)

Returns non-zero value iff BitImage bitImage is left-aligned.

int BitGetSize(BitImage *bitImage)

Returns the number of bytes allocated for BitImage bitImage, counting the number of bytes in each row (including partial bytes), multiply by number of rows. Bytes allocated for the header (height, x, y etc.) is not counted.

int BitGetWidth(BitImage *bitImage)

Returns the width of the BitImage bitImage.

int BitGetHeight(BitImage *bitImage)

Returns the height of the BitImage bitImage.

int BitGetVirtual(BitImage *bitImage)

Returns the virtual flag of the BitImage bitImage.

int BitGetX(BitImage *bitImage)

Returns the X of the BitImage bitImage.

int BitGetY(BitImage *bitImage)

Returns the Y of the BitImage bitImage.