Module pwcapture 

PipeWire consumer turning a portal monitor stream into host frames. PipeWire consumer for a portal monitor stream: one Video/Input stream per host output on the connection the portal opened, delivering the compositor’s frames to the host-capture consumer as [HostFrame]s.

The compositor allocates and fills the buffers, so a frame is never copied here: a dmabuf buffer becomes a Dmabuf the encoder imports in place (built once per buffer from duplicated fds, so the encoder’s import cache keeps hitting), a memfd buffer is mapped once and read in place by the CPU path. A buffer stays dequeued from the moment its frame is published until the consumer releases it, which is the same slot discipline the Wayland capture threads follow, so the retained frame an IDR re-encodes is still the compositor’s memory. Frames are handed on from the stream’s own thread the instant process runs, and the format offered to the compositor asks it to send at most the capture’s rate, so nothing is captured only to be dropped and nothing waits for a timer.

Format negotiation follows the modifier convention consumers and compositors agree on: each importable (fourcc, modifiers) pair the encoder’s EGL display reported is one format entry with a mandatory, non-fixating modifier choice, followed by plain entries the compositor answers with memfd buffers; the compositor picks, and the fixated format decides whether dmabuf or memfd buffers are requested. Cursor metadata is requested so a metadata-mode session delivers the host’s real cursor sprite to the cursor callback, and damage metadata so unchanged stripes are recognized.

Structs

BufferSlot 🔒

One buffer the compositor handed the stream: its PipeWire handle plus the import built on first use, kept for the buffer’s life so the same fds reach the encoder each time.

CursorPlace

Where a stream’s output sits for its cursor metas: the display’s origin in the union layout and its capture size, as Selkies laid it out (HostSession::set_layout), and the output’s logical size. A zero size is unknown.

Negotiated

The fixated format of a stream.

PwCore

One PipeWire connection, shared by every stream of a portal session.

PwStream

One output’s stream: the consumer end of a portal monitor stream.

Shared 🔒

State shared with the stream callbacks (handed to PipeWire as the listener’s user data).

Stamps 🔒

The capture instant of each portal frame, which the encoded frame carries as capture_ns into the RTP timestamp, abs-capture-time and pipeline_ms: the compositor’s header stamp where it reads as a CLOCK_MONOTONIC instant of this frame, else the frame’s arrival. A stamp is taken when it is no later than the arrival, at most STAMP_MAX_AGE_PERIODS frame periods before it, and later than the last instant given, so a stamp reused from an earlier frame, one on another clock’s scale, or one ahead of now moves neither. Which source each refusal falls back to is logged the first time it happens on a stream.

StreamConfig

What a stream asks the compositor for.

Enums

StampRefusal 🔒

Why a portal frame’s capture instant is its arrival rather than the compositor’s stamp.

Constants

FOURCC_AB24 🔒

FOURCC_AR24 🔒

FOURCC_XB24 🔒

FOURCC_XR24 🔒

HOST_MOTIONS_KEPT 🔒

Sent moves remembered for motion_at: well over a frame’s worth at any input rate.

MAX_CURSOR_EDGE 🔒

The largest cursor sprite edge the cursor meta is asked to hold. A compositor offers that meta at one fixed size (Mutter 384x384, KWin 256x256), and PipeWire leaves it off the buffers, with every sprite, unless the size falls inside the range asked for.

MAX_DAMAGE_REGIONS 🔒

SHM_FORMATS 🔒

The SPA pixel formats a consumer of BGRA-order pixels takes, best first, with the DRM fourcc each corresponds to (SPA names byte order, DRM names the little-endian word).

STAMP_MAX_AGE_PERIODS 🔒

How many frame periods before its arrival a compositor’s stamp may lie and still be taken as the frame’s capture instant (Stamps).

Statics

HOST_MOTIONS 🔒

The motion numbers handed to the host session, each with when it was sent (CLOCK_MONOTONIC ns), newest last: a cursor meta claims the moves sent before its buffer was stamped (motion_at), so one from a frame captured ahead of the latest move does not claim it.

HOST_POINTER

Host capture’s pointer, for WaylandBackend.pointer_location: None without a host session; while one is attached, the newest cursor meta’s position, or None before the first and where the host paints the cursor into its frames (no metas). The compositor’s own PointerShare is not read meanwhile: it stops at its last pass before the host attached. Process-wide like the backend slot.

Functions

enum_format_pod 🔒

enum_format_pods 🔒

The EnumFormat list for cfg: modifier-bearing entries for every importable fourcc when dmabufs are wanted, then the plain entries every compositor answers with memfd buffers.

header_pts 🔒

The compositor’s stamp from the buffer’s header meta, when it carries one.

host_pointer_at 🔒

A cursor meta’s position (x, y) in a stream negotiated at stream pixels as the pointer in the union layout: the display’s origin plus the position scaled to its capture size, the inverse of the mapping absolute motion is injected through (host::stream_point). The scale is the output’s capture pixels per logical pixel, what a relative pixel moves.

import_slot 🔒 ^⚠

Build the slot’s import on its first frame: the dmabuf planes as a Dmabuf of duplicated fds, or the memfd mapped whole.

meta 🔒

A Meta param asking for one metadata type of the given size (a plain or ranged Int).

meta_stamp 🔒

When a buffer was captured, for the moves its cursor meta claims: the compositor’s stamp where it is plausible (no later than arrival, at most four periods older), else arrival.

motion_at 🔒

The newest motion number of sent handed over at or before stamp; 0 before any.

negotiated_params 🔒

Buffers and metadata asked for once the format is fixated: dmabuf or memfd blocks per the modifier’s presence, three to eight buffers so one can be held retained while another is in flight and the compositor still has one to fill, plus header, damage, and cursor metas.

note_host_motion

Note motion number motion handed to the host session now.

on_add_buffer 🔒 ^⚠

on_param_changed 🔒 ^⚠

on_process 🔒 ^⚠

on_remove_buffer 🔒 ^⚠

on_state_changed 🔒 ^⚠

parse_format 🔒

The fixated Format param: pixel format, size, and whether a modifier (dmabuf) was agreed.

prefer_host_pointer

The pointer WaylandBackend.pointer_location reports: under host capture (Some), host capture’s alone, None included; otherwise the compositor’s own.

publish_host_pointer 🔒

Publish a cursor meta’s stream-pixel position to HOST_POINTER while a host session holds it, claiming the moves up to motion.

read_cursor 🔒 ^⚠

Read the cursor meta of a buffer: position, and a changed sprite forwarded to the cursor worker (an empty sprite hides it).

read_damage 🔒 ^⚠

The damage regions of a buffer, or the whole frame when the compositor sent none.

renegotiates 🔒

Whether moving a stream’s ask from cur to new renegotiates (reconfigure): anything but the preferred size does, and that only before a format stands.

shm_code 🔒

The wl_shm-style code HostCpuFrame converts by: 0/1 for the ARGB/XRGB words, DRM fourcc for the rest.

spa_to_fourcc 🔒