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

> Explore Hyprland core files and their role in implementing the Wayland core protocol. Understand how C++ objects bridge client requests for a seamless Wayland experience.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: internals
- Published: 2026-07-23

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/Compositor.hpp) and [`Compositor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/Seat.hpp) and [`Seat.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/Output.hpp) and [`Output.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/Subcompositor.hpp) and [`Subcompositor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/Shm.hpp) and [`Shm.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/DataDevice.hpp) and [`DataDevice.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/Instance.hpp) and [`Instance.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/Seat.cpp) aggregates all input devices into a unified seat, while [`Output.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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.

```cpp
// 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`](https://github.com/hyprwm/Hyprland/blob/main/src/protocols/core/Compositor.cpp). The `CWLSurfaceResource` constructor registers a callback that enqueues the pending state, resets the pending accumulator, and schedules the update.

```cpp
// 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`](https://github.com/hyprwm/Hyprland/blob/main/src/protocols/core/Output.cpp). The function then emits geometry, mode, and scale information so the client can render content with correct dimensions.

```cpp
// 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`](https://github.com/hyprwm/Hyprland/blob/main/Compositor.cpp) for surfaces, [`Seat.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Seat.cpp) for input, [`Output.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Output.cpp) for monitors, [`Subcompositor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Subcompositor.cpp) for subsurfaces, [`Shm.cpp`](https://github.com/hyprwm/Hyprland/blob/main/Shm.cpp) for shared memory, [`DataDevice.cpp`](https://github.com/hyprwm/Hyprland/blob/main/DataDevice.cpp) for clipboard, and [`Instance.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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.