These 2 requests have been added:
- wl_data_source.set_actions: Notifies the compositor of the available
actions on the data source.
- wl_data_offer.set_actions: Notifies the compositor of the available
actions on the destination side, plus the preferred action.
Out of the data from these requests, the compositor can determine the action
both parts agree on (and let the user play a role through eg. keyboard
modifiers). The chosen option will be notified to both parties
through the following two requests:
- wl_data_source.action
- wl_data_offer.action
In addition, the destination side can peek the source side actions through
wl_data_offer.source_actions.
Compared to the XDND protocol, there's two notable changes:
- XDND lets the source suggest an action, whereas wl_data_device lets
the destination prefer a given action. The difference is subtle here,
it comes off as convenience because it is the drag destination which
receives the motion events (unlike in X) and can perform action updates.
The drag destination seems also in a better position to update the
preferred action based on things like the data being transferred, the
place being dropped, and whether the drag is client-local.
- That same source-side preferred action is used in XDND to convey the
modifier-induced action to the drag destination, which would then ack
it, or reply with another action that's accepted (or none), this makes
the XdndPosition/XdndStatus messaging very verbose, and synchronous
because the drag source always needs to know the latest status/action
for every position+action sent.
Here it's the compositor which takes care of modifiers and matching
available/accepted actions, this allows for the signaling to happen
only whenever the actions/modifiers change for real.
Roughly based on previous work by Giulio Camuffo <giuliocamuffo@gmail.com>
Changes since v10:
- Narrow down the situations where wl_data_source/offer.accept requests
are supposed to happen.
Changes since v9:
- Deferred the protocol errors to .finish after some IRC chat with Jonas,
added further errors if actions API is used on selection sources/offers.
Changes since v8:
- Defined further the expected behavior on "ask", described the protocol
errors that may happen. Fix more spaces vs tabs issues.
Changes since v7:
- Misc changes after updating the progress notification patch.
Changes since v6:
- Further explanations on wl_data_source/offer.set_actions, including a
description of "ask" actions. Added protocol errors for unknown action
values.
Changes since v5:
- Applied rewording suggestions from Jonas Ådahl. Dropped slot reservation
scheme for actions. Fixed indentation and other minor formatting issues.
Changes since v4:
- Minor rewording.
Changes since v3:
- Splitted from DnD progress notification changes.
- Further rationales in commit log.
Changes since v2:
- Renamed notify_actions to set_actions on both sides, seems more consistent
with the rest of the protocol.
- Spelled out better which events may be triggered on the compositor side
by the requests, the circumstances in which events are emitted, and
what are events useful for in clients.
- Defined a minimal common ground wrt compositor-side action picking and
keybindings.
- Acknowledge the possibility of compositor/toolkit defined actions, even
though none are used at the moment.
Changes since v1:
- Added wl_data_offer.source_actions to let know of the actions offered
by a data source.
- Renamed wl_data_source.finished to "drag_finished" for clarity
- Improved wording as suggested by Bryce
Signed-off-by: Carlos Garnacho <carlosg@gnome.org>
Reviewed-by: Michael Catanzaro <mcatanzaro@igalia.com>
Reviewed-by: Mike Blumenkrantz <zmike@samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Currently, there's no means for the DnD origin to know whether the
destination is actually finished with the DnD transaction, short of
finalizing it after the first transfer finishes, or leaking it forever.
But this poses other interoperation problems, drag destinations might
be requesting several mimetypes at once, might be just poking to find
out the most suitable format, might want to defer the action to a popup,
might be poking contents early before the selection was dropped...
In addition, data_source.cancelled is suitable for the situations where
the DnD operation fails (not on a drop target, no matching mimetypes,
etc..), but seems undocumented for that use (and unused in weston's DnD).
In order to improve the situation, the drag source should be notified
of all stages of DnD. In addition to documenting the "cancelled" event
for DnD purposes, The following 2 events have been added:
- wl_data_source.dnd_drop_performed: Happens when the operation has been
physically finished (eg. the button is released), it could be the right
place to reset the pointer cursor back and undo any other state resulting
from the initial button press.
- wl_data_source.dnd_finished: Happens when the destination side destroys
the wl_data_offer, at this point the source can just forget all data
related to the DnD selection as well, plus optionally deleting the data
on move operations.
Changes since v6:
- Turned wl_data_offer.finish calls with 0/NULL state/mimetype an
error, made it explicit that it will only result in
wl_data_offer.dnd_finished being sent if successful.
Changes since v5:
- Further rewording of wl_data_offer.finish and wl_data_offer.accept.
Added error for untimely wl_data_offer.finish requests.
Changes since v4:
- Applied rewording suggestions from Jonas Ådahl. Added new
wl_data_offer.finish request to allow explicit finalization on the
destination side.
Changes since v3:
- Renamed dnd_performed to a more descriptive dnd_drop_performed,
documented backwards compatible behavior on wl_data_offer.accept and
wl_data_source.cancelled.
Changes since v2:
- Minor rewording.
Changes since v1:
- Renamed events to have a common "dnd" namespace. Made dnd_performed to
happen invariably, data_device.cancelled may still happen afterwards.
Signed-off-by: Carlos Garnacho <carlosg@gnome.org>
Reviewed-by: Michael Catanzaro <mcatanzaro@igalia.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Mike Blumenkrantz <zmike@samsung.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
The frame event groups separate pointer events together. The primary use-case
for this at the moment is diagonal scrolling - a vertical/horizontal scroll
event can be grouped together to calculate the correct motion vector.
Frame events group all wl_pointer events. An example sequence of motion events
followed by a diagonal scroll followed by a button event is:
wl_pointer.motion
wl_pointer.frame
wl_pointer.motion
wl_pointer.frame
wl_pointer.axis
wl_pointer.axis
wl_pointer.frame
wl_pointer.button
wl_pointer.frame
In the future, other extensions may insert additional information about an
event into the frame. For example, an extension may add information about the
physical device that generated an event into the frame. For this reason,
enter/leave events are grouped by a frame event too.
The axis_source event determines how an axis event was generated. That enables
clients to judge when to use kinetic scrolling. Only one axis_source event is
allowed per frame and applies to all events in this frame.
The axis_stop event notifies a client about the termination of a scroll
sequence, likewise needed to calculate kinetic scrolling parameters.
Multiple axis_stop events within the same frame indicate that scrolling has
stopped in all these axis at the same time.
The axis_discrete event provides the wheel click count. Previously the axis
value was some hardcoded number (10), with the discrete steps this enables a
client to differ between line-based scrolling on a mouse wheel and smooth
scrolling with a touchpad. The axis_discrete event carries the axis
information and the discrete value and can occur at any time in the frame
provided it is ordered before the matching axis event. Specifically, this
sequence is valid:
wl_pointer.axis_source
wl_pointer.axis_discrete (vert)
wl_pointer.axis_discrete (horiz)
wl_pointer.axis (horiz)
wl_pointer.axis (vert)
wl_pointer.frame
Enter and leave event also trigger wl_pointer.frame events, where possible the
compositor should group leave and subsequent enter into the same frame. This
indicates to the client that the pointer has moved between surfaces and may
allow a client to shortcut code otherwise triggerd by the leave or enter
events.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Carlos Garnacho <carlosg@gnome.org>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Also applies to touch/keyboard
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Derek Foreman <derekf@osg.samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
wl_surface.damage uses surface local co-ordinates.
Buffer scale and buffer transforms came along, and EGL surfaces
have no understanding of them.
Theoretically, clients pass damage rectangles - in Y-inverted surface
co-ordinates) to EGLSwapBuffersWithDamage, and the EGL implementation
passed them on to wayland. However, for this to work the EGL
implementation must be able to flip those rectangles into the space
the compositor is expecting, but it's unable to do so because it
doesn't know the height of the transformed buffer.
So, currently, EGLSwapBuffersWithDamage is unusable and EGLSwapBuffers
has to pass (0,0) - (INT32_MAX, INT32_MAX) damage to function.
wl_surface.damage_buffer allows damage to be registered on a surface
in buffer co-ordinates, avoiding this problem.
Credit where it's due, these ideas are not entirely my own:
Over a year ago the idea of changing damage co-ordinates to buffer
co-ordinates was suggested (by Jason Ekstrand), and it was at least
partially rejected and abandoned. At the time it was also suggested
(by Pekka Paalanen) that adding a new wl_surface.damage_buffer request
was another option.
This will eventually resolve:
https://bugs.freedesktop.org/show_bug.cgi?id=78190
by making the problem irrelevant.
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason@jlekstrand.net>
Signed-off-by: Derek Foreman <derekf@osg.samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
The documentation for wl_surface.commit makes it clear that the
application of damage follows attach during the commit, so it
doesn't matter what order the app sends the requests.
Many existing apps post damage before attaching a buffer already,
and it's really quite reasonable to do so.
Signed-off-by: Derek Foreman <derekf@osg.samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Daniel Stone <daniels@collabora.com>
See 851614fa78
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Auke Booij <auke@tulcod.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The scanner parses this already, it doesn't do anything with it though.
The DTD requires the order to be copyright, description, then the interfaces.
That's largely a DTD limitation, the scanner doesn't care.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
This reverts commit 06fb8bd371.
Having a DTD hooked up gives an indication of what we expect the protocol to
be, which is a clearer documentation than the current "whatever scanner.c
manages to parse".
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The wayland scanner defines the protocol. The DTD specification is not used.
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Nils Christopher Brause <nilschrbrause@googlemail.com>
This is required if we want to correctly remove a wl_seat compositor-side. A
wl_seat is announced as a global object, then it is bound by the client. When
the compositor wants to remove the seat, it shall announce the global removal of
the object. The client can then call the release request on the wl_seat (which
means I won't use that object anymore).
Acked-by: Derek Foreman <derekf@osg.samsung.com>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>
Add note about what all wl_pointer.release does. Mainly that
it destroys the proxy object, so programmer must not call
wl_pointer_destroy() on the pointer any further.
Signed-off-by: Marek Chalupa <mchqwerty@gmail.com>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Change wording to be more consistent with other parts of the subsurface
protocol. Before this change, wl_subsurface.set_position explicitly
stated that the new state was to be applied on the parents
wl_surface.commit and wl_subsurface.place_above/below only said "on
the next commit of the parent surface". What "committed" means is
ambiguous considering that a wl_surface.commit actually defers the
actual commit when in synchronized mode, but the intention has always
been that placement of a subsurface should be considered part of its
content, i.e. placement state should be applied when other state
(buffer, regions). This patch makes that more clear.
Note that prior to this patch, one could correctly have interpreted
the protocol meaning that placements operations takes effect explicitly
on wl_surface.commit of the parent surface no matter whether other state
of the parent surface is applied at that point. This patch clarifies that
that is not the case.
https://bugs.freedesktop.org/show_bug.cgi?id=88857
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
Acked-by: Jasper St. Pierre <jstpierre@mecheye.net>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Clarify that a client receiving a wl_data_device.selection event must
destroy the data_offer of the previous wl_data_device.selection event,
if any.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
On the interfaces where it was missing:
- wl_data_device
- wl_shell
- wl_pointer
add an error code for requests that set a wl_surface role when the
wl_surface already has a different role.
This is needed for compositors to appropriately report wl_surface
role violations.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jasper St. Pierre <jstpierre@mecheye.net>
Acked-by: Jason Ekstrand <jason.ekstrand@intel.com>
Now that we have defined "role", use the term.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason.ekstrand@intel.com>
Reword the conditions to make use of the definition of "role".
It is still forbidden to create more than one wl_subsurface for a
wl_surface at a time.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason.ekstrand@intel.com>
Now that we have defined "role", use the term.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason.ekstrand@intel.com>
Now that we have defined "role", use the term.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason.ekstrand@intel.com>
Define what a role is, and what restrictions there are.
A change to existing behaviour is that a role cannot be changed at all
once set. However, this is unlikely to cause problems, as there is no
reason to re-use wl_surfaces in clients.
v2: give more concrete examples of roles, define losing a role, Jasper
rewrote the paragraph on how a role is set.
v3: make role permanent, there is no such thing as "losing a role".
Re-issuing the same role again must be allowed for wl_pointer.set_cursor
et al. to work.
v4: clarify the semantics of destroying a role object.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Jason Ekstrand <jason.ekstrand@intel.com>
In the process wl_keyboard's version has been incremented. Given
clients get the wl_keyboard from wl_seat without a version, wl_seat's
version has also been incremented (wl_seat version 4 implies
wl_keyboard version 4).
earlier Acked-by: Daniel Stone <daniel@fooishbar.org>
Reviewed-by: Pekka Paalanen <ppaalanen@gmail.com>
The "release" message of wl_pointer, wl_keyboard and wl_touch introduced
in version 3 was placed first in the respective interface XML element,
causing wayland-scanner to misbehave and set the version number of the
"release" message to all subsequent messages with no explicitly specified
"since" version.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
"the callback event will arrive after the next output refresh" is wrong,
if you interpret "output refresh" as framebuffer flip or the moment when
the new pixels turn into light the first time. Weston has probably never
worked this way.
Weston triggers the frame callbacks when it submits repainting commands
to the GPU, which is before the framebuffer flip.
Strike the incorrect claim, and the rest of the paragraph which no
longer offers useful information.
As a replacement, expand on the "throttling and driving animations"
characteristic. The main purpose is to let clients animate at the
display refresh rate, while avoiding drawing frames that will never be
presented.
The new claim is that the server should give some time between
triggering frame callbacks and repainting itself, for clients to draw
and commit. This is somewhat intimate with the repaint scheduling
algorithm a compositor uses, but hopefully the right intention.
Another point of this update is to imply, that frame callbacks should
not be used to count compositor repaint cycles nor monitor refresh
cycles. It has never been guaranteed to work. Removing the mention of
frame callback without an attach hopefully discourages such use.
v2: Don't just remove a paragraph, but add useful information about the
request's intent.
v3: Specify the order of posting frame callbacks.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Cc: Axel Davy <axel.davy@ens.fr>
Cc: Jason Ekstrand <jason@jlekstrand.net>
Same reason as commit cd31275f28b0a04d2ec5426dc81e875197b47e52 from weston:
The scanner needs to be good enough. If it crashes or fails to report
invalid input, that needs to get fixed.
Clarify when the pending and current buffer transform and scale values
change, and what exactly happens on commit.
This matches what Weston currently does.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
"data" is the name of the void* argument in the implementation.
While we probably shouldn't use such an easily-collidable name,
just rename the callback's argument to callback_data for now.
Make it clear that multiple requests before commit are allowed and how it
is handled.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Jasper St. Pierre <jstpierre@mecheye.net>
Clarify some semantics of wl_subsurface.place_below and
wl_subsurface.place_below that were not specified.
Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
Reviewed-by: Jasper St. Pierre <jstpierre@mecheye.net>
The sub-surface protocol was originally committed into Weston on May
10th, 2013, in commit 2396aec6842c709a714f3825dbad9fd88478f2e6. The
design for the protocol had started in the beginning of December 2012. I
think it is high time to move this into the core now.
This patch copies the sub-surface protocol as it was in Weston on Nov
15th, 2013, into Wayland. Weston gets a patch to remove the protocol from
there.
Sub-surface is a wl_surface role. You create a wl_surface as usual, and
assign it the sub-surface role and a parent wl_surface. Sub-surfaces are
an integral part of the parent surface, and stay glued to the parent.
For window management, a window is the union of the top-level
wl_surface and all its sub-surfaces. Sub-surfaces are not clipped to the
parent, and the union of the surface tree can be larger than the
(top-level) wl_surface at its root.
The representative use case for sub-surfaces is a video player window.
When the video content is given its own wl_surface, there is no need to
modify the video frame contents after decoding or copy them into a whole
window sized buffer before submitting it to the compositor. This allows
efficient, zero-copy video presentation paths, where video decoding
hardware produces a (YUV) buffer, which eventually ends up in a
(YUV-capable) hardware overlay and is scanned out directly.
This can also be used for zero-copy presentation of windowed OpenGL
content, where the OpenGL rendering engine does not need to draw or
avoid window decorations.
Sub-surfaces allow mixing different buffer types into the same window,
e.g. software-rendered decorations in wl_shm buffers, and live content
in EGL-based buffers.
However, the sub-surface extension does not offer clipping or scaling
facilities, or accurate presentation timing. Those are topics for
additional extensions.
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
The scanner is not very forgiving if the protocol doesn't match it's
expectations and crashes without much of a notice. Thus, validate the protocol
against a DTD.
Move the protocol subdir forward so we validate first before trying anything
else, and install the DTD so we can validate weston's protocols as well.
We missed destroy requests in the 1.0 protocol and since the scanner
generates local-only *_destroy requests in that case we can't add
destroy requests without breaking protocol. A client needs to verify
that the server provides a version 3 seat to use the protocol destructor
so the name needs to be something else than wl_*_destroy.
v2 (Rob Bradford): Rebased, bumped the protocol versions and added since
attributes to the requests.
