feat(wayland): implement cross-process subsurface protocol and rendering integration

[wineee]

Move the qtwaylandscanner tool and its CMake functions from
src/modules/tools/ to waylib/tools/, and update all src/modules/
CMakeLists.txt to remove references to the locally-generated
protocol .c files that are no longer needed.

Summary by Sourcery

Introduce a cross-process subsurface management protocol in Waylib and centralize Wayland server protocol code generation via a Waylib tool, cleaning up module-specific build references.

New Features:

• Add WCrossSubsurfaceManagerV1 protocol implementation and expose it through the Waylib server, including logging and server interface wiring.
• Integrate cross-process (remote) subsurface handling into WSurfaceItem, including creation, ordering, visibility and position updates.
• Attach and configure the cross subsurface manager during compositor startup via Helper::init.
• Provide a Waylib-side qtwaylandscanner executable and a generic waylib_generate_qtwayland_server_protocol CMake function with a compatibility alias for existing modules.

Enhancements:

• Refactor subsurface container management in WSurfaceItem to support separate containers for remote subsurfaces above and below the parent surface.
• Extend Waylib CMake configuration to build tools from waylib/tools and to use TreelandProtocols for protocol XML definitions.

Build:

• Move qtwaylandscanner build logic from src/modules/tools to waylib/tools, renaming targets and adjusting cross-compiling ExternalProject configuration.
• Replace module-local protocol .c file references in multiple src/modules/* CMakeLists.txt with centralized Waylib protocol generation, and remove the src/modules/tools subdirectory from the modules build.
• Add a waylib_generate_qtwayland_server_protocol function and a compatibility wrapper local_qtwayland_server_protocol_treeland for existing code.
• Update waylib/src/server/CMakeLists.txt to include new cross subsurface protocol sources and generated code, and require TreelandProtocols.

Documentation:

• Update internal SKILL documentation to reference waylib/tools/CMakeLists.txt instead of src/modules/tools/CMakeLists.txt.

[deepin-ci-robot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[sourcery-ai]

Reviewer's Guide

Introduces a Waylib-level qtwaylandscanner tool and cross-process subsurface protocol support, wiring a new WCrossSubsurfaceManagerV1 into the compositor and WSurfaceItem so remote subsurfaces are tracked, positioned, ordered, and mapped/unmapped, while cleaning up module CMakeLists to stop using generated .c protocol stubs from src/modules/tools.

Sequence diagram for remote subsurface creation and mapping

sequenceDiagram
    actor ClientApp
    participant Manager as WCrossSubsurfaceManagerV1
    participant Exp as ExportedSurfaceContext
    participant Remote as RemoteSubsurfaceContext
    participant ParentItem as WSurfaceItem
    participant Priv as WSurfaceItemPrivate

    ClientApp->>Manager: export_surface(resource, id, surfaceResource)
    Manager-->>ClientApp: send_surface_token(token)
    ClientApp->>Exp: create_remote_subsurface(resource, id, parent_token)
    Exp->>Manager: addChildToParent(RemoteSubsurfaceContext)
    Manager->>Manager: trackCommits(Remote)
    Manager-->>ParentItem: remoteSubsurfaceAdded(parent, child)
    ParentItem->>Priv: addRemoteSubsurfaceItem(child)

    Remote->>Remote: recheckMapping()
    alt [parent mapped and childHasBuffer]
        Remote->>Manager: emitRemoteSubsurfaceMapped(parent, child)
        Manager-->>ParentItem: remoteSubsurfaceMapped(parent, child)
        ParentItem->>Priv: remoteSubsurfaceItems[child].setVisible(true)
    end

Loading

File-Level Changes

Change	Details	Files
Implement cross-process subsurface management and integrate it with WSurfaceItem rendering and lifecycle.	Add static WSurfaceItem::setCrossSubsurfaceManager and store a global manager pointer for use by all WSurfaceItem instances. Extend WSurfaceItemPrivate with containers, bookkeeping, and connection lists for remote subsurfaces, including setup/teardown and position updates tied to surface lifecycle and size ratio changes. Ensure remote subsurface items are created, parented, stacked above/below the main surface, and cleaned up alongside standard subsurface items and visibility toggles.	waylib/src/server/qtquick/wsurfaceitem.cpp waylib/src/server/qtquick/wsurfaceitem.h waylib/src/server/qtquick/private/wsurfaceitem_p.h
Add WCrossSubsurfaceManagerV1 Wayland protocol implementation to manage exported surfaces and remote subsurface relationships, including ordering, mapping, and position tracking.	Implement WCrossSubsurfaceManagerV1 with private helper classes to export wl_surface objects, assign tokens, and create treeland_remote_subsurface_v1 objects enforcing acyclic parent-child relationships. Track children above/below each parent with ordered lists, and emit signals on add/remove/map/unmap/position/order changes for use by the scene graph. Provide query helpers for remote children, parent lookup, position, and remote-subsurface checks based on internal token/context maps.	waylib/src/server/protocols/wcrosssubsurfacemanagerv1.cpp waylib/src/server/protocols/wcrosssubsurfacemanagerv1.h waylib/src/server/protocols/WCrossSubsurfaceManagerV1
Wire the new cross subsurface manager into the compositor startup, logging, and Waylib server build, and generate its protocol code via the new qtwaylandscanner helper.	Attach WCrossSubsurfaceManagerV1 to WServer during Helper::init and pass it to WSurfaceItem via the new static setter. Add logging category lcWlCrossSubsurface and include the new protocol source/header in WaylibServer SOURCES/HEADERS. Find TreelandProtocols, call waylib_generate_qtwayland_server_protocol for the treeland-cross-subsurface-unstable-v1 XML, and ensure the generated server code is compiled.	src/seat/helper.cpp waylib/src/server/wayliblogging.cpp waylib/src/server/wayliblogging.h waylib/src/server/CMakeLists.txt
Refactor qtwaylandscanner tooling into waylib/tools, rename the executable, and expose a reusable protocol-generation CMake function while cleaning module CMakeLists of old generated .c protocol references.	Move qtwaylandscanner CMake project from src/modules/tools to waylib/tools, rename targets from qtwaylandscanner_treeland to qtwaylandscanner, and adjust cross-compilation ExternalProject wiring and host build linking to Qt6::Core. Introduce waylib_generate_qtwayland_server_protocol(target) that generates server headers and sources, marks them GENERATED/SKIP_AUTOMOC, adds both the common server_code and generated code to target_sources, and keeps a compatibility alias local_qtwayland_server_protocol_treeland. Update waylib top-level CMakeLists to add_subdirectory(tools) and remove src/modules/tools from the modules build; drop explicit references to generated wayland-*-server-protocol.c files from each module’s impl_treeland SOURCE list, relying instead on the central protocol generation. Adjust SKILL.md documentation to point at waylib/tools/CMakeLists.txt instead of src/modules/tools/CMakeLists.txt.	waylib/tools/CMakeLists.txt waylib/CMakeLists.txt src/modules/CMakeLists.txt src/modules/activation/CMakeLists.txt src/modules/app-id-resolver/CMakeLists.txt src/modules/dde-shell/CMakeLists.txt src/modules/ddm/CMakeLists.txt src/modules/foreign-toplevel/CMakeLists.txt src/modules/input-manager/CMakeLists.txt src/modules/keyboard-state-notify/CMakeLists.txt src/modules/output-manager/CMakeLists.txt src/modules/personalization/CMakeLists.txt src/modules/prelaunch-splash/CMakeLists.txt src/modules/screensaver/CMakeLists.txt src/modules/shortcut/CMakeLists.txt src/modules/virtual-output/CMakeLists.txt src/modules/wallpaper/CMakeLists.txt src/modules/wallpaper-color/CMakeLists.txt src/modules/window-management/CMakeLists.txt src/modules/wine-window-management/CMakeLists.txt src/modules/wine-window-state/CMakeLists.txt .agents/skills/treeland-private-wayland-protocol/SKILL.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Pull request overview

EN: This PR centralizes Wayland server protocol code generation into Waylib (moving qtwaylandscanner into waylib/tools), and introduces a new cross-process (remote) subsurface protocol (WRemoteSubsurfaceManagerV1) with rendering integration via WSurfaceItem, wired up during compositor startup.

**中文：**本 PR 将 Wayland 服务端协议代码生成能力集中到 Waylib（把 qtwaylandscanner 移到 waylib/tools），并新增跨进程（remote）subsurface 协议实现（WRemoteSubsurfaceManagerV1），同时将其渲染集成进 WSurfaceItem，并在启动初始化阶段完成挂载。

Changes / 变更：

• Add remote subsurface manager protocol implementation + logging category, and hook it into compositor startup.
• Integrate remote subsurface child item creation/ordering/visibility/position updates into WSurfaceItem.
• Move/rename qtwaylandscanner tooling into Waylib and remove many module-local generated protocol .c references.

Reviewed changes

Copilot reviewed 32 out of 33 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
waylib/tools/qtwaylandscanner.cpp	Adds Waylib-owned QtWayland scanner tool source (moved in).
waylib/tools/CMakeLists.txt	Builds qtwaylandscanner in Waylib and provides protocol generation helper + compatibility alias.
waylib/src/server/wayliblogging.h	Declares new Waylib logging category for remote subsurface protocol.
waylib/src/server/wayliblogging.cpp	Defines lcWlRemoteSubsurface category.
waylib/src/server/qtquick/wsurfaceitem.h	Adds static setter to inject remote subsurface manager into WSurfaceItem.
waylib/src/server/qtquick/wsurfaceitem.cpp	Implements remote subsurface item lifecycle, ordering, visibility and position updates.
waylib/src/server/qtquick/private/wsurfaceitem_p.h	Adds private helpers/state for remote subsurface containers and connections.
waylib/src/server/protocols/wremotesubsurfacemanagerv1.h	Introduces public server interface for remote subsurface manager protocol.
waylib/src/server/protocols/wremotesubsurfacemanagerv1.cpp	Implements protocol objects, token export, parent/child relationship management, and mapping logic.
waylib/src/server/protocols/WRemoteSubsurfaceManagerV1	Provides installed wrapper include for WRemoteSubsurfaceManagerV1.
waylib/src/server/CMakeLists.txt	Adds TreelandProtocols dependency, protocol sources, and protocol code generation invocation.
waylib/CMakeLists.txt	Adds waylib/tools subdirectory to the build.
src/seat/helper.cpp	Attaches WRemoteSubsurfaceManagerV1 and injects it into WSurfaceItem during startup.
src/modules/wine-window-state/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/wine-window-management/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/window-management/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/wallpaper/CMakeLists.txt	Removes module-local generated server-protocol .c source references.
src/modules/wallpaper-color/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/virtual-output/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/shortcut/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/screensaver/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/prelaunch-splash/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/personalization/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/output-manager/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/keyboard-state-notify/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/input-manager/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/foreign-toplevel/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/ddm/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/dde-shell/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/CMakeLists.txt	Stops building the old src/modules/tools subdirectory.
src/modules/app-id-resolver/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
src/modules/activation/CMakeLists.txt	Removes module-local generated server-protocol .c source reference.
.agents/skills/treeland-private-wayland-protocol/SKILL.md	Updates internal documentation to point to waylib/tools/CMakeLists.txt.

Suppressed comments (1)

waylib/tools/CMakeLists.txt:17

• EN: The fallback logic for NATIVE_PREFIX is broken: string(SUBSTRING ${idx} NATIVE_PREFIX) is invalid (wrong signature) and idx is not defined here. This will fail CMake configure for cross-compiling when NATIVE_PREFIX is not provided.
  中文：NATIVE_PREFIX 的兜底逻辑有问题：string(SUBSTRING ${idx} NATIVE_PREFIX) 参数签名不正确且这里没有定义 idx，在交叉编译且未显式设置 NATIVE_PREFIX 时会导致 CMake 配置失败。

[Copilot]

Pull request overview

Copilot reviewed 35 out of 36 changed files in this pull request and generated 4 comments.

Suppressed comments (10)

waylib/tools/CMakeLists.txt:38

• PR 描述承诺保留 local_qtwayland_server_protocol_treeland 兼容包装器，但本文件只定义了新函数；现有外部调用会在配置阶段失败，仓库内 skill 也仍引用旧名称。请添加转发别名，或同步修正 PR 契约和所有文档。 / The PR description promises a local_qtwayland_server_protocol_treeland compatibility wrapper, but only the new function is defined; existing external call sites will fail at configure time, and the repository skill still references the old name. Add a forwarding alias or update the stated contract and all documentation.
  waylib/src/server/protocols/wremotesubsurfacemanagerv1.cpp:656
• 协议要求“子表面添加”在父表面 commit 时双缓冲应用；这里立即加入活动列表并开始跟踪/映射，所以已映射父表面上的带缓冲 child 会在请求处理期间立刻出现。请保存 pending 关系，并在下一次父表面 commit 时再发布 added/mapped 状态。 / The protocol requires subsurface addition to be double-buffered on the parent commit. Adding it to the active list and mapping immediately makes a buffered child appear during request handling when the parent is already mapped. Store a pending relationship and publish the added/mapped state on the next parent commit.

    m_manager->addChildToParent(remote);
    m_manager->trackCommits(remote);

waylib/src/server/protocols/wremotesubsurfacemanagerv1.cpp:769

• cascadeUnmap() 这里只更新内部标志和信号，没有调用 wlr_surface_unmap()。因此递归的孙级表面以及从 destroy_resource() 直接进入此函数的 child 仍保持 wlroots mapped=true，违反 destroy 必须立即 unmap 的协议语义。请把实际 unmap 纳入每个节点的级联路径。 / cascadeUnmap() only updates internal flags/signals and never calls wlr_surface_unmap(). Recursive grandchildren, and children reaching this function directly from destroy_resource(), therefore remain mapped=true in wlroots, violating the protocol's immediate-unmap requirement. Perform the native unmap for every node in the cascade.

    m_mapped = false;
    m_manager->emitRemoteSubsurfaceUnmapped(parentSurface(), childSurface());

waylib/src/server/protocols/wremotesubsurfacemanagerv1.cpp:783

• set_position 按协议应在父表面下一次 commit 时应用，但这里立即覆盖 current position 并发信号，渲染会提前移动。请维护 pending/current position，并只在父 commit 时更新及发信号。 / The protocol requires set_position to take effect on the next parent commit, but this immediately overwrites the current position and emits the rendering signal. Keep pending/current position state and publish it only from the parent commit.

    m_position = QPointF(x, y);
    m_manager->emitRemoteSubsurfacePositionChanged(childSurface(), m_position);

waylib/src/server/protocols/wremotesubsurfacemanagerv1.cpp:792

• place_above/place_below 的 z-order 也应在父表面 commit 时双缓冲；这里的 helper 立即修改活动列表并发送 orderChanged，所以请求在 commit 前已经可见。请将目标顺序保存为 pending，并在父 commit 时原子应用。 / place_above/place_below z-order is also double-buffered on the parent, but these helpers mutate the active lists and emit orderChanged immediately, making the request visible before commit. Store pending ordering and apply it atomically on the parent commit.

    if (sibling_token.isEmpty()) {
        m_manager->placeChildAboveParentTop(this);
        qCDebug(lcWlRemoteSubsurface) << "place_above: child" << m_child->token() << "→ top";

waylib/src/server/qtquick/wsurfaceitem.cpp:1561

• 映射发生在 subsurfacesVisible == false 时会把 child 自身永久设为不可见；之后 setSubsurfacesVisible(true) 只恢复 container，不会恢复 child。child 的映射可见性应独立设为 true，由 container 统一控制全局开关。 / If mapping occurs while subsurfacesVisible is false, this permanently hides the child itself; setSubsurfacesVisible(true) later only restores the container. Mark the mapped child visible independently and let the container own the global visibility switch.
  waylib/src/server/qtquick/wsurfaceitem.cpp:1607
• 若 WSurfaceItem 在关系已 mapped 后才创建，setup 只重放 Added、不重放 Mapped，而这里无条件隐藏 item，导致它一直不可见直到以后发生一次 unmap/remap。请用 child 当前 mapped 状态初始化。 / When a WSurfaceItem is created after the relationship is already mapped, setup replays only Added, not Mapped; unconditionally hiding the item leaves it invisible until a later unmap/remap. Initialize it from the child's current mapped state.
  waylib/src/server/protocols/wremotesubsurfacemanagerv1.cpp:703
• 协议明确要求忽略 remote subsurface 的 wl_surface.offset，但角色没有 client_commit 处理器；wlroots 仍会提交 offset，且 WSurfacePrivate::updateBufferOffset() 会消费它，导致内容产生协议禁止的额外位移。请在角色提交路径中丢弃 pending offset。 / The protocol explicitly requires wl_surface.offset to be ignored for remote subsurfaces, but this role has no client_commit handler; wlroots can still commit the offset and WSurfacePrivate::updateBufferOffset() consumes it, producing a forbidden extra displacement. Discard the pending offset in the role commit path.

        .client_commit = nullptr,

waylib/src/server/qtquick/wsurfaceitem.cpp:1545

• remote position 在三个路径中都直接作为 item 坐标使用，既没有加上父表面的 contentContainer->position()（标准 subsurface 在 updateSubsurfaceItem() 中会加），动态移动后也未刷新父项 bounding rect；带 padding/content offset 的父表面会错位，旧边界还会影响裁剪/命中。请集中成一个坐标转换 helper，并在位置改变后调用 updateBoundingRect()。 / All three remote-position paths use surface coordinates directly as item coordinates, omitting the parent's contentContainer->position() that standard subsurfaces add in updateSubsurfaceItem(); dynamic moves also do not refresh the parent bounding rect. Parents with padding/content offsets render incorrectly and retain stale clipping/hit bounds. Centralize the coordinate conversion and call updateBoundingRect() after moves.

This issue also appears on line 1559 of the same file.
.agents/skills/treeland-private-wayland-protocol/SKILL.md:31

• 这里只更新了工具文件路径，但同一 skill 的 Build Path、触发条件和示例仍要求已被本 PR 移除的 local_qtwayland_server_protocol_treeland(...)。合并后 agent 会继续生成无效 CMake；请将所有引用改为新 canonical helper（或真正提供并说明兼容别名）。 / This updates only the tool-file path, while the same skill's Build Path, triggers, and examples still require local_qtwayland_server_protocol_treeland(...), which this PR removes. Agents will continue generating invalid CMake; update every reference to the new canonical helper (or actually provide and document the compatibility alias).

2. `waylib/tools/CMakeLists.txt`

[zzxyb]

这个计算要小心

[sourcery-ai]

Sorry @wineee, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: wineee, zccrs

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[deepin-bot]

TAG Bot

New tag: 0.8.18
DISTRIBUTION: unstable
Suggest: synchronizing this PR through rebase #1286