Add initial FnixLib development implementation

docs/DECISIONS.md

@@ -0,0 +1,101 @@
+# Decisiones de diseño de FnixLib
+
+Registro de las decisiones técnicas tomadas en la versión 0.1.0, con su motivo y
+lo que costaría revertirlas. Es un documento nuevo; no sustituye a ningún otro.
+
+## Convenciones
+
+- **Lenguaje:** C17 estricto (`-std=c17`, sin extensiones de GNU).
+- **Nombres:** funciones `fnix_modulo_accion`, tipos `FnixTipo`, constantes y
+  macros `FNIX_NOMBRE`. Los identificadores van en inglés; los comentarios y los
+  mensajes de error, en español.
+- **Errores:** las funciones que crean objetos devuelven `NULL` si fallan; las de
+  consulta no fallan (devuelven 0/false ante argumentos inválidos). El motivo se
+  guarda por hilo y se lee con `fnix_last_error_code()` / `fnix_last_error()`.
+  Un éxito no borra el último error (como `errno`).
+- **Objetos opacos:** `FnixWindow` y `FnixCanvas` solo se manejan por puntero, de
+  modo que su contenido puede cambiar sin romper la API.
+
+## Decisiones
+
+### D1. Xlib (libX11) como interfaz con el sistema gráfico de Linux
+Se trata como interfaz nativa del sistema, igual que Win32 en Windows. Alternativas
+descartadas por ahora: hablar el protocolo X11 a mano sobre un socket (mucho trabajo
+sin beneficio en 0.1.0) y Wayland nativo (exige además implementar el protocolo y
+buscar una forma de dibujar). Los ejecutables se verifican bajo X11; en sesiones
+Wayland deberían funcionar mediante XWayland, pero **no está verificado**.
+*Reversible:* todo lo específico de X11 está en `src/platform/linux/` detrás de
+`src/platform/platform.h`.
+
+### D2. Renderizador 2D por software y presentación con `XPutImage`
+Es la forma más sencilla de validar la arquitectura sin depender de la GPU. Coste:
+no hay aceleración ni sincronización vertical. El backend de GPU (OpenGL) queda para
+la fase 4 y se añadirá detrás de la misma API de dibujo.
+
+### D3. Formato de píxel `0x00RRGGBB` y requisitos de pantalla
+El lienzo guarda `uint32_t 0x00RRGGBB`. Es lo que acepta X11 sin conversión en el
+caso habitual. Si el servidor no ofrece un visual TrueColor de 24/32 bits con esas
+máscaras y el mismo orden de bytes que la CPU, `fnix_window_create` falla con
+`FNIX_ERROR_UNSUPPORTED` y un mensaje explicativo (no se intenta convertir).
+
+### D4. Destino de dibujo implícito, por hilo
+`fnix_draw_*` dibuja sobre el lienzo fijado con `fnix_set_target()`;
+`fnix_begin_frame()` fija el de la ventana. Mantiene la API corta
+(`fnix_draw_circle(x, y, r, color)`) y permite pruebas sin ventana usando
+`fnix_canvas_create()`. Coste: estado oculto por hilo.
+
+### D5. Ventana de tamaño fijo
+Se indica con los *hints* de tamaño mínimo = máximo. Redimensionar exigiría decidir
+qué ocurre con el lienzo y no aporta a la primera versión.
+
+### D6. Entrada: estado por fotograma + cola de eventos
+`fnix_begin_frame()` borra los *pressed/released* y la rueda, procesa los eventos del
+sistema y los aplica a una máquina de estados (`input.c`), que es lo que consultan
+`fnix_key_down`, `fnix_key_pressed`, etc. Además cada evento se guarda en una cola
+de 256 entradas (se descarta lo más antiguo) para quien prefiera
+`fnix_window_poll_event`. Detalles:
+- El autorepeat no vuelve a activar *pressed* (`XkbSetDetectableAutoRepeat`).
+- Al perder el foco, lo pulsado pasa a soltado: evita teclas pegadas.
+- Las teclas se identifican por el KeySym sin modificadores (índice 0) de la
+  distribución activa; con distribuciones no QWERTY la tecla física puede cambiar de
+  identificador. Alternativa (códigos físicos/scancodes) pospuesta.
+
+### D7. Tiempo entre fotogramas y límite de FPS
+El *delta time* se mide de `begin_frame` a `begin_frame` (0 en el primero). El límite
+de FPS (60 por defecto) duerme en `end_frame` hasta una fecha límite que avanza un
+periodo por fotograma, de modo que el promedio a largo plazo es exacto. Si se va más
+de un fotograma tarde, se reajusta en lugar de recuperar con una ráfaga.
+
+### D8. Geometría y recorte
+- Entradas limitadas a `[-2^28, 2^28]`; fuera de ese rango no se dibuja y se
+  registra un error. Con ese límite los cálculos en `int64_t` no desbordan.
+- Todo se recorta antes de recorrer píxeles: el coste depende del lienzo, no del
+  tamaño de la figura (una línea de millones de píxeles fuera de pantalla es barata).
+- Cada primitiva escribe cada píxel como máximo una vez, para que la mezcla con alfa
+  no se aplique dos veces.
+- Líneas: Bresenham con aritmética entera; los empates se redondean hacia arriba, por
+  lo que una línea y su inversa pueden diferir en algún píxel intermedio.
+- Círculos: un píxel pertenece al disco si `dx² + dy² <= r² + r`; el contorno es el
+  disco de radio `r` menos el de `r - 1`.
+
+### D9. Mezcla alfa
+"Source-over" con alfa recto y redondeo al entero más cercano; alfa 255 reemplaza y
+alfa 0 no dibuja. `fnix_clear` ignora el alfa.
+
+### D10. CMake
+Biblioteca estática por defecto (`BUILD_SHARED_LIBS` la cambia, **sin verificar**),
+tipo *Release* si no se indica otro, opciones `FNIX_BUILD_EXAMPLES`,
+`FNIX_BUILD_TESTS`, `FNIX_WARNINGS_AS_ERRORS` y `FNIX_SANITIZE`. En sistemas que no
+son Linux la configuración falla con un mensaje claro en vez de compilar a medias.
+
+### D11. Pruebas
+Tres ejecutables sin pantalla (núcleo, dibujo, entrada) y una prueba de integración
+que usa un servidor X real: una segunda conexión inyecta eventos con `XSendEvent` y
+lee los píxeles de la ventana con `XGetImage`. Sin `DISPLAY` termina con código 77 y
+`ctest` la marca como omitida.
+
+## Pendiente (no implementado)
+- `cmake --install`, `find_package(FnixLib CONFIG)` y empaquetado.
+- Windows, y compilación cruzada desde Linux.
+- Imágenes y texturas, fuentes y texto, audio, matemáticas, colisiones, 3D.
+- Licencia: el repositorio no incluye `LICENSE`; debe elegirla el autor.