Add character input eventt and foreign window attach/detach support (#2)

* attach window feature

* demo test

* update changelog

* demo test win32

* detach window

* event helpers

* fix keyup event lost

* key char event win32

* key char event x11

* updated readme

* fix window state bug

* code format

* fix warning

---------

Co-authored-by: nichcode <nicholasagbo04@gmail.com>

Author: nichcode

CHANGELOG.md

@@ -46,3 +46,26 @@
 - No API or ABI changes - existing Windows code remains compatible.
 - Linux video support currently targets **X11** only: **Wayland** is planned for future releases.
 - Safe upgrade from **v1.0.1** - just rebuild your project after updating.
+
+## [1.2.0] - 2025-10-22
+
+### Features
+- **Video:** Added **palGetInstance()** to retrieve the native display or instance handle.
+- **Video:** Added **palAttachWindow()** for attaching **foreign windows** to PAL.
+- **Video:** Added **palDetachWindow()** for detaching **foreign windows** from PAL.
+- **Event:** Added **PAL_EVENT_KEYCHAR** to `PalEventType` enum.
+- **Event:** Added documentation for event bits(payload) layout.
+
+### Naming Update
+- PAL now stands for **Prime Abstraction Layer**, 
+reflecting its role as the primary explicit foundation for OS and graphics abstraction.
+- All API remains unchanged — this is an identity update only.
+
+### Tests
+- Added multi-threaded OpenGL example: demonstrating **Multi-Threaded OpenGL Rendering**. see **multi_thread_opengl_test.c**.
+- Added attaching and detach foreign windows example. see **attach_window_test.c**
+- Added key character example. see **char_event_test.c**
+
+### Notes
+- No API or ABI changes - existing code remains compatible.
+- Safe upgrade from **v1.1.0** - just rebuild your project after updating.

README.md

@@ -1,4 +1,4 @@
-# PAL (Platform Abstraction Layer)
+# PAL (Prime Abstraction Layer)
 
 ![License: Zlib](https://img.shields.io/badge/License-Zlib-blue.svg)
 ![Language: C99](https://img.shields.io/badge/language-C99-green.svg)
@@ -7,6 +7,9 @@
 
 PAL is a lightweight, low-level, cross-platform abstraction layer in **C**, designed to be **explicit** and as close to the **OS** as possible — similar in philosophy to Vulkan. It gives you precise control without hidden behavior, making it ideal for developers who want performance and predictability.
 
+Originally named as **Platform Abstraction Layer**, 
+PAL has evolved into **Prime Abstraction Layer** — the **first** and most **direct** layer between your engine or software and the operating system.
+
 PAL is transparent. All queries — window size, position, monitor info, and more — reflect the current platform state. Using PAL is like working directly with the OS: it applies no hidden logic, makes no assumptions, and leaves behavior fully in your control.
 
 This approach gives you total control: you handle events, manage resources, and cache state explicitly. PAL provides the building blocks; how you use them — whether for simple applications or advanced frameworks — is entirely up to you.
@@ -22,7 +25,8 @@ palGetWindowSize(window, &w, &h);
 
 ## Why PAL?
 
-Other libraries like SDL or GLFW provide high-level abstractions but at the cost of overhead, implicit behavior, and limited control. **PAL is different:**
+While libraries like SDL or GLFW focus on simplifying development 
+through high-level abstractions. **PAL is different:**
 
 - ✅ **Explicit**: You decide how memory, events, and handles are managed.
 - ✅ **Low Overhead**: PAL is close to raw OS calls, ensuring performance.

include/pal/pal_event.h

@@ -111,25 +111,243 @@ typedef bool(PAL_CALL* PalPollFn)(
  * @ingroup pal_event
  */
 typedef enum {
-    PAL_EVENT_WINDOW_CLOSE, /**< Window close button.*/
+    /**
+     * PAL_EVENT_WINDOW_CLOSE
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
+    PAL_EVENT_WINDOW_CLOSE,
+
+    /**
+     * PAL_EVENT_WINDOW_SIZE
+     *
+     * event.data : lower 32 bits = width, upper 32 bits = height
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackUint32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_WINDOW_SIZE,
+
+    /**
+     * PAL_EVENT_WINDOW_MOVE
+     *
+     * event.data : lower 32 bits = x, upper 32 bits = y
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackInt32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_WINDOW_MOVE,
-    PAL_EVENT_WINDOW_STATE,       /**< (minimized, maximized, restored).*/
-    PAL_EVENT_WINDOW_FOCUS,       /**< True for focus gained.*/
-    PAL_EVENT_WINDOW_VISIBILITY,  /**< True for visible.*/
-    PAL_EVENT_WINDOW_MODAL_BEGIN, /**< WM_ENTERSIZEMOVE (Windows Only).*/
-    PAL_EVENT_WINDOW_MODAL_END,   /**< WM_EXITSIZEMOVE. (Windows Only).*/
+
+    /**
+     * PAL_EVENT_WINDOW_STATE
+     *
+     * event.data : state(minimized, maximized, restored).
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
+    PAL_EVENT_WINDOW_STATE,
+
+    /**
+     * PAL_EVENT_WINDOW_FOCUS
+     *
+     * event.data : `true` for focus gained or `false` for focus lost.
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
+    PAL_EVENT_WINDOW_FOCUS,
+
+    /**
+     * PAL_EVENT_WINDOW_VISIBILITY
+     *
+     * event.data : `true` for visible or `false` for hidden.
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
+    PAL_EVENT_WINDOW_VISIBILITY,
+
+    /**
+     * @brief WM_ENTERSIZEMOVE (Windows Only).
+     *
+     * PAL_EVENT_WINDOW_MODAL_BEGIN
+     *
+     * event.data2 : window
+     */
+    PAL_EVENT_WINDOW_MODAL_BEGIN,
+
+    /**
+     * @brief WM_EXITSIZEMOVE (Windows Only).
+     *
+     * PAL_EVENT_WINDOW_MODAL_END
+     *
+     * event.data2 : window
+     */
+    PAL_EVENT_WINDOW_MODAL_END,
+
+    /**
+     * PAL_EVENT_MONITOR_DPI_CHANGED
+     *
+     * event.data2 : window
+     */
     PAL_EVENT_MONITOR_DPI_CHANGED,
-    PAL_EVENT_MONITOR_LIST_CHANGED, /**< Monitor list changed.*/
+
+    /**
+     * @brief Monitor list changed
+     *
+     * PAL_EVENT_MONITOR_LIST_CHANGED
+     *
+     * event.data2 : window
+     */
+    PAL_EVENT_MONITOR_LIST_CHANGED,
+
+    /**
+     * PAL_EVENT_KEYDOWN
+     *
+     * event.data : lower 32 bits = keycode, upper 32 bits = scancode
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackUint32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_KEYDOWN,
+
+    /**
+     * PAL_EVENT_KEYREPEAT
+     *
+     * event.data : lower 32 bits = keycode, upper 32 bits = scancode
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackUint32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_KEYREPEAT,
+
+    /**
+     * PAL_EVENT_KEYUP
+     *
+     * event.data : lower 32 bits = keycode, upper 32 bits = scancode
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackUint32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_KEYUP,
+
+    /**
+     * PAL_EVENT_MOUSE_BUTTONDOWN
+     *
+     * event.data : mouse button
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
     PAL_EVENT_MOUSE_BUTTONDOWN,
+
+    /**
+     * PAL_EVENT_MOUSE_BUTTONUP
+     *
+     * event.data : mouse button
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
     PAL_EVENT_MOUSE_BUTTONUP,
+
+    /**
+     * PAL_EVENT_MOUSE_MOVE
+     *
+     * event.data : lower 32 bits = x, upper 32 bits = y
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackInt32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_MOUSE_MOVE,
-    PAL_EVENT_MOUSE_DELTA, /**< Mouse movement delta.*/
+
+    /**
+     * @brief Mouse movement delta.
+     *
+     * PAL_EVENT_MOUSE_DELTA
+     *
+     * event.data : lower 32 bits = dx, upper 32 bits = dy
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackInt32()
+     * - palUnpackPointer()
+     */
+    PAL_EVENT_MOUSE_DELTA,
+
+    /**
+     * PAL_EVENT_MOUSE_WHEEL
+     *
+     * event.data : lower 32 bits = dx, upper 32 bits = dy
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackInt32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_MOUSE_WHEEL,
+
+    /**
+     * PAL_EVENT_USER
+     *
+     * event.userId : User event ID or type.
+     *
+     * Use inline helpers:
+     * - palPackInt32()
+     * - palPackUint32()
+     * - palPackPointer()
+     * - palUnpackInt32()
+     * - palUnpackUint32()
+     * - palUnpackPointer()
+     */
     PAL_EVENT_USER,
+
+    /**
+     * PAL_EVENT_USER
+     *
+     * event.data : codepoint
+     *
+     * event.data2 : window
+     *
+     * Use inline helpers:
+     * - palUnpackPointer()
+     */
+    PAL_EVENT_KEYCHAR,
+
     PAL_EVENT_MAX
 } PalEventType;