Документация по текстурным программам

docs/texture_pipeline.md

@@ -0,0 +1,105 @@
+# Текстурные программы (TexturePipelineProgram)
+
+Текстурная программа — это строка, описывающая источник текстуры и цепочку операций
+над ней. Такие строки используются в `textures` моделей и компилируются
+`TexturePipelineProgram`.
+
+## Общая форма
+```
+[tex] <base> [|> op(...)]*
+```
+`tex` в начале необязателен.
+
+## Базовые выражения
+- `name` или `"name.png"` — ссылка на текстуру из assets. Расширение .png/.jpg/.jpeg допустимо.
+- `anim(...)` — анимация из спрайт-листа (см. ниже).
+- `<w>x<h> <#RRGGBB|#RRGGBBAA>` — заливка цветом.
+
+Примеры:
+```
+stone
+tex "core:stone.png"
+32x32 "#FF00FF"
+```
+
+## Аргументы операций
+- Позиционные: `op(1, 2, "str")`
+- Именованные: `op(w=16, h=16)`
+- Значения: числа (uint32), строки в кавычках, либо идентификаторы.
+
+Цвета задаются `#RRGGBB` или `#RRGGBBAA`.
+
+## Операции пайплайна
+
+Операции без аргументов можно писать без `()`: `brighten` и т.п.
+В подвыражениях текстур (см. ниже) операции без аргументов нужно писать со скобками:
+`brighten()`.
+
+### Операции, принимающие текстуру
+- `overlay(tex)` — наложение с альфой.
+- `mask(tex)` — применение альфа-маски.
+- `lowpart(percent, tex)` — смешивание нижней части (percent 1..100).
+
+`tex` может быть:
+- именем текстуры: `overlay("core:stone")`
+- именованным аргументом: `overlay(tex="core:stone")`
+- вложенной программой: `overlay( tex stone |> invert("rgb") )`
+
+### Геометрия и альфа
+- `resize(w, h)` — ресайз до размеров.
+- `transform(t)` — трансформация (значение 0..7).
+- `opacity(a)` — прозрачность 0..255.
+- `remove_alpha` или `noalpha` — убрать альфа-канал.
+- `make_alpha(color)` — сделать альфу по цвету (цвет в `#RRGGBB`).
+
+### Цвет и яркость
+- `invert(channels="rgb")` — инверсия каналов (`r`, `g`, `b`, `a`).
+- `brighten()` — лёгкое осветление.
+- `contrast(value, brightness)` — контраст и яркость (-127..127).
+- `multiply(color)` — умножение на цвет.
+- `screen(color)` — экранный режим.
+- `colorize(color, ratio=255)` — тонирование цветом.
+
+### Анимация
+`anim` можно использовать в базе (с указанием текстуры) или в пайплайне
+над текущим изображением.
+
+База:
+```
+anim(tex, frame_w, frame_h, frames, fps, smooth, axis)
+```
+
+Пайплайн:
+```
+... |> anim(frame_w, frame_h, frames, fps, smooth, axis)
+```
+
+Именованные аргументы:
+- `tex` — имя текстуры (только для базового `anim`).
+- `frame_w` или `w`
+- `frame_h` или `h`
+- `frames` или `count`
+- `fps`
+- `smooth` (0/1)
+- `axis` — режим нарезки:
+  - `g` или пусто: по сетке (слева направо, сверху вниз)
+  - `x`/`h`: по горизонтали
+  - `y`/`v`: по вертикали
+
+Если `frames` не задан, количество кадров вычисляется автоматически:
+- сетка: `(sheet.W / frame_w) * (sheet.H / frame_h)`
+- ось X/Y: `sheet.W / frame_w` или `sheet.H / frame_h`
+
+Примеры:
+```
+anim("core:sheet", 16, 16, fps=8)         # сетка по умолчанию
+anim("core:sheet", 16, 16, axis="x")      # по горизонтали
+stone |> anim(16, 16, fps=10, smooth=1)   # анимировать текущую текстуру
+```
+
+## Вложенные текстурные выражения
+Некоторые операции принимают текстуру в аргументах. Чтобы передать не только имя,
+но и полноценную программу, используйте префикс `tex`:
+```
+overlay( tex "core:stone" |> resize(16,16) |> brighten() )
+```