Treeland capture

protocol for capturing output contents or window contents

This protocol allows authorized application to capture output contents or window contents(useful for window streaming).

Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.

treeland_capture_session_v1

Deprecatedversion 1
persistent screen capture session

Represents a persistent screen capture session that continuously sends frames.

destroy()
delete this object

Unreferences the frame. This request must be called as soon as it's no longer valid.

start()
start session

Start session and keeps sending frame.

frame_done(tv_sec_hi: uint, tv_sec_lo: uint, tv_usec: uint)
Argument
Type
Description
tv_sec_hiuint
high 32 bits of the ready timestamp seconds
tv_sec_louint
low 32 bits of the ready timestamp seconds
tv_usecuint
ready timestamp microseconds
Indicates current frame is done.

This is the ACK to the current "ready" event. The next "frame" event will be sent only when current "ready" event is acknowledged. The timestamp should be the same as the one sent in "ready" event. If the frame has the "transient" flag, all objects sent before become invalid after this event.

frame(offset_x: int, offset_y: int, width: uint, height: uint, buffer_flags: uint, flags: uint<treeland_capture_session_v1.flags>, format: uint, mod_high: uint, mod_low: uint, num_objects: uint)
Argument
Type
Description
offset_xint
crop offset x
offset_yint
crop offset y
widthuint
frame width in pixels
heightuint
frame height in pixels
buffer_flagsuint
buffer flags
flagsuint<treeland_capture_session_v1.flags>
formatuint
DRM format code
mod_highuint
DRM format modifier high bits
mod_lowuint
DRM format modifier low bits
num_objectsuint
number of DMA-BUF objects in the frame
supply the client with information about the frame

Main event supplying the client with information about the frame. If the capture didn't fail, this event is always emitted first before any other events. When mask is provided, x and y should be offset relative to mask surface origin. Otherwise offset_x and offset_y should always be zero.

object(index: uint, fd: fd, size: uint, offset: uint, stride: uint, plane_index: uint)
Argument
Type
Description
indexuint
object index
fdfd
DMA-BUF file descriptor
sizeuint
size of the DMA-BUF in bytes
offsetuint
offset into the DMA-BUF
strideuint
line stride in bytes
plane_indexuint
plane index within the buffer
supply the client with object fd

Provides a DMA-BUF object for the current frame.

ready(tv_sec_hi: uint, tv_sec_lo: uint, tv_nsec: uint)
Argument
Type
Description
tv_sec_hiuint
high 32 bits of the presentation timestamp seconds
tv_sec_louint
low 32 bits of the presentation timestamp seconds
tv_nsecuint
presentation timestamp nanoseconds
indicates frame is available for reading

This event is sent as soon as the frame is presented, indicating it is available for reading. This event includes the time at which presentation happened at.

Notifies current frame is no longer valid.

If the capture failed or if the frame is no longer valid after the "frame" event has been emitted, this event will be used to inform the client to scrap the frame.

cancel_reason { temporary, permanent, resizing } 
Argument
Value
Description
temporary0
temporary error, source will produce more frames
permanent1
fatal error, source will not produce frames
resizing2
temporary error, source will produce more frames
flags { transient } 
Argument
Value
Description
transient0x1
clients should copy frame before processing

treeland_capture_frame_v1

Deprecatedversion 1

destroy()
delete this object, used or not

Destroys the context. This request can be sent at any time by the client.

copy(buffer: object<wl_buffer>)
Argument
Type
Description
bufferobject<wl_buffer>
copy capture contents

Copy capture contents to provided buffer

buffer(format: uint<wl_shm.format>, width: uint, height: uint, stride: uint)
Argument
Type
Description
formatuint<wl_shm.format>
widthuint
heightuint
strideuint
inform client to prepare buffer

Inform client to prepare buffer.

buffer_done()
all buffer formats have done

Inform client that all buffer formats supported are emitted.

Argument
Type
Description
flagsuint<treeland_capture_frame_v1.flags>
frame flags
frame flags

Provides flags about the frame. This event is sent once before the "ready" event.

ready()
buffer is copied

Inform that buffer is ready for reading

failed()
frame copy failed

Inform that frame copy fails.

flags { y_inverted } 
Argument
Value
Description
y_inverted0x1
contents are y-inverted

treeland_capture_context_v1

Deprecatedversion 1

destroy()
delete this object, used or not

Destroys the context. This request can be sent at any time by the client.

Argument
Type
Description
source_hintuint<treeland_capture_context_v1.source_type>
hint for the type of source to select
freezeuint
freeze compositing or not
with_cursoruint
whether source content contains cursor or not
maskobject<wl_surface>allow null
this mask is guaranteed to be at the top most
select source interactively

Selector is provided by compositor. Client can provide source hint to hint compositor to provide certain kinds of source.

Argument
Type
Description
framenew_id<treeland_capture_frame_v1>
the new capture frame object
capture one frame

This request can be called just once. A second call might result in a protocol error cause we just provide transient

create_session(session: new_id<treeland_capture_session_v1>)
Argument
Type
Description
sessionnew_id<treeland_capture_session_v1>
create a persistent session for capturing

Often used by a screen recorder.

Argument
Type
Description
region_xint
offset x of capture region relative to mask for capture contents
region_yint
offset y of capture region relative to mask for capture contents
region_widthuint
width of capture region
region_heightuint
height of capture region
source_typeuint<treeland_capture_context_v1.source_type>
final capture source type
notify client that source is ready

This event supplies the client some information about the capture source, including the capture region relative to mask and source type.

notify client that source selection is failed

There could a lot of reasons but the most common one is that selector is busy

source_type { output, window, region } 
Argument
Value
Description
output0x1
output source type
window0x2
window source type
region0x4
region source type
Argument
Value
Description
selector_busy1
selector is occupied by other context
user_cancel2
User cancel this context from compositor
source_destroyed3
Source has been destroyed
other4
other failure
source failure reason

treeland_capture_manager_v1

Deprecatedversion 1
capture manager

Global factory for creating capture sessions and capture contexts.

destroy()
destroy the capture manager

Destroy the treeland_capture_manager_v1 object.

get_context(context: new_id<treeland_capture_context_v1>)
Argument
Type
Description
contextnew_id<treeland_capture_context_v1>
get a capture context

Compositor Support

treeland_capture_manager_v1↓
Compositors
CageCage0.3.0
x
COSMICCOSMIC1.11.0
x
flakewm3.0.5
1
GameScopeGameScope3.17.0
x
HyprlandHyprland0.57.2
x
Jay1.14.0
x
KWinKWin6.7
x
LabwcLabwc0.20.2
x
LouvreLouvre2.14.1
x
MangoMango0.16.3
x
MirMir2.26
x
MuffinMuffin6.7.4
x
MutterMutter51
x
niriniri26.04
x
phocphoc0.55
x
Pila0.5.1
x
QtileQtile0.37.1
x
riverriver0.5.0
x
SwaySway1.11
x
TreelandTreeland0.8.0
1
WayfireWayfire0.9.0
x
WestonWeston15.0.1
x

SPDX-FileCopyrightText: 2024 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT