[TOC]
XDG（跨桌面組）shell是Wayland的標準協議擴展，它描述了應用程序窗口的語義。它定義了兩個wl_surface角色：“toplevel”，用于頂層應用程序窗口，以及“popup”，用于上下文菜單、下拉菜單、工具提示等頂級窗口的子項。將它們放在一起，您可以形成surface的樹，頂級位于頂部，彈出窗口或額外的頂級位于葉子上。該協議還定義了一個定位器接口，用于幫助定位彈出窗口，并限制有關窗口周圍事物的信息。

xdg-shell作為協議擴展，不在wayland.xml中定義。相反，您可以在wayland-protocols軟件包中找到它。它可能安裝在系統上的/usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml之類的路徑上。

xdg_wm_base

xdg_wm_base是規范中定義的唯一全局變量，它提供了創建所需的其他對象的請求。最基本的實現是從處理“ping”事件開始的，當合成器發送它時，您應該及時使用“pong”請求進行響應，以提示您沒有陷入死鎖。另一個請求處理定位器的創建，這是前面提到的對象，我們將在第10章中詳細介紹它們。我們首先要查看的請求是get_xdg_surface。

7.1 XDG surfaces

在xdg-shell領域中的surface被稱為xdg_surface，此接口帶來了兩種類型的XDG surface（頂級和彈出窗口）共同使用的一小部分功能。每種類型的XDG surface的語義仍然存在很大差異，因此必須通過額外的角色明確指定。

xdg_surface接口提供了其他請求，用于分配更具體的頂級和彈出窗口角色。一旦我們將對象綁定到xdg_wm_base全局，我們就可以使用get_xdg_surface請求獲取一個wl_surface的id。

<request name="get_xdg_surface">
  <arg name="id" type="new_id" interface="xdg_surface"/>
  <arg name="surface" type="object" interface="wl_surface"/>
</request>

xdg_surface接口除了包含請求為surface分配更具體的頂級或彈出窗口角色外，還包括一些對兩種角色都重要的功能。在繼續學習頂級和彈出窗口特定的語義之前，讓我們回顧一下這些功能。

<event name="configure">
  <arg name="serial" type="uint" summary="serial of the configure event"/>
</event>

<request name="ack_configure">
  <arg name="serial" type="uint" summary="the serial from the configure event"/>
</request>

xdg_surface最重要的API是一對configure和ack_configure。您可能還記得Wayland的目標是使每一幀都完美無缺。這意味著不會顯示一半應用狀態更改的幀，為了實現這一點，必須在客戶端和服務器之間同步這些更改。對于XDG surface，這對消息是支持此目標的機制。

現在我們只介紹基礎知識，因此我們將總結這兩個事件的重要性如下：來自服務器的事件會通知您surface的配置（或重新配置），并將其應用于掛起狀態。當配置事件到達時，應用掛起的更改，使用ack_configure來確認您已完成操作，并呈現和提交新的一幀。我們將在下一章中展示這一點，并在第8.1章中詳細解釋。

<request name="set_window_geometry">
  <arg name="x" type="int"/>
  <arg name="y" type="int"/>
  <arg name="width" type="int"/>
  <arg name="height" type="int"/>
</request>

set_window_geometry請求主要用于使用客戶端裝飾的應用程序，以區分其surface中被視為窗口的一部分和不被視為窗口的部分。最常見的是，這用于排除被認為是窗口一部分的客戶端陰影。合成器可以使用此信息來管理自己的行為，以安排和與窗口進行交互。

7.2 應用窗口

We have shaved many yaks to get here（俚語），但現在是時候了：XDG頂級層是用于顯示應用程序窗口的接口。 XDG頂級層接口包含許多請求和事件，用于管理應用程序窗口，包括處理最小化和最大化狀態、設置窗口標題等。 我們將在以后的章節中詳細討論它的每個部分，所以現在只關心基礎知識。

根據上一章的知識，我們知道可以從wl_surface獲取xdg_surface，但這只是第一步：將surface帶入XDG shell的懷抱。 下一步是將該XDG surface變成XDG頂級層-“頂級”應用程序窗口，之所以這樣命名，是因為它在最終使用XDG shell創建的窗口和彈出菜單層次結構中的頂級位置。 要創建其中一個，我們可以使用xdg_surface接口的適當請求：

<request name="get_toplevel">
  <arg name="id" type="new_id" interface="xdg_toplevel"/>
</request>

這個新的xdg_toplevel接口為我們提供了許多請求和事件，用于管理應用程序窗口的生命周期。第10章深入探討了這些，但我知道你迫不及待地想在屏幕上看到一些東西。如果你按照以下步驟操作，處理前一章討論的XDG surface的configure和ack_configure裝備，并將wl_buffer附加到我們的wl_surface并提交，應用程序窗口將出現并將緩沖區內容呈現給用戶。下一章提供了示例代碼，實現了上述操作。此外，它還利用了我們尚未介紹的一個額外的XDG頂級請求：

<request name="set_title">
  <arg name="title" type="string"/>
</request>

這應該是相當顯而易見的。還有一個類似的，我們沒有在示例代碼中使用，但可能適合你的應用程序：

<request name="set_app_id">
  <arg name="app_id" type="string"/>
</request>

標題通常顯示在窗口裝飾、任務欄等中，而應用程序ID用于標識你的應用程序或將你的窗口組合在一起。你可以通過將窗口標題設置為“應用程序窗口-Wayland協議-Firefox”，并將應用程序ID設置為“firefox”來利用這些功能。

總之，以下步驟將幫助你從零開始在屏幕上創建一個窗口：

• 綁定到wl_compositor并使用它創建一個wl_surface。
• 綁定到xdg_wm_base并使用它創建一個帶有你的wl_surface的xdg_surface。
• 從xdg_surface使用xdg_surface.get_toplevel創建一個xdg_頂級層。
• 為xdg_surface配置一個監聽器并等待configure事件。
• 綁定到你選擇的緩沖區分配機制（例如wl_shm）并分配一個共享緩沖區，然后將你* 的內容渲染到其中。
• 使用wl_surface.attach將wl_buffer附加到wl_surface。
• 使用xdg_surface.ack_configure，傳遞來自configure的序列號，確認你已經準備好了一幀合適的畫面。
• 發送一個wl_surface.commit請求。

翻到下一頁以查看這些步驟的演示。

7.3 擴展示例代碼

使用到目前為止我們所學的知識，我們現在可以編寫一個Wayland客戶端，以便在屏幕上顯示一些內容。以下代碼是一個完整的Wayland應用程序，它打開一個XDG頂級窗口，并在其上顯示一個640x480的方塊網格。像這樣編譯它：

wayland-scanner private-code \
  < /usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml \
  > xdg-shell-protocol.c
wayland-scanner client-header \
  < /usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml \
  > xdg-shell-client-protocol.h
cc -o client client.c xdg-shell-protocol.c -lwayland-client -lrt

然后運行./client以查看其運行情況，或使用WAYLAND_DEBUG=1 ./client以包含大量有用的調試信息。Tada！在以后的章節中，我們將在此基礎上構建客戶端，因此請將此代碼保存在安全的地方。

#define _POSIX_C_SOURCE 200112L
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdbool.h>
#include <string.h>
#include <sys/mman.h>
#include <time.h>
#include <unistd.h>
#include <wayland-client.h>
#include "xdg-shell-client-protocol.h"

/* Shared memory support code */
static void
randname(char *buf)
{
    struct timespec ts;
    clock_gettime(CLOCK_REALTIME, &ts);
    long r = ts.tv_nsec;
    for (int i = 0; i < 6; ++i) {
        buf[i] = 'A'+(r&15)+(r&16)*2;
        r >>= 5;
    }
}

static int
create_shm_file(void)
{
    int retries = 100;
    do {
        char name[] = "/wl_shm-XXXXXX";
        randname(name + sizeof(name) - 7);
        --retries;
        int fd = shm_open(name, O_RDWR | O_CREAT | O_EXCL, 0600);
        if (fd >= 0) {
            shm_unlink(name);
            return fd;
        }
    } while (retries > 0 && errno == EEXIST);
    return -1;
}

static int
allocate_shm_file(size_t size)
{
    int fd = create_shm_file();
    if (fd < 0)
        return -1;
    int ret;
    do {
        ret = ftruncate(fd, size);
    } while (ret < 0 && errno == EINTR);
    if (ret < 0) {
        close(fd);
        return -1;
    }
    return fd;
}

/* Wayland code */
struct client_state {
    /* Globals */
    struct wl_display *wl_display;
    struct wl_registry *wl_registry;
    struct wl_shm *wl_shm;
    struct wl_compositor *wl_compositor;
    struct xdg_wm_base *xdg_wm_base;
    /* Objects */
    struct wl_surface *wl_surface;
    struct xdg_surface *xdg_surface;
    struct xdg_toplevel *xdg_toplevel;
};

static void
wl_buffer_release(void *data, struct wl_buffer *wl_buffer)
{
    /* Sent by the compositor when it's no longer using this buffer */
    wl_buffer_destroy(wl_buffer);
}

static const struct wl_buffer_listener wl_buffer_listener = {
    .release = wl_buffer_release,
};

static struct wl_buffer *
draw_frame(struct client_state *state)
{
    const int width = 640, height = 480;
    int stride = width * 4;
    int size = stride * height;

    int fd = allocate_shm_file(size);
    if (fd == -1) {
        return NULL;
    }

    uint32_t *data = mmap(NULL, size,
            PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
    if (data == MAP_FAILED) {
        close(fd);
        return NULL;
    }

    struct wl_shm_pool *pool = wl_shm_create_pool(state->wl_shm, fd, size);
    struct wl_buffer *buffer = wl_shm_pool_create_buffer(pool, 0,
            width, height, stride, WL_SHM_FORMAT_XRGB8888);
    wl_shm_pool_destroy(pool);
    close(fd);

    /* Draw checkerboxed background */
    for (int y = 0; y < height; ++y) {
        for (int x = 0; x < width; ++x) {
            if ((x + y / 8 * 8) % 16 < 8)
                data[y * width + x] = 0xFF666666;
            else
                data[y * width + x] = 0xFFEEEEEE;
        }
    }

    munmap(data, size);
    wl_buffer_add_listener(buffer, &wl_buffer_listener, NULL);
    return buffer;
}

static void
xdg_surface_configure(void *data,
        struct xdg_surface *xdg_surface, uint32_t serial)
{
    struct client_state *state = data;
    xdg_surface_ack_configure(xdg_surface, serial);

    struct wl_buffer *buffer = draw_frame(state);
    wl_surface_attach(state->wl_surface, buffer, 0, 0);
    wl_surface_commit(state->wl_surface);
}

static const struct xdg_surface_listener xdg_surface_listener = {
    .configure = xdg_surface_configure,
};

static void
xdg_wm_base_ping(void *data, struct xdg_wm_base *xdg_wm_base, uint32_t serial)
{
    xdg_wm_base_pong(xdg_wm_base, serial);
}

static const struct xdg_wm_base_listener xdg_wm_base_listener = {
    .ping = xdg_wm_base_ping,
};

static void
registry_global(void *data, struct wl_registry *wl_registry,
        uint32_t name, const char *interface, uint32_t version)
{
    struct client_state *state = data;
    if (strcmp(interface, wl_shm_interface.name) == 0) {
        state->wl_shm = wl_registry_bind(
                wl_registry, name, &wl_shm_interface, 1);
    } else if (strcmp(interface, wl_compositor_interface.name) == 0) {
        state->wl_compositor = wl_registry_bind(
                wl_registry, name, &wl_compositor_interface, 4);
    } else if (strcmp(interface, xdg_wm_base_interface.name) == 0) {
        state->xdg_wm_base = wl_registry_bind(
                wl_registry, name, &xdg_wm_base_interface, 1);
        xdg_wm_base_add_listener(state->xdg_wm_base,
                &xdg_wm_base_listener, state);
    }
}

static void
registry_global_remove(void *data,
        struct wl_registry *wl_registry, uint32_t name)
{
    /* This space deliberately left blank */
}

static const struct wl_registry_listener wl_registry_listener = {
    .global = registry_global,
    .global_remove = registry_global_remove,
};

int
main(int argc, char *argv[])
{
    struct client_state state = { 0 };
    state.wl_display = wl_display_connect(NULL);
    state.wl_registry = wl_display_get_registry(state.wl_display);
    wl_registry_add_listener(state.wl_registry, &wl_registry_listener, &state);
    wl_display_roundtrip(state.wl_display);

    state.wl_surface = wl_compositor_create_surface(state.wl_compositor);
    state.xdg_surface = xdg_wm_base_get_xdg_surface(
            state.xdg_wm_base, state.wl_surface);
    xdg_surface_add_listener(state.xdg_surface, &xdg_surface_listener, &state);
    state.xdg_toplevel = xdg_surface_get_toplevel(state.xdg_surface);
    xdg_toplevel_set_title(state.xdg_toplevel, "Example client");
    wl_surface_commit(state.wl_surface);

    while (wl_display_dispatch(state.wl_display)) {
        /* This space deliberately left blank */
    }

    return 0;
}