Windowing System Architecture

Overview

FreeWorld uses a native windowing system with kernel-level graphics and a central window manager service. This architecture is similar to how X11, Wayland, and Windows DWM work.

┌─────────────────────────────────────────────────────────┐
│  Node.js Applications (User Space)                      │
│  - Desktop apps                                         │
│  - System utilities                                      │
│  - User programs                                        │
└──────────────────┬──────────────────────────────────────┘
                   │ IPC (Unix Socket / TCP Port)
                   │ Protocol: JSON-RPC or Binary Protocol
┌──────────────────▼──────────────────────────────────────┐
│  Window Manager Service (fwcompositor)                  │
│  - Window management                                     │
│  - Compositing                                           │
│  - Input routing                                         │
│  - IPC server (listens on port 8080 or /tmp/fwcompositor)│
└──────────────────┬──────────────────────────────────────┘
                   │ Syscalls
                   │ - SYS_GRAPHICS_* (custom syscalls)
                   │ - SYS_MMAP (framebuffer access)
┌──────────────────▼──────────────────────────────────────┐
│  Kernel Graphics Layer                                  │
│  - VESA framebuffer driver                              │
│  - Graphics syscalls                                     │
│  - Direct framebuffer access                            │
│  - Hardware abstraction                                  │
└──────────────────┬──────────────────────────────────────┘
                   │ Hardware
┌──────────────────▼──────────────────────────────────────┐
│  Graphics Hardware (VGA/VESA)                           │
└─────────────────────────────────────────────────────────┘
                    

Architecture Layers

1. Kernel Graphics Layer

Location: kernel/gui/

Purpose: Low-level graphics primitives, framebuffer management

Key Functions:

• gui_renderer_init() - Initialize VESA framebuffer
• gui_draw_pixel() - Draw pixel to framebuffer
• gui_draw_rect() - Draw rectangle
• gui_draw_window() - Draw window with title bar
• gui_blit() - Copy buffer to framebuffer
• gui_swap_buffers() - Double buffering

System Calls:

• SYS_GRAPHICS_INIT - Initialize graphics
• SYS_GRAPHICS_GET_FB - Get framebuffer address
• SYS_GRAPHICS_BLIT - Blit buffer to screen
• SYS_MMAP - Map framebuffer to user space

2. Window Manager Service

Location: services/fwcompositor/

Purpose: Central window management, compositing, IPC server

Responsibilities:

• Window creation/destruction
• Window positioning and sizing
• Z-order management
• Compositing (blending windows)
• Input event routing
• IPC server for applications

See fwcompositor Service for detailed documentation.

3. Node.js Client Library

Location: system/wm-client.js

Purpose: IPC client for Node.js applications to communicate with window manager

Usage Example:

const WindowManager = require('./wm-client');

const wm = new WindowManager();
await wm.connect(); // Connect to fwcompositor service

const hwnd = await wm.createWindow('My App', 800, 600);
await wm.showWindow(hwnd);
await wm.moveWindow(hwnd, 100, 100);

// Draw to window buffer
const buffer = await wm.getWindowBuffer(hwnd);
// ... draw to buffer ...
await wm.updateWindow(hwnd, buffer); // Send buffer to compositor

See Window Manager Client for detailed API documentation.

Application Flow

1. Application Starts

1. Application connects to fwcompositor service via IPC
2. Requests window creation
3. Receives HWND (window handle)

2. Application Draws

1. Gets window buffer from window manager
2. Draws to buffer (using DeviceContext)
3. Sends buffer back to window manager

3. Window Manager

1. Receives buffer from application
2. Composites all windows (blends them)
3. Sends final composite to kernel
4. Kernel blits to framebuffer

4. Input Events

1. Kernel receives keyboard/mouse input
2. Kernel sends to window manager via syscall
3. Window manager routes to correct window
4. Window manager sends event to application via IPC

IPC Communication

Socket Location

• Unix Domain Socket: /tmp/fwcompositor.sock (Linux/WSL)
• TCP Port: 127.0.0.1:8080 (fallback)
• Named Pipe: \\.\pipe\fwcompositor (Windows)

Protocol

• Format: JSON-RPC 2.0 or custom binary protocol
• Transport: Unix socket (preferred) or TCP
• Encoding: UTF-8 JSON or binary

Example Request/Response

Create Window:

Request:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "CreateWindow",
  "params": {
    "title": "My Application",
    "width": 800,
    "height": 600,
    "flags": 0
  }
}

Response:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hwnd": "FW_HWND_abc123",
    "status": "ok"
  }
}

Update Window Buffer:

Request:
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "UpdateWindow",
  "params": {
    "hwnd": "FW_HWND_abc123",
    "buffer": "<base64 encoded pixel data>",
    "x": 0,
    "y": 0,
    "width": 800,
    "height": 600
  }
}

Benefits

• Native Windows: Real windows, not web-based
• Kernel Integration: Direct framebuffer access
• Centralized Management: One service manages all windows
• IPC Communication: Clean separation between apps and window manager
• Scalable: Multiple apps can connect simultaneously
• Secure: Window manager controls access to graphics

Similar Systems

• X11: X server manages windows, apps connect via X protocol
• Wayland: Compositor manages windows, apps use Wayland protocol
• Windows DWM: Desktop Window Manager handles compositing
• macOS Quartz: Window Server manages windows

Implementation Status

Related Documentation

• fwcompositor Service - Window manager service details
• Window Manager Client - Node.js IPC client API
• Kernel GUI System - Low-level graphics functions
• Compositor - Window compositing system
• Window Management - Window API and management