Port Cairo 2D graphics library to meniOS #396
Description
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 #23 - Refactor the code structure #395)
- FreeType - Required for font rendering (will be issue Port Cairo 2D graphics library to meniOS #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
- Implement thread-safe libc with proper locking #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