Valid image types in leptonica: Pix: 1 bpp, with and without colormap Pix: 2 bpp, with and without colormap Pix: 4 bpp, with and without colormap Pix: 8 bpp, with and without colormap Pix: 16 bpp (1 spp) Pix: 32 bpp (rgb, 3 spp) Pix: 32 bpp (rgba, 4 spp) FPix: 32 bpp float DPix: 64 bpp double Notes: (1) The only valid Pix image type with alpha is rgba. In particular, the alpha component is not used in cmapped images. (2) PixComp can hold any Pix with IFF_PNG encoding. This file is internal: it is not part of the public interface. It contains the definitions of most of the image-related structs used in leptonica: struct Pix struct PixColormap struct RGBA_Quad struct Pixa struct Pixaa struct Box struct Boxa struct Boxaa struct Pta struct Ptaa struct Pixacc struct PixTiling struct FPix struct FPixa struct DPix struct PixComp struct PixaComp This file can be #included after allheaders.h in source files that require direct access to the internal data fields in these structs. Notes on the pixels in the raster image. Most of this information can also be found in pix.h. (1) The image data is stored in a single contiguous array of l_uint32, into which the pixels are packed. By "packed" we mean that there are no unused bits between pixels, except for end-of-line padding to satisfy item (2) below. (2) Every image raster line begins on a 32-bit word boundary within this array. (3) Pix image data is stored in 32-bit units, with the pixels ordered from left to right in the image being stored in order from the MSB to LSB within the word, for both big-endian and little-endian machines. This is the natural ordering for big-endian machines, as successive bytes are stored and fetched progressively to the right. However, for little-endians, when storing we re-order the bytes from this byte stream order, and reshuffle again for byte access on 32-bit entities. So if the bytes come in sequence from left to right, we store them on little-endians in byte order: 3 2 1 0 7 6 5 4 ... This MSB to LSB ordering allows left and right shift operations on 32 bit words to move the pixels properly. (4) We use 32 bit pixels for both RGB and RGBA color images. The A (alpha) byte is ignored in most leptonica functions operating on color images. Within each 4 byte pixel, the color samples are ordered from MSB to LSB, as follows: | MSB | 2nd MSB | 3rd MSB | LSB | red green blue alpha 0 1 2 3 (big-endian) 3 2 1 0 (little-endian) Because we use MSB to LSB ordering within the 32-bit word, the individual 8-bit samples can be accessed with GET_DATA_BYTE and SET_DATA_BYTE macros, using the (implicitly big-ending) ordering red: byte 0 (MSB) green: byte 1 (2nd MSB) blue: byte 2 (3rd MSB) alpha: byte 3 (LSB) The specific color assignment is made in this file, through the definitions of COLOR_RED, etc. Then the R, G B and A sample values can be retrieved using redval = GET_DATA_BYTE(&pixel, COLOR_RED); greenval = GET_DATA_BYTE(&pixel, COLOR_GREEN); blueval = GET_DATA_BYTE(&pixel, COLOR_BLUE); alphaval = GET_DATA_BYTE(&pixel, L_ALPHA_CHANNEL); and they can be set with SET_DATA_BYTE(&pixel, COLOR_RED, redval); SET_DATA_BYTE(&pixel, COLOR_GREEN, greenval); SET_DATA_BYTE(&pixel, COLOR_BLUE, blueval); SET_DATA_BYTE(&pixel, L_ALPHA_CHANNEL, alphaval); More efficiently, these components can be extracted directly by shifting and masking, explicitly using the values in L_RED_SHIFT, etc.: (pixel32 >> L_RED_SHIFT) & 0xff; (red) (pixel32 >> L_GREEN_SHIFT) & 0xff; (green) (pixel32 >> L_BLUE_SHIFT) & 0xff; (blue) (pixel32 >> L_ALPHA_SHIFT) & 0xff; (alpha) The functions extractRGBValues() and extractRGBAValues() are provided to do this. Likewise, the pixels can be set directly by shifting, using composeRGBPixel() and composeRGBAPixel(). All these operations work properly on both big- and little-endians. (5) A reference count is held within each pix, giving the number of ptrs to the pix. When a pixClone() call is made, the ref count is increased by 1, and when a pixDestroy() call is made, the reference count of the pix is decremented. The pix is only destroyed when the reference count goes to zero. (6) The version numbers (below) are used in the serialization of these data structures. They are placed in the files, and rarely (if ever) change. (7) The serialization dependencies are as follows: pixaa : pixa : boxa boxaa : boxa So, for example, pixaa and boxaa can be changed without forcing a change in pixa or boxa. However, if pixa is changed, it forces a change in pixaa, and if boxa is changed, if forces a change in the other three. We define four version numbers: PIXAA_VERSION_NUMBER PIXA_VERSION_NUMBER BOXAA_VERSION_NUMBER BOXA_VERSION_NUMBER pre
Definition in file pix_internal.h.