kmSetPaletteData

Sets the on-chip palette data

KMSTATUS KMAPI
kmSetPaletteData(
IN PKMPALETTEDATA pPaletteTable
)

Description:

This function sets the on-chip palette used by the palettized texture.
A palette has a total of 1,024 entries. The number of entries is the same regardless of whether the screen mode is 16 bpp or 32 bpp. Because a palette can be read at 1 clock/pixel in 16-bpp screen mode, the speed is higher in 32-bpp mode (2 clocks/pixel).
With Palettized-4bpp, the 1,024 entries are divided into 64 banks (1,024 entries/16 colors = 64 banks). With Palettized-8bpp, the 1,024 entries are divided into four banks (1,024 entries/256 colors = 4 banks). The banks are not separated physically, each bank being created by calculating pointers to the 1,024 entries.
The 4-bpp palette texture and 8-bpp palette texture can exist together in one scene, but the overlapping portion of the 1,024 entries is shared. Changing the contents of a palette, therefore, affects both the 4-bpp and 8-bpp textures. The bank of a palette can be specified in units of VERTEX (polygon). Specify a bank number by using the PaletteBank member of KMVERTEXCONTEXT. The entry that is actually used is selected as follows, depending on the palette bank number (PaletteBank) and index value of each pixel of the texture (index_data).

    if (PixelFormat == 8BPP)
    {
        palette_entry = (PaletteBank << 4) & 0x300 + index_data;
    }

    if (PixelFormat == 4BPP)
    {
        palette_entry = (PaletteBank << 4) + index_data;
    }

A value of 0 to 63 can be specified for PaletteBank in 4-bpp mode. Also, 0 to 63 can be specified in 8-bpp mode, but only four types of values, 0 (0 to 15), 16 (16 to 31), 32 (32 to 47), and 48 (48 to 63), can be used in this mode because only the higher two bits of the six are valid for a PaletteBank value.

Caution:

Palette data setting (kmSetPaletteData/kmSetPaletteBank/kmSetPaletteBankData) cannot precede palette mode setting (kmSetPaletteMode). If the palette mode type does not match the palette data type, invalid data will be set in the palette register.

Parameters:

pPaletteTable(input)
This parameter specifies a pointer to a palette setting array. The array is defined as follows:
KMPALETTEDATA PaletteTable;
Example: The following coding is for setting 16-bpp data in the first 256 entries of a palette.

    j = 0;
    for(i = 0; i < 512; i+=2) {
    	PaletteTable.dwPaletteData[j++]
    		= (KMDWORD)((pdata[i+1]*256) + pdata[i]);
    }
    kmSetPaletteData(&PaletteTable);

The number of elements constituting the palette data must be 1,024. If there are no 1,024 elements, KAMUI may not operate normally.

Return values:

Value | Explanation
--- | ---
KMSTATUS_SUCCESS | Success

kmSetPaletteData