Image palettes

Functions
OSL_PALETTE *	oslCreatePaletteEx (int size, int location, short pixelFormat)
static OSL_PALETTE *	oslCreatePalette (int size, short pixelFormat)
OSL_PALETTE *	oslCreatePaletteFrom (void *data, int size, short pixelFormat)
void	oslDeletePalette (OSL_PALETTE *p)
int	oslGetPaletteColor (OSL_PALETTE *p, int index)
void	oslUncachePalette (OSL_PALETTE *pal)

Detailed Description

Palette for 4 and 8-bit images.

Function Documentation

oslCreatePaletteEx()

OSL_PALETTE * oslCreatePaletteEx ( int  size, int  location, short  pixelFormat  )

extern

Creates a new (empty) palette with the specified pixel format.

This function creates a new palette that can be used with 4-bit or 8-bit images. The palette is allocated in the specified location and uses the provided pixel format. For most cases, the pixel format should be OSL_PF_8888 as palettes are generally small in size.

Parameters

size	The number of colors in the palette. For example, a 4-bit image palette will have 16 colors (2^4), and an 8-bit image palette will have 256 colors (2^8).
location	The memory location where the palette will be stored. Use OSL_IN_RAM to allocate the palette in RAM.
pixelFormat	The pixel format of each palette entry. Typically, this should be OSL_PF_8888 to match the common palette size.

Note:

• After creating and filling the palette, it is essential to uncache it to ensure that changes are applied correctly.
• If you need to uncache both the image and its palette, you can use oslUncacheImage(img) which will also uncache the palette.

Example:

OSL_IMAGE *img = oslCreateImage(32, 32, OSL_IN_RAM, OSL_PF_4BIT);
// Determine the palette size based on the image's pixel format.
int palSize = 1 << osl_paletteSizes[img->pixelFormat];
// Create the palette with the required size.
img->palette = oslCreatePaletteEx(palSize, OSL_IN_RAM, OSL_PF_8888);
// Get a pointer to the palette data.
u32 *paletteData = (u32*)img->palette->data;
// Set all entries to bright opaque red.
for (int i = 0; i < img->palette->nElements; i++)
        paletteData[i] = RGBA(255, 0, 0, 255);
// Uncache the palette after finishing.
oslUncachePalette(img->palette);
// Alternatively, uncache the image which also uncaches the palette.
// oslUncacheImage(img);

oslCreatePalette()

static OSL_PALETTE * oslCreatePalette ( int  size, short  pixelFormat  )

inlinestatic

Creates a new palette with the specified pixel format.

This is a simpler function for creating a new palette. It allocates the palette in RAM and uses the provided pixel format. This function is a wrapper around oslCreatePaletteEx with the location parameter set to OSL_IN_RAM.

Parameters

size	The number of colors in the palette (e.g., 16 for 4-bit images, 256 for 8-bit images).
pixelFormat	The pixel format of each palette entry, typically OSL_PF_8888.

Returns

A pointer to the newly created palette.

Example:

OSL_PALETTE *palette = oslCreatePalette(16, OSL_PF_8888);

oslCreatePaletteFrom()

OSL_PALETTE * oslCreatePaletteFrom ( void *  data, int  size, short  pixelFormat  )

extern

Creates a palette from existing data.

This function creates a palette using data that already exists. The data is not copied; it is used directly. You need to specify the size of the palette and the pixel format of the data.

Parameters

data	Pointer to the existing palette data.
size	The number of colors in the palette.
pixelFormat	The pixel format of each palette entry.

Returns

A pointer to the newly created palette.

Note:

• The data is not copied; it is used as is. Ensure that the data remains valid for the lifetime of the palette.
• Only the OSL_PALETTE structure is freed when the palette is deleted; the data is not affected.

Example:

void *existingData = existing palette data;
OSL_PALETTE *palette = oslCreatePaletteFrom(existingData, 256, OSL_PF_8888);

oslDeletePalette()

void oslDeletePalette ( OSL_PALETTE *  p )

extern

Deletes an existing palette.

This function frees the memory used by an OSL_PALETTE structure. If the palette was created using oslCreatePaletteFrom, the data used to create the palette is not freed.

Parameters

p	Pointer to the palette to be deleted.

Example:

oslDeletePalette(palette);

oslGetPaletteColor()

int oslGetPaletteColor ( OSL_PALETTE *  p, int  index  )

extern

Returns a color entry from a palette.

This function retrieves a color from the palette at a specified index. The color value is in the same pixel format as the palette.

Parameters

p	Pointer to the palette.
index	The index of the color entry to retrieve.

Returns

The color value at the specified index.

Example:

int color = oslGetPaletteColor(palette, 0);

oslUncachePalette()

void oslUncachePalette ( OSL_PALETTE *  pal )

extern

Uncaches a palette.

After accessing palette data in a cached way (e.g., through pal->data), you must uncache the palette to ensure changes are applied correctly.

Parameters

pal	Pointer to the palette to uncache.

Example:

oslUncachePalette(palette);