|
| Home |
|
|
Class PegImageConvertPegImageConvert is the base class for PegBmpConvert, PegGifConvert, PegJpgConvert, and PegPngConvert. These classes provide the ability to read, color quantize, RLE (run-length encoding) compress, and generate PegBitmap formatted data structures at program run time. Most applications do not use or enable run-time image conversion. Run-time image conversion can consume a large amount of dynamic memory, and should only be used if required. The better alternative to run-time image conversion in many cases is to use the Image Convert utility program to pre-convert image files into PegBitmap source files. One of the jobs of the image conversion class is to map the input file colors to the target system display capabilities. There are two basic color mapping modes that can be used by the conversion object. These mapping modes are referred to as inline mode and post-read mode. With inline remapping mode, the converter reads and decompresses one scanline of input data to a temporary buffer, and remaps this single row to the target colors or grayscale. This process continues on a line-by-line basis until the entire image has been remapped to the target system palette. The benefit of this conversion mode is that only a single-line temporary buffer is required in addition to the final output data array, meaning that this conversion mode uses less dynamic memory than post-read conversion. Note, however, that inline conversion mode requires that the input data is scan-line oriented and not interlaced. For this reason inline conversion mode cannot be used with interlaced PNG input files, which use an interlace format that is not scan line oriented. Post-read conversion means that the entire input image is read into a temporary buffer, and the image is then color mapped into the final output buffer. This conversion mode can require much more memory than inline conversion, especially for cases when high color depth images are being remapped to lower color depth target displays which may require less than 8 bpp (bits per pixel) output in the final buffer. Post-read conversion has the benefits of being able to produce an optimal color palette for 8 bpp systems, and also is able to handle interlaced PNG files. The color mapping algorithm used can be either a best match algorithm or a dithering algorithm. For inline remapping the algorithm is determined by the conversion mode. For post-read remapping the algorithm used is determined by which color-mapping function is called by the application. After conversion is complete, the conversion objects return a pointer to a PegBitmap structure containing the converted image ready for display. In most cases, only one converted image will be available, however for animated GIF files there may be multiple PegBitmap structures produced. The application software can determine how many images were converted by calling the GetBitmapCount() function, and may retrieve pointers to each bitmap by calling the GetBitmapPointer() function. The image conversion classes can also be used in combination with the color quantization class, PegQuant. The image conversion classes will count the colors present in each image for use in the color quantization histogram. The order in which the PegImageConvert member functions are called is critical for correct operation. This is detailed further in the member function descriptions. In general, the conversion process can either convert the incoming data inline to a pre-defined system palette, or in one pass after reading the entire input image. Inline conversion is the most memory efficient when running with a fixed system palette. The general order of operation for inline conversion to a fixed system palette is:
The general order of operation for post-read conversion to a fixed system palette is:
This order of operation is somewhat different when the goal is to create a custom palette and perform post-read remapping to the optimal palette:
Important: The PegBitmap structures created by the conversion object are not deleted when the object is destroyed. Under normal operation, the caller retrieves the bitmaps after conversion by calling the GetBitmapList() function. The caller then owns the memory associated with the Bitmaps, and must free this memory after the bitmaps are no longer needed. If the caller does not retrieve the PegBitmap structures, they should be deleted with a call to DestroyImages() before deleting the conversion object. This can be useful in an application where you do not actually want to display the images, but you do need to obtain image size or other attribute information. In this case, you can construct the conversion object(s), tell them to read the image, retrieve whatever information is required, and then call DestroyImages() to clean up the memory associated with the conversion objects.
class PegPixel
{
public:
PegPixel(void);
PegPixel(LONG r, LONG g, LONG b);
BOOL operator != (const PegPixel &Pix) const;
BOOL operator == (const PegPixel &Pix) const;
LONG Red;
LONG Green;
LONG Blue;
};
class PegImageConvert
{
public:
PegImageConvert(PEGUINT wId);
void SetSystemPalette(UCHAR * pPal, PEGUINT wPalSize, BOOL bFast = FALSE);
void SetMode(PEGUINT wMode);
void SetTransColor(PegPixel Pixel);
void SetTransColor(UCHAR uIndex);
void SetGrayscale(BOOL bGray);
PegPixel GetTransColor(void);
virtual PegPixel GetULCColor(void);
virtual PegPixel GetPixelColor(UCHAR * pStart, PEGUINT wYPos, PEGUINT wIndex, PEGUINT wImgWidth);
virtual PegPixel GetPixelColor(UCHAR * pGet, PEGUINT wIndex);
virtual void DestroyImages(void);
virtual void RotateImages(PEGINT iRotation);
PEGUINT GetByteWidthForInternalColorDepth(PEGUINT wImgWidth);
PEGUINT GetByteWidthForOutputColorDepth(PEGUINT wImgWidth);
UCHAR GetOutputBitsPerPix(void){return muOutBitsPerPix;}
virtual void CountColors(PegQuant * pQuant);
virtual PEGUINT ConsumeImageInput(UCHAR * Buffer, PEGUINT wLength);
BOOL RleEncode(BOOL bForce = FALSE);
PEGUINT RleEncode(UCHAR * pData, UCHAR * pPut, PEGUINT wWidth);
virtual BOOL ReadImage(FILE *pFile, PEGINT iCount = 100) = 0;
UCHAR * GetLocalPalette(void);
PEGCHAR * GetErrorString(void);
void Id(PEGUINT wId);
PEGUINT Id(void);
LONG GetDataSize(int iIndex = 0);
PegBitmap * GetBitmapPointer(int iIndex);
PEGUINT GetBitmapCount(void);
PEGUINT GetState(void);
PEGUINT GetRowsConverted(void);
PEGUINT GetMode(void);
UCHAR ImageType(void);
BOOL DitherBitmap(void);
BOOL RemapBitmap(void);
};
ConstructorsThis constructor creates an image conversion object. Method ConsumeImageInputThis function is called to get input data. The default implementation reads data from the file specified in ReadImage(), but a derived class could supply the data from some other source. The converter object will call this method repeatedly to read parts of the image. Method CountColorsThis function is called after the image has been decoded to count the occurrences of each possible color value. This is used for color reduction along with the PegQuant class. Method DataSizeThis function returns the data size, in bytes, of the PegBitmap data constructed by the conversion object. Method DestroyImagesThis function can be called to destroy all PegBitmap images created by the conversion object. This should only be done if the caller does not want to keep and use the PegBitmaps produced. Method DitherBitmapThis function can be called after an image has been read and a system palette has been assigned with SetSystemPalette(). This function will dither the contained PegBitmap to the system palette. Method GetBitmapCountThis function returns the number of PegBitmap structures produced during the image read operation. GIF and JPG files can contain any number of individual images. Method GetBitmapPointerThis function returns a pointer to the PegBitmap structure at the specified index produced by the conversion process. Most images (JPG, PNG, etc.) only have one bitmap, so index 0 returns it. GIFs can have multiple bitmaps. Method GetByteWidthForOutputColorDepthThis function returns the byte width based on output color depth, always padding to a full byte scanline. Images with less than 8 bits per pixel always pad to a full byte per scanline. Method GetDataSizeReturns the data size of the specified image. GetErrorStringThis function returns the error string associated with a conversion failure. This value if only valid if the conversion object State variable indicates an error has occurred. Method GetLocalPaletteThis function returns the local palette associated with the converted bitmap(s). This palette is embedded in the source image. Method GetModeReturns the operating mode of the conversion object. The operating mode is determined by the caller when configuring the conversion object. Several mode bits can be set simultaneously. The available modes are:
When operating with a fixed system palette, it is important to configure the conversion object for an inline conversion mode prior to reading the image. This saves a large amount of memory space over reading the image and then converting to a fixed palette. Method GetOutputBitsPerPixThis function returns the output color depth determined by the system palette assigned to the conversion object. Method GetPixelColorReturns the PegPixel value at the specified index. Method GetRowsConvertedIn inline conversion modes, this returns how many rows of image data have been mapped to the system palette. This can be useful for the progressive display of complex images. Method GetStateReturns the state variable of the conversion object. The possible states are:
Method GetTransColorReturns the transparent color value. Method GetULCColorReturns the upper-left hand corner color of the first bitmap. Method IdSets the conversion object ID. Method IdReturns the ID of the conversion object. This is a caller defined value used to identify a particular converter when many conversions are occurring concurrently. Method ImageTypeReturns the image type processed by the conversion object. The supported image types are:
Method InputFreeSpaceReturns the number of bytes free in the input buffer. Method ReadImageThis function begins the conversion process. This function should be called only after the converter has been configured with SetMode(). Use of the iCount parameter depends on the ReadImage() implementation for a specific derived class. Currently, iCount is used only in the GIF image conversion implementation as an upper limit on the number of GIF89a embedded images converted. Method RemapBitmapThis function is called to do a best-color mapping of the bitmap to a fixed system palette. The SetSystemPalette() function must be called before RemapBitmap(). This function does no dithering, but instead uses a closest match algorithm. This is useful when an optimal palette has been generated. Method RleEncodeThis function can be called to RLE encode a converted bitmap. The function will first determine if RLE encoding saves space before doing the encoding, so the caller cannot assume that the contained PegBitmap is encoded after calling this function. Method RotateImagesThis function rotates the bitmap. Only values of 90 or 270 degrees are supported. The bitmap rotates counter-clockwise. Method SetGrayscaleThis function changes the color mapping algorithm to match colors based on brightness using a linear grayscale target palette. Method SetModeThis function configures the conversion object for one of several possible modes. This function should be called before the input image is actually read. Several mode bits can be set simultaneously. The available modes are:
When operating with a fixed system palette, it is important to configure the conversion object for an inline conversion mode prior to reading the image. This saves a large amount of memory space over reading the image and then converting to a fixed palette. SetSystemPaletteThis function informs the conversion object of the working system palette. This is required for best-color remapping and dithering. The bFast parameter is saved in member variable mbUseFastLookup for subsequent palette matching operations. For 16-bit and true color, parameter pPal can be set to NULL and wPalSize to HI_COLOR or TRUE_COLOR, respectively. Method SetTransColorThis function can be used to assign a transparent color, either by its RGB value or its palette index. This is only required for .bmp input images, since other image types embed transparency information.
|
