---

RwPalQuant
[Rasters, Textures & Images]

Data Structures
struct	RwPalQuant
Functions
void	RwPalQuantSetMaxDepth (RwUInt32 depth)
RwUInt32	RwPalQuantGetMaxDepth (void)
void	RwPalQuantAddImage (RwPalQuant *pq, RwImage *img, RwReal weight)
RwInt32	RwPalQuantResolvePalette (RwRGBA *palette, RwInt32 maxcols, RwPalQuant *pq)
void	RwPalQuantMatchImage (RwUInt8 *dstpixels, RwInt32 dststride, RwInt32 dstdepth, RwBool dstPacked, RwPalQuant *pq, RwImage *img)
RwBool	RwPalQuantInit (RwPalQuant *pq)
void	RwPalQuantTerm (RwPalQuant *pq)

---

Detailed Description

Image Quantization

RwPalQuant Overview

Requirements

• Headers: rwcore.h
• Libraries: rwcore.lib

The API functions in this module can be used to convert a set of input images to a set of palettized images (usually 4 or 8 bit) that share a single palette. The input images might correspond, for example, to a set of mipmap levels.

This functionality is used internally in certain image to raster conversion processes (e.g. RwTextureRasterGenerateMipmaps).

The quantization process involves initializing an RwPalQuant object, accumulating pixel data for a series of images, resolving a palette, then generating the new palettized image data.

The following code shows an example of generating a 4-bit palettized image (destImage) from a given source image (sourceImage).

    RwImage    *destImage;
    RwPalQuant  pq;

    destImage = RwImageCreate(
        RwImageGetWidth(sourceImage), RwImageGetHeight(sourceImage), 4);
    RwImageAllocatePixels(destImage);

    RwPalQuantInit(&pq);
    RwPalQuantAddImage(&pq, sourceImage, 1.0f);
    RwPalQuantResolvePalette(RwImageGetPalette(destImage), 16, &pq);
    RwPalQuantMatchImage(RwImageGetPixels(destImage), 
        RwImageGetStride(destImage), RwImageGetDepth(destImage), 
        FALSE, &pq, sourceImage);
    RwPalQuantTerm(&pq);

The RwPalQuant structure contains a color quantization tree. This has a maximum depth given by RwPalQuantSetMaxDepth, which can be anything up to 8 (for 32-bit RGBA color depth). The highest values require significantly more memory and processing time. If this value is modified it should be done before calling RwPalQuantInit. The current value may be queried using RwPalQuantGetMaxDepth.

---

Function Documentation

void RwPalQuantAddImage (  RwPalQuant *    pq, RwImage *    img, RwReal    weight )

RwPalQuantAddImage adds each pixel in the image to the quantization tree population. Parameters: pq  Palquant structure holding the quantization tree. This must have been initialized with RwPalQuantInit. img  Image to add weight  Bias to use for these pixels. For a fixed weight value (e.g. '1'), the total weight of each image in a series of mipmap levels will naturally decrease due to each level having 4 times less pixels than the previous one. The weight value can be used to adjust the contribution of the higher levels. See also: RwPalQuantInit , RwPalQuantResolvePalette , RwPalQuantMatchImage

RwUInt32 RwPalQuantGetMaxDepth (  void    )

RwPalQuantGetMaxDepth returns the maximum depth of the tree used for palette quantization. Returns: Current maximum depth of tree used for quantization See also: RwTextureRasterGenerateMipmaps , RwPalQuantSetMaxDepth

RwBool RwPalQuantInit (  RwPalQuant *    pq )

RwPalQuantInit initializes a palette quantization tree structure. This will use the current maximum tree depth set by RwPalQuantSetMaxDepth. This should not be modified while the RwPalQuant structure is in use. Parameters: pq  Palette quantization structure to be initialized. Returns: TRUE on success, FALSE on failure See also: RwPalQuantTerm

void RwPalQuantMatchImage (  RwUInt8 *    dstpixels, RwInt32    dststride, RwInt32    dstdepth, RwBool    dstPacked, RwPalQuant *    pq, RwImage *    img )

RwPalQuantMatchImage matches an image to the given quantization tree, and writes new palette index image data. This should be called after using RwPalQuantResolvePalette. Parameters: dstpixels  Array of pixels in destination image. When writing to an RwImage, use RwImageGetPixels. dststride  Stride of pixel rows in destination image. For an RwImage, use RwImageGetStride. dstdepth  Bit depth of pixels in destination image. For an RwImage, use RwImageGetDepth. dstPacked  Specifies that the destination pixels should be packed together (2 pixels per byte using 4-bit palette indices). This should always be FALSE when writing to an RwImage. pq  RwPalQuant structure containing the quantization tree to use. img  Source image to match using the quantization tree. See also: RwPalQuantResolvePalette , RwPalQuantTerm

RwInt32 RwPalQuantResolvePalette (  RwRGBA *    palette, RwInt32    maxcols, RwPalQuant *    pq )

RwPalQuantResolvePalette uses the quantization tree in an RwPalQuant object to find a set of representative colors and store them in the specified palette. Parameters: palette  Palette in which to store results of quantization. maxcols  Maximum number of palette entries to use. pq  RwPalQuant structure holding the quantization tree. Returns: The number of palette entries used. RwPalQuantMatchImage

void RwPalQuantSetMaxDepth (  RwUInt32    depth )

RwPalQuantSetMaxDepth sets the maximum depth of the tree used for palette quantization. The deeper the tree, the more memory and time will be used by the quantization process, but the better the results, particularly on images with subtle color gradients. This function should be used before initializing an RwPalQuant object. Parameters: depth  Maximum depth of tree to be used for quantization. Values should be less than or equal to 8. See also: RwTextureRasterGenerateMipmaps , RwPalQuantGetMaxDepth

void RwPalQuantTerm (  RwPalQuant *    pq )

RwPalQuantTerm deinitializes a palette quantization tree structure Parameters: pq  Palette quantization structure to be deinitialized. See also: RwPalQuantInit

---