# yshui/picom architecture

> Architecture diagram of the GitHub repository yshui/picom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yshui/picom
- Repository: https://github.com/yshui/picom

## Overview

##### Project Type and Purpose
- Project Type: picom is a system-level application—a compositor for the X window system. Its purpose is to provide window compositing (transparency, animations, shadow effects, etc.) for X-based systems.
- Indicators: The README clearly states it’s “a compositor for X” and mentions its history as a fork of Compton. It also lists dependencies on various X, XCB, and OpenGL libraries, hinting at its low-level graphics and window management operations.

##### File Structure
- Top Level Structure:
– Build & Configuration: Files like meson.build, meson_options.txt, flake.nix, etc. indicate usage of the Meson build system.
– Documentation & Assets: The README, CHANGELOG.md, Doxyfile, assets, man/, and media directories show there is comprehensive documentation and visual assets.
– Source Code (src/): This is the heart of the project with multiple subdirectories that define various modules.
- Key Subdirectories under src/:
– src/backend: Contains multiple backend implementations (e.g., gl, xrender, dummy), each implementing different rendering strategies.
– src/renderer: Houses the command builder, damage management, layout, and general renderer logic.
– src/config, src/event, and src/dbus: Handle configuration parsing, event management, and optional dbus integration.
– src/transition: Manages animation transitions with curve generation and preset management.
– src/wm: Contains window management logic.
– Additional utility modules under src/utils support various common functions.
- Tests & Tools:
– tests: Includes different configuration examples and test cases, which help verify functionality.
– tools: Contains support utilities like animgen.c and a release-making script.

##### README for Additional Insights
- Detailed Building and Installation Instructions: Clarifies the build process via Meson/Ninja and external dependencies.
- Dependency List: Provides insight into the external systems that interact with picom (X11, XCB, EGL/OpenGL, libconfig, etc.).
- Contribution Guidelines: Emphasis on code quality, testing, and branch stability.

a. Main Components of the System:
– User Configuration Layer: (picom.sample.conf, tests/configs) that feeds configuration input.
– Main Engine: The central coordinator found in files like src/picom.c managing initialization, event loops, and integration of all other components.
– Backend Modules: Under src/backend (gl, xrender, dummy) each representing different ways to render composited output.
– Renderer: Under src/renderer, handling drawing operations, damage tracking, and command building.
– Window Manager Interaction: Modules in src/wm capture and manage window tree states and events.
– Event & Transition Handling: Modules in src/event and src/transition provide user interaction response and animation effects.
– Optional DBus Integration: Files like src/dbus.c enable interprocess communication.
– Utilities: Provided by src/utils supporting caching, logging, dynamic allocation, and process handling.
– External Dependencies: Libraries (e.g., X11, XCB, OpenGL, libconfig, etc.) which interact with picom’s internal modules.

b. Relationships and Interactions:
– User configurations feed into the Main Engine which initializes various modules.
– The Renderer consumes configuration details and coordinates with one or more Backends (selected at runtime or build based on availability/config).
– Event handling routes inputs (from X events or DBus messages) into state changes that trigger appropriate updates in the Renderer and Backend.
– The Window Manager component (src/wm) reports window status changes that feed back into the rendering pipeline.
– External libraries (X11/XCB) act as the interface between the compositor and the system’s graphical subsystem.

c. Architectural Patterns and Principles:
– Modular Design: Clear separation between configuration, backends, renderer, events, transitions, and utilities.
– Abstraction & Extensibility: Multiple backend implementations allow selecting the appropriate rendering strategy based on the runtime environment.
– Integration: A tightly coordinated pipeline from configuration to event processing, to compositing and rendering.

d. Relevant Technologies and Frameworks:
– Meson/Ninja for build management.
– X Window system libraries (libX11, XCB, etc.) and rendering libraries (OpenGL/EGL, libepoxy) for interfacing with hardware.
– Optional DBus integration for interprocess communication.
– Libconfig and uthash for configuration and data management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        UC("User Configuration"):::configuration
        CM("Configuration Module"):::configuration
    end

    %% Core Engine
    subgraph "Core Engine"
        ME("Main Engine"):::engine
        EH("Event Handling"):::engine
        WM("Window Manager Interaction"):::engine
        DB("Optional DBus Integration"):::engine
        TR("Transition Handling"):::engine
        UT("Utilities"):::utility
    end

    %% Rendering Pipeline
    subgraph "Rendering Pipeline"
        R("Renderer"):::renderer
    end

    %% Backend Modules
    subgraph "Backend Modules"
        BG("Backend Module - gl"):::backend
        BX("Backend Module - xrender"):::backend
        BD("Backend Module - dummy"):::backend
    end

    %% External Systems
    ED("External Dependencies (X11, XCB, OpenGL, libconfig)"):::external
    BS("Build System (Meson/Ninja)"):::build

    %% Connections
    UC --> CM
    CM --> ME
    EH --> ME
    WM --> ME
    UT --> ME
    DB --- EH
    ED --> ME
    BS --> ME
    ME --> R
    TR --> R
    R --> BG
    R --> BX
    R --> BD

    %% Click Events
    click UC "https://github.com/yshui/picom/blob/next/picom.sample.conf"
    click UC "https://github.com/yshui/picom/tree/next/tests/configs/"
    click ME "https://github.com/yshui/picom/blob/next/src/picom.c"
    click CM "https://github.com/yshui/picom/blob/next/src/config.c"
    click BG "https://github.com/yshui/picom/tree/next/src/backend/gl/"
    click BX "https://github.com/yshui/picom/tree/next/src/backend/xrender/"
    click BD "https://github.com/yshui/picom/tree/next/src/backend/dummy/"
    click R "https://github.com/yshui/picom/tree/next/src/renderer/"
    click WM "https://github.com/yshui/picom/tree/next/src/wm/"
    click EH "https://github.com/yshui/picom/blob/next/src/event.c"
    click TR "https://github.com/yshui/picom/tree/next/src/transition/"
    click DB "https://github.com/yshui/picom/blob/next/src/dbus.c"
    click UT "https://github.com/yshui/picom/tree/next/src/utils/"

    %% Styles
    classDef configuration fill:#a3c1da,stroke:#000,stroke-width:2px;
    classDef engine fill:#c2e699,stroke:#000,stroke-width:2px;
    classDef renderer fill:#fdd692,stroke:#000,stroke-width:2px;
    classDef backend fill:#cebada,stroke:#000,stroke-width:2px;
    classDef utility fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef build fill:#ffe6cc,stroke:#000,stroke-width:2px;
```
