wclient

Header: kmsroots/wclient.h

Table of contents (click to go)

Macros

Enums

kmr_wc_interface_type

Unions

API Documentation

Well format documentation

https://wayland.app/protocols/

kmr_wc_interface_type

enum kmr_wc_interface_type

KMR_WC_INTERFACE_NULL
KMR_WC_INTERFACE_WL_COMPOSITOR
KMR_WC_INTERFACE_XDG_WM_BASE
KMR_WC_INTERFACE_WL_SHM
KMR_WC_INTERFACE_WL_SEAT
KMR_WC_INTERFACE_ZWP_FULLSCREEN_SHELL_V1
KMR_WC_INTERFACE_ALL

Values may be or’d together to select wayland interface to bind to.

KMR_WC_INTERFACE_NULL: Bind no supported wayland interfaces to a client
KMR_WC_INTERFACE_WL_COMPOSITOR: Bind client to wl_compositor interface
KMR_WC_INTERFACE_XDG_WM_BASE: Bind client to xdg_wm_base interface
KMR_WC_INTERFACE_WL_SHM: Bind client to wl_shm interface
KMR_WC_INTERFACE_WL_SEAT: Bind client to wl_seat interface
KMR_WC_INTERFACE_ZWP_FULLSCREEN_SHELL_V1: Bind client to zwp_fullscreen_shell_v1 interface
KMR_WC_INTERFACE_ALL: Bind to all supported global interfaces to a client

kmr_wc_core

struct kmr_wc_core

kmr_wc_interface_type iType;
struct wl_display *wlDisplay;
struct wl_registry *wlRegistry;
struct wl_compositor *wlCompositor;
struct xdg_wm_base *xdgWmBase;
struct wl_shm *wlShm;
struct wl_seat *wlSeat;
struct zwp_fullscreen_shell_v1 *fullScreenShell;

iType: Wayland objects/interfaces to bind to client. These objects/interfaces

defines what requests are possible by a given wayland client.
wlDisplay: A global object representing the whole connection to wayland server.

This is object ID 1 which is pre-allocated and can be utilzed to

bootstrap all other objects.
wlRegistry: A global object used to recieve events from the server. Events may include

monitor hotplugging for instance.
wlCompositor: A singleton global object representing the compositor itself largely utilized to

allocate surfaces & regions to put pixels into. The compositor itself will combine

the contents of multiple surfaces and put them into one displayable output.
xdgWmBase: A singleton global object that enables clients to turn their surfaces

(rectangle box of pixels) into windows in a desktop environment.
wlShm: A singleton global object that provides support for shared memory.

Used to create a simple way of getting pixels from client to compositor.

Pixels are stored in an unsigned 8 bit integer the buffer is created

with mmap(2).
wlSeat: A singleton global object used to represent a group of

hot-pluggable input devices.
fullScreenShell: A singleton global object that has an interface that allow for

displaying of fullscreen surfaces.

kmr_wc_core_create_info

struct kmr_wc_core_create_info

kmr_wc_interface_type iType;
const char *displayName;

iType: Wayland global objects to include or exclude when the registry emits events
displayName: Specify the wayland server unix domain socket a client should communicate with.

This will set the $WAYLAND_DISPLAY variable to the desired display.

Passing NULL will result in opening unix domain socket /run/user/1000/wayland-0.

kmr_wc_core_create

struct kmr_wc_core *kmr_wc_core_create(struct kmr_wc_core_create_info *coreInfo);

Establishes connection to the wayland display server and sets up client specified global objects that each define what requests and events are possible.

Parameters:: coreInfo

Pointer to a struct kmr_wc_core_create_info which contains

the name of the server to connected to and the client specified

globals to bind to a given wayland client. Only if the server

supports these globals.
Returns:: on success: pointer to a struct kmr_wc_core

on failure: NULL

kmr_wc_core_destroy

void kmr_wc_core_destroy(struct kmr_wc_core *core);

Frees any allocated memory and closes FD’s (if open) created after kmr_wc_core_create() call.

/* Free'd members with fd's closed */
struct kmr_wc_core {
        struct wl_display              *wlDisplay;
        struct wl_registry             *wlRegistry;
        struct wl_compositor           *wlCompositor;
        struct xdg_wm_base             *xdgWmBase;
        struct wl_shm                  *wlShm;
        struct wl_seat                 *wlSeat;
        struct zwp_fullscreen_shell_v1 *fullScreenShell;
}

kmr_wc_shm_buffer

struct kmr_wc_shm_buffer

int shmFd;
size_t shmPoolSize;
uint8_t *shmPoolData;

shmFd: A file descriptor to an open wayland shared memory object.
shmPoolSize: The size of the amount of bytes in a given buffer pixels.

[Value = width * height * bytesPerPixel]
shmPoolData: Actual linear buffer to put pixel data into inorder to display.

The buffer itself created via mmap(2).

kmr_wc_buffer_handle

struct kmr_wc_buffer_handle

struct wl_buffer *buffer;

buffer: Buffer understood by the compositor attached to CPU

visible shm buffer.

kmr_wc_buffer

struct kmr_wc_buffer

int bufferCount;
struct kmr_wc_shm_buffer *shmBufferObjects;
struct kmr_wc_buffer_handle *wlBufferHandles;

bufferCount: The amount of wayland buffers allocated from a given wl_shm_pool.
shmBufferObjects: Pointer to an array of struct kmr_wc_shm_buffer containing all

information required to populate/release wayland shared memory

pixel buffer.
wlBufferHandles: Pointer to an array of struct kmr_wc_buffer_handle containing

compositor assigned buffer object.

kmr_wc_buffer_create_info

struct kmr_wc_buffer_create_info

struct kmr_wc_core *core;
int bufferCount;
int width;
int height;
int bytesPerPixel;
uint64_t pixelFormat;

core: Must pass a valid pointer to all binded/exposed wayland core interfaces

(important interfaces used: wl_shm)
bufferCount: The amount of buffers to allocate when storing pixel data

2 is generally a good option as it allows for double buffering
width: Amount of pixel horizontally (i.e 3840, 1920, …)
height: Amount of pixel vertically (i.e 2160, 1080, …)
bytesPerPixel: The amount of bytes per pixel generally going to be 4 bytes (32 bits)
pixelFormat: Memory layout of an individual pixel

kmr_wc_buffer_create

struct kmr_wc_buffer *kmr_wc_buffer_create(struct kmr_wc_buffer_create_info *bufferInfo);

Adds way to get pixels from client to compositor by creating writable shared memory buffers.

Parameters:: bufferInfo

Must pass a valid pointer to a struct kmr_wc_buffer_create_info

which gives details of how a buffer should be allocated and how

many to allocations to make.
Returns:: on success: pointer to a struct kmr_wc_buffer

on failure: NULL

kmr_wc_buffer_destroy

void kmr_wc_buffer_destroy(struct kmr_wc_buffer *buffer);

Frees any allocated memory and closes FD’s (if open) created after kmr_wc_buffer_create() call.

Parameters:: buffer

Must pass a valid pointer to a struct kmr_wc_buffer.

/* Free'd members with fd's closed */
struct kmr_wc_buffer {
        struct kmr_wc_shm_buffer {
                int     shmFd;
                uint8_t *shmPoolData;
        } *shmBufferObjects;

        struct kmr_wc_buffer_handle {
                struct wl_buffer *buffer;
        } *wlBufferHandles;
}

kmr_wc_renderer_impl

void kmr_wc_renderer_impl(volatile bool*, uint8_t*, int*, void*);

typedef void (*kmr_wc_renderer_impl)(volatile bool*, uint8_t*, void*);

Function pointer used by struct kmr_wc_surface_create_info Allows to pass the address of an external function you want to run Given that the arguments of the function are a pointer to a boolean, pointer to an integer, and a pointer to void data type

volatile bool *: A pointer to a boolean determining if the renderer is running.

Used to exit rendering operations.
uint8_t *: A pointer to an unsigned 8 bit integer determining current shm

buffer being rendered to used.
void *: A pointer to any arbitrary data the custom renderer may want pass

during rendering operations.

kmr_wc_surface

struct kmr_wc_surface

struct xdg_toplevel *xdgToplevel;
struct xdg_surface *xdgSurface;
struct wl_surface *wlSurface;
struct wl_callback *wlCallback;
uint8_t bufferCount;
struct kmr_wc_buffer_handle *wlBufferHandles;
void *rendererInfo;

xdgToplevel: An interface with many requests and events to manage application windows
xdgSurface: Top level surface for the window. Useful if one wants to create

a tree of surfaces. Provides additional requests for assigning

roles.
wlSurface: The image displayed on screen. If a wl_shm interface binded to client user

must attach a wl_buffer (struct kmr_wc_buffer_handle) to display pixels on

screen. Depending on rendering backend wl_buffer may not need to be allocated.
wlCallback: The amount of pixel (uint8_t) buffers allocated.

The array length of struct kmr_wc_buffer_handle.
bufferCount: Amount of elements in pointer to array of wlBufferHandles
wlBufferHandles: A pointer to an array of struct kmr_wc_buffer_handle.

Which holds a struct wl_buffer the pixel storage place

understood by compositor.
rendererInfo: Used by the implementation to free data. DO NOT MODIFY.

kmr_wc_surface_create_info

struct kmr_wc_surface_create_info

struct kmr_wc_core *core;
struct kmr_wc_buffer *buffer;
uint8_t bufferCount;
const char *appName;
bool fullscreen;
kmr_wc_renderer_impl renderer;
void *rendererData;
uint8_t *rendererCurrentBuffer;
volatile bool *rendererRunning;

core: Pointer to a struct kmr_wc_core contains all objects/interfaces

necessary for a client to run.
buffer: Must pass a valid pointer to a struct kmr_wc_buffer need to attach

a wl_buffer object to a wl_surface object. If NULL passed no buffer

will be attached to surface. Thus nothing will be displayed. Passing

this variable also enables in API swapping between shm buffers.

Swapping goes up to struct kmr_wc_buffer { bufferCount }.
appName: Sets the window name.
fullscreen: Determines if window should be fullscreen or not
renderer: Function pointer that allows custom external renderers to be executed by the api

when before registering a frame wl_callback. Renderer before presenting
rendererData: Pointer to an optional address. This address may be the address of a struct.

Reference passed depends on external renderer function.
rendererCurrentBuffer: Pointer to an integer used by the api to update the current displayable buffer.
rendererRunning: Pointer to a boolean that determines if a given window/surface is actively running.

kmr_wc_surface_create

struct kmr_wc_surface *kmr_wc_surface_create(struct kmr_wc_surface_create_info *surfaceInfo);

Creates a surface to place pixels in and a window for displaying surface pixels.

Parameters:: surfaceInfo

Must pass a valid pointer to a struct kmr_wc_surface_create_info

which gives details on what buffers are associated with surface

object, the name of the window, and how the window should be displayed.
Returns:: on success: pointer to a struct kmr_wc_surface

on failure: NULL

kmr_wc_surface_destroy

void kmr_wc_surface_destroy(struct kmr_wc_surface *surface);

Frees any allocated memory and closes FD’s (if open) created after kmr_wc_surface_create() call.

Parameters:: surface

Must pass a valid pointer to a struct kmr_wc_surface.

/* Free'd members with fd's closed */
struct kmr_wc_surface {
        struct xdg_toplevel *xdgToplevel;
        struct xdg_surface  *xdgSurface;
        struct wl_surface   *wlSurface;
        void                *rendererInfo;
}