典型的Wayland client编程实例

1 一、连接服务端
2 二、查询所有已注册的协议对象（接口）
3 三、创建surface
4 四、创建缓存并绑定到surface
5 五提交surface并显示

一、连接服务端

wayland是一个CS的协议架构。client第一步要做的就是连接server，也就是compositor。使用的方法是wl_display_connect。参数为NULL时，表示使用默认的名字“wayland-0”。

函数调用成功的话，会返回一个wl_display类型的变量——display，可以简单理解为client和server之间的连接标识。

连接server

// Connect to the Wayland compositor
struct wl_display *display = wl_display_connect(NULL);
if (display == NULL) {
    fprintf(stderr, "failed to create display\n");
    return EXIT_FAILURE;
}

二、查询所有已注册的协议对象（接口）

为什么要查询所有已注册协议对象（接口）？先说结论，这是因为wayland的扩展协议是以模块化形式编码及动态注册到服务端的。所以client也需要动态查看服务端目前支持的协议，从而决定自己使用什么协议完成编程。

这里动态注册是指compositor启动时，实时判断当前的资源之后，再决定是否注册该协议到服务端。另外对于同一类资源，如缓存，还有多种协议实现，client可以动态选择不同资源接口实现目的。所以需要查询接口是否存在，以及确认它的版本。

wl_display_get_registry获取一个绑定到输入参数display上的registry对象返回。这个函数实际上会请求服务端发送所有已注册的协议对象给客户端。所以下一步要将服务端的response进行处理。

wl_registry_add_listener的作用是将一个处理registry事件的函数绑定到registry事件上。实际上wl_registry_add_listener内部是调用wl_proxy_add_listener( cast(wl_proxy*)wl_registry, cast(Callback*)listener, data)来完成的。

这里的callback就是用来处理服务端返回的所有interface 的registry事件的。

wl_display_roundtrip() 阻塞当前执行流，等待服务端处理完所有异步请求，这里就是请求是指wl_display_get_registry发送的获取所有registry对象的请求。

// Obtain the wl_registry and fetch the list of globals
    struct wl_registry *registry = wl_display_get_registry(display);
    wl_registry_add_listener(registry, &registry_listener, NULL);
    if (wl_display_roundtrip(display) == -1) {
        return EXIT_FAILURE;
    }
 
    // Check that all globals we require are available
    if (shm == NULL || compositor == NULL || xdg_wm_base == NULL) {
        fprintf(stderr, "no wl_shm, wl_compositor or xdg_wm_base support\n");
        return EXIT_FAILURE;
    }

上述代码中的registry_listener是一个wl_registry_listener 类型的结构体。该结构体包含两个函数成员做回调函数，用于处理接口的注册和移除事件。有点意思的是name并不是一个字符串，可以理解为服务端返回的可以用于wl_registry_bind做绑定的一个可表唯一的id值。

可以看到在registry_handle_global方法中，程序先判断接口的名字是否是程序需要的，如果是，则通过wl_registry_bind绑定该接口——实际上是向服务器申请获取这个接口类型的一个id引用，后续就可以用该id调用相关的方法。

registry_listener

static void
registry_handle_global(void *data, struct wl_registry *registry,
        uint32_t name, const char *interface, uint32_t version)
{
    printf("interface: '%s', version: %d, name: %d\n",
            interface, version, name);
    if (strcmp(interface, wl_shm_interface.name) == 0) {
        shm = wl_registry_bind(registry, name, &wl_shm_interface, 1);
    } else if (strcmp(interface, wl_seat_interface.name) == 0) {
        struct wl_seat *seat =
            wl_registry_bind(registry, name, &wl_seat_interface, 1);
        wl_seat_add_listener(seat, &seat_listener, NULL);
    } else if (strcmp(interface, wl_compositor_interface.name) == 0) {
        compositor = wl_registry_bind(registry, name,
            &wl_compositor_interface, 1);
    } else if (strcmp(interface, xdg_wm_base_interface.name) == 0) {
        xdg_wm_base = wl_registry_bind(registry, name, &xdg_wm_base_interface, 1);
        xdg_wm_base_add_listener(xdg_wm_base, &xdg_wm_base_listener, NULL);
    }
}
 
static void
registry_handle_global_remove(void *data, struct wl_registry *registry,
        uint32_t name)
{
    // This space deliberately left blank
}
 
static const struct wl_registry_listener
registry_listener = {
    .global = registry_handle_global,
    .global_remove = registry_handle_global_remove,
};

2.1 这些对象是什么，谁注册了这些对象，这些对象和什么有关

这些对象如下所示。大部分对象由server注册，还有些则由egl实现注册。name实际上表示的是这个接口在服务端的一个id序号，用于绑定接口。

对象列表

2.2 由wayland server注册的对象

它们由wayland server注册，如下代码所示，具体的注册方法是wl_global_create。

registry dma buf

上面的代码截取自mutter。可以看到这段代码查询了系统当前的egl是否存在EGL_EXT_image_dma_buf_import_modifiers扩展，如果不存在，就不注册zwp_linux_dmabuf_v1_interface到系统中。所以说这些对象和系统当前的egl实现（开源egl实现是mesa）有关。

2.2 由egl实现——mesa注册的对象

另外还有些协议对象是由mesa实现的，如mesa主目录下的 src/egl/wayland/wayland-drm/wayland-drm.c有如下代码：

drm implement by mesa

调用wl_global_create注册了wl_drm_interface.版本号是2.

三、创建surface

surface可以为渲染表面的逻辑概念，它有一些属性，比如宽和高，位置和像素类型等，需要绑定buffer才能存储渲染数据，buffer可以自由绑定，这样灵活性强。一个表面绑定不同的buffer，就可以实现切换不同的渲染数据。

wl_compositor_create_surface创建一块绑定到compositor的surface。这是wayland最底层的surface，此时surface和应用窗口还没关联上。

XDG (cross-desktop group) shell 是 Wayland 的一个标准扩展协议，描述了应用窗口的语义。换句话说它能将wl_surfaces转换成桌面环境下的窗口。它定义了两个 wl_surface 角色："toplevel" 用于你的顶层应用窗口；"popup" 则用于诸如上下文菜单、下拉菜单、工具提示等等——它们是顶层窗口的子集

xdg_wm_base_get_xdg_surface创建一块绑定到surface的xdg_surface（应用窗口surface)。

四、创建缓存并绑定到surface

使用wl_shm_create_pool创建一个pool。pool是一个管理buffer的池子，它的作用是减少buffer反复申请和注销给系统内存管理带来碎片化问题。buffer释放后，这段内存还给pool，下一次重新申请buffer时，继续从pool中划分。

所以可以看到wl_shm_pool_create_buffer依赖pool作为参数去创建buffer。

wl_shm_pool_destroy销毁pool，但不会立即销毁pool中的buffer。buffer全部释放后，会自动解除内存映射。

wl_surface_attach将buffer绑定到surface

create buffer

五提交surface并显示

wl_surface_commit提交surface到compositor用于显示，这意味着请求compositor读取surface的内容，compositor读取完内容后，会向这个buffer发送release事件。在compositor返回这个buffer的release信号之前，修改buffer会导致未定义的问题。

当一个surface绑定空buffer或未绑定buffer，调用wl_surface_commit时的含义是清空这个surface当前的内容。

commit

完整的代码：https://github.com/warlice/hello-wayland/blob/master/main.c