OldSchool Library
Image palettes

Functions

OSL_PALETTEoslCreatePaletteEx (int size, int location, short pixelFormat)
 
OSL_PALETTEoslCreatePaletteFrom (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.

@param 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).
@param location
    The memory location where the palette will be stored. Use `OSL_IN_RAM` to allocate the palette in RAM.
@param pixelFormat
    The pixel format of each palette entry. Typically, this should be `OSL_PF_8888` to match the common palette size.

\b 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.

\b Example:
\code
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);
\endcode

◆ 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.

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

@return
    A pointer to the newly created palette.

\b 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.

\b Example:
\code
void *existingData = existing palette data;
OSL_PALETTE *palette = oslCreatePaletteFrom(existingData, 256, OSL_PF_8888);
\endcode

◆ 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.

@param p
    Pointer to the palette to be deleted.

\b Example:
\code
oslDeletePalette(palette);
\endcode

◆ 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.

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

@return
    The color value at the specified index.

\b Example:
\code
int color = oslGetPaletteColor(palette, 0);
\endcode

◆ 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.

@param pal
    Pointer to the palette to uncache.

\b Example:
\code
oslUncachePalette(palette);
\endcode