典型的Wayland client编程实例

一、连接服务端

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对象的请求。

第2段

// 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序号，用于绑定接口。

对象列表

interface: 'wl_compositor', version: 5, name: 1
interface: 'wl_drm', version: 2, name: 2
interface: 'wl_shm', version: 1, name: 3
interface: 'wl_output', version: 4, name: 4
interface: 'zxdg_output_manager_v1', version: 3, name: 5
interface: 'wl_data_device_manager', version: 3, name: 6
interface: 'zwp_primary_selection_device_manager_v1', version: 1, name: 7
interface: 'wl_subcompositor', version: 1, name: 8

2.2 由wayland server注册的对象

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

registry dma buf

gboolean
meta_wayland_dma_buf_init (MetaWaylandCompositor *compositor)
{
  MetaBackend *backend = meta_get_backend ();
  MetaEgl *egl = meta_backend_get_egl (backend);
  ClutterBackend *clutter_backend = meta_backend_get_clutter_backend (backend);
  CoglContext *cogl_context = clutter_backend_get_cogl_context (clutter_backend);
  EGLDisplay egl_display = cogl_egl_context_get_egl_display (cogl_context);
 
  g_assert (backend && egl && clutter_backend && cogl_context && egl_display);
 
  if (!meta_egl_has_extensions (egl, egl_display, NULL,
                                "EGL_EXT_image_dma_buf_import_modifiers",
                                NULL))
    return FALSE;
 
  if (!wl_global_create (compositor->wayland_display,
                         &zwp_linux_dmabuf_v1_interface,
                         META_ZWP_LINUX_DMABUF_V1_VERSION,
                         compositor,
                         dma_buf_bind))
    return FALSE;
 
  return TRUE;
}

上面的代码截取自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

struct wl_drm *
wayland_drm_init(struct wl_display *display, char *device_name,
                 const struct wayland_drm_callbacks *callbacks, void *user_data,
                 uint32_t flags)
{
   struct wl_drm *drm;
 
   drm = malloc(sizeof *drm);
   if (!drm)
      return NULL;
 
   drm->display = display;
   drm->device_name = strdup(device_name);
   drm->callbacks = *callbacks;
   drm->user_data = user_data;
   drm->flags = flags;
 
   drm->buffer_interface.destroy = buffer_destroy;
 
   drm->wl_drm_global =
      wl_global_create(display, &wl_drm_interface, 2, drm, bind_drm);
 
   return drm;
}

调用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)。

三

// Create a wl_surface, a xdg_surface and a xdg_toplevel
    surface = wl_compositor_create_surface(compositor);
    struct xdg_surface *xdg_surface = xdg_wm_base_get_xdg_surface(xdg_wm_base, surface);
    xdg_toplevel = xdg_surface_get_toplevel(xdg_surface);
 
    xdg_surface_add_listener(xdg_surface, &xdg_surface_listener, NULL);
    xdg_toplevel_add_listener(xdg_toplevel, &xdg_toplevel_listener, NULL);
 
    // Perform the initial commit and wait for the first configure event
    wl_surface_commit(surface);
    while (wl_display_dispatch(display) != -1 && !configured) {
        // This space intentionally left blank
    }

四、创建缓存并绑定到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 and commit buffer

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 struct wl_buffer *create_buffer(void) {
    int stride = width * 4;
    int size = stride * height;
 
    // Allocate a shared memory file with the right size
    int fd = create_shm_file(size);
    if (fd < 0) {
        fprintf(stderr, "creating a buffer file for %d B failed: %m\n", size);
        return NULL;
    }
 
    // Map the shared memory file
    shm_data = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
    if (shm_data == MAP_FAILED) {
        fprintf(stderr, "mmap failed: %m\n");
        close(fd);
        return NULL;
    }
 
    // Create a wl_buffer from our shared memory file descriptor
    struct wl_shm_pool *pool = wl_shm_create_pool(shm, fd, size);
    struct wl_buffer *buffer = wl_shm_pool_create_buffer(pool, 0, width, height,stride, WL_SHM_FORMAT_ARGB8888);
    wl_shm_pool_destroy(pool);
 
    // Now that we've mapped the file and created the wl_buffer, we no longer
    // need to keep file descriptor opened
    close(fd);
 
    // Copy pixels into our shared memory file (MagickImage is from cat.h)
    memcpy(shm_data, MagickImage, size);
 
    return buffer;
}
 
// Create a wl_buffer, attach it to the surface and commit the surface
    struct wl_buffer *buffer = create_buffer();
    if (buffer == NULL) {
        return EXIT_FAILURE;
    }
 
    wl_surface_attach(surface, buffer, 0, 0);

五提交surface并显示

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

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

commit

wl_surface_commit(surface);
 
// Continue dispatching events until the user closes the toplevel
while (wl_display_dispatch(display) != -1 && running) {
    // This space intentionally left blank
}
 
xdg_toplevel_destroy(xdg_toplevel);
xdg_surface_destroy(xdg_surface);
wl_surface_destroy(surface);
wl_buffer_destroy(buffer);
 
return EXIT_SUCCESS;

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