reugenio/zcatgui
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
zcatgui/docs/research/DVUI_AUDIT_2025-12-17.md
reugenio 399afc1149 docs: Auditoría DVUI y plan paridad visual 
Nueva documentación:
- docs/research/DVUI_AUDIT_2025-12-17.md (570 líneas)
  - Análisis completo de DVUI vs zcatgui
  - Gap analysis: visual, no funcional
  - Plan de implementación en 3 fases
  - Técnica edge-fade para AA explicada

CLAUDE.md actualizado:
- Nueva tarea pendiente: Paridad Visual con DVUI
- Fases de implementación documentadas
- Estimación ~1,400 LOC
- Sistema dual propuesto (simple/fancy)

Hallazgo: zcatgui tiene MÁS widgets (~45 vs ~42)
El gap es VISUAL (esquinas, AA, transiciones)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-16 13:34:40 +01:00

504 lines
15 KiB
Markdown
Raw Blame History

# Auditoría Completa: DVUI vs zcatgui
> **Fecha**: 2025-12-17
> **Objetivo**: Identificar TODAS las características de DVUI que faltan en zcatgui
> **Versiones**: DVUI main (Dec 2025) | zcatgui v0.16.2
---
## 1. RESUMEN EJECUTIVO
### Estado Actual
| Aspecto | zcatgui | DVUI | Gap |
|---------|---------|------|-----|
| **Widgets** | ~45 | ~42 | ✅ Paridad |
| **Rendering Visual** | Básico | Avanzado | ❌ CRÍTICO |
| **Anti-aliasing** | Supersampling TTF | Edge-fade triangles | ⚠️ Diferente |
| **Esquinas redondeadas** | ❌ No | ✅ Sí | ❌ FALTA |
| **Sombras** | ✅ API existe | ✅ Box shadow | ⚠️ No usado |
| **Backends** | 4 (SDL2,WASM,Android,iOS) | 6 (SDL2/3,Raylib,DX11,Web) | ✅ OK |
| **Themes** | 5 | 6 | ✅ OK |
### Conclusión Principal
**El gap NO está en cantidad de widgets, sino en CALIDAD VISUAL del rendering.**
DVUI se ve mejor porque:
1. Usa **triangulación con anti-aliasing en bordes** (fade to transparent)
2. Tiene **esquinas redondeadas nativas** en todos los widgets
3. Aplica **ninepatch** para efectos visuales complejos
4. **Estados visuales pulidos** (hover, press, focus)
---
## 2. ANÁLISIS DEL SISTEMA DE RENDERING DE DVUI
### 2.1 Arquitectura de Rendering
DVUI usa un enfoque de **triangulación con vértices**:
```
Widget → Path (arcs, lines) → Triangles → GPU/CPU render
```
**Características clave:**
- Todos los elementos se convierten en triángulos
- Anti-aliasing via **2 vértices por borde**: inner (opaco) + outer (transparente)
- Tamaño de AA fijo: 1 pixel
- Soporte para GPU (DirectX, SDL3GPU) y CPU fallback
### 2.2 Path Drawing
```zig
// DVUI: Esquinas redondeadas con arcos
pub fn addRect(corner_radii) {
// 4 arcos (uno por esquina)
// 4 líneas conectando arcos
// Triangulación automática
}
// Error de discretización configurable
theta = acos(radius / (radius + 0.5)); // 0.5px error máximo
```
### 2.3 Anti-Aliasing
**DVUI usa "edge fade":**
- Cada borde tiene 2 vértices paralelos
- Vértice interno: color sólido (alpha = 1.0)
- Vértice externo: transparente (alpha = 0.0)
- Interpolación lineal entre ambos crea suavizado
**Ventajas:**
- Funciona con GPU (hardware interpolation)
- Funciona con CPU (software interpolation)
- No requiere multisampling
### 2.4 Fill Modes
1. **Convex Fill**: Para polígonos convexos simples
- Triangulación desde centro
- Opcional: fade en bordes
2. **Stroke Fill**: Para líneas y bordes
- Extrusión de geometría
- Miter joints con límite de ángulo
- AA fringe de 1px
---
## 3. INVENTARIO COMPLETO DE WIDGETS
### 3.1 DVUI Widgets (42 archivos)
| Categoría | Widgets |
|-----------|---------|
| **Layout** | BoxWidget, FlexBoxWidget, GridWidget, PanedWidget, ScrollContainerWidget, OverlayWidget |
| **Input** | TextEntryWidget, ButtonWidget, DropdownWidget, ColorPickerWidget, ScaleWidget |
| **Display** | LabelWidget, IconWidget, PlotWidget, TextLayoutWidget |
| **Navigation** | MenuWidget, MenuItemWidget, TabsWidget, TreeWidget |
| **Floating** | FloatingWidget, FloatingWindowWidget, FloatingMenuWidget, FloatingTooltipWidget |
| **Utility** | AnimateWidget, CacheWidget, ContextWidget, FocusGroupWidget, ReorderWidget, ScrollAreaWidget, ScrollBarWidget, SuggestionWidget, VirtualParentWidget |
### 3.2 zcatgui Widgets (~45 archivos)
| Categoría | Widgets |
|-----------|---------|
| **Básicos** | label, button, checkbox, radio, slider, text_input, numberentry |
| **Layout** | panel, split, modal, scroll, tabs, menu, grid |
| **Datos** | list, table, tree, reorderable, virtual_scroll |
| **Feedback** | progress, tooltip, toast, loader |
| **Input Avanzado** | autocomplete, select, textarea, colorpicker, datepicker |
| **Especial** | image, icon, canvas, chart, richtext, breadcrumb, badge |
| **Navegación** | appbar, navdrawer, sheet, divider, discloser |
| **Extra** | switch, surface, resize, selectable, iconbutton, focus |
### 3.3 Comparación Widget por Widget
| Widget | zcatgui | DVUI | Notas |
|--------|:-------:|:----:|-------|
| Button | ✅ | ✅ | DVUI: esquinas redondeadas |
| Label | ✅ | ✅ | Similar |
| TextInput | ✅ | ✅ | DVUI: mejor touch |
| Checkbox | ✅ | ✅ | DVUI: animación |
| Radio | ✅ | ✅ | Similar |
| Slider | ✅ ScaleWidget | ✅ | Similar |
| Select/Dropdown | ✅ | ✅ | Similar |
| Panel/Box | ✅ | ✅ | Similar |
| Split/Paned | ✅ | ✅ | Similar |
| Tabs | ✅ | ✅ | Similar |
| ScrollArea | ✅ | ✅ | DVUI: smooth scroll |
| Modal | ✅ | ❌ FloatingWindow | Diferentes |
| Grid | ✅ | ✅ | Similar |
| Menu | ✅ | ✅ | Similar |
| Tree | ✅ | ✅ | Similar |
| Tooltip | ✅ | ✅ | Similar |
| Toast | ✅ | ❌ | zcatgui único |
| Progress | ✅ | ❌ | zcatgui único |
| ColorPicker | ✅ | ✅ | Similar |
| DatePicker | ✅ | ❌ | zcatgui único |
| Image | ✅ | ✅ | DVUI: stb_image |
| Icon | ✅ | ✅ TinyVG | DVUI: vectorial |
| Chart/Plot | ✅ | ✅ | Similar |
| Canvas | ✅ | ❌ | zcatgui único |
| VirtualScroll | ✅ | ✅ | Similar |
| Reorderable | ✅ | ✅ | Similar |
| AppBar | ✅ | ❌ | zcatgui único |
| NavDrawer | ✅ | ❌ | zcatgui único |
| Breadcrumb | ✅ | ❌ | zcatgui único |
| Badge | ✅ | ❌ | zcatgui único |
| RichText | ✅ | ✅ TextLayout | Similar |
| Loader/Spinner | ✅ | ❌ | zcatgui único |
| Switch | ✅ | ❌ | zcatgui único |
| Autocomplete | ✅ | ✅ Suggestion | Similar |
| Table editable | ✅⭐ | ❌ Grid básico | **zcatgui superior** |
| Floating Window | ❌ | ✅ | DVUI único |
| Animate | ❌ directo | ✅ | DVUI: widget dedicado |
| Cache | ❌ | ✅ | DVUI: optimización |
**Conclusión Widgets**: zcatgui tiene MÁS widgets que DVUI, incluyendo varios únicos.
---
## 4. DIFERENCIAS CRÍTICAS DE RENDERING
### 4.1 Lo que DVUI hace mejor visualmente
| Aspecto | DVUI | zcatgui | Impacto Visual |
|---------|------|---------|----------------|
| **Esquinas redondeadas** | ✅ corner_radius | ❌ Solo rectángulos | ⭐⭐⭐ ALTO |
| **Anti-aliasing bordes** | ✅ Edge fade | ❌ Solo en TTF | ⭐⭐⭐ ALTO |
| **Estados hover/press** | ✅ Transiciones suaves | ⚠️ Cambio abrupto | ⭐⭐ MEDIO |
| **Focus ring** | ✅ 2px stroke suave | ⚠️ Rectángulo | ⭐⭐ MEDIO |
| **Ninepatch** | ✅ Imágenes escalables | ❌ No | ⭐ BAJO |
| **Box shadow** | ✅ Blur real | ⚠️ API existe, no usada | ⭐⭐ MEDIO |
### 4.2 Lo que zcatgui hace igual o mejor
| Aspecto | zcatgui | DVUI |
|---------|---------|------|
| **TTF Rendering** | ✅ Supersampling 2x | ✅ stb_truetype |
| **Themes** | ✅ 5 themes | ✅ 6 themes |
| **Effects API** | ✅ Shadow, Gradient, Blur | ⚠️ Solo shadow |
| **Color utilities** | ✅ Básico | ✅ HSLuv completo |
| **Animation system** | ✅ 20+ easing functions | ✅ Similar |
---
## 5. SISTEMA DE THEMING
### 5.1 DVUI Themes
```zig
// DVUI: Theme estructura
Theme {
// Colores por estilo
styles: [content, control, window, highlight, err, app1, app2, app3]
// Cada estilo tiene:
fill, fill_hover, fill_press,
text, text_hover, text_press,
border,
ninepatch_fill, ninepatch_hover, ninepatch_press,
// Fuentes
font_body, font_heading, font_title, font_mono,
// Geometría
max_default_corner_radius,
// Meta
dark: bool,
focus_color,
text_select_color,
}
```
### 5.2 Themes Disponibles
| Theme | DVUI | zcatgui |
|-------|:----:|:-------:|
| Dark | ✅ | ✅ |
| Light | ✅ | ✅ |
| Adwaita | ✅ | ❌ |
| Dracula | ✅ | ✅ |
| Gruvbox | ✅ | ❌ |
| Jungle | ✅ | ❌ |
| OpenDyslexic | ✅ | ❌ |
| Win98 | ✅ | ❌ |
| Solarized | ❌ | ✅ |
| High Contrast | ❌ | ✅ |
| Nord | ❌ | ✅ |
---
## 6. FEATURES ADICIONALES DE DVUI
### 6.1 Features que NO tenemos
| Feature | Descripción | Prioridad |
|---------|-------------|-----------|
| **structEntry** | Auto-genera UI desde struct Zig | MEDIA |
| **AccessKit** | Soporte screen readers | BAJA |
| **Fire-and-forget dialogs** | Dialogs desde cualquier punto | MEDIA |
| **HSLuv color space** | Manipulación perceptual de colores | BAJA |
| **TinyVG icons** | Iconos vectoriales compactos | MEDIA |
| **Ninepatch** | Imágenes escalables 9-slice | BAJA |
| **Cache Widget** | Cacheo de rendering costoso | MEDIA |
| **FPS throttling** | Control de framerate | BAJA |
### 6.2 Features que YA tenemos equivalentes
| Feature | DVUI | zcatgui |
|---------|------|---------|
| Macro system | ❌ | ✅ ÚNICO |
| Lego Panels | ❌ | ✅ ÚNICO |
| DataManager | ❌ | ✅ ÚNICO |
| Table editable | ❌ | ✅ SUPERIOR |
| Progress widgets | ❌ | ✅ |
| Toast notifications | ❌ | ✅ |
| DatePicker | ❌ | ✅ |
| Multiple progress styles | ❌ | ✅ |
---
## 7. EASING Y ANIMACIONES
### 7.1 DVUI Easing Functions
- Linear
- Quad (in/out/inOut)
- Cubic (in/out/inOut)
- Quart (in/out/inOut)
- Quint (in/out/inOut)
- Sine
- Exponential
- Circular
- Elastic
- Back
- Bounce
### 7.2 zcatgui Animation System
Ya tenemos en `animation.zig`:
- 20+ easing functions (similar a DVUI)
- AnimationManager
- Spring physics
- lerp/lerpInt utilities
**Conclusión**: Paridad en animaciones.
---
## 8. BACKENDS
### 8.1 Comparación
| Backend | DVUI | zcatgui |
|---------|:----:|:-------:|
| SDL2 | ✅ | ✅ |
| SDL3 | ✅ | ❌ |
| SDL3GPU | ✅ | ❌ |
| Raylib | ✅ | ❌ |
| DirectX 11 | ✅ | ❌ |
| Web/Canvas | ✅ | ✅ WASM |
| Android | ❌ | ✅ |
| iOS | ❌ | ✅ |
**Conclusión**: DVUI tiene más backends desktop, zcatgui tiene mobile.
---
## 9. GAP ANALYSIS - QUÉ IMPLEMENTAR
### 9.1 PRIORIDAD CRÍTICA (Mejora Visual Inmediata)
| Mejora | Descripción | Esfuerzo | Impacto |
|--------|-------------|----------|---------|
| **Esquinas redondeadas** | corner_radius en todos los widgets | ALTO | ⭐⭐⭐ |
| **Anti-aliasing bordes** | Edge-fade en rectángulos/líneas | ALTO | ⭐⭐⭐ |
| **Aplicar sombras existentes** | Usar Shadow API en widgets | MEDIO | ⭐⭐ |
| **Hover/Press suave** | Transición gradual de colores | MEDIO | ⭐⭐ |
### 9.2 PRIORIDAD ALTA (Mejora UX)
| Mejora | Descripción | Esfuerzo |
|--------|-------------|----------|
| Focus ring suave | Borde con AA en lugar de rectángulo |
| Smooth scrolling | Animación al hacer scroll |
| Button states | Hover → Press → Release animados |
| Color transitions | Animación entre estados de color |
### 9.3 PRIORIDAD MEDIA (Features)
| Feature | Descripción |
|---------|-------------|
| structEntry | Auto UI desde structs |
| Cache widget | Para renders costosos |
| TinyVG icons | Iconos vectoriales |
| Más themes | Adwaita, Gruvbox, Win98 |
### 9.4 PRIORIDAD BAJA (Nice to have)
| Feature | Descripción |
|---------|-------------|
| AccessKit | Screen readers |
| HSLuv | Color perceptual |
| Ninepatch | 9-slice images |
| SDL3 backend | Nuevo SDL |
---
## 10. PLAN DE IMPLEMENTACIÓN PROPUESTO
### Fase 1: Rendering Visual (CRÍTICO)
1. **Implementar Path con esquinas redondeadas**
- Crear `src/render/path.zig`
- Arcos discretizados
- addRoundedRect()
2. **Anti-aliasing en bordes**
- Modificar `software.zig`
- Edge-fade technique
- Aplicar a drawRect, drawLine
3. **Actualizar widgets existentes**
- Button: corner_radius
- Panel: corner_radius
- TextInput: corner_radius
- Select: corner_radius
- Modal: corner_radius
### Fase 2: Estados Visuales
4. **Transiciones de estado**
- Integrar AnimationManager en widgets
- Hover fade (200ms)
- Press transition (100ms)
5. **Focus ring mejorado**
- Borde con AA
- Color de tema
### Fase 3: Efectos
6. **Aplicar sombras**
- Activar Shadow existente en Panel
- Activar en Modal
- Activar en Dropdown/Select
7. **Mejorar gradientes**
- Usar en Progress bars
- Opcional en buttons
### Fase 4: Features Adicionales
8. **Widget variants**
- button_simple vs button_fancy
- panel_simple vs panel_fancy
9. **Nuevos themes**
- Adwaita
- Gruvbox
---
## 11. ARQUITECTURA PROPUESTA
### 11.1 Sistema Dual: Simple vs Fancy
```zig
// Configuración global
pub const RenderMode = enum {
simple, // Rápido, rectángulos, sin AA
fancy, // Esquinas redondeadas, AA, sombras
};
pub var render_mode: RenderMode = .fancy;
// En cada widget
pub fn button(ctx, text) {
if (render_mode == .fancy) {
drawRoundedRect(corner_radius: 5);
applyShadow();
} else {
drawRect();
}
}
```
### 11.2 Nuevos Módulos Necesarios
```
src/render/
├── path.zig # NUEVO: Path con arcos y curvas
├── triangulate.zig # NUEVO: Triangulación de paths
├── software.zig # MODIFICAR: AA en primitivas
├── effects.zig # YA EXISTE: Activar en widgets
├── antialiasing.zig # YA EXISTE: Extender
```
---
## 12. MÉTRICAS DE ÉXITO
### Antes vs Después
| Aspecto | Antes | Después |
|---------|-------|---------|
| Esquinas | Rectangulares | Redondeadas configurable |
| Bordes | Aliased | Anti-aliased |
| Sombras | No usadas | En paneles/modales |
| Transiciones | Abruptas | Suaves (200ms) |
| Focus | Rectángulo | Ring con AA |
### Comparación Visual Objetivo
```
ANTES (zcatgui actual):
┌────────────────┐
│ Botón │ ← Esquinas 90°
└────────────────┘ Sin sombra
Cambio abrupto hover
DESPUÉS (estilo DVUI):
╭────────────────╮
│ Botón │ ← Esquinas redondeadas
╰────────────────╯ Sombra sutil
Transición suave hover
```
---
## 13. CONCLUSIONES
### Lo que DVUI hace mejor
1. **Rendering visual** - Esquinas redondeadas, AA en todo
2. **Estados de widgets** - Transiciones suaves
3. **Consistencia visual** - Todo se ve "pulido"
### Lo que zcatgui hace mejor
1. **Sistema de macros** - Único
2. **Table widget** - Más completo (edit, sort, validate)
3. **Lego Panels** - Arquitectura de composición
4. **Más widgets** - Progress, DatePicker, Toast, etc.
5. **Mobile backends** - Android, iOS
### Recomendación Final
**NO necesitamos reescribir zcatgui.** Necesitamos:
1. **Añadir esquinas redondeadas** (~500 LOC nuevo código)
2. **Mejorar anti-aliasing** (~300 LOC modificaciones)
3. **Aplicar efectos existentes** (~200 LOC en widgets)
4. **Añadir transiciones** (~400 LOC)
**Total estimado: ~1,400 LOC para alcanzar paridad visual con DVUI.**
El esfuerzo es significativamente menor que reescribir desde cero, y mantiene nuestras ventajas únicas (macros, table, panels).
---
*Auditoría completada 2025-12-17*
Reference in a new issue View git blame Copy permalink