feat(text): add styled layout query support

docs/material_clip.lua

@@ -0,0 +1,27 @@
+---@meta soluna.material.clip
+
+---clip material 模块。
+---Clip material module.
+---
+---`rect(width, height)` 打开一个矩形裁剪范围，`rect()` 关闭最近一次打开的裁剪范围。
+---裁剪矩形位于屏幕空间，是轴对齐矩形；它不是 layer-local clip，也不为旋转 layer
+---提供精确裁剪。
+---
+---`rect(width, height)` opens a rectangular clipping region, and `rect()`
+---closes the latest opened clipping region. The clipping rectangle is
+---screen-space and axis-aligned. It is not a layer-local clip and does not
+---provide exact clipping for rotated layers.
+---@class soluna.material.clip
+local matclip = {}
+
+---打开或关闭矩形裁剪范围。
+---Opens or closes a rectangular clipping region.
+---@overload fun(): string
+---@overload fun(width: number, height: number): string
+---@param width number 逻辑像素宽度 / Width in logical pixels.
+---@param height number 逻辑像素高度 / Height in logical pixels.
+---@return string stream 打包后的 clip 命令流 / Packed clip command stream.
+function matclip.rect(width, height)
+end
+
+return matclip

docs/material_text.lua

@@ -1,27 +1,133 @@
 ---@meta soluna.material.text
 
----文本块创建函数
+---text style 配置。
+---Text style configuration.
+---@class soluna.material.text.Style
+---@field font integer `font.name()` 返回的字体 id / Font id returned by `font.name()`
+---@field size? integer 字体像素大小，默认 24 / Font pixel size, default 24
+---@field color? integer ARGB 颜色，默认 `0xff000000` / ARGB color, default `0xff000000`
+---@field line_height? integer 行高；小于字体自然高度时使用自然高度 / Line height; clamped to the natural font height
+
+---text style set。
+---Text style set.
+---@class soluna.material.text.Styles: userdata
+
+---文本行信息。
+---Text line information.
+---
+---`start` 和 `finish` 是 0-based visible position，`finish` 为 exclusive。
+---`start` and `finish` are 0-based visible positions. `finish` is exclusive.
+---@class soluna.material.text.Line
+---@field start integer 行起始 visible position / First visible position on the line
+---@field finish integer 行结束 visible position，exclusive / End visible position, exclusive
+---@field x integer 行矩形 X / Line rectangle X
+---@field y integer 行矩形 Y / Line rectangle Y
+---@field width integer 行矩形宽度 / Line rectangle width
+---@field height integer 行矩形高度 / Line rectangle height
+
+---文本布局查询对象。
+---Text layout query object.
+---@class soluna.material.text.Layout
+local Layout = {}
+
+---返回文本实际高度。
+---Returns text content height.
+---@return integer height 文本实际高度 / Text content height
+function Layout:height()
+end
+
+---返回最大行高。
+---Returns maximum line height.
+---@return integer height 最大行高 / Maximum line height
+function Layout:line_height()
+end
+
+---返回行数。
+---Returns line count.
+---@return integer count 行数 / Line count
+function Layout:line_count()
+end
+
+---返回 cursor position 数量。
+---Returns cursor position count.
+---@return integer count cursor position 数量 / Cursor position count
+function Layout:cursor_count()
+end
+
+---返回 1-based 行信息。
+---Returns 1-based line information.
+---@param index integer 1-based 行号 / 1-based line index
+---@return soluna.material.text.Line? line 行信息 / Line information
+function Layout:line(index)
+end
+
+---查询 cursor 矩形。
+---Queries cursor rectangle.
+---@param position integer 0-based cursor position / 0-based cursor position
+---@return integer x cursor X / Cursor X
+---@return integer y cursor Y / Cursor Y
+---@return integer width cursor 宽度 / Cursor width
+---@return integer height cursor 高度 / Cursor height
+---@return integer position clamp 后的 cursor position / Clamped cursor position
+---@return integer decent 字体 descent / Font descent
+function Layout:cursor(position)
+end
+
+---命中测试，返回 0-based cursor position。
+---Hit-tests and returns a 0-based cursor position.
+---@param x number 本地 X / Local X
+---@param y number 本地 Y / Local Y
+---@return integer position cursor position / Cursor position
+---@return boolean out_of_box 是否在布局盒外 / Whether the point is outside the layout box
+function Layout:hit_test(x, y)
+end
+
+---返回 visible position 使用的 0-based style id。
+---Returns the 0-based style id at a visible position.
+---@param position integer 0-based visible position / 0-based visible position
+---@return integer? style style id；无效 position 返回 nil / Style id; nil for invalid position
+function Layout:style(position)
+end
+
+---文本块创建函数。
 ---Text block builder function.
 ---@alias soluna.material.text.Block fun(text: string, width?: integer, height?: integer): string, integer
 
----光标位置查询函数
----Text cursor query function.
----@alias soluna.material.text.Cursor fun(text: string, position: integer, width?: integer, height?: integer): integer, integer, integer, integer, integer, integer
+---文本布局创建函数。
+---Text layout builder function.
+---@alias soluna.material.text.LayoutBuilder fun(text: string, width?: integer, height?: integer): soluna.material.text.Layout
 
----text material 模块
+---text material 模块。
 ---Text material module.
+---
+---Tagged text stream 支持 `[i42]` icon、`[hex]` 临时颜色、`[sN]` style 切换、
+---`[s]` 回到 style 0，以及 `[[` 输出字面量 `[`。`[sN]` 中的 `N` 是
+---0-based style id，Lua style 数组第一项对应 style 0。
+---
+---Tagged text streams support `[i42]` icons, `[hex]` temporary colors, `[sN]`
+---style switching, `[s]` reset to style 0, and `[[` for a literal `[`.
+---`N` in `[sN]` is a 0-based style id. The first Lua style entry is style 0.
 ---@class soluna.material.text
 local mattext = {}
 
----创建文本块和光标查询函数
----Creates text block and cursor query functions.
+---创建 style set。
+---Creates a style set.
+---@param fontcobj lightuserdata `font.cobj()` 返回的字体管理器指针 / Font manager pointer returned by `font.cobj()`
+---@param styles soluna.material.text.Style[] style 数组，第一项是 style 0 / Style array; first entry is style 0
+---@return soluna.material.text.Styles styles style set / Style set
+function mattext.styles(fontcobj, styles)
+end
+
+---创建文本块和布局查询函数。
+---Creates text block and layout query functions.
+---@overload fun(styles: soluna.material.text.Styles, alignment?: string): soluna.material.text.Block, soluna.material.text.LayoutBuilder
 ---@param fontcobj lightuserdata `font.cobj()` 返回的字体管理器指针 / Font manager pointer returned by `font.cobj()`
 ---@param fontid integer `font.name()` 返回的字体 id / Font id returned by `font.name()`
----@param size? integer 字体像素大小，默认 16 / Font pixel size, default 16
+---@param size? integer 字体像素大小，默认 24 / Font pixel size, default 24
 ---@param color? integer ARGB 颜色，默认 `0xff000000` / ARGB color, default `0xff000000`
 ---@param alignment? string 对齐代码，如 `"LT"`、`"CV"`、`"RB"` / Alignment code such as `"LT"`, `"CV"`, `"RB"`
 ---@return soluna.material.text.Block block 创建 packed text stream / Creates packed text stream
----@return soluna.material.text.Cursor cursor 查询光标矩形 / Queries cursor rectangle
+---@return soluna.material.text.LayoutBuilder layout 创建布局查询对象 / Creates layout query object
 function mattext.block(fontcobj, fontid, size, color, alignment)
 end
 

src/embedlua.c

@@ -26,6 +26,7 @@
 #include "mattext.lua.h"
 #include "matquad.lua.h"
 #include "matmask.lua.h"
+#include "matclip.lua.h"
 
 #include "lua.h"
 #include "lauxlib.h"
@@ -102,6 +103,7 @@ luaopen_embedsource(lua_State *L) {
 			REG_MATERIAL(mattext)
 			REG_MATERIAL(matquad)
 			REG_MATERIAL(matmask)
+			REG_MATERIAL(matclip)
 		lua_setfield(L, -2, "material");
 
 		lua_newtable(L);	// data list

src/luamods.c

@@ -21,6 +21,7 @@ int luaopen_material_default(lua_State *L);
 int luaopen_material_text(lua_State *L);
 int luaopen_material_quad(lua_State *L);
 int luaopen_material_mask(lua_State *L);
+int luaopen_material_clip(lua_State *L);
 int luaopen_material_blit(lua_State *L);
 int luaopen_material_external(lua_State *L);
 int luaopen_soluna_app(lua_State *L);
@@ -53,6 +54,7 @@ void soluna_embed(lua_State* L) {
 		{ "soluna.material.text", luaopen_material_text },
 		{ "soluna.material.quad", luaopen_material_quad },
 		{ "soluna.material.mask", luaopen_material_mask },
+		{ "soluna.material.clip", luaopen_material_clip },
 		{ "soluna.material.blit", luaopen_material_blit },
 		{ "soluna.material.ext", luaopen_material_external },
 		{ "soluna.datalist", luaopen_datalist },

src/luayoga.c

@@ -12,6 +12,7 @@
 #define Wrap 8
 #define Display 16
 #define PositionType 32
+#define Overflow 64
 
 #define ENUM(x, what) { YG##x##ToString(YG##x##what), (x) << 16 | (YG##x##what) },
 
@@ -512,6 +513,11 @@ lsetPosition(lua_State *L, YGNodeRef node) {
 	YGNodeStyleSetPositionType(node, getEnum(L, PositionType, "position"));
 }
 
+static void
+lsetOverflow(lua_State *L, YGNodeRef node) {
+	YGNodeStyleSetOverflow(node, getEnum(L, Overflow, "overflow"));
+}
+
 static void
 setPosition(lua_State *L, YGNodeRef node, YGEdge edge) {
 	static const struct set_edge_number setter = {
@@ -636,6 +642,7 @@ luaopen_layout_yoga(lua_State *L) {
 		{ "display", lsetDisplay },
 		{ "flex", lsetFlex },
 		{ "position", lsetPosition },
+		{ "overflow", lsetOverflow },
 		{ "top", lsetTop },
 		{ "bottom", lsetBottom },
 		{ "left", lsetLeft },
@@ -678,6 +685,9 @@ luaopen_layout_yoga(lua_State *L) {
 		ENUM(PositionType, Static)
 		ENUM(PositionType, Relative)
 		ENUM(PositionType, Absolute)
+		ENUM(Overflow, Visible)
+		ENUM(Overflow, Hidden)
+		ENUM(Overflow, Scroll)
 	};
 	n = sizeof(estr) / sizeof(estr[0]);
 	lua_createtable(L, n, 0);

src/material/matclip.lua

@@ -0,0 +1,25 @@
+local clipmat = require "soluna.material.clip"
+
+local ctx = ...
+local state = ctx.state
+clipmat.set_material_id(ctx.id)
+
+state.material_clip = clipmat.new {
+	uniform = state.uniform,
+}
+
+local material = {}
+
+function material.reset()
+	state.material_clip:reset()
+end
+
+function material.submit(ptr, n)
+	state.material_clip:submit(ptr, n)
+end
+
+function material.draw(ptr, n)
+	state.material_clip:draw(ptr, n)
+end
+
+return material