fwcompositor Service

Central window manager and compositor service

Overview

fwcompositor is the central window manager service for FreeWorld OS. It runs as a daemon/service and manages all windows, handles compositing, and routes input events. Applications connect to it via IPC (Inter-Process Communication).

Status: This service is currently planned and needs to be implemented. The architecture and API are designed, but the actual service code needs to be written.

Purpose

The fwcompositor service provides:

  • Window Management: Creation, destruction, positioning, sizing
  • Compositing: Blending all windows into a single framebuffer
  • Input Routing: Routing keyboard and mouse events to correct windows
  • IPC Server: Communication interface for applications
  • Kernel Integration: Direct access to kernel graphics syscalls

Architecture

Service Structure

fwcompositor
├── IPC Server (Unix socket / TCP)
├── Window Manager
│   ├── Window registry
│   ├── Z-order management
│   └── Focus management
├── Compositor
│   ├── Buffer management
│   ├── Blending engine
│   └── Dirty region tracking
├── Input Router
│   ├── Event queue
│   ├── Hit testing
│   └── Event distribution
└── Kernel Interface
    ├── Graphics syscalls
    └── Framebuffer access

IPC Methods

Window Management

Method Parameters Returns Description
CreateWindow title, width, height, flags hwnd Create a new window
DestroyWindow hwnd status Destroy a window
MoveWindow hwnd, x, y status Move window to new position
ResizeWindow hwnd, width, height status Resize window
ShowWindow hwnd status Show window
HideWindow hwnd status Hide window
SetFocus hwnd status Set keyboard focus
GetWindowInfo hwnd window info Get window information
ListWindows - array of windows List all windows

Buffer Management

Method Parameters Returns Description
UpdateWindow hwnd, buffer, x, y, width, height status Update window buffer content
GetWindowBuffer hwnd buffer Get window's drawing buffer
Composite - status Trigger compositing pass

Implementation Details

Language

The service will be implemented in C/ASM for performance and kernel integration.

IPC Server

  • 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 (initial implementation)
  • Future: Binary protocol for better performance
  • Transport: Unix socket (preferred) or TCP

Kernel Integration

The service communicates with the kernel via:

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

Window Management

Window Registry

All windows are stored in a registry with:

  • HWND (window handle)
  • Position (x, y)
  • Size (width, height)
  • Z-order (stacking order)
  • Focus state
  • Visibility
  • Buffer reference

Z-Order Management

Windows are maintained in a z-order list (bottom to top). When compositing:

  1. Start with desktop/background
  2. Composite windows from bottom to top
  3. Apply transparency and shadows
  4. Send final composite to kernel

Focus Management

Only one window has keyboard focus at a time. Focus changes when:

  • User clicks on a window
  • Application requests focus
  • Window is destroyed

Compositing

Compositing Process

  1. Create composited buffer (screen size)
  2. Clear with background/desktop
  3. For each window (bottom to top):
    • Check if window is visible
    • Check if window overlaps with dirty region
    • Blend window buffer into composite
    • Apply transparency if needed
    • Draw shadow if enabled
  4. Send final composite to kernel
  5. Kernel blits to VESA framebuffer

Dirty Region Tracking

Only redraw regions that have changed:

  • Track dirty regions per window
  • Merge overlapping dirty regions
  • Composite only dirty areas
  • Clear dirty flags after compositing

Input Routing

Event Flow

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

Hit Testing

Determine which window should receive input:

  • Check z-order (top to bottom)
  • Check if point is within window bounds
  • Check if window accepts input
  • Check for modal windows

Implementation Plan

Phase 1: Basic Service

  • IPC server setup (Unix socket/TCP)
  • JSON-RPC protocol handler
  • Basic window registry
  • Window creation/destruction

Phase 2: Compositing

  • Buffer management
  • Basic compositing (no transparency)
  • Kernel graphics syscall integration
  • Framebuffer blitting

Phase 3: Advanced Features

  • Transparency and shadows
  • Dirty region tracking
  • Input event routing
  • Focus management

Phase 4: Optimization

  • Binary protocol
  • Hardware acceleration
  • Multi-threading
  • Performance tuning

Related Documentation