What Is the Role of Core Files in Hyprland? A Wayland Protocol Breakdown

The core files in Hyprland implement the mandatory Wayland core protocol, bridging low-level client requests under src/protocols/core/ and start/src/core/ with the compositor's internal C++ objects.

The Hyprland source tree isolates its foundational Wayland protocol logic in a dedicated set of modules that every standards-compliant compositor must expose to clients. Understanding the role of core files in Hyprland is essential for anyone reading the codebase or contributing to the project, because these modules serve as the primary boundary between the official Wayland specification and Hyprland's high-level rendering and window-management architecture.

Where Core Files Live in the Hyprland Repository

In the Hyprland repository, core protocol implementations are concentrated in src/protocols/core/ for the main runtime modules, with an additional bootstrap layer located under start/src/core/. This separation keeps the low-level Wayland plumbing distinct from protocol extensions such as XDG shell or layer shell, making the codebase easier to navigate and maintain.

The Seven Core Protocol Modules

The core files translate Wayland protocol requests into Hyprland's internal data structures. Each module owns a specific subset of the core protocol.

Compositor: Surfaces and Rendering

The Compositor.hpp and Compositor.cpp files in src/protocols/core/ manage the lifecycle of wl_surface objects. They handle surface commits, damage tracking, mapping and unmapping, and forward surface events into Hyprland's rendering pipeline. When a client creates a surface, the compositor instantiates a CWLSurfaceResource and initializes its state queue for synchronized updates.

Seat: Input Aggregation

Seat.hpp and Seat.cpp implement the wl_seat protocol, representing a logical grouping of input devices including the pointer, keyboard, and touch. This module advertises device capabilities, forwards input events to clients, and exposes the wl_data_device_manager interface for clipboard operations. It translates hardware events into the protocol callbacks that applications expect, such as wl_seat.get_pointer.

Output: Monitor Description

The Output.hpp and Output.cpp files expose every physical monitor as a wl_output object. They report geometry, mode lists, scale factors, and HDR capabilities to clients. These files also handle output-specific events like DPMS state changes and tearing notifications, feeding monitor properties directly into the central CCompositor rendering loop.

Subcompositor: Subsurface Support

Subcompositor.hpp and Subcompositor.cpp implement the wl_subcompositor protocol. This allows clients to create subsurfaces with defined stacking order relative to a parent surface, and to control whether subsurface commits are synchronized with the parent or performed independently.

Shm: Shared-Memory Buffers

The Shm.hpp and Shm.cpp modules provide the wl_shm object for traditional shared-memory buffers. They create wl_buffer resources from client-supplied pixel data and integrate those buffers with Hyprland's texture system for CPU-rendered content.

DataDevice: Clipboard and Drag-and-Drop

DataDevice.hpp and DataDevice.cpp handle wl_data_device, wl_data_source, and wl_data_offer. They mediate all clipboard and drag-and-drop transfers between clients, ensuring that data payloads move securely through the compositor rather than directly between applications.

Instance: Compositor Bootstrap

Located in start/src/core/, the Instance.hpp and Instance.cpp files boot the compositor at startup. They create the CWLCompositorProtocol manager, register every core protocol with the Wayland display, and link the resulting resources to Hyprland's internal state for monitors, windows, and the event loop.

Key Design Principles of the Core Layer

Bridging Wayland and Hyprland Internals

The core files expose the official Wayland objects that clients require. Internally, they translate those objects into Hyprland's own C++ classes such as CWindow, CMonitor, and CWL*Resource. This translation layer allows the compositor to render, position, and manipulate windows using its own architecture while remaining protocol-compliant.

Resource Management

Every core object owns an underlying wl_resource. The code guarantees proper lifetime handling, destroying resources automatically when a client disconnects and forwarding protocol callbacks to Hyprland's event system. This prevents leaks and dangling references in long-running sessions.

State Synchronization

Commit handling inside Compositor.cpp queues pending surface states, respects DMABUF fences for synchronization, and updates textures only when safe. This sequencing eliminates visual tearing and race conditions between the client and the display engine.

Input and Output Integration

Seat.cpp aggregates all input devices into a unified seat, while Output.cpp advertises monitor properties to clients. Both feed their data into the central CCompositor object, which drives the rendering loop and dispatches input events to the appropriate surfaces.

Extensibility Through Isolation

By confining the core protocol implementations to a single directory, Hyprland can add or replace extensions such as XDG shell or layer shell without modifying the low-level Wayland plumbing. This modularity keeps the core stable while the feature set evolves.

How Client Requests Flow Through Core Files

Client requests enter Hyprland through these core modules, where they are wrapped in C++ resources and scheduled for processing. The following snippets show the exact path from raw Wayland request to internal compositor action.

Creating a Surface

The binding manager in start/src/core/Instance.cpp responds to wl_compositor.create_surface by instantiating a CWLSurfaceResource. Inside CWLCompositorResource::bindManager, a lambda captures the request and emits a newSurface event that Hyprland's window manager observes.

// In CWLCompositorResource::bindManager (Instance.cpp)
m_resource->setCreateSurface([](CWlCompositor* r, uint32_t id) {
    const auto RESOURCE = PROTO::compositor->m_surfaces.emplace_back(
        makeShared<CWLSurfaceResource>(makeShared<CWlSurface>(r->client(), r->version(), id)));

    // Initialise state queue and emit creation event
    RESOURCE->m_stateQueue = CSurfaceStateQueue(RESOURCE);
    PROTO::compositor->m_events.newSurface.emit(RESOURCE);
});

Handling a Surface Commit

When a client calls wl_surface.commit, the pending buffer and state changes arrive in src/protocols/core/Compositor.cpp. The CWLSurfaceResource constructor registers a callback that enqueues the pending state, resets the pending accumulator, and schedules the update.

// In CWLSurfaceResource constructor (Compositor.cpp)
m_resource->setCommit([this](CWlSurface* r) {
    // Validate pending state, enqueue it, then schedule processing
    auto state = m_stateQueue.enqueue(makeUnique<SSurfaceState>(m_pending));
    m_pending.reset();
    m_events.stateCommit.emit(state);
    scheduleState(state);
});

Reporting Monitor Geometry

Clients discover monitors by binding wl_output, which triggers CWLOutputResource::bind in src/protocols/core/Output.cpp. The function then emits geometry, mode, and scale information so the client can render content with correct dimensions.

// In Output.cpp – when a client binds wl_output
void CWLOutputResource::bind(wl_client* client, uint32_t version, uint32_t id) {
    const auto OUTPUT = PROTO::outputs->create(...);
    // Send geometry, mode, scale, etc.
    OUTPUT->sendGeometry(...);
    OUTPUT->sendMode(...);
}

Summary

• The core files in Hyprland implement the mandatory Wayland core protocol under src/protocols/core/ and start/src/core/.
• They act as a translation layer between raw Wayland requests and Hyprland's internal C++ classes such as CWindow, CMonitor, and CWLSurfaceResource.
• Each module owns a specific protocol area: Compositor.cpp for surfaces, Seat.cpp for input, Output.cpp for monitors, Subcompositor.cpp for subsurfaces, Shm.cpp for shared memory, DataDevice.cpp for clipboard, and Instance.cpp for startup.
• The design emphasizes resource safety, state synchronization via commit queues and DMABUF fences, and modular isolation so that extensions can be added without touching core protocol code.

Frequently Asked Questions

What are the core files in Hyprland?

The core files are the C++ source modules located primarily in src/protocols/core/ and start/src/core/ that implement the Wayland core protocol. They expose the standard interfaces—such as wl_compositor, wl_seat, and wl_output—that every Wayland client expects, and they translate those protocol requests into Hyprland's internal data structures.

How do core files handle surface updates without tearing?

Surface updates are processed through a commit queue in src/protocols/core/Compositor.cpp. Pending states are enqueued, validated, and scheduled for application only after DMABUF synchronization fences signal that the buffer is ready. This sequencing prevents race conditions and eliminates visual tearing.

Why is the core protocol implementation isolated from other Hyprland modules?

Isolation keeps the low-level Wayland plumbing separate from high-level features and protocol extensions such as XDG shell or layer shell. According to the Hyprland source code, this architecture allows developers to add or replace extensions without risking regressions in the mandatory core protocol that all clients depend on.

What happens when a client requests a new wl_surface?

The request is handled in start/src/core/Instance.cpp inside CWLCompositorResource::bindManager. The core code creates a CWLSurfaceResource, initializes its CSurfaceStateQueue, and emits a newSurface event so that Hyprland's window manager and rendering pipeline can track the new surface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}