mirror of
https://gitlab.freedesktop.org/wayland/wayland-protocols.git
synced 2025-12-20 16:20:09 +01:00
Compare commits
No commits in common. "main" and "1.43" have entirely different histories.
26 changed files with 273 additions and 3223 deletions
|
|
@ -25,9 +25,9 @@ workflow:
|
|||
|
||||
.debian:
|
||||
variables:
|
||||
FDO_DISTRIBUTION_VERSION: trixie
|
||||
FDO_DISTRIBUTION_VERSION: bookworm
|
||||
FDO_DISTRIBUTION_PACKAGES: 'build-essential pkg-config meson git ca-certificates libffi-dev libexpat1-dev libxml2-dev'
|
||||
FDO_DISTRIBUTION_TAG: '2025-11-15.0'
|
||||
FDO_DISTRIBUTION_TAG: '2024-09-05.0'
|
||||
FDO_DISTRIBUTION_EXEC: 'env FDO_CI_CONCURRENT=${FDO_CI_CONCURRENT} ./.gitlab-ci/debian-install.sh'
|
||||
|
||||
check-commit:
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
Input method protocol
|
||||
|
||||
Maintainers:
|
||||
Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
|
||||
|
|
@ -1,905 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="input_method_experimental_v2">
|
||||
|
||||
<copyright>
|
||||
Copyright © 2008-2011 Kristian Høgsberg
|
||||
Copyright © 2010-2011 Intel Corporation
|
||||
Copyright © 2012-2013 Collabora, Ltd.
|
||||
Copyright © 2012, 2013 Intel Corporation
|
||||
Copyright © 2015, 2016 Jan Arne Petersen
|
||||
Copyright © 2017, 2018 Red Hat, Inc.
|
||||
Copyright © 2018 Purism SPC
|
||||
Copyright © 2025 DorotaC
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice (including the next
|
||||
paragraph) shall be included in all copies or substantial portions of the
|
||||
Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<description summary="Protocol for creating input methods">
|
||||
This protocol allows applications to act as input methods for compositors.
|
||||
|
||||
An input method context is used to manage the state of the input method.
|
||||
|
||||
Text strings are UTF-8 encoded, their indices and lengths are in bytes.
|
||||
|
||||
This document adheres to the RFC 2119 when using words like "must",
|
||||
"should", "may", etc.
|
||||
|
||||
Warning! The protocol described in this file is currently in the
|
||||
experimental phase. Backwards incompatible major versions of the
|
||||
protocol are to be expected. Exposing this protocol without an opt-in
|
||||
mechanism is discouraged.
|
||||
</description>
|
||||
|
||||
<interface name="xx_input_method_v1" version="3">
|
||||
<description summary="input method">
|
||||
An input method object allows for clients to compose text.
|
||||
|
||||
The objects connects the client to a text input in an application, and
|
||||
lets the client to serve as an input method for a seat.
|
||||
|
||||
The xx_input_method_v1 object can occupy two distinct states: active and
|
||||
inactive. In the active state, the object is associated to and
|
||||
communicates with a text input. In the inactive state, there is no
|
||||
associated text input, and the only communication is with the compositor.
|
||||
Initially, the input method is in the inactive state.
|
||||
|
||||
Requests issued in the inactive state must be accepted by the compositor.
|
||||
Because of the serial mechanism, and the state reset on activate event,
|
||||
they will not have any effect on the state of the next text input.
|
||||
|
||||
There must be no more than one input method object per seat.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="surface_has_role" value="0x0" summary="surface already has a role"/>
|
||||
<entry name="inactive" value="0x1" summary="operation requires the input method to be active"/>
|
||||
</enum>
|
||||
|
||||
<event name="activate">
|
||||
<description summary="input method has been requested">
|
||||
Notification that a text input focused on this seat requested the input
|
||||
method to be activated.
|
||||
|
||||
This event serves the purpose of providing the compositor with an
|
||||
active input method.
|
||||
|
||||
This event resets all state associated with previous
|
||||
surrounding_text, text_change_cause, and content_type events, as well
|
||||
as the state associated with set_preedit_string, commit_string, and
|
||||
delete_surrounding_text requests, and destroys any existing input_popup_surface objects.
|
||||
In addition, it marks the xx_input_method_v1 object as active.
|
||||
|
||||
The surrounding_text, and content_type events must follow before the
|
||||
next done event if the text input supports the respective
|
||||
functionality.
|
||||
|
||||
State set with this event is double-buffered. It will get applied on
|
||||
the next xx_input_method_v1.done event, and stay valid until changed.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<event name="deactivate">
|
||||
<description summary="deactivate event">
|
||||
Notification that no focused text input currently needs an active
|
||||
input method on this seat.
|
||||
|
||||
This event marks the xx_input_method_v1 object as inactive.
|
||||
compositor must destroy all existing xx_input_popup_surface_v2 objects.
|
||||
|
||||
This event resets all state associated with previous
|
||||
surrounding_text, text_change_cause, and content_type events, as well
|
||||
as the state associated with set_preedit_string, commit_string, and
|
||||
delete_surrounding_text requests.
|
||||
|
||||
State set with this event is double-buffered. It will get applied on
|
||||
the next xx_input_method_v1.done event, and stay valid until changed.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<event name="surrounding_text">
|
||||
<description summary="surrounding text event">
|
||||
Updates the surrounding plain text around the cursor, excluding the
|
||||
preedit text.
|
||||
|
||||
If any preedit text is present, it is replaced with the cursor for the
|
||||
purpose of this event.
|
||||
|
||||
The argument text is a buffer containing the preedit string, and must
|
||||
include the cursor position, and the complete selection. It should
|
||||
contain additional characters before and after these. There is a
|
||||
maximum length of wayland messages, so text can not be longer than 4000
|
||||
bytes.
|
||||
|
||||
cursor is the byte offset of the cursor within the text buffer.
|
||||
|
||||
anchor is the byte offset of the selection anchor within the text
|
||||
buffer. If there is no selected text, anchor must be the same as
|
||||
cursor.
|
||||
|
||||
If this event does not arrive before the first done event, the input
|
||||
method may assume that the text input does not support this
|
||||
functionality and ignore following surrounding_text events.
|
||||
|
||||
Values set with this event are double-buffered. They will get applied
|
||||
and set to initial values on the next xx_input_method_v1.done
|
||||
event.
|
||||
|
||||
The initial state for affected fields is empty, meaning that the text
|
||||
input does not support sending surrounding text. If the empty values
|
||||
get applied, subsequent attempts to change them may have no effect.
|
||||
</description>
|
||||
<arg name="text" type="string"/>
|
||||
<arg name="cursor" type="uint"/>
|
||||
<arg name="anchor" type="uint"/>
|
||||
</event>
|
||||
|
||||
<event name="text_change_cause">
|
||||
<description summary="indicates the cause of surrounding text change">
|
||||
Tells the input method why the text surrounding the cursor changed.
|
||||
|
||||
Whenever the client detects an external change in text, cursor, or
|
||||
anchor position, it must issue this request to the compositor. This
|
||||
request is intended to give the input method a chance to update the
|
||||
preedit text in an appropriate way, e.g. by removing it when the user
|
||||
starts typing with a keyboard.
|
||||
|
||||
cause describes the source of the change.
|
||||
|
||||
The value set with this event is double-buffered. It will get applied
|
||||
and set to its initial value on the next xx_input_method_v1.done
|
||||
event.
|
||||
|
||||
The initial value of cause is input_method.
|
||||
</description>
|
||||
<arg name="cause" type="uint" enum="xx_text_input_v3.change_cause"/>
|
||||
</event>
|
||||
|
||||
<event name="content_type">
|
||||
<description summary="content purpose and hint">
|
||||
Indicates the content type and hint for the current
|
||||
xx_input_method_v1 instance.
|
||||
|
||||
Values set with this event are double-buffered. They will get applied
|
||||
on the next xx_input_method_v1.done event.
|
||||
They get reset to initial on the next committed deactivate event.
|
||||
|
||||
The initial value for hint is none, and the initial value for purpose
|
||||
is normal.
|
||||
</description>
|
||||
<arg name="hint" type="uint" enum="xx_text_input_v3.content_hint"/>
|
||||
<arg name="purpose" type="uint" enum="xx_text_input_v3.content_purpose"/>
|
||||
</event>
|
||||
|
||||
<event name="set_available_actions" since="3">
|
||||
<description summary="announce the available actions">
|
||||
Announces the actions available for the currently active text input.
|
||||
|
||||
Values set with this event are double-buffered. They will get applied
|
||||
on the next .done event.
|
||||
They get reset to the initial value on the next committed deactivate event.
|
||||
|
||||
The initial value is an empty set: no actions are available.
|
||||
|
||||
Values in the available_actions array come from text-input-v3.action.
|
||||
</description>
|
||||
<arg name="available_actions" type="array" summary="available actions"/>
|
||||
</event>
|
||||
|
||||
<event name="announce_supported_features" since="3">
|
||||
<description summary="announce extra supported features">
|
||||
Notifies the input method what the currently active text input client is able to do.
|
||||
|
||||
This event should come within the same .done sequence as .activate. Otherwise, the input method may ignore it.
|
||||
|
||||
Values set with this event are double-buffered. They will get applied
|
||||
on the next .done event.
|
||||
They get reset to initial on the next committed deactivate event.
|
||||
|
||||
The initial value for features is none.
|
||||
</description>
|
||||
<arg name="features" type="uint" enum="xx_text_input_v3.supported_features"/>
|
||||
</event>
|
||||
|
||||
<event name="done">
|
||||
<description summary="apply state">
|
||||
Atomically applies state changes recently sent to the client.
|
||||
|
||||
The done event establishes and updates the state of the client, and
|
||||
must be issued after any changes to apply them.
|
||||
|
||||
Text input state (content purpose, content hint, surrounding text, and
|
||||
change cause) is conceptually double-buffered within an input method
|
||||
context.
|
||||
|
||||
Events modify the pending state, as opposed to the current state in use
|
||||
by the input method. A done event atomically applies all pending state,
|
||||
replacing the current state. After done, the new pending state is as
|
||||
documented for each related request.
|
||||
|
||||
Events must be applied in the order of arrival.
|
||||
|
||||
Neither current nor pending state are modified unless noted otherwise.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<request name="perform_action" since="3">
|
||||
<description summary="perform action">
|
||||
Perform an action on this text input.
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next commit request.
|
||||
|
||||
The initial value of action is none.
|
||||
</description>
|
||||
<arg name="action" type="uint" enum="xx_text_input_v3.action" summary="action to perform"/>
|
||||
</request>
|
||||
|
||||
<request name="commit_string">
|
||||
<description summary="commit string">
|
||||
Send the commit string text for insertion to the application.
|
||||
|
||||
Inserts a string at current cursor position (see commit event
|
||||
sequence). The string to commit could be either just a single character
|
||||
after a key press or the result of some composing.
|
||||
|
||||
The argument text is a buffer containing the string to insert. There is
|
||||
a maximum length of wayland messages, so text can not be longer than
|
||||
4000 bytes.
|
||||
|
||||
Values set with this request are double-buffered. They must be applied
|
||||
and reset to initial on the next .commit request.
|
||||
|
||||
The initial value of text is an empty string.
|
||||
</description>
|
||||
<arg name="text" type="string"/>
|
||||
</request>
|
||||
|
||||
<request name="set_preedit_string">
|
||||
<description summary="pre-edit string">
|
||||
Send the pre-edit string text to the application text input.
|
||||
|
||||
Place a new composing text (pre-edit) at the current cursor position.
|
||||
Any previously set composing text must be removed. Any previously
|
||||
existing selected text must be removed. The cursor is moved to a new
|
||||
position within the preedit string.
|
||||
|
||||
The argument text is a buffer containing the preedit string. There is
|
||||
a maximum length of wayland messages, so text can not be longer than
|
||||
4000 bytes.
|
||||
|
||||
The arguments cursor_begin and cursor_end are counted in bytes relative
|
||||
to the beginning of the submitted string buffer. Cursor should be
|
||||
hidden by the text input when both are equal to -1.
|
||||
|
||||
cursor_begin indicates the beginning of the cursor. cursor_end
|
||||
indicates the end of the cursor. It may be equal or different than
|
||||
cursor_begin.
|
||||
|
||||
Values set with this request are double-buffered. They must be applied on
|
||||
the next xx_input_method_v1.commit request.
|
||||
They must be reset to initial on the next committed disable event.
|
||||
|
||||
The initial value of text is an empty string. The initial value of
|
||||
cursor_begin, and cursor_end are both 0.
|
||||
</description>
|
||||
<arg name="text" type="string"/>
|
||||
<arg name="cursor_begin" type="int"/>
|
||||
<arg name="cursor_end" type="int"/>
|
||||
</request>
|
||||
|
||||
<request name="delete_surrounding_text">
|
||||
<description summary="delete text">
|
||||
Remove the surrounding text.
|
||||
|
||||
before_length and after_length are the number of bytes before and after
|
||||
the current cursor index (excluding the preedit text) to delete.
|
||||
|
||||
If any preedit text is present, it is replaced with the cursor for the
|
||||
purpose of this event. In effect before_length is counted from the
|
||||
beginning of preedit text, and after_length from its end (see commit
|
||||
event sequence).
|
||||
|
||||
Values set with this request are double-buffered. They must be applied
|
||||
and reset to initial on the next xx_input_method_v1.commit request.
|
||||
|
||||
The initial values of both before_length and after_length are 0.
|
||||
</description>
|
||||
<arg name="before_length" type="uint"/>
|
||||
<arg name="after_length" type="uint"/>
|
||||
</request>
|
||||
|
||||
<request name="move_cursor" since="3">
|
||||
<description summary="move cursor and change selection">
|
||||
Unselects text, moves the cursor and selects text.
|
||||
|
||||
This is equivalent to dragging the mouse over some text: it deselects whatever might be currently selected and selects a new range of text.
|
||||
|
||||
The offsets used in arguments are in bytes relative to the current cursor position. Cursor is the new position of the cursor, and anchor is the opposite end of selection. If there's no selection, anchor should be equal to cursor.
|
||||
|
||||
The offsets do not take preedit contents into account, nor is preedit changed in any way with this request.
|
||||
|
||||
Both cursor and anchor must fall on code point boundaries, otherwise text input client may ignore the request. It is therefore not recommended for an input method to move any of them beyond the text received in surrounding_text.
|
||||
|
||||
When surrounding_text is not supported, the offsets must not be interpreted as bytes, but as some human-readable unit at least as big as a code point, for example a grapheme.
|
||||
|
||||
The cursor and anchor arguments can also take the following special values:
|
||||
BEGINNING := 0x8000_0000 = i32::MIN
|
||||
END := 0x7fff_ffff = i32::MAX
|
||||
meaning, respectively, the beginning and the end of of all text in the input field.
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next commit request.
|
||||
|
||||
The initial values of both cursor and anchor are 0.
|
||||
</description>
|
||||
<arg name="cursor" type="int"/>
|
||||
<arg name="anchor" type="int"/>
|
||||
</request>
|
||||
|
||||
<request name="commit">
|
||||
<description summary="apply state">
|
||||
Apply state changes from commit_string, set_preedit_string and
|
||||
delete_surrounding_text requests.
|
||||
|
||||
The state relating to these events is double-buffered, and each one
|
||||
modifies the pending state. This request replaces the current state
|
||||
with the pending state.
|
||||
|
||||
The connected text input is expected to proceed by evaluating the
|
||||
changes in the following order:
|
||||
|
||||
1. Replace existing preedit string with the cursor.
|
||||
2. Delete requested surrounding text.
|
||||
3. Insert commit string with the cursor at its end.
|
||||
4. Move the cursor and selection.
|
||||
5. Calculate surrounding text to send.
|
||||
6. Insert new preedit text in cursor position.
|
||||
7. Place cursor inside preedit text.
|
||||
8. Perform the requested action.
|
||||
|
||||
Note that the input method can not receive more than 4000 bytes of selection text, which might be the case for example when the entire document is selected. Nevertheless, the text input must delete the entire selected range before inserting the commit string.
|
||||
|
||||
The serial number reflects the last state of the xx_input_method_v1
|
||||
object known to the client. The value of the serial argument must be
|
||||
equal to the number of done events already issued by that object. When
|
||||
the compositor receives a commit request with a serial different than
|
||||
the number of past done events, it must proceed as normal, except it
|
||||
should not change the current state of the xx_input_method_v1 object.
|
||||
</description>
|
||||
<arg name="serial" type="uint"/>
|
||||
</request>
|
||||
|
||||
<request name="get_input_popup_surface" since="2">
|
||||
<description summary="create popup surface">
|
||||
Creates a new xx_input_popup_surface_v2 object wrapping a given
|
||||
surface.
|
||||
|
||||
The surface gets assigned the "input_popup" role. If the surface
|
||||
already has an assigned role, the compositor must issue a protocol
|
||||
error.
|
||||
|
||||
Issuing this request before receiving a committed .activate causes the "inactive" error.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="xx_input_popup_surface_v2"/>
|
||||
<arg name="surface" type="object" interface="wl_surface"/>
|
||||
<arg name="positioner" type="object" interface="xx_input_popup_positioner_v1"/>
|
||||
</request>
|
||||
|
||||
<event name="unavailable">
|
||||
<description summary="input method unavailable">
|
||||
The input method ceased to be available.
|
||||
|
||||
The compositor must issue this event as the only event on the object if
|
||||
there was another input_method object associated with the same seat at
|
||||
the time of its creation.
|
||||
|
||||
The compositor must issue this request when the object is no longer
|
||||
useable, e.g. due to seat removal.
|
||||
|
||||
The input method context becomes inert and should be destroyed after
|
||||
deactivation is handled. Any further requests and events except for the
|
||||
destroy request must be ignored.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the input method">
|
||||
Destroys the xx_input_method_v1 object and any associated child
|
||||
objects.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_input_popup_surface_v2" version="1">
|
||||
<description summary="popup surface">
|
||||
An input method popup surface is a short-lived, temporary surface.
|
||||
It is meant as an area to show suggestions, candidates, or for other input-related uses.
|
||||
|
||||
The compositor should anchor it at the active text input cursor area.
|
||||
|
||||
The client must call wl_surface.commit on the corresponding wl_surface
|
||||
for input_popup_surface state updates to take effect, unless otherwise noted.
|
||||
|
||||
After the initial wl_surface.commit, the compositor must reply with a configure sequence (see .start_configure) initializing all the compositor-provided state of the popup. That means providing values for:
|
||||
|
||||
- width
|
||||
- height
|
||||
- anchor_x
|
||||
- anchor_y
|
||||
- anchor_width
|
||||
- anchor_height
|
||||
- serial
|
||||
|
||||
using the appropriate events.
|
||||
|
||||
The popup will only be presented to the user after the client receives the configure sequence and replies with .ack_configure.
|
||||
|
||||
An example init sequence could look like this:
|
||||
|
||||
1. client (Cl): popup = input_method.get_popup(wl_surface, positioner)
|
||||
2. Cl: wl_surface.commit()
|
||||
3. compositor (Co): popup.start_configure(150, 150, 10, -2, 5, 30)
|
||||
5. Co: input_method.done()
|
||||
6. Cl: ack_configure()
|
||||
7. Cl: wl_surface.commit()
|
||||
|
||||
A newly created input_popup_surface will be stacked on top of all previously created
|
||||
input_popup_surfaces associated with the same text input.
|
||||
|
||||
A typical sequence resulting from the user selecting a new text field and typing some text:
|
||||
|
||||
1. compositor (Co): input_method.enable()
|
||||
2. Co: input_method.done()
|
||||
3. [init sequence]
|
||||
4. Co: input_method.set_surrounding_text("new text")
|
||||
5. Co: popup.start_configure(150, 150, -60, -2, 55, 30)
|
||||
6. Co: input_method.done()
|
||||
7. client (Cl): ack_configure()
|
||||
8. Cl: wl_surface.commit()
|
||||
|
||||
When the corresponding input_method receives a commited .disable event, the popup gets destroyed and becomes invalid and its surface gets unmapped.
|
||||
|
||||
The client must not destroy the underlying wl_surface while the
|
||||
xx_input_popup_surface_v2 object exists.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="invalid_serial" value="0" summary="received acknowledgement for a serial which has already been acknowledged or has never been issued"/>
|
||||
</enum>
|
||||
|
||||
<event name="start_configure">
|
||||
<description summary="configure the popup surface">
|
||||
The start_configure event updates the popup geometry and marks the start of a configure sequence.
|
||||
|
||||
The anchor_* arguments represent the geometry of the anchor to which the popup was attached, relative to the upper left corner of the
|
||||
popup's surface. Note that this makes anchor_x, anchor_y the reverse of the what they represent in xdg_popup.
|
||||
|
||||
A configure sequence is a set of one or more events configuring the state of the
|
||||
input_popup_surface, starting with this event and ending with input_method.done. After the input_method.done event, the configure sequence is considered submitted.
|
||||
|
||||
State set by event in a configure sequence is conceptually double-buffered.
|
||||
Every argument overwrites its previous value. The state change should get applied atomically with the input_method.done ending the sequence, and the value of serial should return to the undefined value.
|
||||
|
||||
Events on the input_popup_surface object received outside a configure sequence (while serial is undefined) must be ignored by the client.
|
||||
|
||||
A configure sequence shall be sent every time the compositor (re)positions the popup, or the shape of the anchor changes, for example after popup creation, or in response to text being typed and the text cursor moving.
|
||||
|
||||
The client may update the surface in response to input_method.done. Unless the popup is destroyed by the input_method.done, the client must reply with
|
||||
an .ack_configure request with the serial sent in the start_configure event at
|
||||
some point after the sequence ends and before committing the new surface.
|
||||
|
||||
If the client receives multiple configure sequences before it can respond
|
||||
to one, it is free to discard all but the last event it received.
|
||||
|
||||
<!--
|
||||
This sounds complicated because it is.
|
||||
There are two semi-dependent states: that of the text input and that of the popup surface(s).
|
||||
|
||||
Alternatives:
|
||||
|
||||
1. Don't synchronize the state of the popup and the state of the text.
|
||||
|
||||
Rejected because every¹ time the pre-edit changes shape there are two events: the .configure for the surface and the .done from the input method.
|
||||
|
||||
¹Actually only when the pre-edit is committed. In the current design, changing the pre-edit doesn't get reported to input-method and doesn't cause a .done. A .done gets emitted for the cursor shape change (so on every stroke), so the compositor would be able to filter it out by paying attention to state changes. That would leave double-rendering only in the case of committing the text (surrounding-text changes) or text changing without input causing reposition (collaborative editing). Worth it maybe?
|
||||
On the other hand, it's not impossible in the future that some other property gets updated on nearly every text change.
|
||||
|
||||
2. Complicate some and mandate .done after some .configures
|
||||
|
||||
Rejected because the different path for syncing (on .confgure or on .done) are difficult to explain and sound like a source of bugs. Also, this ended up needing additional events.
|
||||
|
||||
3. Simplify a lot and remove .configure in favor of relying on .done entirely
|
||||
|
||||
Rejected because it pulls in .ack_configure after every .done regardless of surface status. Also underspecifed regarding which popup needs to be configured.
|
||||
-->
|
||||
</description>
|
||||
<arg name="width" type="uint" summary="popup width"/>
|
||||
<arg name="height" type="uint" summary="popup height"/>
|
||||
<arg name="anchor_x" type="int"
|
||||
summary="x position relative to anchor geometry"/>
|
||||
<arg name="anchor_y" type="int"
|
||||
summary="y position relative to anchor geometry"/>
|
||||
<arg name="anchor_width" type="uint"
|
||||
summary="width of the anchor area"/>
|
||||
<arg name="anchor_height" type="uint"
|
||||
summary="height of the anchor area"/>
|
||||
<arg name="serial" type="uint" summary="serial of the configure sequence"/>
|
||||
</event>
|
||||
|
||||
<request name="ack_configure">
|
||||
<description summary="acknowledge a configure sequence">
|
||||
This request notifies the compositor that the client updated its surface in response to a configure sequence.
|
||||
|
||||
The purpose of this request is to synchronize the updates of the surface geometry with the surface contents.
|
||||
For example, when the compositor assigns a size larger than prevously, the client must fill the additional space before the popup gets displayed to the user with the new size. When the compositor receives .ack_configure, it can proceed to draw the new size.
|
||||
|
||||
.ack_configure should be sent after every submitted configure sequence, passing along the serial received in it.
|
||||
|
||||
An .ack_configure request is conceptually double-buffered.
|
||||
Every request overrides the previous one. The request takes effect once the .commit request is sent on the corresponding surface.
|
||||
|
||||
If the client receives multiple configure sequences before it
|
||||
can respond to one, it may acknowledge only the last configure sequence by using its serial in the .ack_configure request.
|
||||
|
||||
Committing an .ack_configure request consumes the serial number sent with
|
||||
the request, as well as serial numbers sent by all configure sequences
|
||||
submitted on this input_popup_surface prior to the configure sequence referenced by
|
||||
the committed serial.
|
||||
|
||||
Committing this request with a serial that, for this surface, never appeared in a submitted configure sequence, or one that was already committed before, raises an invalid_serial
|
||||
error.
|
||||
</description>
|
||||
<arg name="serial" type="uint" summary="the serial from the configure sequence"/>
|
||||
</request>
|
||||
|
||||
<request name="reposition">
|
||||
<description summary="recalculate the popup's location">
|
||||
Reposition an already-mapped popup. The popup will be placed given the
|
||||
details in the passed input_popup_positioner object.
|
||||
|
||||
The request is processed immediately, without the need to issue wl_surface.commit, but the actual repositioning takes place later, after .ack_configure.
|
||||
|
||||
The compositor should reply with a configure sequence including:
|
||||
- input_popup_surface.start_configure,
|
||||
- input_popup_surface.repositioned, including the token passed in this request.
|
||||
|
||||
This will discard any parameters set by the previous positioner.
|
||||
|
||||
If multiple .reposition requests are sent before the .repositioned event is submitted as part of a configure sequence, the compositor may ignore all
|
||||
but the last one.
|
||||
|
||||
The new popup position will not take
|
||||
effect until the corresponding configure sequence is acknowledged by the
|
||||
client. See input_popup_surface.repositioned for details.
|
||||
|
||||
The token itself is opaque, and has no other special meaning.
|
||||
</description>
|
||||
<arg name="positioner" type="object" interface="xx_input_popup_positioner_v1"/>
|
||||
<arg name="token" type="uint" summary="reposition request token"/>
|
||||
</request>
|
||||
|
||||
<event name="repositioned">
|
||||
<description summary="signal the completion of a reposition request">
|
||||
The compositor sends the .repositioned event in response to the .reposition request to notify about its completion.
|
||||
|
||||
The new geometry of the popup can be communicated using additional events within a configure sequence including:
|
||||
- input_popup_surface.start_configure, and
|
||||
- the .anchor_position event to update the relative position to the anchor.
|
||||
|
||||
When responding to a .reposition request, the token argument is the token passed in the that request.
|
||||
|
||||
This event is sent as part of a configure sequence.
|
||||
State set by this event is conceptually double-buffered.
|
||||
Every argument overwrites its previous value. The state change should get applied atomically with the next input_method.done event.
|
||||
|
||||
The client should optionally update the content of the popup, but must
|
||||
acknowledge the new popup configuration for the new position to take
|
||||
effect. See input_popup_surface.ack_configure for details.
|
||||
</description>
|
||||
<arg name="token" type="uint" summary="reposition request token"/>
|
||||
</event>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="remove the popup">
|
||||
This destroys the popup. Explicitly destroying the input_popup_surface
|
||||
object will also dismiss the popup, and unmap the surface.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_input_popup_positioner_v1" version="1">
|
||||
<description summary="input method popup positioner">
|
||||
The input_popup_positioner provides a collection of rules for the placement of an input method popup surface relative to the cursor.
|
||||
Rules can be defined to ensure
|
||||
the text input area remains within the visible area's borders, and to
|
||||
specify how the popup changes its position, such as sliding along
|
||||
an axis, or flipping around a rectangle. These positioner-created rules are
|
||||
constrained by the requirement that a popup must intersect with or
|
||||
be at least partially adjacent to the surface containing the text input.
|
||||
|
||||
See the various requests for details about possible rules.
|
||||
|
||||
A newly created positioner has the following state:
|
||||
- 0 surface width
|
||||
- 0 surface height
|
||||
- anchor at the center ("none")
|
||||
- gravity towards the center ("none")
|
||||
- constraints adjustment set to none
|
||||
- offset at x = 0, y = 0
|
||||
- not reactive
|
||||
|
||||
Upon receiving a request taking the positioner as an argument, the compositor makes a copy of the rules
|
||||
specified by the input_popup_positioner. Thus, after the request is complete the
|
||||
input_popup_positioner object can be destroyed or reused; further changes to the
|
||||
object will have no effect on previous usages.
|
||||
|
||||
For an input_popup_positioner object to be considered complete, its state must contain a non-zero width and height. Passing an incomplete input_popup_positioner object when
|
||||
positioning a surface raises an invalid_positioner error.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="invalid_input" value="0" summary="invalid input provided"/>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the input_popup_positioner object">
|
||||
Notify the compositor that the positioner will no longer be used.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="set_size">
|
||||
<description summary="set the size of the to-be positioned rectangle">
|
||||
Set the size of the surface that is to be positioned with the positioner
|
||||
object. The size is in surface-local coordinates and corresponds to the
|
||||
window geometry. See xdg_surface.set_window_geometry.
|
||||
|
||||
If any dimension is set to zero, the invalid_input error is raised.
|
||||
</description>
|
||||
<arg name="width" type="uint" summary="width of positioned rectangle"/>
|
||||
<arg name="height" type="uint" summary="height of positioned rectangle"/>
|
||||
</request>
|
||||
|
||||
<enum name="anchor">
|
||||
<entry name="none" value="0" summary="no edge, specfies center"/>
|
||||
<entry name="top" value="1"/>
|
||||
<entry name="bottom" value="2"/>
|
||||
<entry name="left" value="3"/>
|
||||
<entry name="right" value="4"/>
|
||||
<entry name="top_left" value="5"/>
|
||||
<entry name="bottom_left" value="6"/>
|
||||
<entry name="top_right" value="7"/>
|
||||
<entry name="bottom_right" value="8"/>
|
||||
</enum>
|
||||
|
||||
<request name="set_anchor">
|
||||
<description summary="set anchor rectangle anchor">
|
||||
Defines the anchor point for the anchor rectangle. The specified anchor
|
||||
is used to derive an anchor point that the popup surface will be
|
||||
positioned relative to. If a corner anchor is set (e.g. 'top_left' or
|
||||
'bottom_right'), the anchor point will be at the specified corner;
|
||||
otherwise, the derived anchor point will be centered on the specified
|
||||
edge, or in the center of the anchor rectangle if no edge is specified.
|
||||
</description>
|
||||
<arg name="anchor" type="uint" enum="anchor"
|
||||
summary="anchor"/>
|
||||
</request>
|
||||
|
||||
<enum name="gravity">
|
||||
<entry name="none" value="0" summary="center to center"/>
|
||||
<entry name="top" value="1"/>
|
||||
<entry name="bottom" value="2"/>
|
||||
<entry name="left" value="3"/>
|
||||
<entry name="right" value="4"/>
|
||||
<entry name="top_left" value="5"/>
|
||||
<entry name="bottom_left" value="6"/>
|
||||
<entry name="top_right" value="7"/>
|
||||
<entry name="bottom_right" value="8"/>
|
||||
</enum>
|
||||
|
||||
<request name="set_gravity">
|
||||
<description summary="set surface gravity">
|
||||
Defines in what direction the surface should be positioned, relative to
|
||||
the anchor point of the anchor rectangle. If a corner gravity is
|
||||
specified (e.g. 'bottom_right' or 'top_left'), then the surface
|
||||
will be placed towards the specified gravity; otherwise, the child
|
||||
surface will be centered over the anchor point on any axis that had no
|
||||
gravity specified. If the gravity is not in the ‘gravity’ enum, an
|
||||
invalid_input error is raised.
|
||||
</description>
|
||||
<arg name="gravity" type="uint" enum="gravity"
|
||||
summary="gravity direction"/>
|
||||
</request>
|
||||
|
||||
<enum name="constraint_adjustment" bitfield="true">
|
||||
<description summary="constraint adjustments">
|
||||
The constraint adjustment value define ways the compositor will adjust
|
||||
the position of the surface, if the unadjusted position would result
|
||||
in the surface being partly constrained.
|
||||
|
||||
Whether a surface is considered 'constrained' is left to the compositor
|
||||
to determine. For example, the surface may be partly outside the
|
||||
compositor's defined 'work area', thus necessitating the child surface's
|
||||
position be adjusted until it is entirely inside the work area.
|
||||
|
||||
The adjustments can be combined, according to a defined precedence: 1)
|
||||
Flip, 2) Slide, 3) Resize.
|
||||
</description>
|
||||
<entry name="none" value="0">
|
||||
<description summary="don't move the surface when constrained">
|
||||
Don't alter the surface position even if it is constrained on some
|
||||
axis, for example partially outside the edge of an output.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="slide_x" value="1">
|
||||
<description summary="move along the x axis until unconstrained">
|
||||
Slide the surface along the x axis until it is no longer constrained.
|
||||
|
||||
First try to slide towards the direction of the gravity on the x axis
|
||||
until either the edge in the opposite direction of the gravity is
|
||||
unconstrained or the edge in the direction of the gravity is
|
||||
constrained.
|
||||
|
||||
Then try to slide towards the opposite direction of the gravity on the
|
||||
x axis until either the edge in the direction of the gravity is
|
||||
unconstrained or the edge in the opposite direction of the gravity is
|
||||
constrained.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="slide_y" value="2">
|
||||
<description summary="move along the y axis until unconstrained">
|
||||
Slide the surface along the y axis until it is no longer constrained.
|
||||
|
||||
First try to slide towards the direction of the gravity on the y axis
|
||||
until either the edge in the opposite direction of the gravity is
|
||||
unconstrained or the edge in the direction of the gravity is
|
||||
constrained.
|
||||
|
||||
Then try to slide towards the opposite direction of the gravity on the
|
||||
y axis until either the edge in the direction of the gravity is
|
||||
unconstrained or the edge in the opposite direction of the gravity is
|
||||
constrained.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="flip_x" value="4">
|
||||
<description summary="invert the anchor and gravity on the x axis">
|
||||
Invert the anchor and gravity on the x axis if the surface is
|
||||
constrained on the x axis. For example, if the left edge of the
|
||||
surface is constrained, the gravity is 'left' and the anchor is
|
||||
'left', change the gravity to 'right' and the anchor to 'right'.
|
||||
|
||||
If the adjusted position also ends up being constrained, the resulting
|
||||
position of the flip_x adjustment will be the one before the
|
||||
adjustment.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="flip_y" value="8">
|
||||
<description summary="invert the anchor and gravity on the y axis">
|
||||
Invert the anchor and gravity on the y axis if the surface is
|
||||
constrained on the y axis. For example, if the bottom edge of the
|
||||
surface is constrained, the gravity is 'bottom' and the anchor is
|
||||
'bottom', change the gravity to 'top' and the anchor to 'top'.
|
||||
|
||||
The adjusted position is calculated given the original anchor
|
||||
rectangle and offset, but with the new flipped anchor and gravity
|
||||
values.
|
||||
|
||||
If the adjusted position also ends up being constrained, the resulting
|
||||
position of the flip_y adjustment will be the one before the
|
||||
adjustment.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="resize_x" value="16">
|
||||
<description summary="horizontally resize the surface">
|
||||
Resize the surface horizontally so that it is completely
|
||||
unconstrained.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="resize_y" value="32">
|
||||
<description summary="vertically resize the surface">
|
||||
Resize the surface vertically so that it is completely unconstrained.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<request name="set_constraint_adjustment">
|
||||
<description summary="set the adjustment to be done when constrained">
|
||||
Specify how the popup should be positioned if the originally intended
|
||||
position caused the surface to be constrained, meaning at least
|
||||
partially outside positioning boundaries set by the compositor. The
|
||||
adjustment is set by constructing a bitmask describing the adjustment to
|
||||
be made when the surface is constrained on that axis.
|
||||
|
||||
If no bit for one axis is set, the compositor will assume that the child
|
||||
surface should not change its position on that axis when constrained.
|
||||
|
||||
If more than one bit for one axis is set, the order of how adjustments
|
||||
are applied is specified in the corresponding adjustment descriptions.
|
||||
|
||||
The default adjustment is none.
|
||||
</description>
|
||||
<arg name="constraint_adjustment" type="uint" enum="constraint_adjustment"
|
||||
summary="bit mask of constraint adjustments"/>
|
||||
</request>
|
||||
|
||||
<request name="set_offset">
|
||||
<description summary="set surface position offset">
|
||||
Specify the surface position offset relative to the position of the
|
||||
anchor on the anchor rectangle and the anchor on the surface. For
|
||||
example if the anchor of the anchor rectangle is at (x, y), the surface
|
||||
has the gravity bottom|right, and the offset is (ox, oy), the calculated
|
||||
surface position will be (x + ox, y + oy). The offset position of the
|
||||
surface is the one used for constraint testing. See
|
||||
set_constraint_adjustment.
|
||||
|
||||
An example use case is placing a popup menu on top of a user interface
|
||||
element, while aligning the user interface element of the parent surface
|
||||
with some user interface element placed somewhere in the popup surface.
|
||||
</description>
|
||||
<arg name="x" type="int" summary="surface position x offset"/>
|
||||
<arg name="y" type="int" summary="surface position y offset"/>
|
||||
</request>
|
||||
|
||||
<request name="set_reactive">
|
||||
<description summary="continuously reconstrain the surface">
|
||||
When set reactive, the surface is reconstrained if the conditions used
|
||||
for constraining changed, e.g. the window containing the text input moved.
|
||||
|
||||
Whenever the conditions change and the popup gets reconstrained, a
|
||||
configure sequence is sent with updated geometry.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_input_method_manager_v2" version="3">
|
||||
<description summary="input method manager">
|
||||
The input method manager allows the client to become the input method on
|
||||
a chosen seat.
|
||||
|
||||
No more than one input method must be associated with any seat at any
|
||||
given time.
|
||||
</description>
|
||||
|
||||
<request name="get_input_method">
|
||||
<description summary="request an input method object">
|
||||
Request a new input xx_input_method_v1 object associated with a given
|
||||
seat.
|
||||
</description>
|
||||
<arg name="seat" type="object" interface="wl_seat"/>
|
||||
<arg name="input_method" type="new_id" interface="xx_input_method_v1"/>
|
||||
</request>
|
||||
|
||||
<request name="get_positioner">
|
||||
<description summary="create a positioner object">
|
||||
Create a positioner object. A positioner object is used to position
|
||||
surfaces relative to some parent surface. See the interface description
|
||||
and xdg_surface.get_popup for details.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="xx_input_popup_positioner_v1"/>
|
||||
</request>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the input method manager">
|
||||
Destroys the xx_input_method_manager_v2 object.
|
||||
|
||||
The xx_input_method_v1 objects originating from it remain valid.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
Keyboard filter protocol
|
||||
|
||||
Maintainers:
|
||||
Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
|
||||
|
|
@ -1,176 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="keyboard_filter_experimental_v1">
|
||||
|
||||
<copyright>
|
||||
Copyright 2018 Mike Blumenkrantz
|
||||
Copyright 2018 Samsung Electronics Co., Ltd
|
||||
Copyright 2018 Red Hat Inc.
|
||||
Copyright 2025 DorotaC
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice (including the next
|
||||
paragraph) shall be included in all copies or substantial portions of the
|
||||
Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<description summary="filter and intercept keyboard events">
|
||||
The keyboard_filter protocol allows a client to intercept selected keyboard events and prevent them from reaching the focused surface.
|
||||
|
||||
This protocol offers a way to alter events reaching an application without the need to allow generating arbitrary keyboard events.
|
||||
|
||||
High-level overview of the interfaces:
|
||||
|
||||
The keyboard_filter_manager exposes the bind_to_input_method request which binds a wl_keyboard to an xx_input_method.
|
||||
The resulting keyboard_filter object has the can be then used for intercepting keyboard events in accordance to input method needs.
|
||||
|
||||
This document adheres to the RFC 2119 when using words like "must",
|
||||
"should", "may", etc.
|
||||
|
||||
Warning! The protocol described in this file is currently in the
|
||||
experimental phase. Backwards incompatible major versions of the
|
||||
protocol are to be expected. Exposing this protocol without an opt-in
|
||||
mechanism is discouraged.
|
||||
</description>
|
||||
|
||||
<interface name="xx_keyboard_filter_v1" version="1">
|
||||
<description summary="keyboard event filtering functionality">
|
||||
Manages the filtering of key presses.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="invalid_serial" value="0x1" summary="compositor received serial not adhering to requirements"/>
|
||||
</enum>
|
||||
|
||||
<request name="unbind">
|
||||
<description summary="Stop intercepting">
|
||||
Unbind the keyboard and stop intercepting events.
|
||||
|
||||
Unbinds the bound keyboard and the input method. the compositor must stop redirecting keyboard events. Events that the keyboard_filter client has not yet responded to are treated as if they received the "passthrough" action.
|
||||
|
||||
This request takes effect immediately.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<enum name="filter_action">
|
||||
<entry name="consume" value="0" summary="consume the key event"/>
|
||||
<entry name="passthrough" value="1" summary="pass the key event to the text input client"/>
|
||||
</enum>
|
||||
|
||||
<request name="filter">
|
||||
<description summary="decide the processing of a keyboard event">
|
||||
This request controls the filtering of keyboard input events before reaching the focused surface.
|
||||
|
||||
Usage:
|
||||
|
||||
While keyboard_filter is intercepting, the compositor must send every intercepted event to its bound wl_keyboard, and hold a copy of it in an internal queue.
|
||||
When the client responds with the .filter request, the compositor either removes the event from the queue (filter_action.consume), or sends the copy to the original wl_keyboard objects (filter_action.passthrough).
|
||||
|
||||
The compositor must process .filter the oldest event in the queue before processing more recent ones.
|
||||
For this reason, the client sets the argument "serial" to the serial of the corresponding event it received.
|
||||
|
||||
Exceptions:
|
||||
|
||||
If the event is other than wl_keyboard.key or contains no serial, it cannot be filtered. The keyboard_filter client must not respond to it with .filter request. When such an event is oldest in the queue, the compositor must proceed as if the event had received a "passthrough" reply.
|
||||
|
||||
As of wl_keyboard v10 and keyboard_filter_v1, the only event that can be filtered is the wl_keyboard.key event.
|
||||
|
||||
Sequence:
|
||||
|
||||
The wl_keyboard begins to receive events after input_method.activate is committed.
|
||||
The valid serial is the serial of the oldest wl_keyboard event which has been sent after input_method.activate but which hasn't yet received a .filter confirmation.
|
||||
The compositor may raise the invalid_serial error in response to events with serials it had not issued.
|
||||
The compositor must ignore events with all other serials. (Particularly, this means events with repeating serials are accepted normally and are not ignored).
|
||||
Events must be filtered in order of arrival.
|
||||
</description>
|
||||
<arg name="serial" type="uint"/>
|
||||
<arg name="action" type="uint" enum="filter_action"/>
|
||||
</request>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the keyboard">
|
||||
Destroys the keyboard_filter object, stops event interception, and unbinds the wl_keyboard and input_method objects bound to it.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_keyboard_filter_manager_v1" version="1">
|
||||
<enum name="error">
|
||||
<entry name="already_bound" value="0x1" summary="an argument is already bound"/>
|
||||
<entry name="wrong_seat" value="0x2" summary="the keyboard i attached to the wrong seat for this operation"/>
|
||||
</enum>
|
||||
|
||||
<request name="bind_to_input_method">
|
||||
<description summary="Bind a keyboard to an input method">
|
||||
Bind a keyboard to an input method for the purpose of capturing key presses before they reach the text input client.
|
||||
|
||||
When a wl_keyboard is bound, the compositor must redirect to it the input events intended for the focused surface with text input enabled. The wl_keyboard instance receives no other events from then on.
|
||||
See keyboard_filter.filter.
|
||||
|
||||
For the bound wl_keyboard instance to intercept events, the following conditions must be fulfilled:
|
||||
- there's a focused surface,
|
||||
- the surface has an enabled text input object,
|
||||
- the bound input method is active (for the meaning of "active", see input_method.activate, input_method.deactivate).
|
||||
|
||||
When those conditions are fulfilled, the compositor must start redirecting input events intended for the text input surface to the wl_keyboard bound with this request. Otherwise, the text input surface receives events without intercepting them.
|
||||
|
||||
Be aware that the text input client might use a wl_keyboard object(s) of different version(s) than the one used by the input method. The compositor should issue events as it would normally do for the versions in question. This protocol assumes that events to multiple keyboards of different protocol versions are equivalent.
|
||||
|
||||
Background:
|
||||
|
||||
Whenever the input method is activated, the compositor must start sending it keyboard events intended for the text-input client, so that the input method can be controlled using a keyboard.
|
||||
Traditionally, from the user perspective, input methods receive keys as if they were an overlay: keys which are interesting to the input method gain a special input method meaning, all others work as usual.
|
||||
The binding and the keyboard_filter.filter request together make this possible by letting the input method indicate which events it is interested in.
|
||||
|
||||
Conceptually, when a wl_keyboard is bound to an input_method, the compositor prevents all keyboard events directed to the text input client from reaching it. They are delayed until the input method decides how to filter them using the keyboard_filter.filter request.
|
||||
|
||||
Arguments:
|
||||
|
||||
The wl_keyboard must not be already bound to another interface.
|
||||
The wl_keyboard must only receive events between committed .activate and .deactivate.
|
||||
|
||||
The surface argument represents an arbitrary wl_surface. When issuing wl_keyboard.enter and wl_keyboard.leave on the bound wl_keyboard, the compositor must replace the original surface argument with the one provided by the input method in this request.
|
||||
|
||||
Because the wl_keyboard.enter and wl_keyboard.leave events require a surface as the target, one must be provided even if the input method doesn't display one. A dummy one is sufficient. The provided wl_surface will not be used for any other purpose than explained above.
|
||||
|
||||
The surface must outlive the input method.
|
||||
|
||||
NOTE: This feature works much better with compositor-side key repeat introduced in wl_seat version 10. This protocol doesn't provide controls for filtering repeat key events generated client-side.
|
||||
A compositor implementing this protocol should implement compositor-side key repeat.
|
||||
|
||||
This request takes effect immediately.
|
||||
|
||||
Attempting to bind a keyboard to an input method which is already bound must cause the already_bound error.
|
||||
Attempting to bind a keyboard object which was already bound must cause the already_bound error.
|
||||
Attempting to bind a keyboard object to an input method acting on a different seat must cause the wrong_seat error.
|
||||
|
||||
When the input method gets destroyed, the compositor must stop issuing events to the keyboard and ignore any further requests to keyboard_filter, except keyboard_filter.destroy.
|
||||
</description>
|
||||
<arg name="keyboard" type="object" interface="wl_keyboard" />
|
||||
<arg name="input_method" type="object" interface="xx_input_method_v1" />
|
||||
<arg name="surface" type="object" interface="wl_surface" />
|
||||
<arg name="extensions" type="new_id" interface="xx_keyboard_filter_v1"/>
|
||||
</request>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the input method manager">
|
||||
Destroys the xx_keyboard_filter_manager_v1 object.
|
||||
|
||||
The xx_keyboard_filter_v1 objects originating from it remain unaffected.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
Session management protocol
|
||||
|
||||
Maintainers:
|
||||
Carlos Garnacho <carlosg@gnome.org>
|
||||
|
|
@ -1,264 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="xx_session_management_v1">
|
||||
<copyright>
|
||||
Copyright 2018 Mike Blumenkrantz
|
||||
Copyright 2018 Samsung Electronics Co., Ltd
|
||||
Copyright 2018 Red Hat Inc.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice (including the next
|
||||
paragraph) shall be included in all copies or substantial portions of the
|
||||
Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<description summary="Protocol for managing application sessions">
|
||||
This description provides a high-level overview of the interplay between
|
||||
the interfaces defined this protocol. For details, see the protocol
|
||||
specification.
|
||||
|
||||
The xx_session_manager protocol declares interfaces necessary to
|
||||
allow clients to restore toplevel state from previous executions. The
|
||||
xx_session_manager_v1.get_session request can be used to obtain a
|
||||
xx_session_v1 resource representing the state of a set of toplevels.
|
||||
|
||||
Clients may obtain the session string to use in future calls through
|
||||
the xx_session_v1.created event. Compositors will use this string
|
||||
as an identifiable token for future runs, possibly storing data about
|
||||
the related toplevels in persistent storage.
|
||||
|
||||
Toplevels are managed through the xx_session_v1.add_toplevel and
|
||||
xx_session_toplevel_v1.remove pair of requests. Clients will explicitly
|
||||
request a toplevel to be restored according to prior state through the
|
||||
xx_session_v1.restore_toplevel request before the toplevel is mapped.
|
||||
|
||||
Warning! The protocol described in this file is currently in the
|
||||
experimental phase. Backwards incompatible major versions of the
|
||||
protocol are to be expected. Exposing this protocol without an opt-in
|
||||
mechanism is discouraged.
|
||||
</description>
|
||||
|
||||
<interface name="xx_session_manager_v1" version="1">
|
||||
<description summary="manage sessions for applications">
|
||||
The xx_session_manager interface defines base requests for creating and
|
||||
managing a session for an application. Sessions persist across application
|
||||
and compositor restarts unless explicitly destroyed. A session is created
|
||||
for the purpose of maintaining an application's xdg_toplevel surfaces
|
||||
across compositor or application restarts. The compositor should remember
|
||||
as many states as possible for surfaces in a given session, but there is
|
||||
no requirement for which states must be remembered.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="in_use" summary="a requested session is already in use"
|
||||
value="1"/>
|
||||
</enum>
|
||||
|
||||
<enum name="reason">
|
||||
<description summary="reason for getting a session">
|
||||
The reason may determine in what way a session restores the window
|
||||
management state of associated toplevels.
|
||||
|
||||
For example newly launched applications might be launched on the active
|
||||
workspace with restored size and position, while a recovered
|
||||
applications might restore additional state such as active workspace and
|
||||
stacking order.
|
||||
</description>
|
||||
<entry name="launch" value="1">
|
||||
<description summary="an app is newly launched">
|
||||
A new app instance is launched, for example from an app launcher.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="recover" value="2">
|
||||
<description summary="an app recovered">
|
||||
A app instance is recovering from for example a compositor or app crash.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="session_restore" value="3">
|
||||
<description summary="an app restored">
|
||||
A app instance is restored, for example part of a restored session, or
|
||||
restored from having been temporarily terminated due to resource
|
||||
constraints.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="Destroy this object">
|
||||
This has no effect other than to destroy the xx_session_manager object.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="get_session">
|
||||
<description summary="create or restore a session">
|
||||
Create a session object corresponding to either an existing session
|
||||
identified by the given session identifier string or a new session.
|
||||
While the session object exists, the session is considered to be "in
|
||||
use".
|
||||
|
||||
If a identifier string represents a session that is currently actively
|
||||
in use by the the same client, an 'in_use' error is raised. If some
|
||||
other client is currently using the same session, the new session will
|
||||
replace managing the associated state.
|
||||
|
||||
NULL is passed to initiate a new session. If an id is passed which does
|
||||
not represent a valid session, the compositor treats it as if NULL had
|
||||
been passed.
|
||||
|
||||
A client is allowed to have any number of in use sessions at the same
|
||||
time.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="xx_session_v1"/>
|
||||
<arg name="reason" type="uint" enum="reason"
|
||||
summary="reason for session"/>
|
||||
<arg name="session" type="string"
|
||||
summary="the session to restore"
|
||||
allow-null="true"/>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_session_v1" version="1">
|
||||
<description summary="A session for an application">
|
||||
A xx_session_v1 object represents a session for an application. While the
|
||||
object exists, all surfaces which have been added to the session will
|
||||
have states stored by the compositor which can be reapplied at a later
|
||||
time. Two sessions cannot exist for the same identifier string.
|
||||
|
||||
States for surfaces added to a session are automatically updated by the
|
||||
compositor when they are changed.
|
||||
|
||||
Surfaces which have been added to a session are automatically removed from
|
||||
the session if xdg_toplevel.destroy is called for the surface.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="invalid_restore"
|
||||
summary="restore cannot be performed after initial toplevel commit"
|
||||
value="1"/>
|
||||
<entry name="name_in_use"
|
||||
summary="toplevel name is already in used"
|
||||
value="2"/>
|
||||
<entry name="already_mapped"
|
||||
summary="toplevel was already mapped when restored"
|
||||
value="3"/>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="Destroy the session">
|
||||
Destroy a session object, preserving the current state but not continuing
|
||||
to make further updates if state changes occur. This makes the associated
|
||||
xx_toplevel_session_v1 objects inert.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="remove" type="destructor">
|
||||
<description summary="Remove the session">
|
||||
Remove the session, making it no longer available for restoration. A
|
||||
compositor should in response to this request remove the data related to
|
||||
this session from its storage.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="add_toplevel">
|
||||
<description summary="add a new surface to the session">
|
||||
Attempt to add a given surface to the session. The passed name is used
|
||||
to identify what window is being restored, and may be used store window
|
||||
specific state within the session.
|
||||
|
||||
Calling this with a toplevel that is already managed by the session with
|
||||
the same associated will raise an in_use error.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="xx_toplevel_session_v1"/>
|
||||
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
|
||||
<arg name="name" type="string"/>
|
||||
</request>
|
||||
|
||||
<request name="restore_toplevel">
|
||||
<description summary="restore a surface state">
|
||||
Inform the compositor that the toplevel associated with the passed name
|
||||
should have its window management state restored.
|
||||
|
||||
Calling this with a toplevel that is already managed by the session with
|
||||
the same associated will raise an in_use error.
|
||||
|
||||
This request must be called prior to the first commit on the associated
|
||||
wl_surface, otherwise an already_mapped error is raised.
|
||||
|
||||
As part of the initial configure sequence, if the toplevel was
|
||||
successfully restored, a xx_toplevel_session_v1.restored event is
|
||||
emitted. See the xx_toplevel_session_v1.restored event for further
|
||||
details.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="xx_toplevel_session_v1"/>
|
||||
<arg name="toplevel" type="object" interface="xdg_toplevel"/>
|
||||
<arg name="name" type="string"/>
|
||||
</request>
|
||||
|
||||
<event name="created">
|
||||
<description summary="newly-created session id">
|
||||
Emitted at most once some time after getting a new session object. It
|
||||
means that no previous state was restored, and a new session was created.
|
||||
The passed id can be used to restore previous sessions.
|
||||
</description>
|
||||
<arg name="id" type="string"/>
|
||||
</event>
|
||||
|
||||
<event name="restored">
|
||||
<description summary="the session has been restored">
|
||||
Emitted at most once some time after getting a new session object. It
|
||||
means that previous state was at least partially restored. The same id
|
||||
can again be used to restore previous sessions.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<event name="replaced">
|
||||
<description summary="the session has been restored">
|
||||
Emitted at most once, if the session was taken over by some other
|
||||
client. When this happens, the session and all its toplevel session
|
||||
objects become inert, and should be destroyed.
|
||||
</description>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_toplevel_session_v1" version="1">
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="Destroy the object">
|
||||
Destroy the object. This has no effect window management of the
|
||||
associated toplevel.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="remove" type="destructor">
|
||||
<description summary="remove a surface from the session">
|
||||
Remove a specified surface from the session and render any corresponding
|
||||
xx_toplevel_session_v1 object inert. The compositor should remove any
|
||||
data related to the toplevel in the corresponding session from its internal
|
||||
storage.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<event name="restored">
|
||||
<description summary="a toplevel's session has been restored">
|
||||
The "restored" event is emitted prior to the first
|
||||
xdg_toplevel.configure for the toplevel. It will only be emitted after
|
||||
xx_session_v1.restore_toplevel, and the initial empty surface state has
|
||||
been applied, and it indicates that the surface's session is being
|
||||
restored with this configure event.
|
||||
</description>
|
||||
<arg name="surface" type="object" interface="xdg_toplevel"/>
|
||||
</event>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
Text input protocol
|
||||
|
||||
Maintainers:
|
||||
Dorota Czaplejewicz <gilaac.dcz@porcupinefactory.org>
|
||||
|
||||
|
||||
|
|
@ -1,575 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
|
||||
<protocol name="xx_text_input_unstable_v3">
|
||||
<copyright>
|
||||
Copyright © 2012, 2013 Intel Corporation
|
||||
Copyright © 2015, 2016 Jan Arne Petersen
|
||||
Copyright © 2017, 2018 Red Hat, Inc.
|
||||
Copyright © 2018 Purism SPC
|
||||
|
||||
Permission to use, copy, modify, distribute, and sell this
|
||||
software and its documentation for any purpose is hereby granted
|
||||
without fee, provided that the above copyright notice appear in
|
||||
all copies and that both that copyright notice and this permission
|
||||
notice appear in supporting documentation, and that the name of
|
||||
the copyright holders not be used in advertising or publicity
|
||||
pertaining to distribution of the software without specific,
|
||||
written prior permission. The copyright holders make no
|
||||
representations about the suitability of this software for any
|
||||
purpose. It is provided "as is" without express or implied
|
||||
warranty.
|
||||
|
||||
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
|
||||
SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
||||
FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
||||
SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
|
||||
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
|
||||
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
|
||||
THIS SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<description summary="Protocol for composing text">
|
||||
This protocol allows compositors to act as input methods and to send text
|
||||
to applications. A text input object is used to manage state of what are
|
||||
typically text entry fields in the application.
|
||||
|
||||
This document adheres to the RFC 2119 when using words like "must",
|
||||
"should", "may", etc.
|
||||
|
||||
Warning! The protocol described in this file is experimental and
|
||||
backward incompatible changes may be made. Backward compatible changes
|
||||
may be added together with the corresponding interface version bump.
|
||||
Backward incompatible changes are done by bumping the version number in
|
||||
the protocol and interface names and resetting the interface version.
|
||||
Once the protocol is to be declared stable, the 'xx' prefix and the
|
||||
version number in the protocol and interface names are removed and the
|
||||
interface version number is reset.
|
||||
</description>
|
||||
|
||||
<interface name="xx_text_input_v3" version="2">
|
||||
<description summary="text input">
|
||||
The xx_text_input_v3 interface represents text input and input methods
|
||||
associated with a seat. It provides enter/leave events to follow the
|
||||
text input focus for a seat.
|
||||
|
||||
Requests are used to enable/disable the text-input object and set
|
||||
state information like surrounding and selected text or the content type.
|
||||
The information about the entered text is sent to the text-input object
|
||||
via the preedit_string and commit_string events.
|
||||
|
||||
Text is valid UTF-8 encoded, indices and lengths are in bytes. Indices
|
||||
must not point to middle bytes inside a code point: they must either
|
||||
point to the first byte of a code point or to the end of the buffer.
|
||||
Lengths must be measured between two valid indices.
|
||||
|
||||
Focus moving throughout surfaces will result in the emission of
|
||||
xx_text_input_v3.enter and xx_text_input_v3.leave events. The focused
|
||||
surface must commit xx_text_input_v3.enable and
|
||||
xx_text_input_v3.disable requests as the keyboard focus moves across
|
||||
editable and non-editable elements of the UI. Those two requests are not
|
||||
expected to be paired with each other, the compositor must be able to
|
||||
handle consecutive series of the same request.
|
||||
|
||||
State is sent by the state requests (set_surrounding_text,
|
||||
set_content_type and set_cursor_rectangle) and a commit request. After an
|
||||
enter event or disable request all state information is invalidated and
|
||||
needs to be resent by the client.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="Destroy the xx_text_input">
|
||||
Destroy the xx_text_input object. Also disables all surfaces enabled
|
||||
through this xx_text_input object.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="enable">
|
||||
<description summary="Request text input to be enabled">
|
||||
Requests text input on the surface previously obtained from the enter
|
||||
event.
|
||||
|
||||
This request must be issued every time the active text input changes
|
||||
to a new one, including within the current surface. Use
|
||||
xx_text_input_v3.disable when there is no longer any input focus on
|
||||
the current surface.
|
||||
|
||||
Clients must not enable more than one text input on the single seat
|
||||
and should disable the current text input before enabling the new one.
|
||||
At most one instance of text input may be in enabled state per instance,
|
||||
Requests to enable the another text input when some text input is active
|
||||
must be ignored by compositor.
|
||||
|
||||
This request resets all state associated with previous enable, disable,
|
||||
set_surrounding_text, set_text_change_cause, set_content_type, and
|
||||
set_cursor_rectangle requests, as well as the state associated with
|
||||
preedit_string, commit_string, delete_surrounding_text, and action
|
||||
events.
|
||||
|
||||
The set_surrounding_text, set_content_type and set_cursor_rectangle
|
||||
requests must follow if the text input supports the necessary
|
||||
functionality.
|
||||
|
||||
State set with this request is double-buffered. It will get applied on
|
||||
the next xx_text_input_v3.commit request, and stay valid until the
|
||||
next committed enable or disable request.
|
||||
|
||||
The changes must be applied by the compositor after issuing a
|
||||
xx_text_input_v3.commit request.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="disable">
|
||||
<description summary="Disable text input on a surface">
|
||||
Explicitly disable text input on the current surface (typically when
|
||||
there is no focus on any text entry inside the surface).
|
||||
|
||||
State set with this request is double-buffered. It will get applied on
|
||||
the next xx_text_input_v3.commit request.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="set_surrounding_text">
|
||||
<description summary="sets the surrounding text">
|
||||
Sets the surrounding plain text around the input, excluding the preedit
|
||||
text.
|
||||
|
||||
The client should notify the compositor of any changes in any of the
|
||||
values carried with this request, including changes caused by handling
|
||||
incoming text-input events as well as changes caused by other
|
||||
mechanisms like keyboard typing.
|
||||
|
||||
If the client is unaware of the text around the cursor, it should not
|
||||
issue this request, to signify lack of support to the compositor.
|
||||
|
||||
Text is UTF-8 encoded, and should include the cursor position, the
|
||||
complete selection and additional characters before and after them.
|
||||
There is a maximum length of wayland messages, so text can not be
|
||||
longer than 4000 bytes.
|
||||
|
||||
Cursor is the byte offset of the cursor within text buffer.
|
||||
|
||||
Anchor is the byte offset of the selection anchor within text buffer.
|
||||
If there is no selected text, anchor is the same as cursor.
|
||||
|
||||
If any preedit text is present, it is replaced with a cursor for the
|
||||
purpose of this event.
|
||||
|
||||
Values set with this request are double-buffered. They will get applied
|
||||
on the next xx_text_input_v3.commit request, and stay valid until the
|
||||
next committed enable or disable request.
|
||||
|
||||
The initial state for affected fields is empty, meaning that the text
|
||||
input does not support sending surrounding text. If the empty values
|
||||
get applied, subsequent attempts to change them may have no effect.
|
||||
</description>
|
||||
<arg name="text" type="string"/>
|
||||
<arg name="cursor" type="int"/>
|
||||
<arg name="anchor" type="int"/>
|
||||
</request>
|
||||
|
||||
<enum name="change_cause">
|
||||
<description summary="text change reason">
|
||||
Reason for the change of surrounding text or cursor posision.
|
||||
</description>
|
||||
<entry name="input_method" value="0" summary="input method caused the change"/>
|
||||
<entry name="other" value="1" summary="something else than the input method caused the change"/>
|
||||
</enum>
|
||||
|
||||
<request name="set_text_change_cause">
|
||||
<description summary="indicates the cause of surrounding text change">
|
||||
Tells the compositor why the text surrounding the cursor changed.
|
||||
|
||||
Whenever the client detects an external change in text, cursor, or
|
||||
anchor posision, it must issue this request to the compositor. This
|
||||
request is intended to give the input method a chance to update the
|
||||
preedit text in an appropriate way, e.g. by removing it when the user
|
||||
starts typing with a keyboard.
|
||||
|
||||
cause describes the source of the change.
|
||||
|
||||
The value set with this request is double-buffered. It must be applied
|
||||
and reset to initial at the next xx_text_input_v3.commit request.
|
||||
|
||||
The initial value of cause is input_method.
|
||||
</description>
|
||||
<arg name="cause" type="uint" enum="change_cause"/>
|
||||
</request>
|
||||
|
||||
<enum name="content_hint" bitfield="true">
|
||||
<description summary="content hint">
|
||||
Content hint is a bitmask to allow to modify the behavior of the text
|
||||
input.
|
||||
</description>
|
||||
<entry name="none" value="0x0" summary="no special behavior"/>
|
||||
<entry name="completion" value="0x1" summary="suggest word completions"/>
|
||||
<entry name="spellcheck" value="0x2" summary="suggest word corrections"/>
|
||||
<entry name="auto_capitalization" value="0x4" summary="switch to uppercase letters at the start of a sentence"/>
|
||||
<entry name="lowercase" value="0x8" summary="prefer lowercase letters"/>
|
||||
<entry name="uppercase" value="0x10" summary="prefer uppercase letters"/>
|
||||
<entry name="titlecase" value="0x20" summary="prefer casing for titles and headings (can be language dependent)"/>
|
||||
<entry name="hidden_text" value="0x40" summary="characters should be hidden"/>
|
||||
<entry name="sensitive_data" value="0x80" summary="typed text should not be stored"/>
|
||||
<entry name="latin" value="0x100" summary="just Latin characters should be entered"/>
|
||||
<entry name="multiline" value="0x200" summary="the text input is multiline"/>
|
||||
</enum>
|
||||
|
||||
<enum name="content_purpose">
|
||||
<description summary="content purpose">
|
||||
The content purpose allows to specify the primary purpose of a text
|
||||
input.
|
||||
|
||||
This allows an input method to show special purpose input panels with
|
||||
extra characters or to disallow some characters.
|
||||
</description>
|
||||
<entry name="normal" value="0" summary="default input, allowing all characters"/>
|
||||
<entry name="alpha" value="1" summary="allow only alphabetic characters"/>
|
||||
<entry name="digits" value="2" summary="allow only digits"/>
|
||||
<entry name="number" value="3" summary="input a number (including decimal separator and sign)"/>
|
||||
<entry name="phone" value="4" summary="input a phone number"/>
|
||||
<entry name="url" value="5" summary="input an URL"/>
|
||||
<entry name="email" value="6" summary="input an email address"/>
|
||||
<entry name="name" value="7" summary="input a name of a person"/>
|
||||
<entry name="password" value="8" summary="input a password (combine with sensitive_data hint)"/>
|
||||
<entry name="pin" value="9" summary="input is a numeric password (combine with sensitive_data hint)"/>
|
||||
<entry name="date" value="10" summary="input a date"/>
|
||||
<entry name="time" value="11" summary="input a time"/>
|
||||
<entry name="datetime" value="12" summary="input a date and time"/>
|
||||
<entry name="terminal" value="13" summary="input for a terminal"/>
|
||||
</enum>
|
||||
|
||||
<request name="set_content_type">
|
||||
<description summary="set content purpose and hint">
|
||||
Sets the content purpose and content hint. While the purpose is the
|
||||
basic purpose of an input field, the hint flags allow to modify some of
|
||||
the behavior.
|
||||
|
||||
Values set with this request are double-buffered. They will get applied
|
||||
on the next xx_text_input_v3.commit request.
|
||||
Subsequent attempts to update them may have no effect. The values
|
||||
remain valid until the next committed enable or disable request.
|
||||
|
||||
The initial value for hint is none, and the initial value for purpose
|
||||
is normal.
|
||||
</description>
|
||||
<arg name="hint" type="uint" enum="content_hint"/>
|
||||
<arg name="purpose" type="uint" enum="content_purpose"/>
|
||||
</request>
|
||||
|
||||
<request name="set_cursor_rectangle">
|
||||
<description summary="set cursor position">
|
||||
Marks an area around the cursor as a x, y, width, height rectangle in
|
||||
surface local coordinates.
|
||||
|
||||
Allows the compositor to put a window with word suggestions near the
|
||||
cursor, without obstructing the text being input.
|
||||
|
||||
If the client is unaware of the position of edited text, it should not
|
||||
issue this request, to signify lack of support to the compositor.
|
||||
|
||||
Values set with this request are double-buffered. They will get applied
|
||||
on the next xx_text_input_v3.commit request, and stay valid until the
|
||||
next committed enable or disable request.
|
||||
|
||||
The initial values describing a cursor rectangle are empty. That means
|
||||
the text input does not support describing the cursor area. If the
|
||||
empty values get applied, subsequent attempts to change them may have
|
||||
no effect.
|
||||
</description>
|
||||
<arg name="x" type="int"/>
|
||||
<arg name="y" type="int"/>
|
||||
<arg name="width" type="int"/>
|
||||
<arg name="height" type="int"/>
|
||||
</request>
|
||||
|
||||
<request name="commit">
|
||||
<description summary="commit state">
|
||||
Atomically applies state changes recently sent to the compositor.
|
||||
|
||||
The commit request establishes and updates the state of the client, and
|
||||
must be issued after any changes to apply them.
|
||||
|
||||
Text input state (enabled status, content purpose, content hint,
|
||||
surrounding text and change cause, cursor rectangle) is conceptually
|
||||
double-buffered within the context of a text input, i.e. between a
|
||||
committed enable request and the following committed enable or disable
|
||||
request.
|
||||
|
||||
Protocol requests modify the pending state, as opposed to the current
|
||||
state in use by the input method. A commit request atomically applies
|
||||
all pending state, replacing the current state. After commit, the new
|
||||
pending state is as documented for each related request.
|
||||
|
||||
Requests are applied in the order of arrival.
|
||||
|
||||
Neither current nor pending state are modified unless noted otherwise.
|
||||
|
||||
The compositor must count the number of commit requests coming from
|
||||
each xx_text_input_v3 object and use the count as the serial in done
|
||||
events.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<event name="enter">
|
||||
<description summary="enter event">
|
||||
Notification that this seat's text-input focus is on a certain surface.
|
||||
|
||||
If client has created multiple text input objects, compositor must send
|
||||
this event to all of them.
|
||||
|
||||
When the seat has the keyboard capability the text-input focus follows
|
||||
the keyboard focus. This event sets the current surface for the
|
||||
text-input object.
|
||||
</description>
|
||||
<arg name="surface" type="object" interface="wl_surface"/>
|
||||
</event>
|
||||
|
||||
<event name="leave">
|
||||
<description summary="leave event">
|
||||
Notification that this seat's text-input focus is no longer on a
|
||||
certain surface. The client should reset any preedit string previously
|
||||
set.
|
||||
|
||||
The leave notification clears the current surface. It is sent before
|
||||
the enter notification for the new focus. After leave event, compositor
|
||||
must ignore requests from any text input instances until next enter
|
||||
event.
|
||||
|
||||
When the seat has the keyboard capability the text-input focus follows
|
||||
the keyboard focus.
|
||||
</description>
|
||||
<arg name="surface" type="object" interface="wl_surface"/>
|
||||
</event>
|
||||
|
||||
<event name="preedit_string">
|
||||
<description summary="pre-edit">
|
||||
Notify when a new composing text (pre-edit) should be set at the
|
||||
current cursor position. Any previously set composing text must be
|
||||
removed. Any previously existing selected text must be removed.
|
||||
|
||||
The argument text contains the pre-edit string buffer.
|
||||
|
||||
The parameters cursor_begin and cursor_end are counted in bytes
|
||||
relative to the beginning of the submitted text buffer. Cursor should
|
||||
be hidden when both are equal to -1.
|
||||
|
||||
They could be represented by the client as a line if both values are
|
||||
the same, or as a text highlight otherwise.
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next xx_text_input_v3.done event.
|
||||
|
||||
The initial value of text is an empty string, and cursor_begin,
|
||||
cursor_end and cursor_hidden are all 0.
|
||||
</description>
|
||||
<arg name="text" type="string" allow-null="true"/>
|
||||
<arg name="cursor_begin" type="int"/>
|
||||
<arg name="cursor_end" type="int"/>
|
||||
</event>
|
||||
|
||||
<event name="commit_string">
|
||||
<description summary="text commit">
|
||||
Notify when text should be inserted into the editor widget. The text to
|
||||
commit could be either just a single character after a key press or the
|
||||
result of some composing (pre-edit).
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next xx_text_input_v3.done event.
|
||||
|
||||
The initial value of text is an empty string.
|
||||
</description>
|
||||
<arg name="text" type="string" allow-null="true"/>
|
||||
</event>
|
||||
|
||||
<event name="delete_surrounding_text">
|
||||
<description summary="delete surrounding text">
|
||||
Notify when the text around the current cursor position should be
|
||||
deleted.
|
||||
|
||||
Before_length and after_length are the number of bytes before and after
|
||||
the current cursor index (excluding the selection) to delete.
|
||||
|
||||
If a preedit text is present, in effect before_length is counted from
|
||||
the beginning of it, and after_length from its end (see done event
|
||||
sequence).
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next xx_text_input_v3.done event.
|
||||
|
||||
The initial values of both before_length and after_length are 0.
|
||||
</description>
|
||||
<arg name="before_length" type="uint" summary="length of text before current cursor position"/>
|
||||
<arg name="after_length" type="uint" summary="length of text after current cursor position"/>
|
||||
</event>
|
||||
|
||||
<event name="move_cursor" since="2">
|
||||
<description summary="move cursor and change selection">
|
||||
Unselects text, moves the cursor and selects text.
|
||||
|
||||
This is equivalent to dragging the mouse over some text: it deselects whatever might be currently selected and selects a new range of text.
|
||||
|
||||
The offsets used in arguments are in bytes relative to the current cursor position. Cursor is the new position of the cursor, and anchor is the opposite end of selection. If there's no selection, anchor should be equal to cursor.
|
||||
In terms of dragging the mouse, the anchor is the start, and cursor the end.
|
||||
|
||||
The offsets do not take preedit contents into account, nor is preedit changed in any way with this request.
|
||||
|
||||
Both cursor and anchor must fall on code point boundaries, otherwise text input client may ignore the request. It is therefore not recommended for an input method to move any of them beyond the text received in surrounding_text.
|
||||
<!-- Code point boundary checking must happen in the application because no one else is obliged to track the contents.
|
||||
There are two ways to handle it:
|
||||
|
||||
1. add a request from the application informing the compositor of the mistake, so that the compositor can send an error and crash the input method, giving it the chance to reset and go back to normal
|
||||
2. just ignore the request and hope the input method can resynchronize through surrounding_text
|
||||
|
||||
Choosing 2. because it's easier to implement.
|
||||
-->
|
||||
|
||||
When surrounding_text is not supported, the offsets must not be interpreted as bytes, but as some human-readable unit at least as big as a code point, for example a grapheme.
|
||||
|
||||
The cursor and anchor arguments can also take the following special values:
|
||||
BEGINNING := 0x8000_0000 = i32::MIN
|
||||
END := 0x7fff_ffff = i32::MAX
|
||||
meaning, respectively, the beginning and the end of of all text in the input field.
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next commit request.
|
||||
|
||||
The initial values of both cursor and anchor are 0.
|
||||
</description>
|
||||
<arg name="cursor" type="int"/>
|
||||
<arg name="anchor" type="int"/>
|
||||
</event>
|
||||
|
||||
<event name="done">
|
||||
<description summary="apply changes">
|
||||
Instruct the application to apply changes to state requested by the
|
||||
preedit_string, commit_string delete_surrounding_text, and action
|
||||
events.
|
||||
The state relating to these events is double-buffered, and each one
|
||||
modifies the pending state. This event replaces the current state with
|
||||
the pending state.
|
||||
|
||||
The application must proceed by evaluating the changes in the following
|
||||
order:
|
||||
|
||||
1. Replace existing preedit string with the cursor.
|
||||
2. Delete requested surrounding text.
|
||||
3. Insert commit string with the cursor at its end.
|
||||
4. Move the cursor and selection.
|
||||
5. Calculate surrounding text to send.
|
||||
6. Insert new preedit text in cursor position.
|
||||
7. Place cursor inside preedit text.
|
||||
8. Perform the requested action.
|
||||
|
||||
The serial number reflects the last state of the xx_text_input_v3
|
||||
object known to the compositor. The value of the serial argument must
|
||||
be equal to the number of commit requests already issued on that object.
|
||||
|
||||
When the client receives a done event with a serial different than the
|
||||
number of past commit requests, it must proceed with evaluating and
|
||||
applying the changes as normal, except it should not change the current
|
||||
state of the xx_text_input_v3 object. All pending state requests
|
||||
(set_surrounding_text, set_content_type and set_cursor_rectangle) on
|
||||
the xx_text_input_v3 object should be sent and committed after
|
||||
receiving a xx_text_input_v3.done event with a matching serial.
|
||||
</description>
|
||||
<arg name="serial" type="uint"/>
|
||||
</event>
|
||||
|
||||
<enum name="action" since="2">
|
||||
<description summary="action">
|
||||
A possible action to perform on a text input.
|
||||
</description>
|
||||
<!-- Notably missing: moving cursor, deleting and setting a selection. They are nicer to use as part of the text manipulation interface: ranges can be selected there.
|
||||
Exceptions: the IME doesn't know where lines start or end. The IME will not get to see the entire 4MB document so it can't select all through the text interface. But this doesn't seem urgent. -->
|
||||
|
||||
<!-- types of finish actions are better communicated as a hint: this triggers a URL navigation, this sends a search query, this sends a message, etc. The input method can then choose the appropriate buttons to display -->
|
||||
<entry name="finish" value="0">
|
||||
<description summary="trigger appropriate action for the completion of editing">
|
||||
This should be triggered when the user is done with editing the field and wants to move on. For example, the query was typed and the user wants the search result. Or the name was entered and the address needs to be typed next.
|
||||
|
||||
The action to perform depends on the application, and should match the value of the current content_purpose.
|
||||
|
||||
All clients SHOULD implement this action. Without it, on-screen keyboards don't work as expected.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<event name="perform_action" since="2">
|
||||
<description summary="action performed">
|
||||
The input method issued an action to perform on this text input.
|
||||
|
||||
Values set with this event are double-buffered. They must be applied
|
||||
and reset to initial on the next .done event.
|
||||
|
||||
The initial value of action is none.
|
||||
</description>
|
||||
<arg name="action" type="uint" enum="action" summary="action performed"/>
|
||||
</event>
|
||||
|
||||
<request name="set_available_actions" since="2">
|
||||
<description summary="announce the available actions">
|
||||
Announces the actions available for the currently active text input.
|
||||
|
||||
Values set with this event are double-buffered. They will get applied
|
||||
on the next .done event.
|
||||
They get reset to the initial value on the next committed deactivate event.
|
||||
|
||||
The initial value is an empty set: no actions are available.
|
||||
|
||||
Values in the available_actions array come from text-input-v3.action.
|
||||
</description>
|
||||
<!-- Removed the protocol error on none and duplicates because a client has no interest in crashing for slight compositor misbehaviour. Ignoring extraneous values should not be a problem for any half-competent library. -->
|
||||
<arg name="available_actions" type="array" summary="available actions"/>
|
||||
<!-- Should this be a bitmap instead of an array? 32 generic actions should be enough, and client-specific actions would need a new protocol anyway -->
|
||||
</request>
|
||||
|
||||
<enum name="supported_features" bitfield="true" since="2">
|
||||
<description summary="possible supported features">
|
||||
Client functionality over the baseline that isn't indicated implicitly.
|
||||
|
||||
This does not include events coming with .enable: when the input method receives such an event, it is clear the text input supports it, e.g. content_type, available_actions.
|
||||
|
||||
Baseline functionality like commit_string, set_preedit_string must always be supported for the protocol to be useful.
|
||||
|
||||
The flags match text-input protocol versions, but should be kept general enough to support other protocols.
|
||||
</description>
|
||||
<entry name="none" value="0x0" summary="no extra functionality supported"/>
|
||||
<entry name="move_cursor" value="0x1" summary="the move_cursor request"/>
|
||||
</enum>
|
||||
|
||||
<request name="announce_supported_features" since="2">
|
||||
<description summary="announce extra supported features">
|
||||
Notifies the input method what the currently active text input client is able to do.
|
||||
|
||||
This event should come within the same .done sequence as .activate. Otherwise, the input method may ignore it.
|
||||
|
||||
Values set with this event are double-buffered. They will get applied
|
||||
on the next .done event.
|
||||
They get reset to initial on the next committed deactivate event.
|
||||
|
||||
The initial value for features is none.
|
||||
</description>
|
||||
<arg name="features" type="uint" enum="xx_text_input_v3.supported_features"/>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="xx_text_input_manager_v3" version="2">
|
||||
<description summary="text input manager">
|
||||
A factory for text-input objects. This object is a global singleton.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="Destroy the xx_text_input_manager">
|
||||
Destroy the xx_text_input_manager object.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="get_text_input">
|
||||
<description summary="create a new text input object">
|
||||
Creates a new text-input object for a given seat.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="xx_text_input_v3"/>
|
||||
<arg name="seat" type="object" interface="wl_seat"/>
|
||||
</request>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
header_install_dir = get_option('includedir') / 'wayland-protocols'
|
||||
foreach protocol_file : protocol_files
|
||||
header_name = fs.name(protocol_file).replace('.xml', '-enum.h')
|
||||
headers += custom_target(
|
||||
custom_target(
|
||||
header_name,
|
||||
output: header_name,
|
||||
input: '../..' / protocol_file,
|
||||
|
|
|
|||
45
meson.build
45
meson.build
|
|
@ -1,5 +1,5 @@
|
|||
project('wayland-protocols',
|
||||
version: '1.47',
|
||||
version: '1.43',
|
||||
meson_version: '>= 0.58.0',
|
||||
license: 'MIT/Expat',
|
||||
)
|
||||
|
|
@ -47,12 +47,10 @@ unstable_protocols = {
|
|||
staging_protocols = {
|
||||
'alpha-modifier': ['v1'],
|
||||
'color-management': ['v1'],
|
||||
'color-representation': ['v1'],
|
||||
'commit-timing': ['v1'],
|
||||
'content-type': ['v1'],
|
||||
'cursor-shape': ['v1'],
|
||||
'drm-lease': ['v1'],
|
||||
'ext-background-effect': ['v1'],
|
||||
'ext-data-control': ['v1'],
|
||||
'ext-foreign-toplevel-list': ['v1'],
|
||||
'ext-idle-notify': ['v1'],
|
||||
|
|
@ -64,7 +62,6 @@ staging_protocols = {
|
|||
'fifo': ['v1'],
|
||||
'fractional-scale': ['v1'],
|
||||
'linux-drm-syncobj': ['v1'],
|
||||
'pointer-warp': ['v1'],
|
||||
'security-context': ['v1'],
|
||||
'single-pixel-buffer': ['v1'],
|
||||
'tearing-control': ['v1'],
|
||||
|
|
@ -77,60 +74,33 @@ staging_protocols = {
|
|||
'xwayland-shell': ['v1'],
|
||||
}
|
||||
|
||||
experimental_protocols = {
|
||||
'xx-input-method': ['v2'],
|
||||
'xx-keyboard-filter': ['v1'],
|
||||
'xx-session-management': ['v1'],
|
||||
'xx-text-input': ['v3'],
|
||||
}
|
||||
|
||||
protocol_files = []
|
||||
installed_protocol_files = []
|
||||
|
||||
stable_protocol_files = []
|
||||
foreach name, versions : stable_protocols
|
||||
foreach version : versions
|
||||
if version == ''
|
||||
stable_protocol_files += ['stable/@0@/@0@.xml'.format(name)]
|
||||
protocol_files += ['stable/@0@/@0@.xml'.format(name)]
|
||||
else
|
||||
stable_protocol_files += ['stable/@0@/@0@-@1@.xml'.format(name, version)]
|
||||
protocol_files += ['stable/@0@/@0@-@1@.xml'.format(name, version)]
|
||||
endif
|
||||
endforeach
|
||||
endforeach
|
||||
installed_protocol_files += stable_protocol_files
|
||||
protocol_files += stable_protocol_files
|
||||
|
||||
staging_protocol_files = []
|
||||
foreach name, versions : staging_protocols
|
||||
foreach version : versions
|
||||
staging_protocol_files += [
|
||||
protocol_files += [
|
||||
'staging/@0@/@0@-@1@.xml'.format(name, version)
|
||||
]
|
||||
endforeach
|
||||
endforeach
|
||||
installed_protocol_files += staging_protocol_files
|
||||
protocol_files += staging_protocol_files
|
||||
|
||||
unstable_protocol_files = []
|
||||
foreach name, versions : unstable_protocols
|
||||
foreach version : versions
|
||||
unstable_protocol_files += [
|
||||
protocol_files += [
|
||||
'unstable/@0@/@0@-unstable-@1@.xml'.format(name, version)
|
||||
]
|
||||
endforeach
|
||||
endforeach
|
||||
installed_protocol_files += unstable_protocol_files
|
||||
protocol_files += unstable_protocol_files
|
||||
|
||||
experimental_protocol_files = []
|
||||
foreach name, versions : experimental_protocols
|
||||
foreach version : versions
|
||||
experimental_protocol_files += [
|
||||
'experimental/@0@/@0@-@1@.xml'.format(name, version)
|
||||
]
|
||||
endforeach
|
||||
endforeach
|
||||
protocol_files += experimental_protocol_files
|
||||
|
||||
# Check that each protocol has a README
|
||||
foreach protocol_file : protocol_files
|
||||
|
|
@ -140,7 +110,7 @@ foreach protocol_file : protocol_files
|
|||
endif
|
||||
endforeach
|
||||
|
||||
foreach protocol_file : installed_protocol_files
|
||||
foreach protocol_file : protocol_files
|
||||
protocol_install_dir = fs.parent(join_paths(
|
||||
get_option('datadir'),
|
||||
'wayland-protocols',
|
||||
|
|
@ -153,7 +123,6 @@ foreach protocol_file : installed_protocol_files
|
|||
endforeach
|
||||
|
||||
include_dirs = []
|
||||
headers = []
|
||||
if dep_scanner.version().version_compare('>=1.22.90')
|
||||
subdir('include/wayland-protocols')
|
||||
include_dirs = ['include']
|
||||
|
|
@ -163,7 +132,6 @@ wayland_protocols_srcdir = meson.current_source_dir()
|
|||
|
||||
pkgconfig_configuration = configuration_data()
|
||||
pkgconfig_configuration.set('prefix', get_option('prefix'))
|
||||
pkgconfig_configuration.set('includedir', '${prefix}/@0@'.format(get_option('includedir')))
|
||||
pkgconfig_configuration.set('datarootdir', '${prefix}/@0@'.format(get_option('datadir')))
|
||||
pkgconfig_configuration.set('abs_top_srcdir', wayland_protocols_srcdir)
|
||||
pkgconfig_configuration.set('PACKAGE', 'wayland-protocols')
|
||||
|
|
@ -188,7 +156,6 @@ wayland_protocols = declare_dependency(
|
|||
variables: {
|
||||
'pkgdatadir': wayland_protocols_srcdir,
|
||||
},
|
||||
sources: headers,
|
||||
)
|
||||
|
||||
meson.override_dependency('wayland-protocols', wayland_protocols)
|
||||
|
|
|
|||
|
|
@ -35,19 +35,19 @@
|
|||
More than one tablet may exist, and device-specifics matter. Tablets are
|
||||
not represented by a single virtual device like wl_pointer. A client
|
||||
binds to the tablet manager object which is just a proxy object. From
|
||||
that, the client requests zwp_tablet_manager_v2.get_tablet_seat(wl_seat)
|
||||
that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat)
|
||||
and that returns the actual interface that has all the tablets. With
|
||||
this indirection, we can avoid merging zwp_tablet_v2 into the actual Wayland
|
||||
this indirection, we can avoid merging wp_tablet into the actual Wayland
|
||||
protocol, a long-term benefit.
|
||||
|
||||
The zwp_tablet_seat_v2 sends a "tablet added" event for each tablet
|
||||
The wp_tablet_seat sends a "tablet added" event for each tablet
|
||||
connected. That event is followed by descriptive events about the
|
||||
hardware; currently that includes events for name, vid/pid and
|
||||
a zwp_tablet_v2.path event that describes a local path. This path can be
|
||||
a wp_tablet.path event that describes a local path. This path can be
|
||||
used to uniquely identify a tablet or get more information through
|
||||
libwacom. Emulated or nested tablets can skip any of those, e.g. a
|
||||
virtual tablet may not have a vid/pid. The sequence of descriptive
|
||||
events is terminated by a zwp_tablet_v2.done event to signal that a client
|
||||
events is terminated by a wp_tablet.done event to signal that a client
|
||||
may now finalize any initialization for that tablet.
|
||||
|
||||
Events from tablets require a tool in proximity. Tools are also managed
|
||||
|
|
@ -55,15 +55,15 @@
|
|||
to the compositor. That event is followed by a number of descriptive
|
||||
events about the hardware; currently that includes capabilities,
|
||||
hardware id and serial number, and tool type. Similar to the tablet
|
||||
interface, a zwp_tablet_tool_v2.done event is sent to terminate that initial
|
||||
interface, a wp_tablet_tool.done event is sent to terminate that initial
|
||||
sequence.
|
||||
|
||||
Any event from a tool happens on the zwp_tablet_tool_v2 interface. When the
|
||||
Any event from a tool happens on the wp_tablet_tool interface. When the
|
||||
tool gets into proximity of the tablet, a proximity_in event is sent on
|
||||
the zwp_tablet_tool_v2 interface, listing the tablet and the surface. That
|
||||
the wp_tablet_tool interface, listing the tablet and the surface. That
|
||||
event is followed by a motion event with the coordinates. After that,
|
||||
it's the usual motion, axis, button, etc. events. The protocol's
|
||||
serialisation means events are grouped by zwp_tablet_tool_v2.frame events.
|
||||
serialisation means events are grouped by wp_tablet_tool.frame events.
|
||||
|
||||
Two special events (that don't exist in X) are down and up. They signal
|
||||
"tip touching the surface". For tablets without real proximity
|
||||
|
|
@ -95,7 +95,7 @@
|
|||
|
||||
Since tablets work independently of the pointer controlled by the mouse,
|
||||
the focus handling is independent too and controlled by proximity.
|
||||
The zwp_tablet_tool_v2.set_cursor request sets a tool-specific cursor.
|
||||
The wp_tablet_tool.set_cursor request sets a tool-specific cursor.
|
||||
This cursor surface may be the same as the mouse cursor, and it may be
|
||||
the same across tools but it is possible to be more fine-grained. For
|
||||
example, a client may set different cursors for the pen and eraser.
|
||||
|
|
@ -110,12 +110,12 @@
|
|||
<description summary="controller object for graphic tablet devices">
|
||||
An object that provides access to the graphics tablets available on this
|
||||
system. All tablets are associated with a seat, to get access to the
|
||||
actual tablets, use zwp_tablet_manager_v2.get_tablet_seat.
|
||||
actual tablets, use wp_tablet_manager.get_tablet_seat.
|
||||
</description>
|
||||
|
||||
<request name="get_tablet_seat">
|
||||
<description summary="get the tablet seat">
|
||||
Get the zwp_tablet_seat_v2 object for the given seat. This object
|
||||
Get the wp_tablet_seat object for the given seat. This object
|
||||
provides access to all graphics tablets in this seat.
|
||||
</description>
|
||||
<arg name="tablet_seat" type="new_id" interface="zwp_tablet_seat_v2"/>
|
||||
|
|
@ -124,7 +124,7 @@
|
|||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="release the memory for the tablet manager object">
|
||||
Destroy the zwp_tablet_manager_v2 object. Objects created from this
|
||||
Destroy the wp_tablet_manager object. Objects created from this
|
||||
object are unaffected and should be destroyed separately.
|
||||
</description>
|
||||
</request>
|
||||
|
|
@ -134,12 +134,12 @@
|
|||
<description summary="controller object for graphic tablet devices of a seat">
|
||||
An object that provides access to the graphics tablets available on this
|
||||
seat. After binding to this interface, the compositor sends a set of
|
||||
zwp_tablet_seat_v2.tablet_added and zwp_tablet_seat_v2.tool_added events.
|
||||
wp_tablet_seat.tablet_added and wp_tablet_seat.tool_added events.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="release the memory for the tablet seat object">
|
||||
Destroy the zwp_tablet_seat_v2 object. Objects created from this
|
||||
Destroy the wp_tablet_seat object. Objects created from this
|
||||
object are unaffected and should be destroyed separately.
|
||||
</description>
|
||||
</request>
|
||||
|
|
@ -149,7 +149,7 @@
|
|||
This event is sent whenever a new tablet becomes available on this
|
||||
seat. This event only provides the object id of the tablet, any
|
||||
static information about the tablet (device name, vid/pid, etc.) is
|
||||
sent through the zwp_tablet_v2 interface.
|
||||
sent through the wp_tablet interface.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="zwp_tablet_v2" summary="the newly added graphics tablet"/>
|
||||
</event>
|
||||
|
|
@ -159,7 +159,7 @@
|
|||
This event is sent whenever a tool that has not previously been used
|
||||
with a tablet comes into use. This event only provides the object id
|
||||
of the tool; any static information about the tool (capabilities,
|
||||
type, etc.) is sent through the zwp_tablet_tool_v2 interface.
|
||||
type, etc.) is sent through the wp_tablet_tool interface.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="zwp_tablet_tool_v2" summary="the newly added tablet tool"/>
|
||||
</event>
|
||||
|
|
@ -168,13 +168,13 @@
|
|||
<description summary="new pad notification">
|
||||
This event is sent whenever a new pad is known to the system. Typically,
|
||||
pads are physically attached to tablets and a pad_added event is
|
||||
sent immediately after the zwp_tablet_seat_v2.tablet_added.
|
||||
sent immediately after the wp_tablet_seat.tablet_added.
|
||||
However, some standalone pad devices logically attach to tablets at
|
||||
runtime, and the client must wait for zwp_tablet_pad_v2.enter to know
|
||||
runtime, and the client must wait for wp_tablet_pad.enter to know
|
||||
the tablet a pad is attached to.
|
||||
|
||||
This event only provides the object id of the pad. All further
|
||||
features (buttons, strips, rings) are sent through the zwp_tablet_pad_v2
|
||||
features (buttons, strips, rings) are sent through the wp_tablet_pad
|
||||
interface.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="zwp_tablet_pad_v2" summary="the newly added pad"/>
|
||||
|
|
@ -184,24 +184,24 @@
|
|||
<interface name="zwp_tablet_tool_v2" version="2">
|
||||
<description summary="a physical tablet tool">
|
||||
An object that represents a physical tool that has been, or is
|
||||
currently in use with a tablet in this seat. Each zwp_tablet_tool_v2
|
||||
currently in use with a tablet in this seat. Each wp_tablet_tool
|
||||
object stays valid until the client destroys it; the compositor
|
||||
reuses the zwp_tablet_tool_v2 object to indicate that the object's
|
||||
reuses the wp_tablet_tool object to indicate that the object's
|
||||
respective physical tool has come into proximity of a tablet again.
|
||||
|
||||
A zwp_tablet_tool_v2 object's relation to a physical tool depends on the
|
||||
A wp_tablet_tool object's relation to a physical tool depends on the
|
||||
tablet's ability to report serial numbers. If the tablet supports
|
||||
this capability, then the object represents a specific physical tool
|
||||
and can be identified even when used on multiple tablets.
|
||||
|
||||
A tablet tool has a number of static characteristics, e.g. tool type,
|
||||
hardware_serial and capabilities. These capabilities are sent in an
|
||||
event sequence after the zwp_tablet_seat_v2.tool_added event before any
|
||||
event sequence after the wp_tablet_seat.tool_added event before any
|
||||
actual events from this tool. This initial event sequence is
|
||||
terminated by a zwp_tablet_tool_v2.done event.
|
||||
terminated by a wp_tablet_tool.done event.
|
||||
|
||||
Tablet tool events are grouped by zwp_tablet_tool_v2.frame events.
|
||||
Any events received before a zwp_tablet_tool_v2.frame event should be
|
||||
Tablet tool events are grouped by wp_tablet_tool.frame events.
|
||||
Any events received before a wp_tablet_tool.frame event should be
|
||||
considered part of the same hardware state change.
|
||||
</description>
|
||||
|
||||
|
|
@ -232,9 +232,9 @@
|
|||
and pending input regions become undefined, and the wl_surface is
|
||||
unmapped.
|
||||
|
||||
This request gives the surface the role of a zwp_tablet_tool_v2 cursor. A
|
||||
This request gives the surface the role of a wp_tablet_tool cursor. A
|
||||
surface may only ever be used as the cursor surface for one
|
||||
zwp_tablet_tool_v2. If the surface already has another role or has
|
||||
wp_tablet_tool. If the surface already has another role or has
|
||||
previously been used as cursor surface for a different tool, a
|
||||
protocol error is raised.
|
||||
</description>
|
||||
|
|
@ -278,7 +278,7 @@
|
|||
the interaction expected from this tool.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_tool_v2.done event.
|
||||
wp_tablet_tool.done event.
|
||||
</description>
|
||||
<arg name="tool_type" type="uint" enum="type" summary="the physical tool type"/>
|
||||
</event>
|
||||
|
|
@ -295,11 +295,11 @@
|
|||
Otherwise, if the tool has no serial number and this event is
|
||||
missing, the tool is tied to the tablet it first comes into
|
||||
proximity with. Even if the physical tool is used on multiple
|
||||
tablets, separate zwp_tablet_tool_v2 objects will be created, one per
|
||||
tablets, separate wp_tablet_tool objects will be created, one per
|
||||
tablet.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_tool_v2.done event.
|
||||
wp_tablet_tool.done event.
|
||||
</description>
|
||||
<arg name="hardware_serial_hi" type="uint" summary="the unique serial number of the tool, most significant bits"/>
|
||||
<arg name="hardware_serial_lo" type="uint" summary="the unique serial number of the tool, least significant bits"/>
|
||||
|
|
@ -316,7 +316,7 @@
|
|||
Pen (a stylus) is 0x802.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_tool_v2.done event.
|
||||
wp_tablet_tool.done event.
|
||||
</description>
|
||||
<arg name="hardware_id_hi" type="uint" summary="the hardware id, most significant bits"/>
|
||||
<arg name="hardware_id_lo" type="uint" summary="the hardware id, least significant bits"/>
|
||||
|
|
@ -345,7 +345,7 @@
|
|||
One event is sent for each extra capability available on this tool.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_tool_v2.done event.
|
||||
wp_tablet_tool.done event.
|
||||
</description>
|
||||
<arg name="capability" type="uint" enum="capability" summary="the capability"/>
|
||||
</event>
|
||||
|
|
@ -362,17 +362,17 @@
|
|||
<description summary="tool removed">
|
||||
This event is sent when the tool is removed from the system and will
|
||||
send no further events. Should the physical tool come back into
|
||||
proximity later, a new zwp_tablet_tool_v2 object will be created.
|
||||
proximity later, a new wp_tablet_tool object will be created.
|
||||
|
||||
It is compositor-dependent when a tool is removed. A compositor may
|
||||
remove a tool on proximity out, tablet removal or any other reason.
|
||||
A compositor may also keep a tool alive until shutdown.
|
||||
|
||||
If the tool is currently in proximity, a proximity_out event will be
|
||||
sent before the removed event. See zwp_tablet_tool_v2.proximity_out for
|
||||
sent before the removed event. See wp_tablet_tool.proximity_out for
|
||||
the handling of any buttons logically down.
|
||||
|
||||
When this event is received, the client must zwp_tablet_tool_v2.destroy
|
||||
When this event is received, the client must wp_tablet_tool.destroy
|
||||
the object.
|
||||
</description>
|
||||
</event>
|
||||
|
|
@ -402,7 +402,7 @@
|
|||
When the tablet tool leaves proximity of the tablet, button release
|
||||
events are sent for each button that was held down at the time of
|
||||
leaving proximity. These events are sent before the proximity_out
|
||||
event but within the same zwp_tablet_v2.frame.
|
||||
event but within the same wp_tablet.frame.
|
||||
|
||||
If the tool stays within proximity of the tablet, but the focus
|
||||
changes from one surface to another, a button release event may not
|
||||
|
|
@ -418,8 +418,8 @@
|
|||
|
||||
If the tool is already in contact with the tablet when entering the
|
||||
input region, the client owning said region will receive a
|
||||
zwp_tablet_v2.proximity_in event, followed by a zwp_tablet_v2.down
|
||||
event and a zwp_tablet_v2.frame event.
|
||||
wp_tablet.proximity_in event, followed by a wp_tablet.down
|
||||
event and a wp_tablet.frame event.
|
||||
|
||||
Note that this event describes logical contact, not physical
|
||||
contact. On some devices, a compositor may not consider a tool in
|
||||
|
|
@ -438,8 +438,8 @@
|
|||
If the tablet tool moves out of the input region while in contact
|
||||
with the surface of the tablet and the compositor does not have an
|
||||
ongoing grab on the surface, the client owning said region will
|
||||
receive a zwp_tablet_v2.up event, followed by a zwp_tablet_v2.proximity_out
|
||||
event and a zwp_tablet_v2.frame event. If the compositor has an ongoing
|
||||
receive a wp_tablet.up event, followed by a wp_tablet.proximity_out
|
||||
event and a wp_tablet.frame event. If the compositor has an ongoing
|
||||
grab on this device, this event sequence is sent whenever the grab
|
||||
is dismissed in the future.
|
||||
|
||||
|
|
@ -523,7 +523,7 @@
|
|||
Clients should choose either value and avoid mixing degrees and
|
||||
clicks. The compositor may accumulate values smaller than a logical
|
||||
click and emulate click events when a certain threshold is met.
|
||||
Thus, zwp_tablet_tool_v2.wheel events with non-zero clicks values may
|
||||
Thus, wl_tablet_tool.wheel events with non-zero clicks values may
|
||||
have different degrees values.
|
||||
</description>
|
||||
<arg name="degrees" type="fixed" summary="The wheel delta in degrees"/>
|
||||
|
|
@ -544,7 +544,7 @@
|
|||
|
||||
If a button is held down when the tool moves in or out of proximity,
|
||||
button events are generated by the compositor. See
|
||||
zwp_tablet_tool_v2.proximity_in and zwp_tablet_tool_v2.proximity_out for
|
||||
wp_tablet_tool.proximity_in and wp_tablet_tool.proximity_out for
|
||||
details.
|
||||
</description>
|
||||
<arg name="serial" type="uint"/>
|
||||
|
|
@ -569,14 +569,14 @@
|
|||
|
||||
<interface name="zwp_tablet_v2" version="2">
|
||||
<description summary="graphics tablet device">
|
||||
The zwp_tablet_v2 interface represents one graphics tablet device. The
|
||||
The wp_tablet interface represents one graphics tablet device. The
|
||||
tablet interface itself does not generate events; all events are
|
||||
generated by zwp_tablet_tool_v2 objects when in proximity above a tablet.
|
||||
generated by wp_tablet_tool objects when in proximity above a tablet.
|
||||
|
||||
A tablet has a number of static characteristics, e.g. device name and
|
||||
pid/vid. These capabilities are sent in an event sequence after the
|
||||
zwp_tablet_seat_v2.tablet_added event. This initial event sequence is
|
||||
terminated by a zwp_tablet_v2.done event.
|
||||
wp_tablet_seat.tablet_added event. This initial event sequence is
|
||||
terminated by a wp_tablet.done event.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
|
|
@ -592,7 +592,7 @@
|
|||
If the device has no descriptive name, this event is not sent.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_v2.done event.
|
||||
wp_tablet.done event.
|
||||
</description>
|
||||
<arg name="name" type="string" summary="the device name"/>
|
||||
</event>
|
||||
|
|
@ -601,16 +601,16 @@
|
|||
<description summary="tablet device vendor/product id">
|
||||
The vendor and product IDs for the tablet device.
|
||||
|
||||
The interpretation of the id depends on the zwp_tablet_v2.bustype.
|
||||
The interpretation of the id depends on the wp_tablet.bustype.
|
||||
Prior to version v2 of this protocol, the id was implied to be a USB
|
||||
vendor and product ID. If no zwp_tablet_v2.bustype is sent, the ID
|
||||
vendor and product ID. If no wp_tablet.bustype is sent, the ID
|
||||
is to be interpreted as USB vendor and product ID.
|
||||
|
||||
If the device has no vendor/product ID, this event is not sent.
|
||||
This can happen for virtual devices or non-USB devices, for instance.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_v2.done event.
|
||||
wp_tablet.done event.
|
||||
</description>
|
||||
<arg name="vid" type="uint" summary="vendor id"/>
|
||||
<arg name="pid" type="uint" summary="product id"/>
|
||||
|
|
@ -619,11 +619,11 @@
|
|||
<event name="path">
|
||||
<description summary="path to the device">
|
||||
A system-specific device path that indicates which device is behind
|
||||
this zwp_tablet_v2. This information may be used to gather additional
|
||||
this wp_tablet. This information may be used to gather additional
|
||||
information about the device, e.g. through libwacom.
|
||||
|
||||
A device may have more than one device path. If so, multiple
|
||||
zwp_tablet_v2.path events are sent. A device may be emulated and not
|
||||
wp_tablet.path events are sent. A device may be emulated and not
|
||||
have a device path, and in that case this event will not be sent.
|
||||
|
||||
The format of the path is unspecified, it may be a device node, a
|
||||
|
|
@ -631,7 +631,7 @@
|
|||
identify the string provided.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_v2.done event.
|
||||
wp_tablet.done event.
|
||||
</description>
|
||||
<arg name="path" type="string" summary="path to local device"/>
|
||||
</event>
|
||||
|
|
@ -650,7 +650,7 @@
|
|||
Sent when the tablet has been removed from the system. When a tablet
|
||||
is removed, some tools may be removed.
|
||||
|
||||
When this event is received, the client must zwp_tablet_v2.destroy
|
||||
When this event is received, the client must wp_tablet.destroy
|
||||
the object.
|
||||
</description>
|
||||
</event>
|
||||
|
|
@ -677,7 +677,7 @@
|
|||
queried, this event is not sent.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_v2.done event.
|
||||
wp_tablet.done event.
|
||||
</description>
|
||||
<arg name="bustype" type="uint" enum="bustype" summary="bus type"/>
|
||||
</event>
|
||||
|
|
@ -688,7 +688,7 @@
|
|||
A circular interaction area, such as the touch ring on the Wacom Intuos
|
||||
Pro series tablets.
|
||||
|
||||
Events on a ring are logically grouped by the zwp_tablet_pad_ring_v2.frame
|
||||
Events on a ring are logically grouped by the wl_tablet_pad_ring.frame
|
||||
event.
|
||||
</description>
|
||||
|
||||
|
|
@ -696,9 +696,9 @@
|
|||
<description summary="set compositor feedback">
|
||||
Request that the compositor use the provided feedback string
|
||||
associated with this ring. This request should be issued immediately
|
||||
after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding
|
||||
after a wp_tablet_pad_group.mode_switch event from the corresponding
|
||||
group is received, or whenever the ring is mapped to a different
|
||||
action. See zwp_tablet_pad_group_v2.mode_switch for more details.
|
||||
action. See wp_tablet_pad_group.mode_switch for more details.
|
||||
|
||||
Clients are encouraged to provide context-aware descriptions for
|
||||
the actions associated with the ring; compositors may use this
|
||||
|
|
@ -710,7 +710,7 @@
|
|||
internationalization rules apply.
|
||||
|
||||
The serial argument will be that of the last
|
||||
zwp_tablet_pad_group_v2.mode_switch event received for the group of this
|
||||
wp_tablet_pad_group.mode_switch event received for the group of this
|
||||
ring. Requests providing other serials than the most recent one will be
|
||||
ignored.
|
||||
</description>
|
||||
|
|
@ -739,11 +739,11 @@
|
|||
Source information for ring events.
|
||||
|
||||
This event does not occur on its own. It is sent before a
|
||||
zwp_tablet_pad_ring_v2.frame event and carries the source information
|
||||
wp_tablet_pad_ring.frame event and carries the source information
|
||||
for all events within that frame.
|
||||
|
||||
The source specifies how this event was generated. If the source is
|
||||
zwp_tablet_pad_ring_v2.source.finger, a zwp_tablet_pad_ring_v2.stop event
|
||||
wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event
|
||||
will be sent when the user lifts the finger off the device.
|
||||
|
||||
This event is optional. If the source is unknown for an interaction,
|
||||
|
|
@ -766,13 +766,13 @@
|
|||
<description summary="interaction stopped">
|
||||
Stop notification for ring events.
|
||||
|
||||
For some zwp_tablet_pad_ring_v2.source types, a zwp_tablet_pad_ring_v2.stop
|
||||
For some wp_tablet_pad_ring.source types, a wp_tablet_pad_ring.stop
|
||||
event is sent to notify a client that the interaction with the ring
|
||||
has terminated. This enables the client to implement kinetic scrolling.
|
||||
See the zwp_tablet_pad_ring_v2.source documentation for information on
|
||||
See the wp_tablet_pad_ring.source documentation for information on
|
||||
when this event may be generated.
|
||||
|
||||
Any zwp_tablet_pad_ring_v2.angle events with the same source after this
|
||||
Any wp_tablet_pad_ring.angle events with the same source after this
|
||||
event should be considered as the start of a new interaction.
|
||||
</description>
|
||||
</event>
|
||||
|
|
@ -783,13 +783,13 @@
|
|||
together. A client is expected to accumulate the data in all events
|
||||
within the frame before proceeding.
|
||||
|
||||
All zwp_tablet_pad_ring_v2 events before a zwp_tablet_pad_ring_v2.frame event belong
|
||||
All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event belong
|
||||
logically together. For example, on termination of a finger interaction
|
||||
on a ring the compositor will send a zwp_tablet_pad_ring_v2.source event,
|
||||
a zwp_tablet_pad_ring_v2.stop event and a zwp_tablet_pad_ring_v2.frame event.
|
||||
on a ring the compositor will send a wp_tablet_pad_ring.source event,
|
||||
a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame event.
|
||||
|
||||
A zwp_tablet_pad_ring_v2.frame event is sent for every logical event
|
||||
group, even if the group only contains a single zwp_tablet_pad_ring_v2
|
||||
A wp_tablet_pad_ring.frame event is sent for every logical event
|
||||
group, even if the group only contains a single wp_tablet_pad_ring
|
||||
event. Specifically, a client may get a sequence: angle, frame,
|
||||
angle, frame, etc.
|
||||
</description>
|
||||
|
|
@ -802,7 +802,7 @@
|
|||
A linear interaction area, such as the strips found in Wacom Cintiq
|
||||
models.
|
||||
|
||||
Events on a strip are logically grouped by the zwp_tablet_pad_strip_v2.frame
|
||||
Events on a strip are logically grouped by the wl_tablet_pad_strip.frame
|
||||
event.
|
||||
</description>
|
||||
|
||||
|
|
@ -810,9 +810,9 @@
|
|||
<description summary="set compositor feedback">
|
||||
Requests the compositor to use the provided feedback string
|
||||
associated with this strip. This request should be issued immediately
|
||||
after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding
|
||||
after a wp_tablet_pad_group.mode_switch event from the corresponding
|
||||
group is received, or whenever the strip is mapped to a different
|
||||
action. See zwp_tablet_pad_group_v2.mode_switch for more details.
|
||||
action. See wp_tablet_pad_group.mode_switch for more details.
|
||||
|
||||
Clients are encouraged to provide context-aware descriptions for
|
||||
the actions associated with the strip, and compositors may use this
|
||||
|
|
@ -824,7 +824,7 @@
|
|||
internationalization rules apply.
|
||||
|
||||
The serial argument will be that of the last
|
||||
zwp_tablet_pad_group_v2.mode_switch event received for the group of this
|
||||
wp_tablet_pad_group.mode_switch event received for the group of this
|
||||
strip. Requests providing other serials than the most recent one will be
|
||||
ignored.
|
||||
</description>
|
||||
|
|
@ -853,11 +853,11 @@
|
|||
Source information for strip events.
|
||||
|
||||
This event does not occur on its own. It is sent before a
|
||||
zwp_tablet_pad_strip_v2.frame event and carries the source information
|
||||
wp_tablet_pad_strip.frame event and carries the source information
|
||||
for all events within that frame.
|
||||
|
||||
The source specifies how this event was generated. If the source is
|
||||
zwp_tablet_pad_strip_v2.source.finger, a zwp_tablet_pad_strip_v2.stop event
|
||||
wp_tablet_pad_strip.source.finger, a wp_tablet_pad_strip.stop event
|
||||
will be sent when the user lifts their finger off the device.
|
||||
|
||||
This event is optional. If the source is unknown for an interaction,
|
||||
|
|
@ -881,13 +881,13 @@
|
|||
<description summary="interaction stopped">
|
||||
Stop notification for strip events.
|
||||
|
||||
For some zwp_tablet_pad_strip_v2.source types, a zwp_tablet_pad_strip_v2.stop
|
||||
For some wp_tablet_pad_strip.source types, a wp_tablet_pad_strip.stop
|
||||
event is sent to notify a client that the interaction with the strip
|
||||
has terminated. This enables the client to implement kinetic
|
||||
scrolling. See the zwp_tablet_pad_strip_v2.source documentation for
|
||||
scrolling. See the wp_tablet_pad_strip.source documentation for
|
||||
information on when this event may be generated.
|
||||
|
||||
Any zwp_tablet_pad_strip_v2.position events with the same source after this
|
||||
Any wp_tablet_pad_strip.position events with the same source after this
|
||||
event should be considered as the start of a new interaction.
|
||||
</description>
|
||||
</event>
|
||||
|
|
@ -898,14 +898,14 @@
|
|||
hardware strip event. A client is expected to accumulate the data
|
||||
in all events within the frame before proceeding.
|
||||
|
||||
All zwp_tablet_pad_strip_v2 events before a zwp_tablet_pad_strip_v2.frame event belong
|
||||
All wp_tablet_pad_strip events before a wp_tablet_pad_strip.frame event belong
|
||||
logically together. For example, on termination of a finger interaction
|
||||
on a strip the compositor will send a zwp_tablet_pad_strip_v2.source event,
|
||||
a zwp_tablet_pad_strip_v2.stop event and a zwp_tablet_pad_strip_v2.frame
|
||||
on a strip the compositor will send a wp_tablet_pad_strip.source event,
|
||||
a wp_tablet_pad_strip.stop event and a wp_tablet_pad_strip.frame
|
||||
event.
|
||||
|
||||
A zwp_tablet_pad_strip_v2.frame event is sent for every logical event
|
||||
group, even if the group only contains a single zwp_tablet_pad_strip_v2
|
||||
A wp_tablet_pad_strip.frame event is sent for every logical event
|
||||
group, even if the group only contains a single wp_tablet_pad_strip
|
||||
event. Specifically, a client may get a sequence: position, frame,
|
||||
position, frame, etc.
|
||||
</description>
|
||||
|
|
@ -922,40 +922,40 @@
|
|||
change on the fly.
|
||||
|
||||
Pad groups will announce their features during pad initialization. Between
|
||||
the corresponding zwp_tablet_pad_v2.group event and zwp_tablet_pad_group_v2.done, the
|
||||
the corresponding wp_tablet_pad.group event and wp_tablet_pad_group.done, the
|
||||
pad group will announce the buttons, rings and strips contained in it,
|
||||
plus the number of supported modes.
|
||||
|
||||
Modes are a mechanism to allow multiple groups of actions for every element
|
||||
in the pad group. The number of groups and available modes in each is
|
||||
persistent across device plugs. The current mode is user-switchable, it
|
||||
will be announced through the zwp_tablet_pad_group_v2.mode_switch event both
|
||||
whenever it is switched, and after zwp_tablet_pad_v2.enter.
|
||||
will be announced through the wp_tablet_pad_group.mode_switch event both
|
||||
whenever it is switched, and after wp_tablet_pad.enter.
|
||||
|
||||
The current mode logically applies to all elements in the pad group,
|
||||
although it is at clients' discretion whether to actually perform different
|
||||
actions, and/or issue the respective .set_feedback requests to notify the
|
||||
compositor. See the zwp_tablet_pad_group_v2.mode_switch event for more details.
|
||||
compositor. See the wp_tablet_pad_group.mode_switch event for more details.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the pad object">
|
||||
Destroy the zwp_tablet_pad_group_v2 object. Objects created from this object
|
||||
Destroy the wp_tablet_pad_group object. Objects created from this object
|
||||
are unaffected and should be destroyed separately.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<event name="buttons">
|
||||
<description summary="buttons announced">
|
||||
Sent on zwp_tablet_pad_group_v2 initialization to announce the available
|
||||
Sent on wp_tablet_pad_group initialization to announce the available
|
||||
buttons in the group. Button indices start at 0, a button may only be
|
||||
in one group at a time.
|
||||
|
||||
This event is first sent in the initial burst of events before the
|
||||
zwp_tablet_pad_group_v2.done event.
|
||||
wp_tablet_pad_group.done event.
|
||||
|
||||
Some buttons are reserved by the compositor. These buttons may not be
|
||||
assigned to any zwp_tablet_pad_group_v2. Compositors may broadcast this
|
||||
assigned to any wp_tablet_pad_group. Compositors may broadcast this
|
||||
event in the case of changes to the mapping of these reserved buttons.
|
||||
If the compositor happens to reserve all buttons in a group, this event
|
||||
will be sent with an empty array.
|
||||
|
|
@ -965,39 +965,39 @@
|
|||
|
||||
<event name="ring">
|
||||
<description summary="ring announced">
|
||||
Sent on zwp_tablet_pad_group_v2 initialization to announce available rings.
|
||||
Sent on wp_tablet_pad_group initialization to announce available rings.
|
||||
One event is sent for each ring available on this pad group.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_group_v2.done event.
|
||||
wp_tablet_pad_group.done event.
|
||||
</description>
|
||||
<arg name="ring" type="new_id" interface="zwp_tablet_pad_ring_v2"/>
|
||||
</event>
|
||||
|
||||
<event name="strip">
|
||||
<description summary="strip announced">
|
||||
Sent on zwp_tablet_pad_v2 initialization to announce available strips.
|
||||
Sent on wp_tablet_pad initialization to announce available strips.
|
||||
One event is sent for each strip available on this pad group.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_group_v2.done event.
|
||||
wp_tablet_pad_group.done event.
|
||||
</description>
|
||||
<arg name="strip" type="new_id" interface="zwp_tablet_pad_strip_v2"/>
|
||||
</event>
|
||||
|
||||
<event name="modes">
|
||||
<description summary="mode-switch ability announced">
|
||||
Sent on zwp_tablet_pad_group_v2 initialization to announce that the pad
|
||||
Sent on wp_tablet_pad_group initialization to announce that the pad
|
||||
group may switch between modes. A client may use a mode to store a
|
||||
specific configuration for buttons, rings and strips and use the
|
||||
zwp_tablet_pad_group_v2.mode_switch event to toggle between these
|
||||
wl_tablet_pad_group.mode_switch event to toggle between these
|
||||
configurations. Mode indices start at 0.
|
||||
|
||||
Switching modes is compositor-dependent. See the
|
||||
zwp_tablet_pad_group_v2.mode_switch event for more details.
|
||||
wp_tablet_pad_group.mode_switch event for more details.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_group_v2.done event. This event is only sent when more than
|
||||
wp_tablet_pad_group.done event. This event is only sent when more than
|
||||
more than one mode is available.
|
||||
</description>
|
||||
<arg name="modes" type="uint" summary="the number of modes"/>
|
||||
|
|
@ -1029,18 +1029,18 @@
|
|||
Intuos Pro, the button inside the ring may be assigned to switch
|
||||
between modes.
|
||||
|
||||
The compositor will also send this event after zwp_tablet_pad_v2.enter on
|
||||
The compositor will also send this event after wp_tablet_pad.enter on
|
||||
each group in order to notify of the current mode. Groups that only
|
||||
feature one mode will use mode=0 when emitting this event.
|
||||
|
||||
If a button action in the new mode differs from the action in the
|
||||
previous mode, the client should immediately issue a
|
||||
zwp_tablet_pad_v2.set_feedback request for each changed button.
|
||||
wp_tablet_pad.set_feedback request for each changed button.
|
||||
|
||||
If a ring, strip or dial action in the new mode differs from the action
|
||||
in the previous mode, the client should immediately issue a
|
||||
zwp_tablet_ring_v2.set_feedback, zwp_tablet_strip_v2.set_feedback or
|
||||
zwp_tablet_dial_v2.set_feedback request for each changed ring, strip or dial.
|
||||
wp_tablet_ring.set_feedback, wp_tablet_strip.set_feedback or
|
||||
wp_tablet_dial.set_feedback request for each changed ring, strip or dial.
|
||||
</description>
|
||||
<arg name="time" type="uint" summary="the time of the event with millisecond granularity"/>
|
||||
<arg name="serial" type="uint"/>
|
||||
|
|
@ -1051,11 +1051,11 @@
|
|||
|
||||
<event name="dial" since="2">
|
||||
<description summary="dial announced">
|
||||
Sent on zwp_tablet_pad_v2 initialization to announce available dials.
|
||||
Sent on wp_tablet_pad initialization to announce available dials.
|
||||
One event is sent for each dial available on this pad group.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_group_v2.done event.
|
||||
wp_tablet_pad_group.done event.
|
||||
</description>
|
||||
<arg name="dial" type="new_id" interface="zwp_tablet_pad_dial_v2"/>
|
||||
</event>
|
||||
|
|
@ -1073,14 +1073,14 @@
|
|||
|
||||
A pad device has a number of static characteristics, e.g. the number
|
||||
of rings. These capabilities are sent in an event sequence after the
|
||||
zwp_tablet_seat_v2.pad_added event before any actual events from this pad.
|
||||
This initial event sequence is terminated by a zwp_tablet_pad_v2.done
|
||||
wp_tablet_seat.pad_added event before any actual events from this pad.
|
||||
This initial event sequence is terminated by a wp_tablet_pad.done
|
||||
event.
|
||||
|
||||
All pad features (buttons, rings, strips and dials) are logically divided into
|
||||
groups and all pads have at least one group. The available groups are
|
||||
notified through the zwp_tablet_pad_v2.group event; the compositor will
|
||||
emit one event per group before emitting zwp_tablet_pad_v2.done.
|
||||
notified through the wp_tablet_pad.group event; the compositor will
|
||||
emit one event per group before emitting wp_tablet_pad.done.
|
||||
|
||||
Groups may have multiple modes. Modes allow clients to map multiple
|
||||
actions to a single pad feature. Only one mode can be active per group,
|
||||
|
|
@ -1091,9 +1091,9 @@
|
|||
<description summary="set compositor feedback">
|
||||
Requests the compositor to use the provided feedback string
|
||||
associated with this button. This request should be issued immediately
|
||||
after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding
|
||||
after a wp_tablet_pad_group.mode_switch event from the corresponding
|
||||
group is received, or whenever a button is mapped to a different
|
||||
action. See zwp_tablet_pad_group_v2.mode_switch for more details.
|
||||
action. See wp_tablet_pad_group.mode_switch for more details.
|
||||
|
||||
Clients are encouraged to provide context-aware descriptions for
|
||||
the actions associated with each button, and compositors may use
|
||||
|
|
@ -1102,7 +1102,7 @@
|
|||
|
||||
Button indices start at 0. Setting the feedback string on a button
|
||||
that is reserved by the compositor (i.e. not belonging to any
|
||||
zwp_tablet_pad_group_v2) does not generate an error but the compositor
|
||||
wp_tablet_pad_group) does not generate an error but the compositor
|
||||
is free to ignore the request.
|
||||
|
||||
The provided string 'description' is a UTF-8 encoded string to be
|
||||
|
|
@ -1110,7 +1110,7 @@
|
|||
internationalization rules apply.
|
||||
|
||||
The serial argument will be that of the last
|
||||
zwp_tablet_pad_group_v2.mode_switch event received for the group of this
|
||||
wp_tablet_pad_group.mode_switch event received for the group of this
|
||||
button. Requests providing other serials than the most recent one will
|
||||
be ignored.
|
||||
</description>
|
||||
|
|
@ -1121,18 +1121,18 @@
|
|||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the pad object">
|
||||
Destroy the zwp_tablet_pad_v2 object. Objects created from this object
|
||||
Destroy the wp_tablet_pad object. Objects created from this object
|
||||
are unaffected and should be destroyed separately.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<event name="group">
|
||||
<description summary="group announced">
|
||||
Sent on zwp_tablet_pad_v2 initialization to announce available groups.
|
||||
Sent on wp_tablet_pad initialization to announce available groups.
|
||||
One event is sent for each pad group available.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_v2.done event. At least one group will be announced.
|
||||
wp_tablet_pad.done event. At least one group will be announced.
|
||||
</description>
|
||||
<arg name="pad_group" type="new_id" interface="zwp_tablet_pad_group_v2"/>
|
||||
</event>
|
||||
|
|
@ -1140,7 +1140,7 @@
|
|||
<event name="path">
|
||||
<description summary="path to the device">
|
||||
A system-specific device path that indicates which device is behind
|
||||
this zwp_tablet_pad_v2. This information may be used to gather additional
|
||||
this wp_tablet_pad. This information may be used to gather additional
|
||||
information about the device, e.g. through libwacom.
|
||||
|
||||
The format of the path is unspecified, it may be a device node, a
|
||||
|
|
@ -1148,18 +1148,18 @@
|
|||
identify the string provided.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_v2.done event.
|
||||
wp_tablet_pad.done event.
|
||||
</description>
|
||||
<arg name="path" type="string" summary="path to local device"/>
|
||||
</event>
|
||||
|
||||
<event name="buttons">
|
||||
<description summary="buttons announced">
|
||||
Sent on zwp_tablet_pad_v2 initialization to announce the available
|
||||
Sent on wp_tablet_pad initialization to announce the available
|
||||
buttons.
|
||||
|
||||
This event is sent in the initial burst of events before the
|
||||
zwp_tablet_pad_v2.done event. This event is only sent when at least one
|
||||
wp_tablet_pad.done event. This event is only sent when at least one
|
||||
button is available.
|
||||
</description>
|
||||
<arg name="buttons" type="uint" summary="the number of buttons"/>
|
||||
|
|
@ -1215,7 +1215,7 @@
|
|||
is removed its pad(s) will be removed too.
|
||||
|
||||
When this event is received, the client must destroy all rings, strips
|
||||
and groups that were offered by this pad, and issue zwp_tablet_pad_v2.destroy
|
||||
and groups that were offered by this pad, and issue wp_tablet_pad.destroy
|
||||
the pad itself.
|
||||
</description>
|
||||
</event>
|
||||
|
|
@ -1225,7 +1225,7 @@
|
|||
<description summary="pad dial">
|
||||
A rotary control, e.g. a dial or a wheel.
|
||||
|
||||
Events on a dial are logically grouped by the zwp_tablet_pad_dial_v2.frame
|
||||
Events on a dial are logically grouped by the wl_tablet_pad_dial.frame
|
||||
event.
|
||||
</description>
|
||||
|
||||
|
|
@ -1233,9 +1233,9 @@
|
|||
<description summary="set compositor feedback">
|
||||
Requests the compositor to use the provided feedback string
|
||||
associated with this dial. This request should be issued immediately
|
||||
after a zwp_tablet_pad_group_v2.mode_switch event from the corresponding
|
||||
after a wp_tablet_pad_group.mode_switch event from the corresponding
|
||||
group is received, or whenever the dial is mapped to a different
|
||||
action. See zwp_tablet_pad_group_v2.mode_switch for more details.
|
||||
action. See wp_tablet_pad_group.mode_switch for more details.
|
||||
|
||||
Clients are encouraged to provide context-aware descriptions for
|
||||
the actions associated with the dial, and compositors may use this
|
||||
|
|
@ -1247,7 +1247,7 @@
|
|||
internationalization rules apply.
|
||||
|
||||
The serial argument will be that of the last
|
||||
zwp_tablet_pad_group_v2.mode_switch event received for the group of this
|
||||
wp_tablet_pad_group.mode_switch event received for the group of this
|
||||
dial. Requests providing other serials than the most recent one will be
|
||||
ignored.
|
||||
</description>
|
||||
|
|
@ -1283,11 +1283,11 @@
|
|||
hardware dial event. A client is expected to accumulate the data
|
||||
in all events within the frame before proceeding.
|
||||
|
||||
All zwp_tablet_pad_dial_v2 events before a zwp_tablet_pad_dial_v2.frame event belong
|
||||
All wp_tablet_pad_dial events before a wp_tablet_pad_dial.frame event belong
|
||||
logically together.
|
||||
|
||||
A zwp_tablet_pad_dial_v2.frame event is sent for every logical event
|
||||
group, even if the group only contains a single zwp_tablet_pad_dial_v2
|
||||
A wp_tablet_pad_dial.frame event is sent for every logical event
|
||||
group, even if the group only contains a single wp_tablet_pad_dial
|
||||
event. Specifically, a client may get a sequence: delta, frame,
|
||||
delta, frame, etc.
|
||||
</description>
|
||||
|
|
|
|||
|
|
@ -514,10 +514,7 @@
|
|||
The window geometry of a surface is its "visible bounds" from the
|
||||
user's perspective. Client-side decorations often have invisible
|
||||
portions like drop-shadows which should be ignored for the
|
||||
purposes of aligning, placing and constraining windows. Note that
|
||||
in some situations, compositors may clip rendering to the window
|
||||
geometry, so the client should avoid putting functional elements
|
||||
outside of it.
|
||||
purposes of aligning, placing and constraining windows.
|
||||
|
||||
The window geometry is double-buffered state, see wl_surface.commit.
|
||||
|
||||
|
|
@ -939,7 +936,7 @@
|
|||
</description>
|
||||
</entry>
|
||||
<entry name="constrained_bottom" value="13" since="7">
|
||||
<description summary="the surface’s bottom edge is constrained">
|
||||
<description summary="the surface’s bottom edge is tiled">
|
||||
The bottom edge of the window is currently constrained, meaning it
|
||||
shouldn't attempt to resize from that edge. It can for example mean
|
||||
it's tiled next to a monitor edge on the constrained side of the
|
||||
|
|
|
|||
|
|
@ -1,144 +0,0 @@
|
|||
---
|
||||
SPDX-FileCopyrightText: 2025 Collabora, Ltd.
|
||||
SPDX-License-Identifier: MIT
|
||||
---
|
||||
|
||||
Contents
|
||||
|
||||
[TOC]
|
||||
|
||||
# Wayland Color-Management Protocol
|
||||
|
||||
This document is an appendix to the [color-management][cm-spec]
|
||||
protocol specification.
|
||||
|
||||
## Transfer functions (normative)
|
||||
|
||||
`wp_color_manager_v1` enumeration `transfer_function` lists a selection
|
||||
of transfer functions describing display-referred image encoding between
|
||||
normalized [electrical] $`E`$ and [optical] $`L`$ values. The function
|
||||
definitions are as follows.
|
||||
|
||||
$`L`$
|
||||
: Screen luminance in cd/m² in the assumed viewing environment.
|
||||
Since the protocol uses the reference luminance level as a proxy for the
|
||||
environment, these values must be interpreted in the context of the
|
||||
reference luminance level.
|
||||
|
||||
$`L_W`$
|
||||
: Screen luminance for peak white; the primary color volume maximum luminance.
|
||||
|
||||
$`L_B`$
|
||||
: Screen luminance for black; the primary color volume minimum luminance.
|
||||
|
||||
|
||||
### `bt1886`
|
||||
|
||||
```math
|
||||
L = a\left(\max\left(E + b,0\right)\right)^\gamma
|
||||
```
|
||||
|
||||
where $`\gamma = 2.4`$ and the parameters
|
||||
|
||||
```math
|
||||
a = \left(L_W^{1/\gamma} - L_B^{1/\gamma}\right)^\gamma,
|
||||
```
|
||||
|
||||
```math
|
||||
b = \frac{L_B^{1/\gamma}}{L_W^{1/\gamma} - L_B^{1/\gamma}}.
|
||||
```
|
||||
|
||||
The above are specified by [ITU-R BT.1886].
|
||||
|
||||
Note, that $`E < 0`$ and $`E > 1`$ are possible with limited range
|
||||
quantization, as required by e.g. the calibration method in [ITU-R BT.814].
|
||||
|
||||
### `compound_power_2_4`
|
||||
|
||||
```math
|
||||
O = \begin{cases}
|
||||
\frac{E}{12.92}, & 0 \leq E < 0.04045\\
|
||||
\left( \frac{E + 0.055}{1.055} \right)^{2.4}, & 0.04045 \leq E \leq 1
|
||||
\end{cases}
|
||||
```
|
||||
|
||||
The above is the IEC 61966-2-1 piece-wise transfer function,
|
||||
as recorded in [Khronos Data Format Specification][KDFS] 1.4.0
|
||||
Section 13.3, and restricted to the unit range.
|
||||
|
||||
```math
|
||||
L = (L_W - L_B)O + L_B
|
||||
```
|
||||
|
||||
### `gamma22`
|
||||
|
||||
```math
|
||||
O = E^{2.2}, \quad 0 \leq E \leq 1
|
||||
```
|
||||
|
||||
```math
|
||||
L = (L_W - L_B)O + L_B
|
||||
```
|
||||
|
||||
### `gamma28`
|
||||
|
||||
```math
|
||||
O = E^{2.8}, \quad 0 \leq E \leq 1
|
||||
```
|
||||
|
||||
```math
|
||||
L = (L_W - L_B)O + L_B
|
||||
```
|
||||
|
||||
### `ext_linear`
|
||||
|
||||
```math
|
||||
O = E, \quad \forall E \in \Reals
|
||||
```
|
||||
|
||||
```math
|
||||
L = (L_W - L_B)O + L_B
|
||||
```
|
||||
|
||||
### `st2084_pq`
|
||||
|
||||
```math
|
||||
\begin{align*}
|
||||
m_1 &=& \vphantom{\Bigg(} \frac{2610}{16384} &= 0.1593017578125\\
|
||||
m_2 &=& \vphantom{\Bigg(} 128\left(\frac{2523}{4096}\right) &= 78.84375\\
|
||||
c_1 = c_3 − c_2 + 1 &=& \vphantom{\Bigg(} \frac{3424}{4096} &= 0.8359375\\
|
||||
c_2 &=& \vphantom{\Bigg(} 32\left(\frac{2413}{4096}\right) &= 18.8515625\\
|
||||
c_3 &=& \vphantom{\Bigg(} 32\left(\frac{2392}{4096}\right) &= 18.6875
|
||||
\end{align*}
|
||||
```
|
||||
|
||||
```math
|
||||
O = \left(
|
||||
\frac{\max\left[
|
||||
\left(E^\frac{1}{m_2} - c_1\right), 0
|
||||
\right]}{c_2 - c_3 E^\frac{1}{m_2}}
|
||||
\right)^\frac{1}{m_1},
|
||||
\quad 0 \leq E \leq 1
|
||||
```
|
||||
|
||||
And the inverse
|
||||
|
||||
```math
|
||||
E = \left( \frac{c_1 + c_2 O^{m_1}}{1 + c_3 O^{m_1}} \right)^{m_2},
|
||||
\quad 0 \leq O \leq 1
|
||||
```
|
||||
|
||||
The above are specified by [ITU-R BT.2100].
|
||||
|
||||
```math
|
||||
L = 10'000\ \mathrm{cd/m²} \cdot O + L_B
|
||||
```
|
||||
|
||||
|
||||
[cm-spec]: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/tree/main/staging/color-management
|
||||
[electrical]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/glossary.md#electrical-color-value
|
||||
[optical]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/glossary.md#optical-color-value
|
||||
[ITU-R BT.814]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt814
|
||||
[ITU-R BT.1886]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt1886
|
||||
[ITU-R BT.2100]: https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/specs.md#itu-r-bt2100
|
||||
[KDFS]: https://registry.khronos.org/DataFormat/
|
||||
|
|
@ -31,14 +31,9 @@
|
|||
<description summary="color management protocol">
|
||||
The aim of the color management extension is to allow clients to know
|
||||
the color properties of outputs, and to tell the compositor about the color
|
||||
properties of their content on surfaces. All surface contents must be
|
||||
readily intended for some display, but not necessarily for the display at
|
||||
hand. Doing this enables a compositor to perform automatic color management
|
||||
of content for different outputs according to how content is intended to
|
||||
look like.
|
||||
|
||||
For an introduction, see the section "Color management" in the Wayland
|
||||
documentation at https://wayland.freedesktop.org/docs/html/ .
|
||||
properties of their content on surfaces. Doing this enables a compositor
|
||||
to perform automatic color management of content for different outputs
|
||||
according to how content is intended to look like.
|
||||
|
||||
The color properties are represented as an image description object which
|
||||
is immutable after it has been created. A wl_output always has an
|
||||
|
|
@ -48,17 +43,16 @@
|
|||
description on a wl_surface to denote the color characteristics of the
|
||||
surface contents.
|
||||
|
||||
An image description essentially defines a display and (indirectly) its
|
||||
viewing environment. An image description includes SDR and HDR colorimetry
|
||||
and encoding, HDR metadata, and some parameters related to the viewing
|
||||
environment. An image description does not include the properties set
|
||||
through color-representation extension. It is expected that the
|
||||
color-representation extension is used in conjunction with the
|
||||
color-management extension when necessary, particularly with the YUV family
|
||||
of pixel formats.
|
||||
An image description includes SDR and HDR colorimetry and encoding, HDR
|
||||
metadata, and viewing environment parameters. An image description does
|
||||
not include the properties set through color-representation extension.
|
||||
It is expected that the color-representation extension is used in
|
||||
conjunction with the color management extension when necessary,
|
||||
particularly with the YUV family of pixel formats.
|
||||
|
||||
The normative appendix for this protocol is in the appendix.md file beside
|
||||
this XML file.
|
||||
Recommendation ITU-T H.273
|
||||
"Coding-independent code points for video signal type identification"
|
||||
shall be referred to as simply H.273 here.
|
||||
|
||||
The color-and-hdr repository
|
||||
(https://gitlab.freedesktop.org/pq/color-and-hdr) contains
|
||||
|
|
@ -77,7 +71,7 @@
|
|||
only be done by creating a new major version of the extension.
|
||||
</description>
|
||||
|
||||
<interface name="wp_color_manager_v1" version="2">
|
||||
<interface name="wp_color_manager_v1" version="1">
|
||||
<description summary="color manager singleton">
|
||||
A singleton global interface used for getting color management extensions
|
||||
for wl_surface and wl_output objects, and for creating client defined
|
||||
|
|
@ -124,14 +118,6 @@
|
|||
summary="ICC-absolute colorimetric"/>
|
||||
<entry name="relative_bpc" value="4"
|
||||
summary="media-relative colorimetric + black point compensation"/>
|
||||
<entry name="absolute_no_adaptation" value="5" since="2">
|
||||
<description summary="ICC-absolute colorimetric without adaptation">
|
||||
This rendering intent is a modified absolute rendering intent that
|
||||
assumes the viewer is not adapted to the display white point, so no
|
||||
chromatic adaptation between surface and display is done.
|
||||
This can be useful for color proofing applications.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<enum name="feature">
|
||||
|
|
@ -168,9 +154,13 @@
|
|||
|
||||
<enum name="primaries">
|
||||
<description summary="named color primaries">
|
||||
Named color primaries used to encode well-known sets of primaries.
|
||||
Named color primaries used to encode well-known sets of primaries. H.273
|
||||
is the authority, when it comes to the exact values of primaries and
|
||||
authoritative specifications, where an equivalent code point exists.
|
||||
|
||||
A value of 0 is invalid and will never be present in the list of enums.
|
||||
|
||||
Descriptions do list the specifications for convenience.
|
||||
</description>
|
||||
|
||||
<entry name="srgb" value="1">
|
||||
|
|
@ -183,6 +173,7 @@
|
|||
- IEC 61966-2-4
|
||||
- Society of Motion Picture and Television Engineers (SMPTE) RP 177
|
||||
(1993) Annex B
|
||||
Equivalent to H.273 ColourPrimaries code point 1.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="pal_m" value="2">
|
||||
|
|
@ -193,6 +184,7 @@
|
|||
Recommendation for transmission standards for color television
|
||||
- United States Federal Communications Commission (2003) Title 47 Code
|
||||
of Federal Regulations 73.682 (a)(20)
|
||||
Equivalent to H.273 ColourPrimaries code point 4.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="pal" value="3">
|
||||
|
|
@ -202,6 +194,7 @@
|
|||
- Rec. ITU-R BT.601-7 625
|
||||
- Rec. ITU-R BT.1358-0 625 (historical)
|
||||
- Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
|
||||
Equivalent to H.273 ColourPrimaries code point 5.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="ntsc" value="4">
|
||||
|
|
@ -212,13 +205,13 @@
|
|||
- Rec. ITU-R BT.1700-0 NTSC
|
||||
- SMPTE 170M (2004)
|
||||
- SMPTE 240M (1999) (historical)
|
||||
Equivalent to H.273 ColourPrimaries code point 6 and 7.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="generic_film" value="5">
|
||||
<description summary="Generic film with colour filters using Illuminant C">
|
||||
Color primaries as defined by Recommendation ITU-T H.273
|
||||
"Coding-independent code points for video signal type identification"
|
||||
for "generic film".
|
||||
Color primaries as defined by H.273 for generic film.
|
||||
Equivalent to H.273 ColourPrimaries code point 8.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="bt2020" value="6">
|
||||
|
|
@ -226,6 +219,7 @@
|
|||
Color primaries as defined by
|
||||
- Rec. ITU-R BT.2020-2
|
||||
- Rec. ITU-R BT.2100-0
|
||||
Equivalent to H.273 ColourPrimaries code point 9.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="cie1931_xyz" value="7">
|
||||
|
|
@ -234,18 +228,21 @@
|
|||
space by
|
||||
- SMPTE ST 428-1
|
||||
- (CIE 1931 XYZ as in ISO 11664-1)
|
||||
Equivalent to H.273 ColourPrimaries code point 10.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="dci_p3" value="8">
|
||||
<description summary="Color primaries of the DCI P3 color space as defined by the SMPTE RP 431 standard">
|
||||
Color primaries as defined by Digital Cinema System and published in
|
||||
SMPTE RP 431-2 (2011).
|
||||
SMPTE RP 431-2 (2011). Equivalent to H.273 ColourPrimaries code point
|
||||
11.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="display_p3" value="9">
|
||||
<description summary="Color primaries of Display P3 variant of the DCI-P3 color space as defined by the SMPTE EG 432 standard">
|
||||
Color primaries as defined by Digital Cinema System and published in
|
||||
SMPTE EG 432-1 (2010).
|
||||
Equivalent to H.273 ColourPrimaries code point 12.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="adobe_rgb" value="10">
|
||||
|
|
@ -259,11 +256,13 @@
|
|||
<enum name="transfer_function">
|
||||
<description summary="named transfer functions">
|
||||
Named transfer functions used to represent well-known transfer
|
||||
characteristics of displays.
|
||||
characteristics. H.273 is the authority, when it comes to the exact
|
||||
formulas and authoritative specifications, where an equivalent code
|
||||
point exists.
|
||||
|
||||
A value of 0 is invalid and will never be present in the list of enums.
|
||||
|
||||
See appendix.md for the formulae.
|
||||
Descriptions do list the specifications for convenience.
|
||||
</description>
|
||||
|
||||
<entry name="bt1886" value="1">
|
||||
|
|
@ -272,6 +271,8 @@
|
|||
- Rec. ITU-R BT.601-7 525 and 625
|
||||
- Rec. ITU-R BT.709-6
|
||||
- Rec. ITU-R BT.2020-2
|
||||
These recommendations are referred to by H.273 TransferCharacteristics
|
||||
code points 1, 6, 14, and 15, which are all equivalent.
|
||||
|
||||
This TF implies these default luminances from Rec. ITU-R BT.2035:
|
||||
- primary color volume minimum: 0.01 cd/m²
|
||||
|
|
@ -288,57 +289,65 @@
|
|||
- United States Federal Communications Commission (2003) Title 47 Code
|
||||
of Federal Regulations 73.682 (a) (20)
|
||||
- Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
|
||||
- IEC 61966-2-1 (reference display)
|
||||
Equivalent to H.273 TransferCharacteristics code point 4.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="gamma28" value="3">
|
||||
<description summary="Assumed display gamma 2.8 transfer function">
|
||||
Transfer characteristics as defined by
|
||||
- Rec. ITU-R BT.470-6 System B, G (historical)
|
||||
Equivalent to H.273 TransferCharacteristics code point 5.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="st240" value="4">
|
||||
<description summary="SMPTE ST 240 transfer function">
|
||||
Transfer characteristics as defined by
|
||||
- SMPTE ST 240 (1999)
|
||||
Equivalent to H.273 TransferCharacteristics code point 7.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="ext_linear" value="5">
|
||||
<description summary="extended linear transfer function">
|
||||
Linear transfer function defined over all real numbers.
|
||||
Normalised electrical values are equal the normalised optical values.
|
||||
|
||||
The differences to H.273 TransferCharacteristics code point 8 are
|
||||
the definition over all real numbers.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="log_100" value="6">
|
||||
<description summary="logarithmic 100:1 transfer function">
|
||||
Logarithmic transfer characteristic (100:1 range).
|
||||
Equivalent to H.273 TransferCharacteristics code point 9.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="log_316" value="7">
|
||||
<description summary="logarithmic (100*Sqrt(10) : 1) transfer function">
|
||||
Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range).
|
||||
Equivalent to H.273 TransferCharacteristics code point 10.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="xvycc" value="8">
|
||||
<description summary="IEC 61966-2-4 transfer function">
|
||||
Transfer characteristics as defined by
|
||||
- IEC 61966-2-4
|
||||
Equivalent to H.273 TransferCharacteristics code point 11.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="srgb" value="9" deprecated-since="2">
|
||||
<description summary="Deprecated (ambiguous sRGB transfer function)">
|
||||
<entry name="srgb" value="9">
|
||||
<description summary="sRGB piece-wise transfer function">
|
||||
Transfer characteristics as defined by
|
||||
- IEC 61966-2-1 sRGB
|
||||
|
||||
As a rule of thumb, use gamma22 for video, motion picture and
|
||||
computer graphics, or compound_power_2_4 for ICC calibrated print
|
||||
workflows.
|
||||
Equivalent to H.273 TransferCharacteristics code point 13 with
|
||||
MatrixCoefficients set to 0.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="ext_srgb" value="10" deprecated-since="2">
|
||||
<description summary="Deprecated (Extended sRGB piece-wise transfer function)">
|
||||
<entry name="ext_srgb" value="10">
|
||||
<description summary="Extended sRGB piece-wise transfer function">
|
||||
Transfer characteristics as defined by
|
||||
- IEC 61966-2-1 sYCC
|
||||
Equivalent to H.273 TransferCharacteristics code point 13 with
|
||||
MatrixCoefficients set to anything but 0.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="st2084_pq" value="11">
|
||||
|
|
@ -346,6 +355,7 @@
|
|||
Transfer characteristics as defined by
|
||||
- SMPTE ST 2084 (2014) for 10-, 12-, 14- and 16-bit systems
|
||||
- Rec. ITU-R BT.2100-2 perceptual quantization (PQ) system
|
||||
Equivalent to H.273 TransferCharacteristics code point 16.
|
||||
|
||||
This TF implies these default luminances
|
||||
- primary color volume minimum: 0.005 cd/m²
|
||||
|
|
@ -363,6 +373,7 @@
|
|||
<description summary="SMPTE ST 428 transfer function">
|
||||
Transfer characteristics as defined by
|
||||
- SMPTE ST 428-1 (2019)
|
||||
Equivalent to H.273 TransferCharacteristics code point 17.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="hlg" value="13">
|
||||
|
|
@ -370,6 +381,7 @@
|
|||
Transfer characteristics as defined by
|
||||
- ARIB STD-B67 (2015)
|
||||
- Rec. ITU-R BT.2100-2 hybrid log-gamma (HLG) system
|
||||
Equivalent to H.273 TransferCharacteristics code point 18.
|
||||
|
||||
This TF implies these default luminances
|
||||
- primary color volume minimum: 0.005 cd/m²
|
||||
|
|
@ -386,12 +398,6 @@
|
|||
ARIB STD-B67 or BT.2100.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="compound_power_2_4" value="14" since="2">
|
||||
<description summary="IEC 61966-2-1 encoding function">
|
||||
Encoding characteristics as defined by IEC 61966-2-1, for displays
|
||||
that invert the encoding function.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<request name="get_output">
|
||||
|
|
@ -525,9 +531,6 @@
|
|||
<description summary="supported rendering intent">
|
||||
When this object is created, it shall immediately send this event once
|
||||
for each rendering intent the compositor supports.
|
||||
|
||||
A compositor must not advertise intents that are deprecated in the
|
||||
bound version of the interface.
|
||||
</description>
|
||||
|
||||
<arg name="render_intent" type="uint" enum="render_intent"
|
||||
|
|
@ -538,9 +541,6 @@
|
|||
<description summary="supported features">
|
||||
When this object is created, it shall immediately send this event once
|
||||
for each compositor supported feature listed in the enumeration.
|
||||
|
||||
A compositor must not advertise features that are deprecated in the
|
||||
bound version of the interface.
|
||||
</description>
|
||||
|
||||
<arg name="feature" type="uint" enum="feature"
|
||||
|
|
@ -552,9 +552,6 @@
|
|||
When this object is created, it shall immediately send this event once
|
||||
for each named transfer function the compositor supports with the
|
||||
parametric image description creator.
|
||||
|
||||
A compositor must not advertise transfer functions that are deprecated
|
||||
in the bound version of the interface.
|
||||
</description>
|
||||
|
||||
<arg name="tf" type="uint" enum="transfer_function"
|
||||
|
|
@ -566,9 +563,6 @@
|
|||
When this object is created, it shall immediately send this event once
|
||||
for each named set of primaries the compositor supports with the
|
||||
parametric image description creator.
|
||||
|
||||
A compositor must not advertise names that are deprecated in the
|
||||
bound version of the interface.
|
||||
</description>
|
||||
|
||||
<arg name="primaries" type="uint" enum="primaries"
|
||||
|
|
@ -581,23 +575,9 @@
|
|||
transfer functions and named primaries have been sent.
|
||||
</description>
|
||||
</event>
|
||||
|
||||
<request name="get_image_description" since="2">
|
||||
<description summary="create an image description from a reference">
|
||||
This request retrieves the image description backing a reference.
|
||||
|
||||
The get_information request can be used if and only if the request that
|
||||
creates the reference allows it.
|
||||
</description>
|
||||
|
||||
<arg name="image_description"
|
||||
type="new_id" interface="wp_image_description_v1"/>
|
||||
<arg name="reference"
|
||||
type="object" interface="wp_image_description_reference_v1"/>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_color_management_output_v1" version="2">
|
||||
<interface name="wp_color_management_output_v1" version="1">
|
||||
<description summary="output color properties">
|
||||
A wp_color_management_output_v1 describes the color properties of an
|
||||
output.
|
||||
|
|
@ -667,7 +647,7 @@
|
|||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_color_management_surface_v1" version="2">
|
||||
<interface name="wp_color_management_surface_v1" version="1">
|
||||
<description summary="color management extension to a surface">
|
||||
A wp_color_management_surface_v1 allows the client to set the color
|
||||
space and HDR properties of a surface.
|
||||
|
|
@ -713,18 +693,18 @@
|
|||
All image descriptions which are ready (see wp_image_description_v1)
|
||||
are allowed and must always be accepted by the compositor.
|
||||
|
||||
When an image description is set on a surface, it establishes an
|
||||
explicit link between surface pixel values and surface colorimetry.
|
||||
This link may be undefined for some pixel values, see the image
|
||||
description creator interfaces for the conditions. Non-finite
|
||||
floating-point values (NaN, Inf) always have an undefined colorimetry.
|
||||
|
||||
A rendering intent provides the client's preference on how surface
|
||||
colorimetry should be mapped to each output. The render_intent value
|
||||
must be one advertised by the compositor with
|
||||
A rendering intent provides the client's preference on how content
|
||||
colors should be mapped to each output. The render_intent value must
|
||||
be one advertised by the compositor with
|
||||
wp_color_manager_v1.render_intent event, otherwise the protocol error
|
||||
render_intent is raised.
|
||||
|
||||
When an image description is set on a surface, the Transfer
|
||||
Characteristics of the image description defines the valid range of
|
||||
the nominal (real-valued) color channel values. The processing of
|
||||
out-of-range color channel values is undefined, but compositors are
|
||||
recommended to clamp the values to the valid range when possible.
|
||||
|
||||
By default, a surface does not have an associated image description
|
||||
nor a rendering intent. The handling of color on such surfaces is
|
||||
compositor implementation defined. Compositors should handle such
|
||||
|
|
@ -755,7 +735,7 @@
|
|||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_color_management_surface_feedback_v1" version="2">
|
||||
<interface name="wp_color_management_surface_feedback_v1" version="1">
|
||||
<description summary="color management extension to a surface">
|
||||
A wp_color_management_surface_feedback_v1 allows the client to get the
|
||||
preferred image description of a surface.
|
||||
|
|
@ -778,14 +758,27 @@
|
|||
summary="attempted to use an unsupported feature"/>
|
||||
</enum>
|
||||
|
||||
<event name="preferred_changed" deprecated-since="2">
|
||||
<description summary="the preferred image description changed (32-bit)">
|
||||
Starting from interface version 2, 'preferred_changed2' is sent instead
|
||||
of this event. See the 'preferred_changed2' event for the definition.
|
||||
<event name="preferred_changed">
|
||||
<description summary="the preferred image description changed">
|
||||
The preferred image description is the one which likely has the most
|
||||
performance and/or quality benefits for the compositor if used by the
|
||||
client for its wl_surface contents. This event is sent whenever the
|
||||
compositor changes the wl_surface's preferred image description.
|
||||
|
||||
This event sends the identity of the new preferred state as the argument,
|
||||
so clients who are aware of the image description already can reuse it.
|
||||
Otherwise, if the client client wants to know what the preferred image
|
||||
description is, it shall use the get_preferred request.
|
||||
|
||||
The preferred image description is not automatically used for anything.
|
||||
It is only a hint, and clients may set any valid image description with
|
||||
set_image_description, but there might be performance and color accuracy
|
||||
improvements by providing the wl_surface contents in the preferred
|
||||
image description. Therefore clients that can, should render according
|
||||
to the preferred image description
|
||||
</description>
|
||||
|
||||
<arg name="identity" type="uint"
|
||||
summary="the 32-bit image description id number"/>
|
||||
<arg name="identity" type="uint" summary="image description id number"/>
|
||||
</event>
|
||||
|
||||
<request name="get_preferred">
|
||||
|
|
@ -842,38 +835,9 @@
|
|||
<arg name="image_description"
|
||||
type="new_id" interface="wp_image_description_v1"/>
|
||||
</request>
|
||||
|
||||
<!-- Version 2 additions -->
|
||||
|
||||
<event name="preferred_changed2" since="2">
|
||||
<description summary="the preferred image description changed">
|
||||
The preferred image description is the one which likely has the most
|
||||
performance and/or quality benefits for the compositor if used by the
|
||||
client for its wl_surface contents. This event is sent whenever the
|
||||
compositor changes the wl_surface's preferred image description.
|
||||
|
||||
This event sends the identity of the new preferred state as the argument,
|
||||
so clients who are aware of the image description already can reuse it.
|
||||
Otherwise, if the client client wants to know what the preferred image
|
||||
description is, it shall use the get_preferred request.
|
||||
|
||||
The preferred image description is not automatically used for anything.
|
||||
It is only a hint, and clients may set any valid image description with
|
||||
set_image_description, but there might be performance and color accuracy
|
||||
improvements by providing the wl_surface contents in the preferred
|
||||
image description. Therefore clients that can, should render according
|
||||
to the preferred image description
|
||||
</description>
|
||||
|
||||
<arg name="identity_hi" type="uint"
|
||||
summary="high 32 bits of the 64-bit image description id number"/>
|
||||
<arg name="identity_lo" type="uint"
|
||||
summary="low 32 bits of the 64-bit image description id number"/>
|
||||
</event>
|
||||
|
||||
</interface>
|
||||
|
||||
<interface name="wp_image_description_creator_icc_v1" version="2">
|
||||
<interface name="wp_image_description_creator_icc_v1" version="1">
|
||||
<description summary="holder of image description ICC information">
|
||||
This type of object is used for collecting all the information required
|
||||
to create a wp_image_description_v1 object from an ICC file. A complete
|
||||
|
|
@ -889,10 +853,6 @@
|
|||
Once all properties have been set, the create request must be used to
|
||||
create the image description object, destroying the creator in the
|
||||
process.
|
||||
|
||||
The link between a pixel value (a device value in ICC) and its respective
|
||||
colorimetry is defined by the details of the particular ICC profile.
|
||||
Those details also determine when colorimetry becomes undefined.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
|
|
@ -989,7 +949,7 @@
|
|||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_image_description_creator_params_v1" version="2">
|
||||
<interface name="wp_image_description_creator_params_v1" version="1">
|
||||
<description summary="holder of image description parameters">
|
||||
This type of object is used for collecting all the parameters required
|
||||
to create a wp_image_description_v1 object. A complete set of required
|
||||
|
|
@ -1018,20 +978,6 @@
|
|||
Once all properties have been set, the create request must be used to
|
||||
create the image description object, destroying the creator in the
|
||||
process.
|
||||
|
||||
A viewer, who is viewing the display defined by the resulting image
|
||||
description (the viewing environment included), is assumed to be fully
|
||||
adapted to the primary color volume's white point.
|
||||
|
||||
Any of the following conditions will cause the colorimetry of a pixel
|
||||
to become undefined:
|
||||
- Values outside of the defined range of the transfer characteristic.
|
||||
- Tristimulus that exceeds the target color volume.
|
||||
- If extended_target_volume is not supported: tristimulus that exceeds
|
||||
the primary color volume.
|
||||
|
||||
The closest correspondence to an image description created through this
|
||||
interface is the Display class of profiles in ICC.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
|
|
@ -1060,16 +1006,14 @@
|
|||
complete, the protocol error incomplete_set is raised. For the
|
||||
definition of a complete set, see the description of this interface.
|
||||
|
||||
When both max_cll and max_fall are set, max_fall must be less or equal
|
||||
to max_cll otherwise the invalid_luminance protocol error is raised.
|
||||
|
||||
In version 1, these following conditions also result in the
|
||||
invalid_luminance protocol error. Version 2 and later do not have this
|
||||
requirement.
|
||||
The protocol error invalid_luminance is raised if any of the following
|
||||
requirements is not met:
|
||||
- When max_cll is set, it must be greater than min L and less or equal
|
||||
to max L of the mastering luminance range.
|
||||
- When max_fall is set, it must be greater than min L and less or equal
|
||||
to max L of the mastering luminance range.
|
||||
- When both max_cll and max_fall are set, max_fall must be less or equal
|
||||
to max_cll.
|
||||
|
||||
If the particular combination of the parameter set is not supported
|
||||
by the compositor, the resulting image description object shall
|
||||
|
|
@ -1095,7 +1039,7 @@
|
|||
functions.
|
||||
|
||||
When the resulting image description is attached to an image, the
|
||||
content should be decoded according to the industry standard
|
||||
content should be encoded and decoded according to the industry standard
|
||||
practices for the transfer characteristic.
|
||||
|
||||
Only names advertised with wp_color_manager_v1 event supported_tf_named
|
||||
|
|
@ -1117,6 +1061,9 @@
|
|||
range of the curve are all finite real numbers. This curve represents
|
||||
the conversion from electrical to optical color channel values.
|
||||
|
||||
When the resulting image description is attached to an image, the
|
||||
content should be encoded with the inverse of the power curve.
|
||||
|
||||
The curve exponent shall be multiplied by 10000 to get the argument eexp
|
||||
value to carry the precision of 4 decimals.
|
||||
|
||||
|
|
@ -1182,8 +1129,8 @@
|
|||
<request name="set_luminances">
|
||||
<description summary="primary color volume luminance range and reference white">
|
||||
Sets the primary color volume luminance range and the reference white
|
||||
luminance level. These values include the minimum display emission, but
|
||||
not external flare. The minimum display emission is assumed to have
|
||||
luminance level. These values include the minimum display emission
|
||||
and ambient flare luminances, assumed to be optically additive and have
|
||||
the chromaticity of the primary color volume white point.
|
||||
|
||||
The default luminances from
|
||||
|
|
@ -1363,15 +1310,13 @@
|
|||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_image_description_v1" version="2">
|
||||
<interface name="wp_image_description_v1" version="1">
|
||||
<description summary="Colorimetric image description">
|
||||
An image description carries information about the pixel color encoding
|
||||
and its intended display and viewing environment. The image description is
|
||||
attached to a wl_surface via
|
||||
An image description carries information about the color encoding used on
|
||||
a surface when attached to a wl_surface via
|
||||
wp_color_management_surface_v1.set_image_description. A compositor can use
|
||||
this information to decode pixel values into colorimetrically meaningful
|
||||
quantities, which allows the compositor to transform the surface contents
|
||||
to become suitable for various displays and viewing environments.
|
||||
quantities.
|
||||
|
||||
Note, that the wp_image_description_v1 object is not ready to be used
|
||||
immediately after creation. The object eventually delivers either the
|
||||
|
|
@ -1440,22 +1385,38 @@
|
|||
summary="ad hoc human-readable explanation"/>
|
||||
</event>
|
||||
|
||||
<event name="ready" deprecated-since="2">
|
||||
<description summary="the object is ready to be used (32-bit)">
|
||||
Starting from interface version 2, the 'ready2' event is sent instead
|
||||
of this event.
|
||||
<event name="ready">
|
||||
<description summary="indication that the object is ready to be used">
|
||||
Once this event has been sent, the wp_image_description_v1 object is
|
||||
deemed "ready". Ready objects can be used to send requests and can be
|
||||
used through other interfaces.
|
||||
|
||||
For the definition of this event, see the 'ready2' event. The
|
||||
difference to this event is as follows.
|
||||
Every ready wp_image_description_v1 protocol object refers to an
|
||||
underlying image description record in the compositor. Multiple protocol
|
||||
objects may end up referring to the same record. Clients may identify
|
||||
these "copies" by comparing their id numbers: if the numbers from two
|
||||
protocol objects are identical, the protocol objects refer to the same
|
||||
image description record. Two different image description records
|
||||
cannot have the same id number simultaneously. The id number does not
|
||||
change during the lifetime of the image description record.
|
||||
|
||||
The id number is valid only as long as the protocol object is alive. If
|
||||
all protocol objects referring to the same image description record are
|
||||
destroyed, the id number may be recycled for a different image
|
||||
description record.
|
||||
|
||||
Image description id number is not a protocol object id. Zero is
|
||||
reserved as an invalid id number. It shall not be possible for a client
|
||||
to refer to an image description by its id number in protocol. The id
|
||||
numbers might not be portable between Wayland connections. A compositor
|
||||
shall not send an invalid id number.
|
||||
|
||||
This identity allows clients to de-duplicate image description records
|
||||
and avoid get_information request if they already have the image
|
||||
description information.
|
||||
</description>
|
||||
|
||||
<arg name="identity" type="uint"
|
||||
summary="the 32-bit image description id number"/>
|
||||
<arg name="identity" type="uint" summary="image description id number"/>
|
||||
</event>
|
||||
|
||||
<request name="get_information">
|
||||
|
|
@ -1472,45 +1433,9 @@
|
|||
<arg name="information"
|
||||
type="new_id" interface="wp_image_description_info_v1"/>
|
||||
</request>
|
||||
|
||||
<!-- Version 2 additions -->
|
||||
|
||||
<event name="ready2" since="2">
|
||||
<description summary="the object is ready to be used">
|
||||
Once this event has been sent, the wp_image_description_v1 object is
|
||||
deemed "ready". Ready objects can be used to send requests and can be
|
||||
used through other interfaces.
|
||||
|
||||
Every ready wp_image_description_v1 protocol object refers to an
|
||||
underlying image description record in the compositor. Multiple protocol
|
||||
objects may end up referring to the same record. Clients may identify
|
||||
these "copies" by comparing their id numbers: if the numbers from two
|
||||
protocol objects are identical, the protocol objects refer to the same
|
||||
image description record. Two different image description records
|
||||
cannot have the same id number simultaneously. The id number does not
|
||||
change during the lifetime of the image description record.
|
||||
|
||||
Image description id number is not a protocol object id. Zero is
|
||||
reserved as an invalid id number. It shall not be possible for a client
|
||||
to refer to an image description by its id number in protocol. The id
|
||||
numbers might not be portable between Wayland connections. A compositor
|
||||
shall not send an invalid id number.
|
||||
|
||||
Compositors must not recycle image description id numbers.
|
||||
|
||||
This identity allows clients to de-duplicate image description records
|
||||
and avoid get_information request if they already have the image
|
||||
description information.
|
||||
</description>
|
||||
|
||||
<arg name="identity_hi" type="uint"
|
||||
summary="high 32 bits of the 64-bit image description id number"/>
|
||||
<arg name="identity_lo" type="uint"
|
||||
summary="low 32 bits of the 64-bit image description id number"/>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_image_description_info_v1" version="2">
|
||||
<interface name="wp_image_description_info_v1" version="1">
|
||||
<description summary="Colorimetric image description information">
|
||||
Sends all matching events describing an image description object exactly
|
||||
once and finally sends the 'done' event.
|
||||
|
|
@ -1703,22 +1628,4 @@
|
|||
summary="Maximum frame-average light level (cd/m²)"/>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_image_description_reference_v1" version="1">
|
||||
<description summary="Reference to an image description">
|
||||
This object is a reference to an image description. This interface is
|
||||
frozen at version 1 to allow other protocols to create
|
||||
wp_image_description_v1 objects.
|
||||
|
||||
The wp_color_manager_v1.get_image_description request can be used to
|
||||
retrieve the underlying image description.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the reference">
|
||||
Destroy this object. This has no effect on the referenced image
|
||||
description.
|
||||
</description>
|
||||
</request>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
|
|||
|
|
@ -1,6 +0,0 @@
|
|||
color-representation protocol
|
||||
|
||||
Maintainers:
|
||||
Simon Ser <contact@emersion.fr>
|
||||
Sebastian Wick <sebastian@sebastianwick.net>
|
||||
Pekka Paalanen <pekka.paalanen@collabora.com>
|
||||
|
|
@ -1,433 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="color_representation_v1">
|
||||
<copyright>
|
||||
Copyright 2022 Simon Ser
|
||||
Copyright 2022 Red Hat, Inc.
|
||||
Copyright 2022 Collabora, Ltd.
|
||||
Copyright 2022-2025 Red Hat, Inc.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice (including the next
|
||||
paragraph) shall be included in all copies or substantial portions of the
|
||||
Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<description summary="color representation protocol extension">
|
||||
This protocol extension delivers the metadata required to define alpha mode,
|
||||
the color model, sub-sampling and quantization range used when interpreting
|
||||
buffer contents. The main use case is defining how the YCbCr family of pixel
|
||||
formats convert to RGB.
|
||||
|
||||
Note that this protocol does not define the colorimetry of the resulting RGB
|
||||
channels / tristimulus values. Without the help of other extensions the
|
||||
resulting colorimetry is therefore implementation defined.
|
||||
|
||||
If this extension is not used, the color representation used is compositor
|
||||
implementation defined.
|
||||
|
||||
Recommendation ITU-T H.273
|
||||
"Coding-independent code points for video signal type identification"
|
||||
shall be referred to as simply H.273 here.
|
||||
</description>
|
||||
|
||||
<interface name="wp_color_representation_manager_v1" version="1">
|
||||
<description summary="color representation manager singleton">
|
||||
A singleton global interface used for getting color representation
|
||||
extensions for wl_surface. The extension interfaces allow setting the
|
||||
color representation of surfaces.
|
||||
|
||||
Compositors should never remove this global.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<description summary="protocol errors"/>
|
||||
<entry name="surface_exists" value="1"
|
||||
summary="color representation surface exists already"/>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the manager">
|
||||
Destroy the wp_color_representation_manager_v1 object. This does not
|
||||
affect any other objects in any way.
|
||||
</description>
|
||||
|
||||
</request>
|
||||
|
||||
<request name="get_surface">
|
||||
<description summary="create a color representation interface for a wl_surface">
|
||||
If a wp_color_representation_surface_v1 object already exists for the
|
||||
given wl_surface, the protocol error surface_exists is raised.
|
||||
|
||||
This creates a new color wp_color_representation_surface_v1 object for
|
||||
the given wl_surface.
|
||||
|
||||
See the wp_color_representation_surface_v1 interface for more details.
|
||||
</description>
|
||||
<arg name="id"
|
||||
type="new_id" interface="wp_color_representation_surface_v1"/>
|
||||
<arg name="surface"
|
||||
type="object" interface="wl_surface"/>
|
||||
</request>
|
||||
|
||||
<event name="supported_alpha_mode">
|
||||
<description summary="supported alpha modes">
|
||||
When this object is created, it shall immediately send this event once
|
||||
for each alpha mode the compositor supports.
|
||||
|
||||
For the definition of the supported values, see the
|
||||
wp_color_representation_surface_v1::alpha_mode enum.
|
||||
</description>
|
||||
<arg name="alpha_mode"
|
||||
type="uint" enum="wp_color_representation_surface_v1.alpha_mode"
|
||||
summary="supported alpha mode"/>
|
||||
</event>
|
||||
|
||||
<event name="supported_coefficients_and_ranges">
|
||||
<description summary="supported matrix coefficients and ranges">
|
||||
When this object is created, it shall immediately send this event once
|
||||
for each matrix coefficient and color range combination the compositor
|
||||
supports.
|
||||
|
||||
For the definition of the supported values, see the
|
||||
wp_color_representation_surface_v1::coefficients and
|
||||
wp_color_representation_surface_v1::range enums.
|
||||
</description>
|
||||
<arg name="coefficients"
|
||||
type="uint" enum="wp_color_representation_surface_v1.coefficients"
|
||||
summary="supported matrix coefficients"/>
|
||||
<arg name="range"
|
||||
type="uint" enum="wp_color_representation_surface_v1.range"
|
||||
summary="full range flag"/>
|
||||
</event>
|
||||
|
||||
<event name="done">
|
||||
<description summary="all features have been sent">
|
||||
This event is sent when all supported features have been sent.
|
||||
</description>
|
||||
</event>
|
||||
</interface>
|
||||
|
||||
<interface name="wp_color_representation_surface_v1" version="1">
|
||||
<description summary="color representation extension to a surface">
|
||||
A wp_color_representation_surface_v1 allows the client to set the color
|
||||
representation metadata of a surface.
|
||||
|
||||
By default, a surface does not have any color representation metadata set.
|
||||
The reconstruction of R, G, B signals on such surfaces is compositor
|
||||
implementation defined. The alpha mode is assumed to be
|
||||
premultiplied_electrical when the alpha mode is unset.
|
||||
|
||||
If the wl_surface associated with the wp_color_representation_surface_v1
|
||||
is destroyed, the wp_color_representation_surface_v1 object becomes inert.
|
||||
</description>
|
||||
|
||||
<enum name="error">
|
||||
<description summary="protocol errors"/>
|
||||
<entry name="alpha_mode" value="1"
|
||||
summary="unsupported alpha mode"/>
|
||||
<entry name="coefficients" value="2"
|
||||
summary="unsupported coefficients"/>
|
||||
<entry name="pixel_format" value="3"
|
||||
summary="the pixel format and a set value are incompatible"/>
|
||||
<entry name="inert" value="4"
|
||||
summary="forbidden request on inert object"/>
|
||||
<entry name="chroma_location" value="5"
|
||||
summary="invalid chroma location"/>
|
||||
</enum>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the color representation">
|
||||
Destroy the wp_color_representation_surface_v1 object.
|
||||
|
||||
Destroying this object unsets all the color representation metadata from
|
||||
the surface. See the wp_color_representation_surface_v1 interface
|
||||
description for how a compositor handles a surface without color
|
||||
representation metadata. Unsetting is double-buffered state, see
|
||||
wl_surface.commit.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<enum name="alpha_mode">
|
||||
<description summary="alpha mode">
|
||||
Specifies how the alpha channel affects the color channels.
|
||||
</description>
|
||||
<entry name="premultiplied_electrical" value="0">
|
||||
<description summary="premultiplied alpha in electrical values">
|
||||
Electrical color channel values (after transfer function encoding)
|
||||
are already multiplied with the alpha channel value.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="premultiplied_optical" value="1">
|
||||
<description summary="premultiplied alpha in optical values">
|
||||
Optical color channel values (before transfer function encoding)
|
||||
are already multiplied with the alpha channel value.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="straight" value="2">
|
||||
<description summary="straight alpha">
|
||||
Alpha channel has not been pre-multiplied into color channels.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<enum name="coefficients">
|
||||
<description summary="named coefficients">
|
||||
Named matrix coefficients used to encode well-known sets of
|
||||
coefficients. H.273 is the authority, when it comes to the exact values
|
||||
of coefficients and authoritative specifications, where an equivalent
|
||||
code point exists.
|
||||
|
||||
A value of 0 is invalid and will never be present in the list of enums.
|
||||
|
||||
Descriptions do list the specifications for convenience.
|
||||
</description>
|
||||
<entry name="identity" value="1">
|
||||
<description summary="The identity matrix">
|
||||
Coefficients as defined by
|
||||
- IEC 61966-2-1 sRGB
|
||||
- SMPTE ST 428-1 (2019)
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 0.
|
||||
Compatible with pixel formats of the RGB family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="bt709" value="2">
|
||||
<description summary="BT.709 matrix coefficients">
|
||||
Coefficients as defined by
|
||||
- Rec. ITU-R BT.709-6
|
||||
- Rec. ITU-R BT.1361-0 conventional colour gamut system (historical)
|
||||
- Rec. ITU-R BT.1361-0 conventional colour gamut system and extended
|
||||
colour gamut system (historical)
|
||||
- IEC 61966-2-4 xvYCC709
|
||||
- SMPTE RP 177 (1993) Annex B
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 1.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="fcc" value="3">
|
||||
<description summary="FCC matrix coefficients">
|
||||
Coefficients as defined by
|
||||
- United States Federal Communications Commission (2003) Title 47
|
||||
Code of Federal Regulations 73.682 (a) (20)
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 4.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="bt601" value="4">
|
||||
<description summary="BT.601-7 matrix coefficients">
|
||||
Coefficients as defined by
|
||||
- Rec. ITU-R BT.470-6 System B, G (historical)
|
||||
- Rec. ITU-R BT.601-7 625
|
||||
- Rec. ITU-R BT.601-7 525
|
||||
- Rec. ITU-R BT.1358-0 625 (historical)
|
||||
- Rec. ITU-R BT.1358-1 525 or 625 (historical)
|
||||
- Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM
|
||||
- Rec. ITU-R BT.1700-0 NTSC
|
||||
- IEC 61966-2-1 sYCC
|
||||
- IEC 61966-2-4 xvYCC601
|
||||
- SMPTE ST 170 (2004)
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 5, 6.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="smpte240" value="5">
|
||||
<description summary="SMPTE ST 240 matrix coefficients">
|
||||
Coefficients as defined by
|
||||
- SMPTE ST 240 (1999)
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 7.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="bt2020" value="6">
|
||||
<description summary="BT.2020 and BT.2100 YCbCr matrix coefficients">
|
||||
Coefficients as defined by
|
||||
- Rec. ITU-R BT.2020-2 (non-constant luminance)
|
||||
- Rec. ITU-R BT.2100-2 Y′CbCr
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 9.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="bt2020_cl" value="7">
|
||||
<description summary="BT.2020 matrix coefficients for constant luminance">
|
||||
Coefficients as defined by
|
||||
- Rec. ITU-R BT.2020-2 (constant luminance)
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 10.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="ictcp" value="8">
|
||||
<description summary="BT.2100 ICtCp matrix coefficients">
|
||||
Coefficients as defined by
|
||||
- Rec. ITU-R BT.2100-2 ICTCP
|
||||
|
||||
Equivalent to H.273 MatrixCoefficients code point 14.
|
||||
Compatible with pixel formats of the YCbCr family.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<enum name="range">
|
||||
<description summary="Color range values">
|
||||
Possible color range values.
|
||||
|
||||
A value of 0 is invalid and will never be present in the list of enums.
|
||||
</description>
|
||||
<entry name="full" value="1" summary="Full color range"/>
|
||||
<entry name="limited" value="2" summary="Limited color range"/>
|
||||
</enum>
|
||||
|
||||
<enum name="chroma_location">
|
||||
<description summary="Chroma sample location for 4:2:0 YCbCr">
|
||||
Chroma sample location as defined by H.273 Chroma420SampleLocType.
|
||||
|
||||
A value of 0 is invalid and will never be present in the list of enums.
|
||||
|
||||
The descriptions list the matching Vulkan VkChromaLocation combinations
|
||||
for convenience.
|
||||
</description>
|
||||
<entry name="type_0" value="1">
|
||||
<description summary="Horizontal offset of 0, vertical offset of 0.5">
|
||||
Corresponding to VkChromaLocations:
|
||||
- xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
|
||||
- yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
|
||||
|
||||
Equivalent to H.273 Chroma420SampleLocType 0.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="type_1" value="2">
|
||||
<description summary="Horizontal offset of 0.5, vertical offset of 0.5">
|
||||
Corresponding to VkChromaLocations:
|
||||
- xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
|
||||
- yChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
|
||||
|
||||
Equivalent to H.273 Chroma420SampleLocType 1.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="type_2" value="3">
|
||||
<description summary="Horizontal offset of 0, vertical offset of 0">
|
||||
Corresponding to VkChromaLocations:
|
||||
- xChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
|
||||
- yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
|
||||
|
||||
Equivalent to H.273 Chroma420SampleLocType 2.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="type_3" value="4">
|
||||
<description summary="Horizontal offset of 0.5, vertical offset of 0">
|
||||
Corresponding to VkChromaLocations:
|
||||
- xChromaOffset: VK_CHROMA_LOCATION_MIDPOINT
|
||||
- yChromaOffset: VK_CHROMA_LOCATION_COSITED_EVEN
|
||||
|
||||
Equivalent to H.273 Chroma420SampleLocType 3.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="type_4" value="5">
|
||||
<description summary="Horizontal offset of 0, vertical offset of 1">
|
||||
Equivalent to H.273 Chroma420SampleLocType 4.
|
||||
</description>
|
||||
</entry>
|
||||
<entry name="type_5" value="6">
|
||||
<description summary="Horizontal offset of 0.5, vertical offset of 1">
|
||||
Equivalent to H.273 Chroma420SampleLocType 5.
|
||||
</description>
|
||||
</entry>
|
||||
</enum>
|
||||
|
||||
<request name="set_alpha_mode">
|
||||
<description summary="set the surface alpha mode">
|
||||
If this protocol object is inert, the protocol error inert is raised.
|
||||
|
||||
Assuming an alpha channel exists, it is always linear. The alpha mode
|
||||
determines whether and how the color channels include pre-multiplied
|
||||
alpha. Using straight alpha might have performance benefits.
|
||||
|
||||
Only alpha modes advertised by the compositor are allowed to be used as
|
||||
argument for this request. The "alpha_mode" protocol error is raised
|
||||
otherwise.
|
||||
|
||||
Alpha mode is double buffered, see wl_surface.commit.
|
||||
</description>
|
||||
<arg name="alpha_mode" type="uint" enum="alpha_mode"
|
||||
summary="alpha mode"/>
|
||||
</request>
|
||||
|
||||
<request name="set_coefficients_and_range">
|
||||
<description summary="set the matrix coefficients and range">
|
||||
If this protocol object is inert, the protocol error inert is raised.
|
||||
|
||||
Set the matrix coefficients and video range which defines the formula
|
||||
and the related constants used to derive red, green and blue signals.
|
||||
Usually coefficients correspond to MatrixCoefficients code points in
|
||||
H.273.
|
||||
|
||||
Only combinations advertised by the compositor are allowed to be used as
|
||||
argument for this request. The "coefficients" protocol error is raised
|
||||
otherwise.
|
||||
|
||||
A call to wl_surface.commit verifies that the pixel format and the
|
||||
coefficients-range combination in the committed surface contents are
|
||||
compatible, if contents exist. The "pixel_format" protocol error is
|
||||
raised otherwise.
|
||||
|
||||
A pixel format is compatible with the coefficients-range combination if
|
||||
the related equations and conventions as defined in H.273 can produce
|
||||
the color channels (RGB or YCbCr) of the pixel format.
|
||||
|
||||
For the definition of the supported combination, see the
|
||||
wp_color_representation_surface_v1::coefficients and
|
||||
wp_color_representation_surface_v1::range enums.
|
||||
|
||||
The coefficients-range combination is double-buffered, see
|
||||
wl_surface.commit.
|
||||
</description>
|
||||
<arg name="coefficients" type="uint" enum="coefficients"
|
||||
summary="matrix coefficients"/>
|
||||
<arg name="range" type="uint" enum="range"
|
||||
summary="range"/>
|
||||
</request>
|
||||
|
||||
<request name="set_chroma_location">
|
||||
<description summary="set the chroma location">
|
||||
If this protocol object is inert, the protocol error inert is raised.
|
||||
|
||||
Set the chroma location type which defines the position of downsampled
|
||||
chroma samples, corresponding to Chroma420SampleLocType code points in
|
||||
H.273.
|
||||
|
||||
An invalid chroma location enum value raises the "chroma_location"
|
||||
protocol error.
|
||||
|
||||
A call to wl_surface.commit verifies that the pixel format and chroma
|
||||
location type in the committed surface contents are compatible, if
|
||||
contents exist. The "pixel_format" protocol error is raised otherwise.
|
||||
|
||||
For the definition of the supported chroma location types, see the
|
||||
wp_color_representation_surface_v1::chroma_location enum.
|
||||
|
||||
The chroma location type is double-buffered, see wl_surface.commit.
|
||||
</description>
|
||||
<arg name="chroma_location" type="uint" enum="chroma_location"
|
||||
summary="chroma sample location"/>
|
||||
</request>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -1,79 +0,0 @@
|
|||
.. Copyright 2022 Red Hat, Inc.
|
||||
|
||||
.. contents::
|
||||
|
||||
Rec ITU-T H.273
|
||||
===============
|
||||
|
||||
Rec ITU-T H.273 (short H.273) is a Recommendation from the International
|
||||
Telecommunication Union (ITU) with the title "Coding-independent code points for
|
||||
video signal type identification". All published versions can be found at
|
||||
https://www.itu.int/rec/T-REC-H.273/en.
|
||||
|
||||
For a quick introduction to Rec ITU-T H.273 see
|
||||
https://gitlab.freedesktop.org/pq/color-and-hdr/-/blob/main/doc/cicp_h273.md.
|
||||
|
||||
Code point and pixel format compatibility
|
||||
=========================================
|
||||
|
||||
Certain color representation metadata requires the selected code point to be
|
||||
compatible with the buffer's pixel format. Which code points are compatible with
|
||||
which pixel formats depends on the type of metadata.
|
||||
|
||||
All ``Chroma420SampleLocType`` chroma location code points are compatible with
|
||||
4:2:0 subsampled pixel formats. Using a pixel format which is not 4:2:0
|
||||
subsampled in a commit where a ``Chroma420SampleLocType`` code point is set
|
||||
results in a protocol error. Clients can unset all code points again by
|
||||
destroying the wp_color_representation_surface_v1, when they switch to such
|
||||
formats.
|
||||
|
||||
The matrix coefficients' code point and pixel format compatibility is harder to
|
||||
determine and depends on the specific code point.
|
||||
|
||||
The ``MatrixCoefficients`` code points are defined by "Rec ITU-T H.273
|
||||
Coding-independent code points for video signal type identification". This
|
||||
document further defines equations which describe how a tristimulus value can be
|
||||
transformed. Which equations can be applied depends on which
|
||||
``MatrixCoefficients`` code point is selected and if the ``VideoFullRangeFlag``
|
||||
is set or not. By applying the applicable equations on a tristimulus value one
|
||||
or more color encodings can be inferred. This color encoding has three channels
|
||||
and each of those channels must map to the pixel format of the surface's buffer.
|
||||
In Rec ITU-T H.273 (07/21) those channels are either R, G and B or Y, Cb and Cr.
|
||||
|
||||
Equations numbers used in the examples below are taken from Rec ITU-T H.273
|
||||
(07/21) and might change in future versions.
|
||||
|
||||
For example code point 0: equations 11-13 transform the tristimulus values E\
|
||||
:sub:`R`, E\ :sub:`G`, E\ :sub:`B` to a non-linear encoding E'\ :sub:`R`, E'\
|
||||
:sub:`G`, E'\ :sub:`B`. Those can be transformed to an RGB encoding with
|
||||
equations 20-22 (if the ``VideoFullRangeFlag`` is not set) or 26-28 (if the
|
||||
``VideoFullRangeFlag`` is set). A YCbCr encoding can be inferred from the RGB
|
||||
encoding with equations 41-43.
|
||||
|
||||
Therefore the code point 0 is compatible only with pixel formats which contain
|
||||
the RGB or YCbCr color channels. The pixel formats may additionally carry unused
|
||||
bits, alpha or other channels.
|
||||
|
||||
For example code point 1: apply equations 11-13, 38-40 and either 23-25 or 29-31
|
||||
(depending on the ``VideoFullRangeFlag``) to arrive at the YCbCr encoding. An
|
||||
RGB encoding cannot be inferred from the applicable equations.
|
||||
|
||||
Therefore code point 1 is is compatible only with pixel formats which contain
|
||||
the YCbCr color channels.
|
||||
|
||||
MatrixCoefficients usage
|
||||
========================
|
||||
|
||||
Note that the ``MatrixCoefficients`` equations as defined by Rec ITU-T H.273
|
||||
describe how the client transforms the tristimulus values to an encoding which
|
||||
ends up in the buffer it sends to the compositor. Compositors will use the
|
||||
inverse steps, including the transfer characteristics which are not defined by
|
||||
this protocol to convert the encoding back to tristimulus values with color
|
||||
primaries which are also not defined by this protocol.
|
||||
|
||||
Some ``MatrixCoefficients`` code points require applying formulas or infering
|
||||
constants from the transfer characteristics or color primaries of the image.
|
||||
Compositors should not advertise support for such code points if the client
|
||||
can't communicate the transfer characteristics and color primaries to the
|
||||
compositor. Communicating those when needed is left for other Wayland extensions
|
||||
to be used in conjunction with color-representation.
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
ext_blur protocol
|
||||
|
||||
Maintainers:
|
||||
David Edmundson <davidedmundson@kde.org>
|
||||
Vlad Zahorodnii <vlad.zahorodnii@kde.org>
|
||||
Xaver Hugl <xaver.hugl@kde.org>
|
||||
|
|
@ -1,129 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="ext_background_effect_v1">
|
||||
<copyright>
|
||||
Copyright (C) 2015 Martin Gräßlin
|
||||
Copyright (C) 2015 Marco Martin
|
||||
Copyright (C) 2020 Vlad Zahorodnii
|
||||
Copyright (C) 2024 Xaver Hugl
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice (including the next
|
||||
paragraph) shall be included in all copies or substantial portions of the
|
||||
Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<interface name="ext_background_effect_manager_v1" version="1">
|
||||
<description summary="background effect factory">
|
||||
This protocol provides a way to improve visuals of translucent surfaces
|
||||
by applying effects like blur to the background behind them.
|
||||
|
||||
The capabilities are send when the global is bound, and every time they
|
||||
change. Note that when the capability goes away, the corresponding effect
|
||||
is no longer applied by the compositor, even if it was set before.
|
||||
|
||||
Warning! The protocol described in this file is currently in the testing
|
||||
phase. Backward compatible changes may be added together with the
|
||||
corresponding interface version bump. Backward incompatible changes can
|
||||
only be done by creating a new major version of the extension.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the background effect manager">
|
||||
Informs the server that the client will no longer be using this
|
||||
protocol object. Existing objects created by this object are not
|
||||
affected.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="background_effect_exists" value="0"
|
||||
summary="the surface already has a background effect object"/>
|
||||
</enum>
|
||||
|
||||
<enum name="capability" bitfield="true">
|
||||
<entry name="blur" value="1"
|
||||
summary="the compositor supports applying blur"/>
|
||||
</enum>
|
||||
|
||||
<event name="capabilities">
|
||||
<description summary="capabilities of the compositor"/>
|
||||
<arg name="flags" type="uint" enum="capability"/>
|
||||
</event>
|
||||
|
||||
<request name="get_background_effect">
|
||||
<description summary="get a background effects object">
|
||||
Instantiate an interface extension for the given wl_surface to add
|
||||
effects like blur for the background behind it.
|
||||
|
||||
If the given wl_surface already has a ext_background_effect_surface_v1
|
||||
object associated, the background_effect_exists protocol error will be
|
||||
raised.
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="ext_background_effect_surface_v1"
|
||||
summary="the new ext_background_effect_surface_v1 object"/>
|
||||
<arg name="surface" type="object" interface="wl_surface"
|
||||
summary="the surface"/>
|
||||
</request>
|
||||
</interface>
|
||||
|
||||
<interface name="ext_background_effect_surface_v1" version="1">
|
||||
<description summary="background effects for a surface">
|
||||
The background effect object provides a way to specify a region behind
|
||||
a surface that should have background effects like blur applied.
|
||||
|
||||
If the wl_surface associated with the ext_background_effect_surface_v1
|
||||
object has been destroyed, this object becomes inert.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="release the blur object">
|
||||
Informs the server that the client will no longer be using this protocol
|
||||
object. The effect regions will be removed on the next commit.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<enum name="error">
|
||||
<entry name="surface_destroyed" value="0"
|
||||
summary="the associated surface has been destroyed"/>
|
||||
</enum>
|
||||
|
||||
<request name="set_blur_region">
|
||||
<description summary="set blur region">
|
||||
This request sets the region of the surface that will have its
|
||||
background blurred.
|
||||
|
||||
The blur region is specified in the surface-local coordinates, and
|
||||
clipped by the compositor to the surface size.
|
||||
|
||||
The initial value for the blur region is empty. Setting the pending
|
||||
blur region has copy semantics, and the wl_region object can be
|
||||
destroyed immediately. A NULL wl_region removes the effect.
|
||||
|
||||
The blur region is double-buffered state, and will be applied on
|
||||
the next wl_surface.commit.
|
||||
|
||||
The blur algorithm is subject to compositor policies.
|
||||
|
||||
If the associated surface has been destroyed, the surface_destroyed
|
||||
error will be raised.
|
||||
</description>
|
||||
<arg name="region" type="object" interface="wl_region" allow-null="true"
|
||||
summary="blur region of the surface"/>
|
||||
</request>
|
||||
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -246,7 +246,7 @@
|
|||
The client may request that the compositor activate or deactivate the workspace.
|
||||
|
||||
Each workspace can belong to only a single workspace group.
|
||||
Depending on the compositor policy, there might be workspaces with
|
||||
Depepending on the compositor policy, there might be workspaces with
|
||||
the same name in different workspace groups, but these workspaces are still
|
||||
separate (e.g. one of them might be active while the other is not).
|
||||
</description>
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
pointer-warp protocol
|
||||
|
||||
Maintainers:
|
||||
Neal Gompa <neal@gompa.dev> (@Conan_Kudo)
|
||||
Xaver Hugl <xaver.hugl@kde.org> (@Zamundaaa)
|
||||
Matthias Klumpp <matthias@tenstral.net> (@mak)
|
||||
Vlad Zahorodnii <vlad.zahorodnii@kde.org> (@zzag)
|
||||
|
|
@ -1,72 +0,0 @@
|
|||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<protocol name="pointer_warp_v1">
|
||||
<copyright>
|
||||
Copyright © 2024 Neal Gompa
|
||||
Copyright © 2024 Xaver Hugl
|
||||
Copyright © 2024 Matthias Klumpp
|
||||
Copyright © 2024 Vlad Zahorodnii
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a
|
||||
copy of this software and associated documentation files (the "Software"),
|
||||
to deal in the Software without restriction, including without limitation
|
||||
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
||||
and/or sell copies of the Software, and to permit persons to whom the
|
||||
Software is furnished to do so, subject to the following conditions:
|
||||
The above copyright notice and this permission notice (including the next
|
||||
paragraph) shall be included in all copies or substantial portions of the
|
||||
Software.
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
||||
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
||||
DEALINGS IN THE SOFTWARE.
|
||||
</copyright>
|
||||
|
||||
<interface name="wp_pointer_warp_v1" version="1">
|
||||
<description summary="reposition the pointer to a location on a surface">
|
||||
This global interface allows applications to request the pointer to be
|
||||
moved to a position relative to a wl_surface.
|
||||
|
||||
Note that if the desired behavior is to constrain the pointer to an area
|
||||
or lock it to a position, this protocol does not provide a reliable way
|
||||
to do that. The pointer constraint and pointer lock protocols should be
|
||||
used for those use cases instead.
|
||||
|
||||
Warning! The protocol described in this file is currently in the testing
|
||||
phase. Backward compatible changes may be added together with the
|
||||
corresponding interface version bump. Backward incompatible changes can
|
||||
only be done by creating a new major version of the extension.
|
||||
</description>
|
||||
|
||||
<request name="destroy" type="destructor">
|
||||
<description summary="destroy the warp manager">
|
||||
Destroy the pointer warp manager.
|
||||
</description>
|
||||
</request>
|
||||
|
||||
<request name="warp_pointer">
|
||||
<description summary="reposition the pointer">
|
||||
Request the compositor to move the pointer to a surface-local position.
|
||||
Whether or not the compositor honors the request is implementation defined,
|
||||
but it should
|
||||
- honor it if the surface has pointer focus, including
|
||||
when it has an implicit pointer grab
|
||||
- reject it if the enter serial is incorrect
|
||||
- reject it if the requested position is outside of the surface
|
||||
|
||||
Note that the enter serial is valid for any surface of the client,
|
||||
and does not have to be from the surface the pointer is warped to.
|
||||
|
||||
</description>
|
||||
<arg name="surface" type="object" interface="wl_surface"
|
||||
summary="surface to position the pointer on"/>
|
||||
<arg name="pointer" type="object" interface="wl_pointer"
|
||||
summary="the pointer that should be repositioned"/>
|
||||
<arg name="x" type="fixed"/>
|
||||
<arg name="y" type="fixed"/>
|
||||
<arg name="serial" type="uint" summary="serial number of the enter event"/>
|
||||
</request>
|
||||
</interface>
|
||||
</protocol>
|
||||
|
|
@ -58,13 +58,6 @@
|
|||
pre-multiplied alpha.
|
||||
|
||||
The width and height of the buffer are 1.
|
||||
|
||||
The r, g, b and a arguments valid range is from UINT32_MIN (0)
|
||||
to UINT32_MAX (0xffffffff).
|
||||
|
||||
These arguments should be interpreted as a percentage, i.e.
|
||||
- UINT32_MIN = 0% of the given color component
|
||||
- UINT32_MAX = 100% of the given color component
|
||||
</description>
|
||||
<arg name="id" type="new_id" interface="wl_buffer"/>
|
||||
<arg name="r" type="uint" summary="value of the buffer's red channel"/>
|
||||
|
|
|
|||
|
|
@ -89,15 +89,16 @@
|
|||
Requests text input on the surface previously obtained from the enter
|
||||
event.
|
||||
|
||||
This request must be issued every time the focused text input changes
|
||||
This request must be issued every time the active text input changes
|
||||
to a new one, including within the current surface. Use
|
||||
zwp_text_input_v3.disable when there is no longer any input focus on
|
||||
the current surface.
|
||||
|
||||
Clients must not enable more than one text input on the single seat
|
||||
and should disable the current text input before enabling the new one.
|
||||
Requests to enable a text input when another text input is enabled
|
||||
on the same seat must be ignored by compositor.
|
||||
At most one instance of text input may be in enabled state per instance,
|
||||
Requests to enable the another text input when some text input is active
|
||||
must be ignored by compositor.
|
||||
|
||||
This request resets all state associated with previous enable, disable,
|
||||
set_surrounding_text, set_text_change_cause, set_content_type, and
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
prefix=@prefix@
|
||||
includedir=@includedir@
|
||||
datarootdir=@datarootdir@
|
||||
pkgdatadir=${pc_sysrootdir}${datarootdir}/@PACKAGE@
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue