[TOC]
XDG（跨桌面組）shell是Wayland的標(biāo)準(zhǔn)協(xié)議擴(kuò)展，它描述了應(yīng)用程序窗口的語(yǔ)義。它定義了兩個(gè)wl_surface角色：“toplevel”，用于頂層應(yīng)用程序窗口，以及“popup”，用于上下文菜單、下拉菜單、工具提示等頂級(jí)窗口的子項(xiàng)。將它們放在一起，您可以形成surface的樹(shù)，頂級(jí)位于頂部，彈出窗口或額外的頂級(jí)位于葉子上。該協(xié)議還定義了一個(gè)定位器接口，用于幫助定位彈出窗口，并限制有關(guān)窗口周?chē)挛锏男畔ⅰ?/p>

xdg-shell作為協(xié)議擴(kuò)展，不在wayland.xml中定義。相反，您可以在wayland-protocols軟件包中找到它。它可能安裝在系統(tǒng)上的/usr/share/wayland-protocols/stable/xdg-shell/xdg-shell.xml之類(lèi)的路徑上。

xdg_wm_base

xdg_wm_base是規(guī)范中定義的唯一全局變量，它提供了創(chuàng)建所需的其他對(duì)象的請(qǐng)求。最基本的實(shí)現(xiàn)是從處理“ping”事件開(kāi)始的，當(dāng)合成器發(fā)送它時(shí)，您應(yīng)該及時(shí)使用“pong”請(qǐng)求進(jìn)行響應(yīng)，以提示您沒(méi)有陷入死鎖。另一個(gè)請(qǐng)求處理定位器的創(chuàng)建，這是前面提到的對(duì)象，我們將在第10章中詳細(xì)介紹它們。我們首先要查看的請(qǐng)求是get_xdg_surface。

7.1 XDG surfaces

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

xdg_surface接口提供了其他請(qǐng)求，用于分配更具體的頂級(jí)和彈出窗口角色。一旦我們將對(duì)象綁定到xdg_wm_base全局，我們就可以使用get_xdg_surface請(qǐng)求獲取一個(gè)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接口除了包含請(qǐng)求為surface分配更具體的頂級(jí)或彈出窗口角色外，還包括一些對(duì)兩種角色都重要的功能。在繼續(xù)學(xué)習(xí)頂級(jí)和彈出窗口特定的語(yǔ)義之前，讓我們回顧一下這些功能。

<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是一對(duì)configure和ack_configure。您可能還記得Wayland的目標(biāo)是使每一幀都完美無(wú)缺。這意味著不會(huì)顯示一半應(yīng)用狀態(tài)更改的幀，為了實(shí)現(xiàn)這一點(diǎn)，必須在客戶端和服務(wù)器之間同步這些更改。對(duì)于XDG surface，這對(duì)消息是支持此目標(biāo)的機(jī)制。

現(xiàn)在我們只介紹基礎(chǔ)知識(shí)，因此我們將總結(jié)這兩個(gè)事件的重要性如下：來(lái)自服務(wù)器的事件會(huì)通知您surface的配置（或重新配置），并將其應(yīng)用于掛起狀態(tài)。當(dāng)配置事件到達(dá)時(shí)，應(yīng)用掛起的更改，使用ack_configure來(lái)確認(rèn)您已完成操作，并呈現(xiàn)和提交新的一幀。我們將在下一章中展示這一點(diǎn)，并在第8.1章中詳細(xì)解釋。

<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請(qǐng)求主要用于使用客戶端裝飾的應(yīng)用程序，以區(qū)分其surface中被視為窗口的一部分和不被視為窗口的部分。最常見(jiàn)的是，這用于排除被認(rèn)為是窗口一部分的客戶端陰影。合成器可以使用此信息來(lái)管理自己的行為，以安排和與窗口進(jìn)行交互。

7.2 應(yīng)用窗口

We have shaved many yaks to get here（俚語(yǔ)），但現(xiàn)在是時(shí)候了：XDG頂級(jí)層是用于顯示應(yīng)用程序窗口的接口。 XDG頂級(jí)層接口包含許多請(qǐng)求和事件，用于管理應(yīng)用程序窗口，包括處理最小化和最大化狀態(tài)、設(shè)置窗口標(biāo)題等。 我們將在以后的章節(jié)中詳細(xì)討論它的每個(gè)部分，所以現(xiàn)在只關(guān)心基礎(chǔ)知識(shí)。

根據(jù)上一章的知識(shí)，我們知道可以從wl_surface獲取xdg_surface，但這只是第一步：將surface帶入XDG shell的懷抱。 下一步是將該XDG surface變成XDG頂級(jí)層-“頂級(jí)”應(yīng)用程序窗口，之所以這樣命名，是因?yàn)樗谧罱K使用XDG shell創(chuàng)建的窗口和彈出菜單層次結(jié)構(gòu)中的頂級(jí)位置。 要?jiǎng)?chuàng)建其中一個(gè)，我們可以使用xdg_surface接口的適當(dāng)請(qǐng)求：

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

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

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

這應(yīng)該是相當(dāng)顯而易見(jiàn)的。還有一個(gè)類(lèi)似的，我們沒(méi)有在示例代碼中使用，但可能適合你的應(yīng)用程序：

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

標(biāo)題通常顯示在窗口裝飾、任務(wù)欄等中，而應(yīng)用程序ID用于標(biāo)識(shí)你的應(yīng)用程序或?qū)⒛愕拇翱诮M合在一起。你可以通過(guò)將窗口標(biāo)題設(shè)置為“應(yīng)用程序窗口-Wayland協(xié)議-Firefox”，并將應(yīng)用程序ID設(shè)置為“firefox”來(lái)利用這些功能。

總之，以下步驟將幫助你從零開(kāi)始在屏幕上創(chuàng)建一個(gè)窗口：

• 綁定到wl_compositor并使用它創(chuàng)建一個(gè)wl_surface。
• 綁定到xdg_wm_base并使用它創(chuàng)建一個(gè)帶有你的wl_surface的xdg_surface。
• 從xdg_surface使用xdg_surface.get_toplevel創(chuàng)建一個(gè)xdg_頂級(jí)層。
• 為xdg_surface配置一個(gè)監(jiān)聽(tīng)器并等待configure事件。
• 綁定到你選擇的緩沖區(qū)分配機(jī)制（例如wl_shm）并分配一個(gè)共享緩沖區(qū)，然后將你* 的內(nèi)容渲染到其中。
• 使用wl_surface.attach將wl_buffer附加到wl_surface。
• 使用xdg_surface.ack_configure，傳遞來(lái)自configure的序列號(hào)，確認(rèn)你已經(jīng)準(zhǔn)備好了一幀合適的畫(huà)面。
• 發(fā)送一個(gè)wl_surface.commit請(qǐng)求。

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

7.3 擴(kuò)展示例代碼

使用到目前為止我們所學(xué)的知識(shí)，我們現(xiàn)在可以編寫(xiě)一個(gè)Wayland客戶端，以便在屏幕上顯示一些內(nèi)容。以下代碼是一個(gè)完整的Wayland應(yīng)用程序，它打開(kāi)一個(gè)XDG頂級(jí)窗口，并在其上顯示一個(gè)640x480的方塊網(wǎng)格。像這樣編譯它：

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

然后運(yùn)行./client以查看其運(yùn)行情況，或使用WAYLAND_DEBUG=1 ./client以包含大量有用的調(diào)試信息。Tada！在以后的章節(jié)中，我們將在此基礎(chǔ)上構(gòu)建客戶端，因此請(qǐng)將此代碼保存在安全的地方。

#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;
}