menios icon indicating copy to clipboard operation
menios copied to clipboard
verified publisher icon pbalduino

Port Cairo 2D graphics library to meniOS

Open pbalduino opened this issue 3 months ago • 0 comments

Summary

Port the Cairo 2D graphics library to meniOS to provide high-quality vector graphics, text rendering, and compositing capabilities. Cairo is the foundation for the GUI stack and compositor.

Background

Cairo is an industry-standard 2D graphics library used by GTK, Firefox, Inkscape, LibreOffice, and many other projects. It provides:

  • Vector graphics with anti-aliasing
  • Excellent text rendering (via FreeType)
  • Image compositing with alpha blending
  • PDF, SVG, and PostScript output
  • Multiple rendering backends

Version: Cairo 1.18.0 (latest stable) Language: C (~150,000 lines) License: LGPL 2.1 / MPL 1.1 (dual-licensed)

Goals

Primary

  • Port Cairo to compile and run on meniOS
  • Implement framebuffer backend for direct rendering
  • Support basic shapes, paths, fills, and strokes
  • Enable text rendering with TrueType fonts (via FreeType)
  • Provide image surface support

Secondary

  • PDF surface support (for document generation)
  • SVG output (for vector graphics)
  • Optimize for x86-64 (SIMD where applicable)
  • Ensure thread-safe operation

Implementation Plan

Phase 1: Build System Integration (1 week)

Goal: Get Cairo to compile

Tasks:

  • [ ] Download Cairo 1.18.0 source
  • [ ] Place in `vendor/cairo-1.18.0/`
  • [ ] Create Makefile for meniOS build
  • [ ] Configure build options (disable unneeded backends)
  • [ ] Resolve compilation errors

Cairo Backends to Enable:

  • ✅ Image surface (required)
  • ✅ Framebuffer (for /dev/fb0)
  • ⏳ PDF surface (optional)
  • ⏳ SVG surface (optional)
  • ❌ X11 backend (not needed)
  • ❌ OpenGL backend (future)

Phase 2: Dependency Integration (2-3 weeks)

Goal: Link Cairo with Pixman and FreeType

Dependencies:

  • Pixman - Required for pixel manipulation (will be issue #395)
  • FreeType - Required for font rendering (will be issue #396)
  • libpng (optional) - For PNG image support

Tasks:

  • [ ] Ensure Pixman is built and linked
  • [ ] Ensure FreeType is built and linked
  • [ ] Configure Cairo to find dependencies
  • [ ] Verify linking succeeds
  • [ ] Test basic Cairo initialization

Phase 3: Framebuffer Backend (1-2 weeks)

Goal: Render Cairo output to /dev/fb0

Current State:

  • meniOS has `/dev/fb0` device
  • Framebuffer is linear memory-mapped buffer
  • Format: RGB24 or ARGB32
  • Resolution: Configurable (default 1024x768)

Tasks:

  • [ ] Create Cairo framebuffer surface wrapper
  • [ ] Map `/dev/fb0` to Cairo surface
  • [ ] Implement direct rendering
  • [ ] Test basic drawing operations

Phase 4: Text Rendering (1 week)

Goal: Render text with TrueType fonts

Requirements:

  • FreeType integration
  • Font files available on filesystem
  • Cairo FT font backend enabled

Tasks:

  • [ ] Configure Cairo FT font support
  • [ ] Load TrueType fonts from `/usr/share/fonts/`
  • [ ] Test text rendering with various fonts and sizes
  • [ ] Verify subpixel anti-aliasing works

Phase 5: Advanced Features (1-2 weeks)

Goal: Support paths, gradients, transformations

Tasks:

  • [ ] Test complex paths (Bezier curves, arcs)
  • [ ] Implement gradient fills (linear, radial)
  • [ ] Test transformations (translate, rotate, scale)
  • [ ] Test compositing modes (alpha blending)
  • [ ] Performance optimization

Phase 6: PDF/SVG Support (Optional, 1-2 weeks)

Goal: Enable document and vector graphics output

Tasks:

  • [ ] Enable Cairo PDF backend
  • [ ] Test PDF generation
  • [ ] Enable Cairo SVG backend
  • [ ] Test SVG output

Timeline

Phase Task Duration
1 Build system integration 1 week
2 Dependency integration 2-3 weeks
3 Framebuffer backend 1-2 weeks
4 Text rendering 1 week
5 Advanced features 1-2 weeks
6 PDF/SVG support (optional) 1-2 weeks

Total: 7-11 weeks (depending on optional features)

Definition of Done

Core Requirements

  • [ ] Cairo library compiles on meniOS
  • [ ] All dependencies linked (Pixman, FreeType)
  • [ ] Can create Cairo surfaces
  • [ ] Can render to framebuffer (/dev/fb0)
  • [ ] Basic shapes work (rectangles, circles, paths)
  • [ ] Text rendering works with TrueType fonts
  • [ ] Demo programs run successfully

Advanced Features

  • [ ] Gradients work (linear and radial)
  • [ ] Transformations work (translate, rotate, scale)
  • [ ] Alpha blending works
  • [ ] Complex paths render correctly
  • [ ] Performance is acceptable (60fps for simple scenes)

Optional Features

  • [ ] PDF output works
  • [ ] SVG output works
  • [ ] PNG image loading works (requires libpng)

Documentation

  • [ ] Cairo examples in `/app/cairo_demo/`
  • [ ] Integration guide in docs
  • [ ] API usage documented

Dependencies

Required (Blockers)

  • Pixman (issue to be created) - Cairo's pixel manipulation backend
  • FreeType (issue to be created) - Font rendering for Cairo text

Optional

  • libpng - For PNG image support
  • #339: Thread-safe libc - For multi-threaded Cairo usage

Enables

  • Compositor Core (issue to be created) - Needs Cairo for window composition
  • Window Decorations (issue to be created) - Uses Cairo for title bars/buttons
  • Desktop Shell (issue to be created) - Uses Cairo for panel and menus
  • Core GUI Applications (issue to be created) - All GUI apps use Cairo

Related Issues

See docs/road/road_to_gui.md for the complete GUI roadmap.

Resources

  • Cairo Website: https://www.cairographics.org/
  • Cairo Manual: https://www.cairographics.org/manual/
  • Cairo Tutorial: https://www.cairographics.org/tutorial/
  • Source Code: https://gitlab.freedesktop.org/cairo/cairo
  • API Reference: https://www.cairographics.org/manual/index.html

Priority

HIGH - Cairo is the foundation for the entire GUI stack. All compositor, window manager, and desktop environment work depends on this.

Timeline: Target completion in 2-3 months

pbalduino avatar Oct 30 '25 22:10 pbalduino