// Part of JoeyLib, Copyright (c) 2026 Scott Duensing, under the MIT License.
// See LICENSE.md for license information.
// SPDX-License-Identifier: MIT
//
// Palette and SCB (scanline control byte) accessors.
//
// Colors are 12-bit $0RGB (bits 11..8 red, 7..4 green, 3..0 blue).
// The library forces color 0 of every palette to black; jlPaletteSet
// silently masks that entry to $000 regardless of what the caller
// passed, and jlSurfaceLoadFile does the same. Palette and SCB changes
// to the stage reach the display at the next jlStagePresent. See the
// manual's "Palette and Scanline Control" (docs/ApiPalette.adoc).

#ifndef JOEYLIB_PALETTE_H
#define JOEYLIB_PALETTE_H

#include "platform.h"
#include "surface.h"
#include "types.h"

// Load all 16 colors of a palette. colors16 must point to exactly 16
// uint16_t values in $0RGB format.
void jlPaletteSet(jlSurfaceT *s, uint8_t paletteIndex, const uint16_t *colors16);

// Read all 16 colors of a palette into out16: the values set (color 0
// forced to $000, bits 12-15 as passed), not what the display shows of
// them. A paletteIndex above 15 is ignored by both calls.
void jlPaletteGet(const jlSurfaceT *s, uint8_t paletteIndex, uint16_t *out16);

// Assign a single palette index (0..15) to a single scanline (0..199).
void jlScbSet(jlSurfaceT *s, uint16_t line, uint8_t paletteIndex);

// Assign a palette index to an inclusive range of scanlines.
void jlScbSetRange(jlSurfaceT *s, uint16_t firstLine, uint16_t lastLine, uint8_t paletteIndex);

// Read the palette index assigned to a scanline.
uint8_t jlScbGet(const jlSurfaceT *s, uint16_t line);

#endif