Wayland

https://github.com/xquartz/wayland
Admin
Wayland is a protocol and library implementation for compositors to communicate with clients,...
Tokens:11,744
Snippets:53
Trust Score:7.2
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Animate Wayland Pointer Cursor (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Animates the Wayland pointer cursor by calculating the current frame based on time, getting the corresponding image buffer, and updating the Wayland surface. It then informs the pointer of the updated cursor. Requires `cursor_data`, `wl_pointer`, serial, `wl_cursor`, and current time.

```c
#include <wayland-client.h>
#include <wayland-cursor.h>
#include <stdio.h>

struct cursor_data {
    struct wl_cursor_theme *theme;
    struct wl_cursor *default_cursor;
    struct wl_cursor *pointer_cursor;
    struct wl_surface *cursor_surface;
    struct wl_shm *shm;
};

void animate_cursor(struct cursor_data *data, struct wl_pointer *pointer,
                    uint32_t serial, struct wl_cursor *cursor, uint32_t time) {
    int frame = wl_cursor_frame(cursor, time);
    struct wl_cursor_image *image = cursor->images[frame];
    struct wl_buffer *buffer = wl_cursor_image_get_buffer(image);

    wl_surface_attach(data->cursor_surface, buffer, 0, 0);
    wl_surface_damage(data->cursor_surface, 0, 0, image->width, image->height);
    wl_surface_commit(data->cursor_surface);

    wl_pointer_set_cursor(pointer, serial, data->cursor_surface,
                          image->hotspot_x, image->hotspot_y);
}

```

--------------------------------

### Implement C coding style conventions

Source: https://github.com/xquartz/wayland/blob/main/CONTRIBUTING.md

Demonstrates the project's required C coding style, including tab indentation, brace placement for if-else blocks, and vertical spacing between declarations and logic.

```c
static int
my_function(void)
{
	int a = 0;

	if (a)
		b();
	else
		c();

	if (a) {
		b();
		c();
	} else {
		d();
	}
}
```

--------------------------------

### Establish Wayland Display Connection in C

Source: https://context7.com/xquartz/wayland/llms.txt

Demonstrates how to connect to a Wayland compositor using wl_display_connect. It initializes the display object and performs a roundtrip to synchronize with the server.

```c
#include <wayland-client.h>
#include <stdio.h>
#include <stdlib.h>

int main(void) {
    struct wl_display *display;
    struct wl_registry *registry;

    /* Connect to the default Wayland display (WAYLAND_DISPLAY env var or "wayland-0") */
    display = wl_display_connect(NULL);
    if (!display) {
        fprintf(stderr, "Failed to connect to Wayland display\n");
        return EXIT_FAILURE;
    }

    printf("Connected to Wayland display\n");

    /* Get the registry to discover available global objects */
    registry = wl_display_get_registry(display);

    /* Perform a roundtrip to ensure all initial events are processed */
    wl_display_roundtrip(display);

    /* Clean up */
    wl_registry_destroy(registry);
    wl_display_disconnect(display);

    return EXIT_SUCCESS;
}
```

--------------------------------

### Initialize and Manage EGL Windows in Wayland

Source: https://context7.com/xquartz/wayland/llms.txt

Demonstrates the lifecycle of an EGL window on a Wayland surface, including creation, resizing, rendering, and cleanup. It requires the wayland-client, wayland-egl, and EGL/GLES2 libraries.

```c
#include <wayland-client.h>
#include <wayland-egl.h>
#include <EGL/egl.h>
#include <GLES2/gl2.h>
#include <stdio.h>

struct egl_window {
    struct wl_surface *surface;
    struct wl_egl_window *egl_window;
    EGLDisplay egl_display;
    EGLContext egl_context;
    EGLSurface egl_surface;
    int width;
    int height;
};

int create_egl_window(struct egl_window *win, struct wl_display *display,
                      struct wl_compositor *compositor, int width, int height) {
    win->width = width;
    win->height = height;

    /* Create Wayland surface */
    win->surface = wl_compositor_create_surface(compositor);

    /* Create EGL window wrapper */
    win->egl_window = wl_egl_window_create(win->surface, width, height);
    if (!win->egl_window) {
        fprintf(stderr, "Failed to create EGL window\n");
        return -1;
    }

    /* Initialize EGL */
    win->egl_display = eglGetDisplay((EGLNativeDisplayType)display);
    eglInitialize(win->egl_display, NULL, NULL);
    eglBindAPI(EGL_OPENGL_ES_API);

    /* Choose config */
    EGLConfig config;
    EGLint num_configs;
    EGLint config_attribs[] = {
        EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
        EGL_RED_SIZE, 8,
        EGL_GREEN_SIZE, 8,
        EGL_BLUE_SIZE, 8,
        EGL_ALPHA_SIZE, 8,
        EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
        EGL_NONE
    };
    eglChooseConfig(win->egl_display, config_attribs, &config, 1, &num_configs);

    /* Create context */
    EGLint context_attribs[] = {
        EGL_CONTEXT_CLIENT_VERSION, 2,
        EGL_NONE
    };
    win->egl_context = eglCreateContext(win->egl_display, config,
                                        EGL_NO_CONTEXT, context_attribs);

    /* Create window surface */
    win->egl_surface = eglCreateWindowSurface(win->egl_display, config,
                                              (EGLNativeWindowType)win->egl_window,
                                              NULL);

    eglMakeCurrent(win->egl_display, win->egl_surface,
                   win->egl_surface, win->egl_context);

    return 0;
}

void resize_egl_window(struct egl_window *win, int width, int height) {
    win->width = width;
    win->height = height;
    wl_egl_window_resize(win->egl_window, width, height, 0, 0);
    glViewport(0, 0, width, height);
}

void render_frame(struct egl_window *win) {
    glClearColor(0.2f, 0.3f, 0.4f, 1.0f);
    glClear(GL_COLOR_BUFFER_BIT);

    /* Your OpenGL ES 2.0 rendering here */

    eglSwapBuffers(win->egl_display, win->egl_surface);
}

void destroy_egl_window(struct egl_window *win) {
    eglMakeCurrent(win->egl_display, EGL_NO_SURFACE,
                   EGL_NO_SURFACE, EGL_NO_CONTEXT);
    eglDestroySurface(win->egl_display, win->egl_surface);
    eglDestroyContext(win->egl_display, win->egl_context);
    eglTerminate(win->egl_display);

    wl_egl_window_destroy(win->egl_window);
    wl_surface_destroy(win->surface);
}
```

--------------------------------

### Create Wayland Surface and Manage Frame Callbacks

Source: https://context7.com/xquartz/wayland/llms.txt

Demonstrates the creation of a Wayland surface using wl_compositor and setting up frame callbacks for rendering updates. It includes functions to create and destroy windows, managing frame synchronization with the compositor.

```c
#include <wayland-client.h>

struct window {
    struct wl_surface *surface;
    struct wl_callback *frame_callback;
    int width;
    int height;
};

static void frame_done(void *data, struct wl_callback *callback, uint32_t time);

static const struct wl_callback_listener frame_listener = {
    .done = frame_done,
};

static void frame_done(void *data, struct wl_callback *callback, uint32_t time) {
    struct window *window = data;

    /* Destroy the old callback */
    wl_callback_destroy(callback);

    /* Request next frame */
    window->frame_callback = wl_surface_frame(window->surface);
    wl_callback_add_listener(window->frame_callback, &frame_listener, window);

    /* Render and commit the frame */
    /* ... rendering code ... */
    wl_surface_commit(window->surface);
}

struct window *create_window(struct wl_compositor *compositor, int width, int height) {
    struct window *window = calloc(1, sizeof(*window));

    window->width = width;
    window->height = height;
    window->surface = wl_compositor_create_surface(compositor);

    /* Request first frame callback for animation */
    window->frame_callback = wl_surface_frame(window->surface);
    wl_callback_add_listener(window->frame_callback, &frame_listener, window);

    return window;
}

void destroy_window(struct window *window) {
    if (window->frame_callback)
        wl_callback_destroy(window->frame_callback);
    wl_surface_destroy(window->surface);
    free(window);
}

```

--------------------------------

### Wayland Event Loop with Timers and Signals (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Demonstrates setting up and running a Wayland event loop using `wl_event_loop`. It includes adding a repeating timer that triggers a callback and handling SIGINT signals for graceful termination. This is essential for responsive Wayland compositors.

```c
#include <wayland-server.h>
#include <stdio.h>
#include <signal.h>

struct app_state {
    struct wl_display *display;
    struct wl_event_source *timer;
    int counter;
};

static int timer_callback(void *data) {
    struct app_state *state = data;
    printf("Timer fired: count=%d\n", ++state->counter);

    if (state->counter >= 5) {
        wl_display_terminate(state->display);
        return 0;
    }

    /* Reset timer for next interval (1000ms) */
    wl_event_source_timer_update(state->timer, 1000);
    return 0;
}

static int signal_callback(int signal_number, void *data) {
    struct app_state *state = data;
    printf("Received signal %d, terminating\n", signal_number);
    wl_display_terminate(state->display);
    return 0;
}

int main(void) {
    struct app_state state = {0};
    struct wl_event_loop *loop;
    struct wl_event_source *signal_source;

    state.display = wl_display_create();
    loop = wl_display_get_event_loop(state.display);

    /* Add a repeating timer (initial delay 1000ms) */
    state.timer = wl_event_loop_add_timer(loop, timer_callback, &state);
    wl_event_source_timer_update(state.timer, 1000);

    /* Handle SIGINT for clean shutdown */
    signal_source = wl_event_loop_add_signal(loop, SIGINT,
                                              signal_callback, &state);

    printf("Running event loop with timer...\n");
    wl_display_run(state.display);

    wl_event_source_remove(signal_source);
    wl_event_source_remove(state.timer);
    wl_display_destroy(state.display);

    return 0;
}

```

--------------------------------

### Load Wayland Cursor Theme and Cursors (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Initializes cursor data by loading a Wayland cursor theme and retrieving default and pointer cursors. It also creates a Wayland surface to display the cursor. Requires `wayland-client.h` and `wayland-cursor.h`.

```c
#include <wayland-client.h>
#include <wayland-cursor.h>
#include <stdio.h>

struct cursor_data {
    struct wl_cursor_theme *theme;
    struct wl_cursor *default_cursor;
    struct wl_cursor *pointer_cursor;
    struct wl_surface *cursor_surface;
    struct wl_shm *shm;
};

int setup_cursors(struct cursor_data *data, struct wl_compositor *compositor,
                  struct wl_shm *shm) {
    data->shm = shm;

    /* Load the default cursor theme at size 24 */
    data->theme = wl_cursor_theme_load(NULL, 24, shm);
    if (!data->theme) {
        fprintf(stderr, "Failed to load cursor theme\n");
        return -1;
    }

    /* Get specific cursors */
    data->default_cursor = wl_cursor_theme_get_cursor(data->theme, "left_ptr");
    data->pointer_cursor = wl_cursor_theme_get_cursor(data->theme, "hand1");

    if (!data->default_cursor) {
        /* Fallback cursor names */
        data->default_cursor = wl_cursor_theme_get_cursor(data->theme, "default");
    }

    /* Create a surface for the cursor */
    data->cursor_surface = wl_compositor_create_surface(compositor);

    return 0;
}

```

--------------------------------

### Wayland Server Display Creation (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Creates a Wayland display for compositor applications using wl_display_create. It sets up a listening socket for clients, initializes shared memory support, and registers a listener for new client connections. The main loop then runs to handle events.

```c
#include <wayland-server.h>
#include <stdio.h>
#include <stdlib.h>

static void client_created(struct wl_listener *listener, void *data) {
    struct wl_client *client = data;
    pid_t pid;
    uid_t uid;
    gid_t gid;

    wl_client_get_credentials(client, &pid, &uid, &gid);
    printf("New client connected: pid=%d, uid=%d\n", pid, uid);
}

int main(void) {
    struct wl_display *display;
    struct wl_event_loop *loop;
    const char *socket;

    /* Create the display */
    display = wl_display_create();
    if (!display) {
        fprintf(stderr, "Failed to create display\n");
        return EXIT_FAILURE;
    }

    /* Add a socket for clients to connect */
    socket = wl_display_add_socket_auto(display);
    if (!socket) {
        fprintf(stderr, "Failed to add socket\n");
        wl_display_destroy(display);
        return EXIT_FAILURE;
    }

    printf("Listening on %s\n", socket);

    /* Initialize shared memory support */
    wl_display_init_shm(display);

    /* Listen for new client connections */
    struct wl_listener client_listener = {
        .notify = client_created
    };
    wl_display_add_client_created_listener(display, &client_listener);

    /* Get the event loop for adding custom sources */
    loop = wl_display_get_event_loop(display);

    /* Run the main loop */
    wl_display_run(display);

    wl_display_destroy(display);
    return EXIT_SUCCESS;
}

```

--------------------------------

### Implement Observer Pattern with wl_signal and wl_listener

Source: https://context7.com/xquartz/wayland/llms.txt

Demonstrates how to define signals and listeners to handle event notifications in a Wayland compositor. It includes creating signals, attaching listeners, and emitting events when surface states change.

```c
#include <wayland-server.h>
#include <stdio.h>

struct surface {
    struct wl_resource *resource;
    struct wl_signal destroy_signal;
    struct wl_signal commit_signal;
    int width, height;
};

struct surface_observer {
    struct wl_listener destroy_listener;
    struct wl_listener commit_listener;
    const char *name;
};

static void on_surface_destroy(struct wl_listener *listener, void *data) {
    struct surface_observer *observer = wl_container_of(listener, observer,
                                                         destroy_listener);
    printf("[%s] Surface destroyed\n", observer->name);

    /* Clean up observer resources */
    wl_list_remove(&observer->destroy_listener.link);
    wl_list_remove(&observer->commit_listener.link);
}

static void on_surface_commit(struct wl_listener *listener, void *data) {
    struct surface_observer *observer = wl_container_of(listener, observer,
                                                         commit_listener);
    struct surface *surface = data;
    printf("[%s] Surface committed: %dx%d\n", observer->name,
           surface->width, surface->height);
}

struct surface *surface_create(void) {
    struct surface *surface = calloc(1, sizeof(*surface));
    wl_signal_init(&surface->destroy_signal);
    wl_signal_init(&surface->commit_signal);
    return surface;
}

void surface_destroy(struct surface *surface) {
    wl_signal_emit(&surface->destroy_signal, surface);
    free(surface);
}

void surface_commit(struct surface *surface) {
    wl_signal_emit(&surface->commit_signal, surface);
}

void observer_add(struct surface *surface, struct surface_observer *observer,
                  const char *name) {
    observer->name = name;
    observer->destroy_listener.notify = on_surface_destroy;
    observer->commit_listener.notify = on_surface_commit;

    wl_signal_add(&surface->destroy_signal, &observer->destroy_listener);
    wl_signal_add(&surface->commit_signal, &observer->commit_listener);
}
```

--------------------------------

### Discover Global Objects via Wayland Registry in C

Source: https://context7.com/xquartz/wayland/llms.txt

Shows how to implement a wl_registry_listener to bind to global interfaces like wl_compositor, wl_shm, and wl_seat. This is essential for clients to access compositor functionality.

```c
#include <wayland-client.h>
#include <string.h>

struct client_state {
    struct wl_compositor *compositor;
    struct wl_shm *shm;
    struct wl_seat *seat;
};

static void registry_global(void *data, struct wl_registry *registry,
                           uint32_t name, const char *interface, uint32_t version) {
    struct client_state *state = data;

    printf("Global: %s (name=%u, version=%u)\n", interface, name, version);

    if (strcmp(interface, wl_compositor_interface.name) == 0) {
        state->compositor = wl_registry_bind(registry, name,
                                             &wl_compositor_interface, 4);
    } else if (strcmp(interface, wl_shm_interface.name) == 0) {
        state->shm = wl_registry_bind(registry, name,
                                      &wl_shm_interface, 1);
    } else if (strcmp(interface, wl_seat_interface.name) == 0) {
        state->seat = wl_registry_bind(registry, name,
                                       &wl_seat_interface, 7);
    }
}

static void registry_global_remove(void *data, struct wl_registry *registry,
                                   uint32_t name) {
    printf("Global removed: name=%u\n", name);
}

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

int main(void) {
    struct wl_display *display = wl_display_connect(NULL);
    struct wl_registry *registry = wl_display_get_registry(display);
    struct client_state state = {0};

    wl_registry_add_listener(registry, &registry_listener, &state);
    wl_display_roundtrip(display);

    if (state.compositor)
        printf("Got compositor\n");
    if (state.shm)
        printf("Got shm\n");
    if (state.seat)
        printf("Got seat\n");

    wl_display_disconnect(display);
    return 0;
}
```

--------------------------------

### Manage Wayland Protocol Resources

Source: https://context7.com/xquartz/wayland/llms.txt

Shows how to create and manage server-side protocol objects using wl_resource. It covers setting up implementation interfaces, handling destruction, and associating user data with resources.

```c
#include <wayland-server.h>
#include <stdio.h>

struct my_surface {
    struct wl_resource *resource;
    struct wl_list link;
    int x, y;
    int width, height;
};

static void surface_destroy_handler(struct wl_resource *resource) {
    struct my_surface *surface = wl_resource_get_user_data(resource);
    printf("Destroying surface resource %u\n", wl_resource_get_id(resource));

    wl_list_remove(&surface->link);
    free(surface);
}

static void surface_attach(struct wl_client *client,
                          struct wl_resource *resource,
                          struct wl_resource *buffer,
                          int32_t x, int32_t y) {
    struct my_surface *surface = wl_resource_get_user_data(resource);
    surface->x = x;
    surface->y = y;
    printf("Surface %u: attach at (%d, %d)\n",
           wl_resource_get_id(resource), x, y);
}

static void surface_commit(struct wl_client *client,
                          struct wl_resource *resource) {
    struct my_surface *surface = wl_resource_get_user_data(resource);
    printf("Surface %u: commit\n", wl_resource_get_id(resource));
}

static void surface_destroy(struct wl_client *client,
                           struct wl_resource *resource) {
    wl_resource_destroy(resource);
}

static const struct wl_surface_interface surface_impl = {
    .destroy = surface_destroy,
    .attach = surface_attach,
    .commit = surface_commit,
};

struct my_surface *create_surface_resource(struct wl_client *client,
                                           uint32_t id, int version,
                                           struct wl_list *surface_list) {
    struct my_surface *surface = calloc(1, sizeof(*surface));

    surface->resource = wl_resource_create(client, &wl_surface_interface,
                                           version, id);
    wl_resource_set_implementation(surface->resource, &surface_impl,
                                   surface, surface_destroy_handler);

    wl_list_insert(surface_list, &surface->link);

    return surface;
}
```

--------------------------------

### Wayland Global Object Registration (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Illustrates how to register global Wayland objects using `wl_global_create`. This function allows the compositor to expose interfaces, such as `wl_compositor`, to clients. It defines the interface implementation and the bind function that handles client connections.

```c
#include <wayland-server.h>
#include <stdio.h>

struct compositor_impl {
    struct wl_global *global;
    struct wl_list surfaces;
};

static void compositor_create_surface(struct wl_client *client,
                                      struct wl_resource *resource,
                                      uint32_t id) {
    printf("Client requested new surface with id %u\n", id);

    struct wl_resource *surface_resource = wl_resource_create(client,
                                                              &wl_surface_interface,
                                                              wl_resource_get_version(resource),
                                                              id);
    /* Set up surface implementation... */
}

static void compositor_create_region(struct wl_client *client,
                                     struct wl_resource *resource,
                                     uint32_t id) {
    printf("Client requested new region with id %u\n", id);
    /* Create region resource... */
}

static const struct wl_compositor_interface compositor_impl = {
    .create_surface = compositor_create_surface,
    .create_region = compositor_create_region,
};

static void compositor_bind(struct wl_client *client, void *data,
                           uint32_t version, uint32_t id) {
    struct compositor_impl *compositor = data;

    struct wl_resource *resource = wl_resource_create(client,
                                                      &wl_compositor_interface,
                                                      version, id);
    wl_resource_set_implementation(resource, &compositor_impl,
                                   compositor, NULL);

    printf("Client bound to compositor (version %u)\n", version);
}

struct compositor_impl *create_compositor(struct wl_display *display) {
    struct compositor_impl *compositor = calloc(1, sizeof(*compositor));
    wl_list_init(&compositor->surfaces);

    compositor->global = wl_global_create(display,
                                          &wl_compositor_interface,
                                          5,  /* version */
                                          compositor,
                                          compositor_bind);
    return compositor;
}

```

--------------------------------

### Wayland Keyboard Input Handling (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Handles keyboard input events by setting up a wl_keyboard listener. It interprets keymap formats (XKB_V1) and processes key presses and releases, converting keycodes to keysyms for display. Dependencies include wayland-client.h and xkbcommon.

```c
#include <wayland-client.h>
#include <sys/mman.h>
#include <xkbcommon/xkbcommon.h>
#include <unistd.h>
#include <stdio.h>

struct keyboard_state {
    struct wl_keyboard *keyboard;
    struct xkb_context *xkb_context;
    struct xkb_keymap *xkb_keymap;
    struct xkb_state *xkb_state;
};

static void keyboard_keymap(void *data, struct wl_keyboard *keyboard,
                           uint32_t format, int fd, uint32_t size) {
    struct keyboard_state *state = data;

    if (format != WL_KEYBOARD_KEYMAP_FORMAT_XKB_V1) {
        close(fd);
        return;
    }

    char *map_str = mmap(NULL, size, PROT_READ, MAP_PRIVATE, fd, 0);
    if (map_str == MAP_FAILED) {
        close(fd);
        return;
    }

    state->xkb_keymap = xkb_keymap_new_from_string(state->xkb_context,
                                                   map_str,
                                                   XKB_KEYMAP_FORMAT_TEXT_V1,
                                                   XKB_KEYMAP_COMPILE_NO_FLAGS);
    munmap(map_str, size);
    close(fd);

    state->xkb_state = xkb_state_new(state->xkb_keymap);
}

static void keyboard_enter(void *data, struct wl_keyboard *keyboard,
                          uint32_t serial, struct wl_surface *surface,
                          struct wl_array *keys) {
    printf("Keyboard focus entered\n");
}

static void keyboard_leave(void *data, struct wl_keyboard *keyboard,
                          uint32_t serial, struct wl_surface *surface) {
    printf("Keyboard focus left\n");
}

static void keyboard_key(void *data, struct wl_keyboard *keyboard,
                        uint32_t serial, uint32_t time, uint32_t key,
                        uint32_t state_w) {
    struct keyboard_state *state = data;

    /* Convert evdev keycode to xkb keycode */
    uint32_t keycode = key + 8;
    xkb_keysym_t keysym = xkb_state_key_get_one_sym(state->xkb_state, keycode);

    char name[64];
    xkb_keysym_get_name(keysym, name, sizeof(name));

    const char *action = state_w == WL_KEYBOARD_KEY_STATE_PRESSED ?
                         "pressed" : "released";
    printf("Key %s: %s (keysym 0x%x)\n", action, name, keysym);
}

static void keyboard_modifiers(void *data, struct wl_keyboard *keyboard,
                              uint32_t serial, uint32_t mods_depressed,
                              uint32_t mods_latched, uint32_t mods_locked,
                              uint32_t group) {
    struct keyboard_state *state = data;
    xkb_state_update_mask(state->xkb_state,
                          mods_depressed, mods_latched, mods_locked,
                          0, 0, group);
}

static void keyboard_repeat_info(void *data, struct wl_keyboard *keyboard,
                                int32_t rate, int32_t delay) {
    printf("Key repeat: %d chars/sec after %dms delay\n", rate, delay);
}

static const struct wl_keyboard_listener keyboard_listener = {
    .keymap = keyboard_keymap,
    .enter = keyboard_enter,
    .leave = keyboard_leave,
    .key = keyboard_key,
    .modifiers = keyboard_modifiers,
    .repeat_info = keyboard_repeat_info,
};

```

--------------------------------

### Handle Dynamic Arrays with wl_array

Source: https://context7.com/xquartz/wayland/llms.txt

Shows how to use wl_array for dynamic memory management, including adding elements, iterating over contents, copying arrays, and handling raw data like strings. Proper release of the array is required to prevent memory leaks.

```c
#include <wayland-util.h>
#include <stdio.h>
#include <string.h>

void demonstrate_array_operations(void) {
    struct wl_array array;
    wl_array_init(&array);

    /* Add integers to the array */
    for (int i = 0; i < 10; i++) {
        int *ptr = wl_array_add(&array, sizeof(int));
        if (ptr)
            *ptr = i * i;
    }

    printf("Array size: %zu bytes\n", array.size);
    printf("Elements: ");

    /* Iterate over array elements */
    int *value;
    wl_array_for_each(value, &array) {
        printf("%d ", *value);
    }
    printf("\n");

    /* Copy array */
    struct wl_array copy;
    wl_array_init(&copy);
    if (wl_array_copy(&copy, &array) == 0) {
        printf("Array copied successfully\n");
    }

    /* Using array for string data */
    struct wl_array strings;
    wl_array_init(&strings);

    const char *items[] = {"hello", "wayland", "world"};
    for (int i = 0; i < 3; i++) {
        size_t len = strlen(items[i]) + 1;
        char *dest = wl_array_add(&strings, len);
        memcpy(dest, items[i], len);
    }

    /* Clean up */
    wl_array_release(&array);
    wl_array_release(&copy);
    wl_array_release(&strings);
}
```

--------------------------------

### Perform Wayland Fixed-Point Conversions

Source: https://context7.com/xquartz/wayland/llms.txt

Shows how to convert integers and doubles to Wayland's 24.8 fixed-point format (wl_fixed_t) and back. This is essential for handling sub-pixel precision in pointer events and coordinate systems.

```c
#include <wayland-util.h>
#include <stdio.h>

void demonstrate_fixed_point(void) {
    /* Convert integers to fixed-point */
    wl_fixed_t fixed_100 = wl_fixed_from_int(100);
    printf("100 as fixed: 0x%x (%d raw)\n", fixed_100, fixed_100);

    /* Convert doubles to fixed-point */
    wl_fixed_t fixed_pi = wl_fixed_from_double(3.14159);
    printf("Pi as fixed: 0x%x\n", fixed_pi);

    /* Convert back to usable values */
    int int_val = wl_fixed_to_int(fixed_100);
    double double_val = wl_fixed_to_double(fixed_pi);
    printf("Back to int: %d\n", int_val);
    printf("Back to double: %.5f\n", double_val);

    /* Sub-pixel coordinates from pointer events */
    wl_fixed_t surface_x = wl_fixed_from_double(150.75);
    wl_fixed_t surface_y = wl_fixed_from_double(200.25);

    /* Get integer pixel position */
    int pixel_x = wl_fixed_to_int(surface_x);
    int pixel_y = wl_fixed_to_int(surface_y);

    /* Get precise position for smooth rendering */
    double precise_x = wl_fixed_to_double(surface_x);
    double precise_y = wl_fixed_to_double(surface_y);

    printf("Position: pixel (%d, %d), precise (%.2f, %.2f)\n",
           pixel_x, pixel_y, precise_x, precise_y);
}
```

--------------------------------

### Manage Intrusive Doubly-Linked Lists with wl_list

Source: https://context7.com/xquartz/wayland/llms.txt

Demonstrates initializing, populating, iterating, and safely removing elements from a Wayland intrusive doubly-linked list. This structure is essential for managing object collections within Wayland-based applications.

```c
#include <wayland-util.h>
#include <stdio.h>
#include <stdlib.h>

struct my_item {
    int value;
    struct wl_list link;
};

void demonstrate_list_operations(void) {
    struct wl_list item_list;
    wl_list_init(&item_list);

    /* Add items to the list */
    for (int i = 0; i < 5; i++) {
        struct my_item *item = calloc(1, sizeof(*item));
        item->value = i * 10;
        wl_list_insert(&item_list, &item->link);  /* Insert at head */
    }

    printf("List length: %d\n", wl_list_length(&item_list));
    printf("Is empty: %s\n", wl_list_empty(&item_list) ? "yes" : "no");

    /* Iterate forward */
    printf("Forward: ");
    struct my_item *item;
    wl_list_for_each(item, &item_list, link) {
        printf("%d ", item->value);
    }
    printf("\n");

    /* Iterate backward */
    printf("Backward: ");
    wl_list_for_each_reverse(item, &item_list, link) {
        printf("%d ", item->value);
    }
    printf("\n");

    /* Safe iteration for removal */
    struct my_item *tmp;
    wl_list_for_each_safe(item, tmp, &item_list, link) {
        if (item->value == 20) {
            printf("Removing item with value %d\n", item->value);
            wl_list_remove(&item->link);
            free(item);
        }
    }

    /* Clean up remaining items */
    wl_list_for_each_safe(item, tmp, &item_list, link) {
        wl_list_remove(&item->link);
        free(item);
    }
}
```

--------------------------------

### Format long function calls in C

Source: https://github.com/xquartz/wayland/blob/main/CONTRIBUTING.md

Illustrates the standard for breaking long lines in C code, ensuring parameters are aligned with opening parentheses or broken at the assignment operator.

```c
	long_variable_name =
		function_with_a_really_long_name(parameter1, parameter2,
						 parameter3, parameter4);

	x = function_with_a_really_long_name(parameter1, parameter2,
					     parameter3, parameter4);
```

--------------------------------

### Create and Manage Shared Memory Buffers for Wayland

Source: https://context7.com/xquartz/wayland/llms.txt

Provides functionality to create and manage shared memory buffers for Wayland using wl_shm. This includes allocating memory, creating Wayland buffers, drawing to them, and cleaning up resources.

```c
#include <wayland-client.h>
#include <sys/mman.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>
#include <string.h>

static int create_shm_file(off_t size) {
    int fd = memfd_create("wayland-shm", MFD_CLOEXEC);
    if (fd < 0)
        return -1;

    if (ftruncate(fd, size) < 0) {
        close(fd);
        return -1;
    }

    return fd;
}

struct shm_buffer {
    struct wl_buffer *buffer;
    void *data;
    int width;
    int height;
    int stride;
    size_t size;
};

struct shm_buffer *create_shm_buffer(struct wl_shm *shm, int width, int height) {
    struct shm_buffer *buf = calloc(1, sizeof(*buf));

    buf->width = width;
    buf->height = height;
    buf->stride = width * 4;  /* ARGB8888 format */
    buf->size = buf->stride * height;

    int fd = create_shm_file(buf->size);
    if (fd < 0) {
        free(buf);
        return NULL;
    }

    buf->data = mmap(NULL, buf->size, PROT_READ | PROT_WRITE,
                     MAP_SHARED, fd, 0);
    if (buf->data == MAP_FAILED) {
        close(fd);
        free(buf);
        return NULL;
    }

    struct wl_shm_pool *pool = wl_shm_create_pool(shm, fd, buf->size);
    buf->buffer = wl_shm_pool_create_buffer(pool, 0, width, height,
                                            buf->stride, WL_SHM_FORMAT_ARGB8888);
    wl_shm_pool_destroy(pool);
    close(fd);

    return buf;
}

void draw_to_buffer(struct shm_buffer *buf, uint32_t color) {
    uint32_t *pixels = buf->data;
    for (int y = 0; y < buf->height; y++) {
        for (int x = 0; x < buf->width; x++) {
            pixels[y * buf->width + x] = color;
        }
    }
}

void destroy_shm_buffer(struct shm_buffer *buf) {
    wl_buffer_destroy(buf->buffer);
    munmap(buf->data, buf->size);
    free(buf);
}

```

--------------------------------

### Wayland Pointer Event Listeners in C

Source: https://context7.com/xquartz/wayland/llms.txt

This C code defines listeners for various Wayland pointer events, including enter, leave, motion, button presses/releases, and scrolling. It utilizes the wl_pointer interface and requires the wayland-client library. The listeners update a state struct and print event details to the console.

```c
#include <wayland-client.h>
#include <stdio.h>

struct pointer_state {
    struct wl_pointer *pointer;
    struct wl_surface *focused_surface;
    double x, y;
    uint32_t button;
    uint32_t serial;
};

static void pointer_enter(void *data, struct wl_pointer *pointer,
                         uint32_t serial, struct wl_surface *surface,
                         wl_fixed_t sx, wl_fixed_t sy) {
    struct pointer_state *state = data;
    state->focused_surface = surface;
    state->x = wl_fixed_to_double(sx);
    state->y = wl_fixed_to_double(sy);
    state->serial = serial;
    printf("Pointer entered surface at (%.2f, %.2f)\n", state->x, state->y);
}

static void pointer_leave(void *data, struct wl_pointer *pointer,
                         uint32_t serial, struct wl_surface *surface) {
    struct pointer_state *state = data;
    state->focused_surface = NULL;
    printf("Pointer left surface\n");
}

static void pointer_motion(void *data, struct wl_pointer *pointer,
                          uint32_t time, wl_fixed_t sx, wl_fixed_t sy) {
    struct pointer_state *state = data;
    state->x = wl_fixed_to_double(sx);
    state->y = wl_fixed_to_double(sy);
}

static void pointer_button(void *data, struct wl_pointer *pointer,
                          uint32_t serial, uint32_t time, uint32_t button,
                          uint32_t state_w) {
    struct pointer_state *state = data;
    const char *action = state_w == WL_POINTER_BUTTON_STATE_PRESSED ?
                         "pressed" : "released";
    printf("Button %u %s at (%.2f, %.2f)\n", button, action, state->x, state->y);
}

static void pointer_axis(void *data, struct wl_pointer *pointer,
                        uint32_t time, uint32_t axis, wl_fixed_t value) {
    const char *axis_name = axis == WL_POINTER_AXIS_VERTICAL_SCROLL ?
                            "vertical" : "horizontal";
    printf("Scroll %s: %.2f\n", axis_name, wl_fixed_to_double(value));
}

static void pointer_frame(void *data, struct wl_pointer *pointer) {
    /* End of a logical pointer event group */
}

static void pointer_axis_source(void *data, struct wl_pointer *pointer,
                               uint32_t axis_source) {}
static void pointer_axis_stop(void *data, struct wl_pointer *pointer,
                             uint32_t time, uint32_t axis) {}
static void pointer_axis_discrete(void *data, struct wl_pointer *pointer,
                                  uint32_t axis, int32_t discrete) {}

static const struct wl_pointer_listener pointer_listener = {
    .enter = pointer_enter,
    .leave = pointer_leave,
    .motion = pointer_motion,
    .button = pointer_button,
    .axis = pointer_axis,
    .frame = pointer_frame,
    .axis_source = pointer_axis_source,
    .axis_stop = pointer_axis_stop,
    .axis_discrete = pointer_axis_discrete,
};

```

--------------------------------

### Set Wayland Pointer Cursor (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Sets the Wayland pointer cursor by attaching a buffer from a cursor image to a Wayland surface and committing the changes. It then informs the pointer of the new cursor's appearance and hotspot. Requires a `cursor_data` struct, `wl_pointer`, serial, and `wl_cursor`.

```c
#include <wayland-client.h>
#include <wayland-cursor.h>
#include <stdio.h>

struct cursor_data {
    struct wl_cursor_theme *theme;
    struct wl_cursor *default_cursor;
    struct wl_cursor *pointer_cursor;
    struct wl_surface *cursor_surface;
    struct wl_shm *shm;
};

void set_cursor(struct cursor_data *data, struct wl_pointer *pointer,
                uint32_t serial, struct wl_cursor *cursor) {
    if (!cursor || cursor->image_count == 0)
        return;

    struct wl_cursor_image *image = cursor->images[0];
    struct wl_buffer *buffer = wl_cursor_image_get_buffer(image);

    wl_surface_attach(data->cursor_surface, buffer, 0, 0);
    wl_surface_damage(data->cursor_surface, 0, 0, image->width, image->height);
    wl_surface_commit(data->cursor_surface);

    wl_pointer_set_cursor(pointer, serial, data->cursor_surface,
                          image->hotspot_x, image->hotspot_y);
}

```

--------------------------------

### Cleanup Wayland Cursor Resources (C)

Source: https://context7.com/xquartz/wayland/llms.txt

Frees the Wayland cursor resources, including the cursor surface and the cursor theme. This should be called when the cursor functionality is no longer needed to prevent memory leaks. Requires a `cursor_data` struct.

```c
#include <wayland-client.h>
#include <wayland-cursor.h>
#include <stdio.h>

struct cursor_data {
    struct wl_cursor_theme *theme;
    struct wl_cursor *default_cursor;
    struct wl_cursor *pointer_cursor;
    struct wl_surface *cursor_surface;
    struct wl_shm *shm;
};

void cleanup_cursors(struct cursor_data *data) {
    wl_surface_destroy(data->cursor_surface);
    wl_cursor_theme_destroy(data->theme);
}

```
Tokens:
Raw