River Protocol & Architecture

info@ozbem.com (ebeem) — Thu, 18 Apr 2024 00:00:00 +0000

I’m currently studying River in the hope of crafting a guile scheme based window manager, River uses a unique non-monolithic approach, unlike the "all-in-one" approach seen in many compositors, it splits the responsibilities of rendering and window management.

I am using this post as a living document to log my notes and findings as I study the river-window-management-v1 protocol. One done, it should be a great foundation for those who want to understand my window manager or write their own based on River.

interfaces

river_window_manager_v1

Window management state influences the communication between the compositor and individual windows (e.g. xdg_toplevels). Window management state includes window dimensions, fullscreen state, keyboard focus, keyboard bindings, and more.Only one window management client may be active at a time. The compositor should use the unavailable event if necessary to enforce this.

Requests

(2) stop

description: client wants to stop/close

task: Nothing, wait for finished event to proceed with killing the process

(4) destroy()

description: should be called after the finished event has been received.

task: clear anything that's still references and terminate

(6) manage_finish()

description: client has made all changes to window management state after receiving the manage_start event

task: Nothing, don't send any requests to change window management state unless you receive another manage_start

(7) manage_dirty()

description: indicates that a manage_sequence events is needed to reflect some new state changes

task: Nothing, you will receive a manage_start soon to make the changes as before

(9) render_finish()

description: client has made all changes to rendering state after receiving the render_start event

task: Nothing, don't send any requests to change render state unless you receive another manage_start or manage_render

(15) get_shell_surface(surface: wl_surface) -> id: river_shell_surface_v1

description: client wants to create a new shell surface and assign river_shell_surface_v1 role to provided surface, it can be used to draw status bars, menus, tab bar, etc.

task: Nothing

(16) exit_session()

description: client wants to terminal the wayland session, this will close all clients and the compositor

task: Nothing

Events

(1) unavailable()

description: indicates that window management is unavailable, most likely due to another window management client already running

task: The client should clear everything in this case and terminate

(3) finished()

description: indicates that the server will send no longer events

task: The client should clear everything in this case and send destroy request

(5) manage_start()

description: indicates that the server has sent events indicating new state changes

task: The client should send all requesting modfying the window management state then make a manage_finish request

(8) render_start()

description: indicates that the server has sent events indicating window positions and dimensions changes in the interface river_window_v1

task: The client should send all requesting modfying the rendering state then make a render_finish request

(10) session_locked()

description: indicates that the session has been locked

task: The client should most likely may restrict the available keybindings or call a lock screen application

(11) session_unlocked()

description: indicates that the session has been unlocked

task: The client should most likely may reinitiate the available keybindings

(12) window() -> id: river_window_v1

description: indicates that a new has been created.

task: store the id/proxy and mapping for further use

(13) output() -> id: river_output_v1

description: indicates that a output has been created (monitor plugged)

task: store the id/proxy and mapping for further use

(14) seat() -> id: river_seat_v1

description: indicates that a seat/input has been created (keyboard/mouse/touchscreen plugged)

task: store the id/proxy and mapping for further use

river_window_v1

Logical window. For example, a window may correspond to an xdg_toplevel or Xwayland window. A newly created window will not be displayed until the window manager makes a propose_dimensions or fullscreen request as part of a render_sequence

Requests

(1) close()

description: client want the window to be closed, window may ignore this request

task: wait for closed

(3) destroy()

description: client cleaned window object and it can be safely destroyed

task: nothing

(4) get_node() -> id: river_node_v1

description: client wants to know the node that corresponds to the window, this can only be called once per node, so it should be cached after first call.

task: store it as metadata of the window record/object

(7) propose_dimensions(width: int, height: int)

description: client proposes dimensions for the window.

task: only send in manage_sequence as it modifies the window management state, wait for dimensions event for confirmation about the update

(8) hide()

description: client wants to hide a window (newly created windows are shown by default).

task: only send in render_sequence as it modifies the rendering state.

(9) show()

description: client wants to show a window, care about windows that are placed on top of it as they will not make the target window visible.

task: only send in render_sequence as it modifies the rendering state.

(15) use_csd()

description: client wants to use client side decoration (default).

task: only send in manage_sequence as it modifies the window management state.

(16) use_ssd()

description: tell the client to use server side decoration

task: only send in manage_sequence as it modifies the window management state.

(17) set_borders(edges: uint, width: int, r: uint, g: uint, b: uint,

a:uint)

description: decorates the window with borders drawn by the compositor

task: only send in render_sequence as it modifies the rendering state.

(18) set_tiled(edges: uint)

description: inform the window that it is part of a tiled layout

task: only send in manage_sequence as it modifies the window management state.

(19) get_decoration_above(surface: wl_surface) -> id: river_decoration_v1

description: inform the window that it is part of a tiled layout

task: only send in manage_sequence as it modifies the window management state.

Events

(2) closed()

description: indicates that the window has been closed

task: clean window and send destroy

(5) dimensions_hint(min_width: int, min_height: int, max_width: int,

max_height: int)

description: indicates the window's preferred min/max dimensions (excluding borders and decorations). The window manager is free to propose other dimensions for layouts that require it like tiling.

task: store the preferred dimensions in window object/record for further use. This event will be followed by manage_start and state changes should be made there.

(6) dimensions(width: int, height: int)

description: indicates the window's dimensions (excluding borders and decorations). This event is sent as part of the render_sequence due to propose_dimensions or fullscreen request

task: store the dimensions in window object/record for further use. This event will be followed by render_start and state changes should be made there.

(10) app_id(app_id: string?)

description: indicates the window's application id was changed

task: store the app_id in window object/record for further use. This will be followed by a manage_sequence in case state changes need to be made.

(11) title(title: string?)

description: indicates the window's title was changed

task: store the title in window object/record for further use. This will be followed by a manage_sequence in case state changes need to be made.

(12) parent(parent: river_window_v1?)

description: indicates the window's parent was changed

task: store the parent in window object/record for further use. This will be followed by a manage_sequence in case state changes need to be made.

(13) decoration_hint(hint: uint)

description: indicates the window's parent was changed

task: store the hint in window object/record for further use. This will be followed by a manage_sequence in case state changes need to be made.

(14) decoration_hint(hint: uint)

description: indicates the window's parent was changed

task: store the hint in window object/record for further use. This will be followed by a manage_sequence in case state changes need to be made.

River on Ozbem

River Protocol & Architecture

interfaces

river_window_manager_v1

Requests

(2) stop

(4) destroy()

(6) manage_finish()

(7) manage_dirty()

(9) render_finish()

(15) get_shell_surface(surface: wl_surface) -> id: river_shell_surface_v1

(16) exit_session()

Events

(1) unavailable()

(3) finished()

(5) manage_start()

(8) render_start()

(10) session_locked()

(11) session_unlocked()

(12) window() -> id: river_window_v1

(13) output() -> id: river_output_v1

(14) seat() -> id: river_seat_v1

river_window_v1

Requests

(1) close()

(3) destroy()

(4) get_node() -> id: river_node_v1

(7) propose_dimensions(width: int, height: int)

(8) hide()

(9) show()

(15) use_csd()

(16) use_ssd()

(17) set_borders(edges: uint, width: int, r: uint, g: uint, b: uint,

(18) set_tiled(edges: uint)

(19) get_decoration_above(surface: wl_surface) -> id: river_decoration_v1

Events

(2) closed()

(5) dimensions_hint(min_width: int, min_height: int, max_width: int,

(6) dimensions(width: int, height: int)

(10) app_id(app_id: string?)

(11) title(title: string?)

(12) parent(parent: river_window_v1?)

(13) decoration_hint(hint: uint)

(14) decoration_hint(hint: uint)