/*
 * meow_img_color.h — MeowOS SDK 封面双色渐变取色（批5）。
 *
 * 定位：从歌曲封面（已解码 RGBA 像素/meow_img 句柄）提取「主色 + 次色」，供播放页/歌词页动态主题
 * （背景渐变/文字 accent）。纯 C 分桶统计，无 GPU、无浮点、无堆分配。
 *
 * 组织：独立公共头（仿 meow_lyric_view.h 模式，不随 meow_ui.h 伞头发布），取色原语是独立源码
 * meow_img_color.c——**不并入 meow_ui.a**（铁律：避免并发重编/四 App 重链）。App/launcher 需显式
 * `#include "meow_img_color.h"` 并在构建时单链 meow_img_color.c（宿主单测同法）。
 *
 * 约束（0 warning / 最小侵入）：
 *   - meow_img 对外保持 opaque；像素直读经 SDK 正式访问器 `meow_img_pixels`（meow_ui_img.c §4，
 *     已上收「局部补全结构体」遗留），宽高经 `meow_img_w`/`meow_img_h`。本 TU 不再局部补全布局。
 *   - 取色算法纯函数：meow_img_duocolor_rgba / meow_img_color_derive 纯 C、无 meow_* 依赖；
 *     meow_img_duocolor（句柄版）仅经上述三访问器读，不触碰 meow_ui.a 内部实现。宿主单测链
 *     meow_img_color.c + meow_ui_img.c 即可。
 *
 * 色彩语义：
 *   - 输入 RGBA（stb_image 输出，4 通道 straight alpha），w×h，最多遍历 ~3.6k 采样（内部自适
 *     副采样步进，等效缩略图成本，避免全尺寸逐像素）。
 *   - 色域分桶 4×4×4=64（RGB 各 4 段），跳过近黑（luma<24）/近白（luma>244）/透明（alpha<64），
 *     按「像素数 + 饱和度」加权；主色=加权最大桶中心；次色=与主色色距最大的显著桶（≥主桶 14%）
 *     中心；无显著桶→次色=主色缩暗 2/3（渐变互补）。
 *   - 返回 0=成功；-1=参数非法 / 有效采样不足（调用方回退全局 meow_theme）。
 */
#ifndef MEOW_IMG_COLOR_H
#define MEOW_IMG_COLOR_H

#include "meow_ui.h"          /* meow_img 句柄 + meow_theme */
#include "meow_lyric_view.h"  /* meow_lyric_view_colors（派生歌词页覆盖） */

#ifdef __cplusplus
extern "C" {
#endif

/* 从 RGBA 像素缓冲取主色+次色（纯算法；样本副采样）。返回 0=成功；-1=失败。 */
int meow_img_duocolor_rgba(const uint8_t *rgba, int w, int h,
                           uint32_t *main, uint32_t *second);

/* 从 meow_img 句柄取主色+次色（经 meow_img_pixels 读像素，见 .c）。返回 0=成功；-1=失败。 */
int meow_img_duocolor(const meow_img *im, uint32_t *main, uint32_t *second);

/* 由主/次色派生播放页 + 歌词页封面主题（纯函数，可宿主单测）。
 * th 用于默认回退色（main/second 为 0 时）；调用方应传 meow_theme_get()。
 * 派生语义：
 *   - 背景渐变 = 主色（顶）→ 次色（底）各压暗 55%（防刺眼 + 保文字可读）；
 *   - fg = 可读文字色（按主次平均亮度选黑/白），fg_dim = 向背景靠拢的次要文字色；
 *   - accent = 次色（与主色底对比），accent_fg = accent 上可读图标色；
 *   - lyr = 歌词页 set_colors 覆盖：scrim=主色压暗(alpha 176)、cur=fg，gray 留 0（由 lyric_view
 *     以「cur 为基准自动递减」——批5 已修正对覆盖 cur 亦然）。 */
typedef struct meow_img_color_theme {
    uint32_t bg_top;        /* 播放页渐变顶 */
    uint32_t bg_bottom;     /* 播放页渐变底 */
    uint32_t fg;            /* 主要文字色（背景上可读） */
    uint32_t fg_dim;        /* 次要文字色 */
    uint32_t accent;        /* 强调色（控件/进度/封面占位） */
    uint32_t accent_fg;     /* accent 上可读前景（图标） */
    meow_lyric_view_colors lyr;   /* 歌词页 set_colors 覆盖 */
} meow_img_color_theme;

void meow_img_color_derive(uint32_t main, uint32_t second, const meow_theme *th,
                           meow_img_color_theme *out);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_IMG_COLOR_H */