/*
 * meow_ui_zorder.h — SDK 绘制物注册表 / z 序 / 区域重画（§6.2，合并 SDK_Z_ORDER_DESIGN）。
 *
 * 原 meow_ui.h 拆分的一部分（zorder/draw 注册表）。非保留模型（§5.8.7）下，把「清底 + 按 z
 * 重画重叠区完整 z 栈」下沉到 SDK，让所有 App 自动获得正确的局部重画。全部 opt-in：
 * 不调用本节的既有 App（widget/activity/flush 均不动）行为完全不变。
 */
#ifndef MEOW_UI_ZORDER_H
#define MEOW_UI_ZORDER_H

#include "meow_ui_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================ */
/* §6.2 绘制物注册表 / z 序 / 区域重画（合并 SDK_Z_ORDER_DESIGN，源:2026-08-31）
 * ------------------------------------------------------------
 * 非保留模型（§5.8.7）下，把「清底 + 按 z 重画重叠区完整 z 栈」下沉到 SDK，让所有 App
 * 自动获得正确的局部重画（根治 P1：下层动态控件局部重绘会把重叠区上层 chrome 抹掉）。
 *   - 控件（meow_widget）创建即自动注册进绘制物注册表；rect 实时读 w->x/y/w/h；
 *   - App 直绘的非控件内容（meow_ui_text/fill_rect 等）须显式 meow_draw_custom_register
 *     注册（声明 bbox + 绘制回调），否则区域重画会漏画（非保留模型固有代价）；
 *   - z 自动推导（子>父、同层注册先序）；显式 meow_widget_set_z(999/MEOW_Z_TOP) 置顶（粘滞）。
 * 用法：meow_ui_invalidate(x,y,w,h) 局部重画（清底+按 z 升序重画所有相交绘制物+上屏），
 * 不整帧；meow_ui_paint_full() 整帧按 z 序重画。默认底=meow_theme bg（set_page_bg 覆盖）。
 * 兼容：新 API 全部 opt-in；不调用本节的既有 App（widget/activity/flush 均不动）行为完全不变。 */
/* ============================================================ */

/* 绘制物种类：控件（自动注册）/ App 直绘内容（显式注册）。 */
typedef enum { MEOW_ITEM_WIDGET = 0, MEOW_ITEM_CUSTOM = 1 } meow_draw_kind;
typedef void (*meow_draw_fn)(void *ctx);   /* CUSTOM 绘制回调（ctx 由 App 持有） */

/* ---- 层级常量（保证"子>父" + 值域远小于置顶值）---- */
#define MEOW_Z_STRIDE        16   /* 每层容器嵌套的 z 步进（子层至少 +16） */
#define MEOW_Z_DEPTH_MAX     7    /* 自动推导最大嵌套深度（0..6，>7 折叠） */
#define MEOW_Z_PER_LEVEL_MAX 15   /* 每层最多 16 槽（seq 0..15，超出折叠按注册序） */
#define MEOW_Z_AUTO_MAX      (MEOW_Z_STRIDE * MEOW_Z_DEPTH_MAX + MEOW_Z_PER_LEVEL_MAX) /* 127 */
#define MEOW_Z_TOP           1000 /* 惯例"置顶"值；≥(MEOW_Z_AUTO_MAX+1)=128 即超一切自动值 */

/* 控件显式置层：z 为任意非负整数（0..INT_MAX，无上限），越大越上；z>所有其它控件即恒在最上。
 * 惯例设 999（或 MEOW_Z_TOP）即"置顶"。显式 z 存于绘制注册表（按 w 反查 entry，不改
 * struct meow_widget——零 ABI 破坏）且**粘滞**：不被后续自动推导覆盖；clear_z 才回退。 */
void meow_widget_set_z(meow_widget *w, int z);
int  meow_widget_z(const meow_widget *w);    /* 当前生效 z（显式=其值，否则=自动推导） */
void meow_widget_clear_z(meow_widget *w);    /* 清除显式 z，回退自动推导 */

/* ---- 非控件直绘内容注册为绘制物（CUSTOM）----
 * App 声明 bbox + 绘制回调 + 显式 z（任意非负；999=置顶）；区域重画/整帧重画会画到它。
 * 返回 id（供 meow_draw_unregister / meow_draw_set_z）；注册表满返回 0。
 * 生命周期契约：App 持有 ctx；widget 类内容不必注册（自动）；离开页面前 unregister。 */
int  meow_draw_custom_register(int z, int x, int y, int w, int h,
                               meow_draw_fn cb, void *ctx);
void meow_draw_unregister(int id);           /* 注销（id 失效，勿再用） */
int  meow_draw_set_z(int id, int z);         /* 改 custom 显式 z；无效 id 返回 -1 */

/* 页面背景色（区域重画/整帧清底用）；默认 meow_theme bg。 */
void     meow_ui_set_page_bg(uint32_t color);
uint32_t meow_ui_page_bg(void);

/* 声明某区域内容已变化 → 清底(page_bg) + 按 z 升序重画所有相交绘制物 + 上屏。
 * 局部（只画相交绘制物，完整 bbox——见 SDK_Z_ORDER_DESIGN §5），不整帧、不冲状态栏。 */
void meow_ui_invalidate(int x, int y, int w, int h);

/* 整帧按 z 序重画全部（set_page_bg 清底 + 全注册表按 z 升序 + 上屏）。 */
void meow_ui_paint_full(void);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_ZORDER_H */