Reference interního API
Tato sekce dokumentuje interní moduly, které propojují Python API a zkompilované C jádro. Nejsou součástí veřejného API — jde o implementační detaily, které se mohou měnit mezi verzemi.
Pouze pro interní použitíModuly zdokumentované zde (tuix.core._lib, tuix.core._structs, tuix.core._tuix_cy) jsou interní. Nespoléhejte na ně v aplikačním kódu. Místo toho používejte moduly veřejného API (engine, scenes, objects, buffers, input, builders, registry).
Čištění API ve v0.3Veřejné API pro raw buffer pointer gettery bylo odstraněno z doporučeného veřejného povrchu ve prospěch lock-safe snapshot API (snapshoty bufferů a objektů podle UID).
tuix.core._lib — C most
Modul _lib načte zkompilované Cython rozšíření (_tuix_cy) nebo se vrátí k načítání sdílené knihovny přes ctypes.CDLL. Poskytuje obalové funkce, které volají nativní C kód.
Proměnné modulu
| Proměnná | Typ | Popis |
|---|
| _mod | module | None | Načtený Cython modul (_tuix_cy), nebo None pokud není dostupný |
| lib | CDLL | None | Handle načtené sdílené C knihovny, nebo None |
Funkce
| Funkce | Popis |
|---|
| get_func(name, restype, argtypes) | Vyhledá nativní funkci podle jména v Cython modulu nebo CDLL. Vrací volatelnou funkci. |
| tuix_render_streaming(buf) | Vyrenderuje TuixFinalBuffer do terminálu pomocí streaming rendereru. |
| tuix_create_native_buffer(py_buf) | Vytvoří nativní buffer z Python buffer objektu. Vrací celočíselný handle. |
| tuix_free_native_buffer(handle) | Uvolní nativní buffer podle handle. |
| tuix_apply_patch_and_render(handle, patch) | Aplikuje binární patch na nativní buffer a vyrenderuje výsledek. Vrací ANSI byty. |
| make_patch_bytes(updates) | Převede seznam dvojic (index, sym, fg, bg) na 20bajtové binární patch záznamy. |
Každý patch záznam má 20 bytů:
| Posun | Velikost | Pole |
|---|
| 0 | 4 bytes | Index pixelu (little-endian uint32) |
| 4 | 8 bytes | UTF-8 symbol (vyplněný nulami) |
| 12 | 3 bytes | RGB popředí |
| 15 | 3 bytes | RGB pozadí |
| 18 | 1 byte | Příznaky (tučné, kurzíva, podtržení, ztlumení) |
| 19 | 1 byte | Rezervováno |
tuix.core._structs — mapování C struktur
Modul _structs definuje třídy Python ctypes.Structure, které zrcadlí C struktury použité v enginu.
TuixRGBTuple
| Pole | Typ | Popis |
|---|
| r | uint8 | Červený kanál (0–255) |
| g | uint8 | Zelený kanál (0–255) |
| b | uint8 | Modrý kanál (0–255) |
TuixPixelStyles
| Pole | Typ | Popis |
|---|
| fg | TuixRGBTuple | Barva popředí |
| bg | TuixRGBTuple | Barva pozadí |
| custom_bg | uint8 | Příznak vlastní barvy pozadí |
| custom_fg | uint8 | Příznak vlastní barvy popředí |
| bold | uint8 | Atribut tučného textu |
| underlined | uint8 | Atribut podtržení |
| italic | uint8 | Atribut kurzívy |
| dim | uint8 | Atribut ztlumení |
TuixPixel
| Pole | Typ | Popis |
|---|
| sym | char[8] | UTF-8 znak (až 8 bytů) |
| styles | TuixPixelStyles | Styly pixelu |
| q_fg | TuixRGBTuple | Kvantizované popředí (cache) |
| q_bg | TuixRGBTuple | Kvantizované pozadí (cache) |
| q_cached | uint8 | Zda je kvantizovaná cache platná |
TuixObject
| Pole | Typ | Popis |
|---|
| uid | int | Unikátní identifikátor objektu (automaticky) |
| builder | void* | Ukazatel na TuixBuilder, který vytvořil tento widget |
| state | void* | Ukazatel na opaque stav widgetu |
| width_mod | float | Šířka jako zlomek šířky terminálu |
| height_mod | float | Výška jako zlomek výšky terminálu |
| margin_top_mod | float | Horní okraj jako zlomek výšky terminálu |
| margin_left_mod | float | Levý okraj jako zlomek šířky terminálu |
TuixBuffer
| Pole | Typ | Popis |
|---|
| obj | TuixObject* | Ukazatel na rodičovský objekt |
| pixels | TuixPixel* | Ukazatel na pole pixelového bufferu |
| width | int | Aktuální vypočtená šířka ve sloupcích |
| height | int | Aktuální vypočtená výška v řádcích |
| required_redraw | int | Příznak dirty — 1 pokud buffer potřebuje rebuild |
| margin_left | int | Vypočtený levý okraj ve sloupcích |
| margin_top | int | Vypočtený horní okraj v řádcích |
TuixFinalBuffer
| Pole | Typ | Popis |
|---|
| pixels | TuixPixel* | Zkomponované pole pixelů (terminal_width × terminal_height) |
| width | int | Šířka ve sloupcích |
| height | int | Výška v řádcích |
| full_redraw | int | Vynutí znovu-renderování všech pixelů |
| Pole | Typ | Popis |
|---|
| term_x | int | Šířka terminálu v okamžiku snímku |
| term_y | int | Výška terminálu v okamžiku snímku |
| mouse | void* | Ukazatel na data události TuixMouseKey |
| keyboard | void* | Ukazatel na data události TuixKeyboardKey |
TuixRegistry
| Pole | Typ | Popis |
|---|
| scenes | void* | Ukazatel na kontejner TuixScenes |
| subcycles | void* | Ukazatel na kontejner TuixSubcycles |
| builders | void* | Ukazatel na kontejner TuixBuilders |
| current_scene_name | char* | Ukazatel na řetězec názvu aktivní scény |
| next_uid | int | Další UID k přiřazení (auto-increment) |
| terminal_width | int | Aktuální šířka terminálu |
| terminal_height | int | Aktuální výška terminálu |
| terminal_width_old | int | Šířka terminálu z předchozího snímku |
| terminal_height_old | int | Výška terminálu z předchozího snímku |
tuix.core._tuix_cy — Cython rozšíření
Modul _tuix_cy je Cython rozšíření, které obaluje všechna C volání. Je kompilovaný z _tuix_cy.pyx a linkovaný proti C zdrojovým souborům. Moduly Python API volají funkce _tuix_cy, pokud jsou dostupné, jinak použijí ctypes, pokud Cython modul není načtený.
Cython vrstva je tenký wrapper — převádí Python typy na C typy, volá nativní funkci a převádí výsledek zpět. Nepřidává žádnou dodatečnou logiku mimo marshaling typů.
Architektura C enginu
Zkompilované C jádro je organizováno do těchto subsystémů:
| Subsystém | Soubory | Účel |
|---|
| Hlavní smyčka | main.c, main.h | Řízení pipeline pro každý snímek |
| Inicializace/Ukončení | init.c, init.h | Nastavení a uvolnění registry |
| Renderování | rendering.c, rendering.h | Delta renderer s kvantizací barev |
| Kompozitor | compositor/ | Kompozice bufferu scén s ořezem |
| Geometrie | compositor/geometry_resolver.c | Výpočet proporcionálního rozložení |
| Správce bufferů | buffer_manager.c | Alokace, vyhledávání a uvolňování bufferů |
| Správce objektů | object_manager.c | Tvorba widgetů s dispatch builderu |
| Správce scén | buffers.c | CRUD scén a správa pole bufferů |
| Buildery | content_builder/ | Registrace typu widgetu a routování |
| Implementace widgetů | content_builder/builders/ | C kód pro Canvas, Choice, Input, Progressbar |
| Vstup | input/ | Zachyt klávesnice a myši specifický pro platformu |
| Subcykly | subcycles/ | Interní řídicí objekty pro vykonání handlerů v každém snímku |
| Dávkový executor | batch_executor.c | Parser binárního command bufferu (interní optimalizace) |
Volitelné C moduly
Zdrojová distribuce obsahuje moduly, které nejsou kompilované ve výchozím buildu. Pokročilí uživatelé je mohou zahrnout úpravou setup.py:
| Modul | Soubor | Popis |
|---|
| Halfblock renderer | rendering_halfblocks.c | 2x vertikální rozlišení pomocí Unicode halfblock znaků (▀). Spojí dva pixelové řádky do jednoho řádku terminálu. |
| Správce cache | cache_manager.c | Experimentální cache modul; produkční strategie v0.3 je data-first statistika scén a kompaktace studených scén. |