Treeland capture
This protocol allows authorized application to capture output contents or window contents(useful for window streaming).
treeland_capture_session_v1
destroy()
Unreferences the frame. This request must be called as soon as it's no longer valid.
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_x | int | crop offset x |
| offset_y | int | crop offset y |
| 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 |
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.
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.
cancel(reason: uint<treeland_capture_session_v1.cancel_reason>)
Argument | Type | Description |
|---|---|---|
| reason | uint<treeland_capture_session_v1.cancel_reason> |
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.
treeland_capture_frame_v1
destroy()
Destroys the context. This request can be sent at any time by the client.
Copy capture contents to provided buffer
buffer(format: uint<wl_shm.format>, width: uint, height: uint, stride: uint)
Argument | Type | Description |
|---|---|---|
| format | uint<wl_shm.format> | |
| width | uint | |
| height | uint | |
| stride | uint |
Inform client to prepare buffer.
buffer_done()
Inform client that all buffer formats supported are emitted.
flags(flags: uint<treeland_capture_once_context_v1.flags>)
Argument | Type | Description |
|---|---|---|
| flags | uint<treeland_capture_once_context_v1.flags> | frame flags |
Provides flags about the frame. This event is sent once before the "ready" event.
flags { y_inverted }
Argument | Value | Description |
|---|---|---|
| y_inverted | 0x1 | contents are y-inverted |
treeland_capture_context_v1
destroy()
Destroys the context. This request can be sent at any time by the client.
select_source(source_hint: uint<treeland_capture_context_v1.source_type>, freeze: uint, with_cursor: uint, mask: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| source_hint | uint<treeland_capture_context_v1.source_type> | |
| freeze | uint | freeze compositing or not |
| with_cursor | uint | whether source content contains cursor or not |
| mask | object<wl_surface>allow null | this mask is guaranteed to be at the top most |
Selector is provided by compositor. Client can provide source hint to hint compositor to provide certain kinds of source.
capture(frame: new_id<treeland_capture_frame_v1>)
Argument | Type | Description |
|---|---|---|
| frame | new_id<treeland_capture_frame_v1> |
This event 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 |
|---|---|---|
| session | new_id<treeland_capture_session_v1> |
Often used by a screen recorder.
source_ready(region_x: int, region_y: int, region_width: uint, region_height: uint, source_type: uint<treeland_capture_context_v1.source_type>)
Argument | Type | Description |
|---|---|---|
| region_x | int | offset x of capture region relative to mask for capture contents |
| region_y | int | offset y of capture region relative to mask for capture contents |
| region_width | uint | width of capture region |
| region_height | uint | height of capture region |
| source_type | uint<treeland_capture_context_v1.source_type> | final capture source type |
This event supplies the client some information about the capture source, including the capture region relative to mask and source type.
source_failed(reason: uint<treeland_capture_context_v1.source_failure>)
Argument | Type | Description |
|---|---|---|
| reason | uint<treeland_capture_context_v1.source_failure> |
There could a lot of reasons but the most common one is that selector is busy
source_failure { selector_busy, user_cancel, source_destroyed, other }
Argument | Value | Description |
|---|---|---|
| selector_busy | 1 | selector is occupied by other context |
| user_cancel | 2 | User cancel this context from compositor |
| source_destroyed | 3 | Source has been destroyed |
| other | 4 | other failure |
treeland_capture_manager_v1
destroy()
Destroy the treeland_capture_manager_v1 object.
get_context(context: new_id<treeland_capture_context_v1>)
Argument | Type | Description |
|---|---|---|
| context | new_id<treeland_capture_context_v1> |
Compositor Support
Mutter  47.3 | KWin  6.3 | Sway  1.10 | COSMIC  0.1 | Hyprland  0.44 | niri 25.01 | Weston  14 | Mir  2.19 | GameScope  3.15.14 | Jay 1.9.0 | Labwc  0.8.2 | Wayfire 0.9.0 | Treeland  0.5.17 | Louvre  2.14.1 | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| treeland_capture_manager_v1 | x | x | x | x | x | x | x | x | x | x | x | x | 1 | x |
Copyright
SPDX-FileCopyrightText: 2024 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT