API

Public API

The G4ENCODER class exposes a few simple methods detailed below.

This is the entire class definition for G4ENCODER:

class G4ENCODER {
  public:
    int init(int iWidth, int iHeight, int iBitDirection, G4ENC_WRITE_CALLBACK *pfnWrite, uint8_t *pOut, int iOutSize);
    int getTIFFHeaderSize();
    int getTIFFHeader(uint8_t *pOut);
    int addLine(uint8_t *pPixels);
    int getOutSize();
    void getOBDLine(int iWidth, uint8_t *pImage, int iLine, uint8_t *pPixels);

  private:
    G4ENCIMAGE _g4;
};

The class is basically a C++ wrapper of C code which does all of the actual work. The G4ENCIMAGE structure is kept private, but is passed as a pointer to the 'worker' functions. This makes it easy to lift out the C code if you want to use it in a pure C project. Here are details of each method:

init(int iWidth, int iHeight, int iBitDirection, G4ENC_WRITE_CALLBACK *pfnWrite, uint8_t *pOut, int iOutSize)
This method needs to be called before beginning the compression of an image. The iWidth and iHeight parameters define the image size, while the iBitDirection tells the library in which bit direction the output should be generated. There are two possible values:
G4ENC_MSB_FIRST - bytes are filled beginning at the MSB (0x80)
G4ENC_LSB_FIRST - bytes are filled beginning at the LSB (0x01)
The pfnWrite callback function will be called periodically during the encoding when the internal buffer has filled and data needs to be written to the output device (e.g. disk). This is one way to manage compressed data that may be larger than the target system's available RAM. Alternatively, this parameter can be NULL and a pre-allocated buffer (pOut / iOutSize) can be used to hold the compressed data.

int getTIFFHeaderSize();
This method is used for when you would like to create a TIFF file from the compressed image data. The value returned is the number of bytes used by the TIFF header. The header data will be generated after the compression is completed, but this allows you to reserve the correct number of bytes ahead of time, since the header is placed before the compressed data in the file.

int getTIFFHeader(uint8_t *pOut);
This function copies the completed header data to a buffer you supply. This must be called after compressing the image since it contains tags which reference the compressed data size. The size of this header is currently around 160 bytes, but could change in the future if TIFF tags are added or removed.

int addLine(uint8_t *pPixels);
This is the heart of the G4 compressor. After initialization, call this repeatedly with each line of image data starting at the top of the image and working your way to the bottom. The pPixels parameter expects the image data to be arranged horizontally with the left-most pixel in the MSB of each byte. A return value of G4ENC_SUCCESS will be returned on each line until the last when it will change to G4ENC_IMAGE_COMPLETE.

int getOutSize();
After completing the image compression, this method will return the number of compressed bytes created.

void getOBDLine(int iWidth, uint8_t *pImage, int iLine, uint8_t *pPixels);
This method is added as a convenience for users of my OneBitDisplay library. It converts a single line of pixels from the internal format used by that library into the format needed by this library.

typedef void (G4ENC_WRITE_CALLBACK)(uint8_t *pData, int iLen);

The optional callback function will be called periodically during the encoding of the image with varying sized blocks of data.