Dali: ByteImage -- C API

Header Files

#include <dvmbasic.h>

Type Definitions

ByteImage

A ByteImage stores a 2 dimensional array of pixels. Each pixel can take value between 0 and 255, inclusive. ByteImages can be physical or virtual. When a physical ByteImage is created (via a call to ByteNew), memory is allocated for the header structure and the array. When a virtual ByteImage is allocated (via a call to ByteClip), memory is allocated for the header, but the array data is shared with a physical ByteImage. Thus, the pixel array is contiguous in physical ByteImages, but usually not contiguous in virtual ByteImages.

    typedef struct ByteImage {
        int width;
        int height;
        int x;
        int y;
        int parentWidth;
        unsigned char isVirtual;
        unsigned char *firstByte;
    } ByteImage;

width

the width of the ByteImage

height

the height of the ByteImage

x

the x-offset of the top-left corner of the ByteImage from it's parent. 0 if the ByteImage is a physical ByteImage.

y

the y-offset of the top-left corner of the ByteImage from it's parent. 0 if the ByteImage is a physical ByteImage.

parentWidth

the width of the physical parent of this ByteImage. (should probably be called "rootWidth" since the parent might not be physical)

isVirtual

1 iff the ByteImage is virtual. 0 otherwise.

firstByte

pointer to the first byte in the buffer.

Constants

Return Code

Return code from various byte primitives. DVM_BYTE_OK indicates the primitives executed succesfully. DVM_BYTE_ERROR indicates that an error has occured.

    #define DVM_BYTE_OK 0
    #define DVM_BYTE_ERROR 1

Operators

Allocation

ByteImage *ByteNew(int w, int h)

Allocate a new physical ByteImage with width w and height h. Return a handle to the new ByteImage.

ByteImage *ByteClip (ByteImage *byteImage, int x, int y, int w, int h)

Create a new virtual ByteImage which points to a window within the existing ByteImage byteImage. The window starts at position (x, y) and has dimension w x h. Return a handle to the new virtual ByteImage.

void ByteReclip (ByteImage *byteImage, int x, int y, int w, int h, ByteImage *clipped)

This function is identical to ByteClip, except that it destructively modifies the virtual ByteImage clipped (instead of creating a new virtual ByteImage). Warning : memory leaks will occurs if clipped is a physical ByteImage.

void ByteFree (ByteImage *byteImage)

Deallocate a ByteImage . The ByteImage can be virtual or physical. If the ByteImage is virtual, only the header is deallocated, the content of the ByteImage remains. If the ByteImage is physical, all virtual ByteImages that depend on byteImage should not be used (because the pixel array they share with byteImage is deallocated by this function).

Initialization

void ByteSet (ByteImage *byteImage, unsigned char value) void ByteSetWithMask (ByteImage *byteImage, BitImage *bitMask, unsigned char value)

Initialize all pixels in byteImage to value. The "with mask" form only copies where the corresponding pixel in bitMask is 1.

void ByteSetMux1 (ByteImage *byteImage, int offset, int stride, unsigned char value) void ByteSetMux2 (ByteImage *byteImage, int offset, int stride, unsigned char value) void ByteSetMux4 (ByteImage *byteImage, int offset, int stride, unsigned char value)

A ByteImage is divided into vertical strips, specified by three parameters : length, offset and stride. Length specifies the width of each strips. Offset is the distance of the first byte of the first strip from the first byte of each row in the ByteImage, and Stride is the distance between the strips. For example, the figure below shows the ByteImage with strips specified by length = 4, offset = 1, and stride = 2.

This group of primitives initialize strips in a ByteImage byteImage to value. The suffix of the name of the primitives specifies the width of the strips. offset and stride is specified using arguments to the primitives.

void ByteCopy (ByteImage *src, ByteImage *dest) void ByteCopyWithMask (ByteImage *src, BitImage *bitMask, ByteImage *dest)

Copy the content of ByteImage src into ByteImage dest. The "with mask" form only copies where the corresponding pixel in bitMask is 1. The images must not overlap.

void ByteCopyMux1 (ByteImage *src, int srcOffset, int srcStride, ByteImage *dest, int destOffset, int destStride) void ByteCopyMux2 (ByteImage *src, int srcOffset, int srcStride, ByteImage *dest, int destOffset, int destStride) void ByteCopyMux4 (ByteImage *src, int srcOffset, int srcStride, ByteImage *dest, int destOffset, int destStride)

These primitives copy the vertical strips of equal width from the src ByteImage into the dest ByteImage. The width of the strips is specified by the suffix of the primitives name. The offsets and strides are specified by the arguments to the primitives.
See the description of the ByteSetMux1 primitive for a detail description of offset, stride and length.

void ByteExtend (ByteImage *byteImage, int bw, int bh)

Fills borders (of total width bw and height bh) of byteImage by copying pixels from the interior as shown. This function can be used in conjunction with byte_clip and byte_copy to prepare an image for convolution.

Query

int ByteGetX(ByteImage *byteImage) int ByteGetY(ByteImage *byteImage) int ByteGetWidth(ByteImage *byteImage) int ByteGetHeight(ByteImage *byteImage) int ByteGetVirtual(ByteImage *byteImage)

These functions (macros in the C version) access various fields in the ByteImage data structure. The first two function return the x or y offset of byteImage within its parent, the next two return the width or height of byteImage, and the last function returns 1 if byteImage is virtual, 0 otherwise.

int ByteHash(ByteImage *byteImage)

This function computes a hash value (a 32 bit signed integer) based on the pixel data in the image.