/*
 * meow_ui_image.h — SDK 图片层（§4，B1）。
 *
 * 原 meow_ui.h 拆分的一部分（image 模块）。内部 stb_image（单头文件，静态编入 meow_ui.a）
 * 解 PNG/JPEG/BMP，统一转 RGBA。meow_img 为不透明句柄（前向声明见 meow_ui_types.h）。
 */
#ifndef MEOW_UI_IMAGE_H
#define MEOW_UI_IMAGE_H

#include "meow_ui_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================ */
/* §4 图片层 */
/* ============================================================ */
typedef struct meow_img meow_img;   /* 句柄，由 meow_img_* 管理，不透明 */

meow_img *meow_img_load_file(const char *path);     /* 内部读文件 + stb 解码 */
meow_img *meow_img_load_mem(const void *buf, int len);
void       meow_img_free(meow_img *img);

/* 追加（M12）预算解码：只读文件头取原始尺寸，不解码像素（零像素内存）。成功 1，失败 0。
 * App 可用它在加载前判断「图太大」并给用户提示，而不必先撞 OOM。 */
int meow_img_probe_file(const char *path, int *w, int *h, int *channels);

/* 追加（M12）预算解码：解码期受长边约束，返回图最长边 ≤ maxdim。
 * JPEG：按 1/2、1/4、1/8 整数步长抽取解码（stbi_load_scaled），整幅原尺寸 RGBA 缓冲从不物化，
 *       峰值 ≈ 亮度分量平面 + 缩解输出 + 单行缓冲；随后用 meow_img_downscale 精修到 maxdim。
 * PNG/BMP 等 stb 无解码期缩放能力的格式：整幅解码后立即降采样（峰值同旧入口，见 M12 报告）。
 * 小图（长边 ≤ maxdim）走旧路径，与原 API 完全一致；maxdim<=0 等价旧入口。失败返回 NULL。 */
meow_img *meow_img_load_file_dim(const char *path, int maxdim);
meow_img *meow_img_load_mem_dim(const void *buf, int len, int maxdim);

int meow_img_w(const meow_img *img);
int meow_img_h(const meow_img *img);
/* 访问器：取 RGBA 像素指针（4 通道 straight alpha；供取色/直读像素）。meow_img 对外 opaque，
 * 本函数为其唯一像素读入口；NULL 返回 NULL。 */
const unsigned char *meow_img_pixels(const meow_img *img);

void meow_ui_img(int x, int y, meow_img *img);                                   /* 原始尺寸 */
/* 内存瘦身：最近邻等比缩放到最长边 ≤maxdim，返回新图；原图已 ≤maxdim 返回 NULL。
 * 调用方负责 free 旧图与返回值（若返回）。封面/背景大图驻留内存瘦身用。 */
meow_img *meow_img_downscale(meow_img *img, int maxdim);
void meow_ui_img_scaled(int x, int y, int w, int h, meow_img *img);              /* 最近邻缩放 */
void meow_ui_img_alpha(int x, int y, int w, int h, meow_img *img, int alpha);
void meow_ui_img_cover(int x, int y, int size, meow_img *img);                   /* 居中裁方 → size×size */

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_IMAGE_H */