This is implemented using Wacom-driver specific properties at
the moment, until libinput becomes the fallback driver handling
tablet and pad management.
Whenever a tool becomes in proximity, a new ClutterInputDeviceToolXI2
will be created (if it wasn't created previously) for the given
serial number. This tool will be set in all events send from the
device.
https://bugzilla.gnome.org/show_bug.cgi?id=773779
Stylus configuration (stylus buttons, pressure) was handled
at the very high level, doing the button and pressure translations
right before sending these to wayland clients.
However, it makes more sense to store these settings into the
ClutterInputDeviceTool itself, and have clutter apply the config
at the lower level so 1) the settings actually apply desktop-wide,
not just in clients and 2) X11 and wayland may share similar
configuration paths. The settings are now just applied whenever
the tool enters proximity, in reaction to
ClutterDeviceManager::tool-changed.
This commit moves all handling of these two settings to
the clutter level, and removes the wayland-specific paths
https://bugzilla.gnome.org/show_bug.cgi?id=773779
We do so whenever a tool enters or leaves proximity. We now also
ensure that last_tool is NULL after it leaves proximity, although
the CLUTTER_PROXIMITY_OUT event itself should still contain tool
information.
https://bugzilla.gnome.org/show_bug.cgi?id=773779
We most notably handle button events (acquired through a passive grab on
all device buttons) which are translated to CLUTTER_PAD_BUTTON* events,
so there is generic handling of pad actions on X11.
https://bugzilla.gnome.org/show_bug.cgi?id=773779
Commit 5fbb479301 was wrong too. What we
really want to do here is getting view relative coordinates given the
view's and the rectangle's global coordinates so we need to subtract
the view's origin from the rectangle's.
https://bugzilla.gnome.org/show_bug.cgi?id=771502
Commit a4fb7ef5a3 dropped translations of our internal cogl/clutter
forks, which broke the local-based text direction support. Instead
of bringing back translations just for this purpose, we can re-use
GTK's translations which use the same technique.
https://bugzilla.gnome.org/show_bug.cgi?id=771549
Now with the existance of offscreen view framebuffers the buffer age
damage regions are only valid if the view in question doesn't doesn't
have an intermediate offscreen. So, for views that doesn't have buffer
age, return the dirty pixel (0,0).
https://bugzilla.gnome.org/show_bug.cgi?id=770672
When blitting an offscreen onto an onscreen, the whole offscreen should
always be drawn on the whole onscreen. Thus, don't try to convert
between coordinate spaces, just draw the whole offscreen on the whole
onscreen.
https://bugzilla.gnome.org/show_bug.cgi?id=770672
Clutter discards any motion event if next event happens to also be a
motion event. This is problematic when the motion event carries
relative motion deltas, since the information about them is completely
lost.
Until we have moved away made the stage stop discarding motion events,
lets work around the issue by compressing them, effectively adding
multiple relative motion deltas together, would one be discarded.
https://bugzilla.gnome.org/show_bug.cgi?id=771049
The rectangle passed to capture_view() is in stage coordinate space;
thus, to translate to framebuffer coordinate space, the origin need to
be translated by the view layout position.
This fixes capturing views not at position (0, 0).
https://bugzilla.gnome.org/show_bug.cgi?id=770127
Absolute pointer events used the X coordinate as both X and Y. This
caused the pointer cursor to be moved incorrectly for absolute pointer
devices, commonly used in virtual machines.
https://bugzilla.gnome.org/show_bug.cgi?id=770557
"Blit" the result on the framebuffer after each view is painted.
This of course only applies if there is an offscreen buffer to
perform any blitting. Otherwise the onscreen framebuffer is rendered
to directly and this step is not necessary.
https://bugzilla.gnome.org/show_bug.cgi?id=745079
The offscreen is given through the ::back-buffer property, the ClutterStageView
will set up the the CoglPipeline used to render it back to the "onscreen"
framebuffer.
The pipeline can be altered through the setup_pipeline() vfunc, so ClutterStageView
implementations can alter the default behavior of blitting from offscreen to
onscreen with no transformations.
All getters of "the framebuffer" that were expecting to get an onscreen have
been updated to call the right clutter_stage_view_get_onscreen() function.
https://bugzilla.gnome.org/show_bug.cgi?id=745079
Various clutter test directly use cogl symbols, so they should be linked
against mutter-cogl as well.
Signed-off-by: Sjoerd Simons <sjoerd.simons@collabora.co.uk>
https://bugzilla.gnome.org/show_bug.cgi?id=769636
This is somewhat gross at the moment, because we're after all mimicking
real keyboard events, we can only lookup keycodes that are available
in the current map, and the control of levels is rather limited.
Eventually, we want to implement the text_input protocol, handle these
events separately to MetaWaylandKeyboard, so event->key.keyval is
is guaranteed to be the final result. Until then, this is the farthest
we can get.
https://bugzilla.gnome.org/show_bug.cgi?id=765009
Evcodes don't cut it when we have something already specifying the
character to be printed, despite the current group/level. This API
allows some more control on the intended output.
https://bugzilla.gnome.org/show_bug.cgi?id=765009
libinput does it for us, but only for physical devices. When we add
virtual devices to the same seat, we need to track button press count
ourself.
https://bugzilla.gnome.org/show_bug.cgi?id=765009
Virtual input devices aim to enable injecting input events as if they
came from hardware events. This is useful for things such as remote
controlling, for example via a remote desktop session.
The API so far only consists of stumps.
https://bugzilla.gnome.org/show_bug.cgi?id=765009
Depending on clutter_input_device_get_mapping(), or whether the current
tool is either cursor or lens (those don't make any sense in absolute
mode), relative motions will be reported.
This function call only applies to tablets, and thus will error
out unless it's called with CLUTTER_TABLET_DEVICEs. This will
allow setting absolute/relative mapping on those on the fly, as
this is optional.
This will only be practical for pads (and maybe generic buttonsets in
the future?), we just need to know the number as the events will also
contain a number as the identificator.
Those map closely what we get from libinput. Button events have
been made its own separate struct, its semantics fall somewhere
in between of ClutterButtonEvent and ClutterKeyEvent, so is better
emitted as its own set.
Currently the setter doesn't take ownership of the value, but dispose()
will unref it (and thus release someone else's reference). Fix this by
taking ownership of the property value in the setter.
There's no need for a cast for printing an object's type or address,
so we can remove variables that are unused when not building with
CLUTTER_ENABLE_DEBUG.
Mutter (and libmutter users) are the only users of this version of
cogl, and will more or less only use the cogl-1.0, cogl-2.0 and cogl
experimental API variants, and having the possibility of having
different API versions of the same API depending on what file includes
it is error prone and confusing. Lets just remove the possibility of
having different versions of the same API.
https://bugzilla.gnome.org/show_bug.cgi?id=768977
We bypass our build configuration to fetch API from a version which
isn't the one we actually use. Stop bypassing and just admit that the
1.0 API is still there, but still deprecated.
https://bugzilla.gnome.org/show_bug.cgi?id=768977
We didn't include clutter-build-config.h, meaning we included a
different API of cogl than the rest of clutter. This API contains the
function cogl_sqrti which was the only thing used. Lets include the
build config file and stop depending on the API that is no longer
exposed to us.
https://bugzilla.gnome.org/show_bug.cgi?id=768977
CoglFrameInfo is a frame info container associated with a single
onscreen framebuffer. The clutter stage will eventually support drawing
a stage frame with multiple onscreen framebuffers, thus needs its own
frame info container.
This patch introduces a new stage signal 'presented' and a accompaning
ClutterFrameInfo and adapts the stage windows and past onscreen frame
callbacks users to use the signal and new info container.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
Add support for drawing a stage using multiple framebuffers each making
up one part of the stage. This works by the stage backend
(ClutterStageWindow) providing a list of views which will be for
splitting up the stage in different regions.
A view layout, for now, is a set of rectangles. The stage window (i.e.
stage "backend" will use this information when drawing a frame, using
one framebuffer for each view. The scene graph is adapted to explictly
take a view when painting the stage. It will use this view, its
assigned framebuffer and layout to offset and clip the drawing
accordingly.
This effectively removes any notion of "stage framebuffer", since each
stage now may consist of multiple framebuffers. Therefore, API
involving this has been deprecated and made no-ops; namely
clutter_stage_ensure_context(). Callers are now assumed to either
always use a framebuffer reference explicitly, or push/pop the
framebuffer of a given view where the code has not yet changed to use
the explicit-buffer-using cogl API.
Currently only the nested X11 backend supports this mode fully, and the
per view framebuffers are all offscreen. Upon frame completion, it'll
blit each view's framebuffer onto the onscreen framebuffer before
swapping.
Other backends (X11 CM and native/KMS) are adapted to manage a
full-stage view. The X11 CM backend will continue to use this method,
while the native/KMS backend will be adopted to use multiple view
drawing.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
Instead of assuming there is a single onscreen framebuffer, use the
helper functions for setting the frame callback and getting the frame
counter.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
In preperation for having allowing drawing onto multiple onscreen
framebuffers, move the onscreen framebuffer handling to the
corresponding winsys dependent backends.
Currently the onscreen framebuffer is still accessed, but, as can seen
by the usage of "legacy" in the accessor name, it should be considered
the legacy method. Eventually only the X11 Compositing Manager backend
will make use of the legacy single onscreen framebuffer API.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
Split the stage window implementations into three separate objects: one
for X11 as a compositing manager, one for X11 running as a nested
Wayland compositor, and one for running with the native backend.
The new stage window implementations are only thin shells; this is in
preparation for making the stage windows behave more differently.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
Instead of passing around the KMS file descriptor via clutter to cogl,
just make our own clutter backend create the cogl renderer and set the
KSM fd.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
The actor-offscreen-redirect didn't initialize its state properly, so
it could potentially end up with the "was_painted" state being TRUE
from the start, effectively skipping the whole test.
Fixing so that the test even run resulted in the test getting stuck in
a dead lock due to the verification that a frame was drawn was done
from a paint callback. A paint callback had the mutex held, so when the
test case tried to run the main loop, the next paint callback caller
path taken would try to re-lock the same mutex, thus dead lock.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
In cogl use cogl-config.h and in clutter use clutter-build-config.h. We
can't use clutter-config.h in clutter because its already used and
installed.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
Introduce two new clutter backends: MetaClutterBackendX11 and
MetaClutterBackendNative. They are so far only wrap ClutterBackendX11
and ClutterBackendEglNative respectively, but the aim is to move things
from the original clutter backends when needed.
https://bugzilla.gnome.org/show_bug.cgi?id=768976
Since the check for backend->cogl_context was accidentally moved
to clutter_backend_do_real_create_context, the Glib source that
is created at the end of clutter_backend_do_create_context() is
created and added each time create_context() is called, though
create_context() is supposed to be idempotent.
https://bugzilla.gnome.org/show_bug.cgi?id=768243
The 'select-all' action is currently only bound to <ctrl>a, which makes
it awkward to use when caps-lock is active, and is inconsistent with GTK+.
Just accept both upper- and lower-case variants.
https://bugzilla.gnome.org/show_bug.cgi?id=766326
The device name is something more natural, similar to what's seen
in X11, the sysname is rather the event node basename, which may
also vary depending on device insertion/detection time.
Clutter out of tree depends on Cogl's required dependencies via the
pkg-config file. Since Clutter and Cogl moved in tree, it means that
those dependencies need to be checked by Clutter itself, otherwise
headers and libraries won't be found.
ClutterActor should warn if a user tries to add or remove an actor to,
and from, itself on the scene graph.
Clutter will likely crash, or warn way down the line, but if we can make
debugging simpler then we should.
For the GDK backend We're using the GdkDeviceManager API, which maps to
Clutter's own device manager API. GDK has now moved to a per-seat device
management model, and deprecated the device manager singleton one.
In order to avoid the deprecation warnings, we'd have to implement a
model similar to the GDK one inside the generic Clutter API, but that
would also require moving all the others backend to it, which is pretty
pointless.
Instead, we can disable deprecation warnings for the
ClutterDeviceManager implementation inside the GDK backend.
This updates config.h.win32.in to be in-sync with the entries that are in
the config.h.in that is generated by the autotools builds. In particular,
for Visual Studio builds, we default to enable all available drivers ("*").
The function should return true not only if the actor is being painted
by a ClutterClone, but also if it's inside a sub-graph being painted by
a ClutterClone.
https://bugzilla.gnome.org/show_bug.cgi?id=756371
The constrain callback cannot rely on the pointer position of the
corresponding ClutterInputDevice to get the actual delta of the motion
event that is to be constrained since it is only updated when an event is
dispatched. So change the API to pass the previous pointer position when
constraining.
https://bugzilla.gnome.org/show_bug.cgi?id=752752
Compositors need more detailed information about motion events. Make it
possible to retrieve this information when running the evdev backend by
adding the information to the backend specific event struct.
https://bugzilla.gnome.org/show_bug.cgi?id=752752
Since commit 6183eb3632 we disabled swap
throttling in favour of being driven by the GDK frame clock (and thus by
the compositor).
Compositors may decide to unredirect full screen windows to avoid the
performance penalty of the additional copy, especially on X11, which
means that a Clutter application marked as full screen is not going to
be driven by the compositor, and it's not going to be throttled by the
underlying GL machinery. This has a performance impact on constrained
platforms.
For this reason, we should re-enable swap throttling when the window is
full screen.
As the change was introduced especially because of Wayland, we should
check that we're not running as clients under a Wayland compositor; if
we do, we always keep swap throttling disabled, as the compositor will
always manage our output, even when full screen.
Those can be used to implement different scrolling behaviors.
The fields have been added to ClutterScrollEvent itself. According
to pahole, this makes the struct as big as ClutterButtonEvent and
ClutterTouchEvent, so already at the limit of the ClutterEvent
union.
https://bugzilla.gnome.org/show_bug.cgi?id=757026
We should allow a configuration file to set up the initial state of the
global state, which also implies being able to set the backend.
If the allowed backends have already been set programmatically via the
clutter_set_windowing_backend(), though, then the application code takes
precedence, as we assume that the application author knows better than
us what their code supports or requires.
The configuration file should set up the global state before we
initialize it; instead of relying on implicit ordering, explicitly read
the configuration file once, when creating the global shared context
data structure.
Like CLUTTER_DRIVER, we want to allow users to specify a list of
backends to test, and fall back to the internally defined priority as a
default.
This requires changing the way the allowed backend string is parsed,
both for the CLUTTER_BACKEND environment variable and for the
clutter_set_windowing_backend() function. Existing callers are still
supported with the exact same semantics.
Using environment variables only is not convenient for all platforms,
and in some cases it's beneficial to decide the default driver when
building Clutter. Cogl already has a similar configuration switch, and
since Clutter is overriding the default Cogl behaviour, it should offer
the same mechanism.
https://bugzilla.gnome.org/show_bug.cgi?id=742678
We have an hardcoded list of drivers we have to go through when creating
a Cogl context. Some platforms may expose those drivers, but not be the
preferred ones.
In order to allow users and system integrators to override the list of
drivers, we should crib the same approach used by GDK, and have an
environment variable with a list of drivers to try.
The new environment variable is called `CLUTTER_DRIVER` and accepts a
comma-separated list of driver names, which will be tested in sequence
until one succeeds. There's also an additional '*' token which is used
to ask Clutter to fall back to the internally defined preferred list of
drivers.
https://bugzilla.gnome.org/show_bug.cgi?id=742678
Being able to select text and being able to edit text are two separate
capabilities, but ClutterText only allows the former with the latter.
The ClutterText:selectable property is set to TRUE by default, given
that it depends on the :editable property; this implies that all
ClutterText instances now are going to show a cursor as soon as they get
key focused. Obviously, this would make labels look a bit off — but if
you have a label then you would not give it key focus, either by
explicitly calling clutter_actor_grab_focus(), or by setting it as
reactive and allowing it to be clicked.
If this turns out to be a problem, we have various ways to avoid showing
a cursor — for instance, we could change the default value of the
selectable property, and ensure that setting the :editable property to
TRUE would also set the :selectable property as a side effect. Or we
could hide the cursor until the first button/touch press event. Finally,
we could always back this commit out if it proves to be too much of a
breakage for existing code bases.
https://bugzilla.gnome.org/show_bug.cgi?id=757470
The X11 part of the GDK backend takes into account the scaling factor of its
window when resizing the underlying X11 objects. We need to do the same for
Wayland.
https://bugzilla.gnome.org/show_bug.cgi?id=755245
This is now stored as platform data in the ClutterEvent, so can
be retrieved with the clutter_evdev_event_get_event_code() call
that's been added to the evdev backend.
https://bugzilla.gnome.org/show_bug.cgi?id=758238
Device managers can now implement the ClutterEventExtender interface
that allows them to set their own data to events, make the backend call
those implementations if the device manager implements the interface.
https://bugzilla.gnome.org/show_bug.cgi?id=758238
This normally belonged to the ClutterBackend, however there's device
managers (eg. evdev) that are somewhat detached from the backend, so
need to bridge this somehow.
This allows device managers to implement these bits that were usually
responsibility of the ClutterBackend.
https://bugzilla.gnome.org/show_bug.cgi?id=758238
On X11 those were skipped, so additional pointer buttons would come up
as button >= 8 events. Do here the same, so we remain compatible across
backends.
https://bugzilla.gnome.org/show_bug.cgi?id=758237
There's handlers around relying on up/down/left/right scroll events,
which won't work as expected if only smooth scroll events are sent.
In order to work properly there, we have to retrofit discrete scroll
events on the evdev backend.
Fix this by implementing emission (on devices with a wheel) and
emulation (on anything else) of discrete scroll events. On the former
both smooth and discrete events are set, for the latter we do accumulate
the dx/dy of the latest scroll events, and emit discrete ones when we
accumulated enough. The ending 0/0 event will reset the accumulators for
the next scrolling batch.
https://bugzilla.gnome.org/show_bug.cgi?id=756284
When enable_paint_unmapped is disabled, we shouldn't force the
source widget to be unmapped if the constraints would keep it
mapped; in practice this shouldn't matter unless a paint handler
is messing with the map state.
https://bugzilla.gnome.org/show_bug.cgi?id=745517
Enable animation updates from the GdkFrameClock whenever any timeline is
added to the ClutterMasterClockGdk. This may improve animation
smoothness (depending on the GDK backend in use) because it allows GDK
to tweak its frame timing for animation purposes.
https://bugzilla.gnome.org/show_bug.cgi?id=755357
This is how GdkFrameClock is meant to be used: the frame time is meant
to be queried from the GdkFrameClock within its frame signals, rather
from the system monotonic time source.
https://bugzilla.gnome.org/show_bug.cgi?id=755357
When removing the frame callback on the CoglOnscreen, we loose the ability
to get notified of swap events. This could leave us with a counter != 0
which leads to a deadlock situation after the next realize/draw cycle.
https://bugzilla.gnome.org/show_bug.cgi?id=755014
If we call _clutter_stage_do_update() on a ClutterStage that isn't
mapped/visible, no GL command will be queued, and the Mesa/DRI2
implementation of SwapBuffers will do nothing. This causes
GLX_INTEL_swap_event to not be emitted by the X server because no swapping
has been requested through DRI2 and it eventually leads to a deadlock
situation in ClutterStageCogl because we're waiting for an event before we
start the next draw cycle.
This patch removes the non mapped stages from the list of stages to process.
This is consistent with a previous patch for the ClutterMasterClockGdk [1].
[1] : 5733ad58e5https://bugzilla.gnome.org/show_bug.cgi?id=755014
Setting up the sync_to_vblank in the MasterClock is a bit too late as
the MasterClock can be created after a StageWindow has been created
and realized (and therefore all of its Cogl/GL state setup already).
So move the setup to the backend, prior to any StageWindow creation.
https://bugzilla.gnome.org/show_bug.cgi?id=754938
Clutter still uses part of the deprecated stateful API of Cogl (in
particulart cogl_set_framebuffer). It means Cogl can keep an internal
reference to the onscreen object we rendered to. In the case of
foreign window, we want to avoid this, as we don't know what's going
to happen to that window.
This change sets the current Cogl framebuffer to a dummy 1x1
framebuffer if the current Cogl framebuffer is the one we're
unrealizing.
https://bugzilla.gnome.org/show_bug.cgi?id=754890
We're currently hooked to the "update" signal of the FrameClock. When
embedding Clutter inside GTK+ we want to have the layout phase of GTK+
to notify us the size of our stage.
This patch change to FrameClock signal we're listening to, to the
"paint" signal to make sure we've received the layout information from
GTK+, before painting. Otherwise we paint with a delay of one frame.
https://bugzilla.gnome.org/show_bug.cgi?id=754889
The commit 6cd24faaa5 (actor: Clean up
transform_stage_point()) changed the validation of the transformation
matrix to ignore the fraction part of the determinant. This caused
clutter_actor_transform_stage_point() to fail and return FALSE for
actors which scale was less than 1.
Previously the validation was ('det' being a float):
det = (RQ[0][0] * ST[0][0])
+ (RQ[0][1] * ST[0][1])
+ (RQ[0][2] * ST[0][2]);
if (!det)
return FALSE;
Semantically, the if statement expression '!det' is equivalent to
'det == 0', i.e. 'det == 0.0f'. Post cleanup patches, 'det' was turned
into a double, and the if statement was changed to:
if (CLUTTER_NEARBYINT (det) == 0)
return FALSE;
which, different from before, rounds the determinant to the nearest
integer value, meaning determinant in the range (-0.5, 0.5) would be
considered invalid.
This patch reverts this part to the old behavior, while, because of the
inexact nature of floating point arithmetics, allowing a bit more liberal
meaning of "equals to 0" than '== 0.0'.
https://bugzilla.gnome.org/show_bug.cgi?id=754766
When running on wayland, we might have our own subsurface
desynchronized from the foreign GdkWindow. It is important that we
report the size of the actually surface we're rendering to, otherwise
the logic in ClutterStage might discard resize operation that
resynchronize the subsurface with the stage's size.
https://bugzilla.gnome.org/show_bug.cgi?id=754697
For foreign windows this should be dealt with by the embedding
framework. In particular on Wayland with foreign windows, we might
want to create a subsurface and use the foreign window only for events
and frame clock synchronization.
https://bugzilla.gnome.org/show_bug.cgi?id=754697
Some operations like :
* resize
* show/hide
* set_title
* set_user_resizable
should be handled by the embedding framework, so disable them for
foreign windows.
https://bugzilla.gnome.org/show_bug.cgi?id=754671
When using Clutter embed inside a Gtk application, a stage might end
up realized but not visible. In this case we might discard doing any
kind of animation processing.
https://bugzilla.gnome.org/show_bug.cgi?id=754671
Just like GtkGrid, changing the orientation of a ClutterGridLayout does
not change the existing layout; the orientation property is only used as
a hint when adding new children.
We automatically switch the request mode of the container depending on
the GridLayout's orientation, but we need to keep track of the request
mode during allocation, so that we don't get out of sync if the user
changed the request mode after adding the layout manager.
This change also brings us closer to the code in GtkGrid.
We use the orientation of the grid to get the preferred size of the
layout, but we should be using the orientation of the request instead.
The preferred width has an orizontal orientation, and the preferred
height has a vertical orientation.
This allows us to refactor the get_preferred_* implementation into a
separate function.
We are currently using deprecated/Clutter-specific API in Cogl to
retrieve the XVisualInfo associated with the (E)GLX context. Cogl 1.21.2
added new CoglRenderer API to achieve the same result.
We want to use the Cogl GL3 driver, if possible, and then go through a
known list of Cogl drivers, before giving up and using COGL_DRIVER_ANY.
Based on original patch from Emmanuele Bassi.
We have to create and tear down the whole context when trying
out the drivers though because the extension checks do not happen
until cogl_context_init.
https://bugzilla.gnome.org/show_bug.cgi?id=742678
The ClutterX11XInputEventTypes enumeration has been unused inside
Clutter for the past 4 years and a half, since we switched to the
XInput 2 API.
The enumeration itself has always been private, and nobody should
have used it in the first place, but if something breaks, we can
revert this commit.
They should be part of the backend-specific API.
The only backend that has an enumeration type is the X11 one, and it's
small, so we can simply put it there.
This is not an ABI change: the backend-specific symbols are still in
the same SO. You'll be required to import clutter-x11.h to have access
to the GType method at the source level, whereas before just importing
clutter.h would have sufficed. The only user of that enumeration was a
function declared in clutter-x11.h, anyway.
We're inconsistently using the NAMESPACE variable instead of passing
the --identifier-prefix and --symbol-prefix command line arguments to
the introspection scanner.
Now that we can warn about deprecated macros, we should finally do it
for the old, non-namespaced key symbol macros that we've been stringing
along since the 1.0 days.
We want to be able to deprecate macros, but right now the best we can do
is to wrap them with things like:
#ifndef CLUTTER_DISABLE_DEPRECATED
# define A_MACRO_I_WANT_TO_DEPRECATE ...
#endif
Which requires adding a new symbol to the build, and will cause a build
error instead of a compiler/pre-processor warning.
Fortunately, we can use the _Pragma() keyword introduced by C99 and
supported by GCC to add a warning to the output, while leaving the macro
itself intact.
GCC does not have a "deprecated" pragma, so we have to use a generic
warning; this also means we cannot do nifty things like concatenating
strings and the like, as we do for the "deprecated" attribute.
The macro deprecation symbol should have the same affordances as the
function deprecation one, and evaluate to nothing if the required
version is lower than the current version; or if the global toggle for
deprecation warnings is in effect.
We now have ClutterTouchpadPinchEvent and ClutterTouchpadSwipeEvent,
each bringing the necessary info for the specific gesture. Each
of these events is defined by begin/update/end/cancel phases.
These events have been also made to propagate down/up the pointer
position, just like scroll and button events do.
When binding models to actors to map items to children we don't often
need the full control of a function; in many cases we just need to
specify the type of the child we want to construct and the properties
on both the item and the child that we want to bind.
We should provide a simple convenience function that does all this for
us.
The whole of ClutterBackend is a final/protected type, so having a bunch
of instance fields and an instance private data structure is redundant
at best, and less efficient at worst.
GCC has some optimization for the inclusion guard, but they only work if
the check is the outermost one.
We're fairly inconsistent because of historical reasons, so we should
ensure that we follow the same pattern in every public header.
Use double precision floats for the intermediate computations, to avoid
loss of precision, and don't convert too integer when unnecessary, to
avoid rounding errors.
It can be useful to bind the children list to set of objects inside a
GListModel implementation; the GListModel stores the objects, and every
time the model changes, a function is called that maps each object in
the model to a newly created ClutterActor, which is then added as a
child. This API, along with the property binding one inside GObject,
allows automatic creation of views based on object models that update
themselves without manual intervention.
The model API was an ad hoc addition to Clutter, back in the 0.6 days,
that was needed because GLib did not offer anything of sort, and the
only model-like storage was inside GTK+. The API design was heavily
based on GtkTreeModel and friends, with column-based collections of
generic data.
Since then, the model API inside Clutter has not really been integrated
in the core API; on the other hand, GIO has grown a model API, and it's
seeing more use in the platform.
This means that the ClutterModel API should finally be deprecated, and
we should move code to the GListModel API inside GIO.
Certain crossing modes notify about synthesized events, where
the pointer didn't really leave the window. Unsetting the stage
from the device at that time is incorrect, and will leave all
remaining touches unable to pick coordinates, so silently eaten
away.
https://bugzilla.gnome.org/show_bug.cgi?id=750496
Straight from Cogl.
This allows us to propagate the GdkVisual Cogl and Clutter use to
embedding toolkits, like GTK+.
The function is annotated as being added to the 1.22 development
cycle because it will be backported to the stable branch, so that
downstream developers can package up a version of Clutter that does
not crash on nVidia.
https://bugzilla.gnome.org/show_bug.cgi?id=747489
GDK 3.16 started selecting different visuals, to best comply with the
requirements for OpenGL, and this has broken Clutter on GLX drivers that
are fairly picky in how they select visuals and GLXFBConfig.
GDK selects GLXFBConfig that do not include depth or stencil buffers;
Cogl, on the other hand, needs both depth and stencil buffers, and keeps
selecting the first available visual, assuming that the GLX driver will
give us the best compliant one, as per specification. Sadly, some
drivers will return incompatible configurations, and then bomb out when
you try to embed Clutter inside GTK+, because of mismatched visuals.
Cogl has an old, deprecated, Clutter-only API that allows us to retrieve
the XVisualInfo mapping to the GLXFBConfig it uses; this means we should
look up the GdkVisual for it when creating our own GdkWindows, instead
of relying on the RGBA and system GdkVisuals exposed by GDK — at least
on X11.
https://bugzilla.gnome.org/show_bug.cgi?id=747489
In order to do device matching we need to propagate more information,
like the device_id (only on X11 with the XInput2 extension enabled),
the vendor id, and the product id.
https://bugzilla.gnome.org/show_bug.cgi?id=747951
When defining clutter_stage_gdk_update_foreign_event_mask, check for the
same macros as when actually using it.
Signed-off-by: Dima Ryazanov <dima@gmail.com>
Reviewed-by: Emmanuele Bassi <ebassi@gnome.org>
Its ::gesture-end implementation used to check the press/release
coordinates for the first touchpoint. On multifinger swipes, we
can receive this vfunc called due to other touch sequence going
first, so we'd get 0/0 as the release coordinates for this still
active sequence, resulting in bogus directions.
Instead, check the last event coordinates, that will be always
correct regardless of whether the touchpoint 0 finished yet or
not.
https://bugzilla.gnome.org/show_bug.cgi?id=749739
Commit 79849ef1d5fff9acd310cd68d59df0c7cf2cb28f had a typo in the
device property format check. This property is formated in 8-bit
items, not 32-bit.
This went unnoticed till now because some touchpads were still being
detected as such due to a second check below:
else if (strstr (name, "touchpad") != NULL)
source = CLUTTER_TOUCHPAD_DEVICE;
https://bugzilla.gnome.org/show_bug.cgi?id=749482
It could happen that gdk_screen_get_setting fails to retreive
Gdk/WindowScalingFactor which leads to the following warnings when
clutter_init is called:
GLib-GObject-WARNING **: value "0" of type 'gint' is invalid or out of range for property 'window-scaling-factor' of type 'gint'
GLib-GObject-WARNING **: value "0" of type 'gint' is invalid or out of range for property 'dnd-drag-threshold' of type 'gint'
https://bugzilla.gnome.org/show_bug.cgi?id=749256
Slightly edited to fix up whitespace issues.
Edited-by: Emmanuele Bassi <ebassi@gnome.org>
The paint opacity for a top level is always overridden to be the full
value, since it's a composited value and we want to paint our scene.
When clearing the stage framebuffer, though, we want to use the actual
opacity, if ClutterStage:use-alpha is set.
-1 is explicitly an invalid value to pass to eglSwapBuffersWithDamage,
and the specification admits as much:
If
eglSwapBuffersWithDamageEXT is called and <n_rects>, is less
than zero or <n_rects> is greater than zero but <rects> is
NULL, EGL_BAD_PARAMETER is generated.
Fix up our usage of SwapBuffersWithDamage to match the behavior in the
EGL specification.
https://bugzilla.gnome.org/show_bug.cgi?id=745512
These are just terrible API that we've been stringing along since the
0.x days. We cannot truly deprecate them, because they are, in some
cases, the only actual API to perform some operation, and porting all
the code in the world is not going to make us any friends.
For the time being, we use a deprecation notice in the documentation.
The macros are useless for language bindings, and are terribly unsafe
from C as well. There's always the option of using the GObject
properties they refer to, but it's more efficient to just have a simple
getter function.
While each stage has at most a GdkFrameClock, the same GdkFrameClock
instance may drive multiple stages per frame. This means that the
mapping between a GdkFrameClock and a ClutterStage is a 1:M one, not a
1:1.
We should store a list of stages associated to each frame clock
instance, so that we can iterate over it when we need to update the
stages.
This commit fixes redraws of applications using multiple stages,
especially when using clutter-gtk.
_cally_actor_get_top_level_origin() uses a compile time check
without runtime check, which will obviously fail when another
backend like wayland is used.
https://bugzilla.gnome.org/show_bug.cgi?id=746575
When multiple relative motion events are received and queued, we can't
base the relative => absolute motion conversion off of the stage pointer
position, since that is only updated when the queue is processed at
the beginning of each frame. The effect of trying to use the stage
pointer position was that subsequent motion events were effectively
dropped.
To improve things, switch to keeping track of the pointer position
ourselves in the evdev backend and adding to that.
This has the side effect of making the internal function
_clutter_input_device_set_coords not effect the internal coordinate
state of the evdev stage, but AFAICS there is nothing depending on that
so that should be fine.
https://bugzilla.gnome.org/show_bug.cgi?id=746328
There's no point in trying to go ahead if we don't have a context to
create the CoglOnscreen framebuffer, and Cogl will crash anyway if we
pass NULL to the constructor.
With server-side buffer allocation, buffers may be returned out of order
(e.g. they may be held onto by external references or hardware). As such
we may see older buffers the frame after we discard the history from
seeing a very young buffer. To overcome this we want to keep the history
in a ring so we can keep track of older entries without keeping an
unbounded list. After converting to a ring, the maximum buffer age
observed during testing was 5 (expected value of 4), but before we could
see ages as high as 9 due to the huge latency spikes caused by doing full
buffer redraws (compounded by external listeners doing readback on the
damaged areas, for example vnc, drm/udl, prime). For this reason, a
maximum age of 16 was chosen to be suitably large enough to prevent these
worst cases from taxing the system.
v2: Fix off-by-one in combining the damage histroy into the clipping
rectangle, and apply copious whitespace fixes.
Bugzilla: https://bugzilla.gnome.org/show_bug.cgi?id=745512
References: https://bugzilla.gnome.org/show_bug.cgi?id=724788
References: https://bugzilla.gnome.org/show_bug.cgi?id=669122
cogl provides an interface to pass along damage with the swap buffers
request. This is useful for the display servers and hardware to minimise
the work done in updating the screen and also reducing the work done by
external listeners (such as vnc, drm/udl and PRIME).
Bugzilla: https://bugzilla.gnome.org/show_bug.cgi?id=745512
If the rectangle is allocate a size smaller than the border, drawing the
border will end up with negative coordinates, and will mess up the whole
thing. Since rectangles don't have a minimum preferred size, we cannot
rely on the allocation being big enough to contain the border and the
background color.
If the rectangle is smaller than the border width value, we just paint
the border color as well.
Point to ClutterImage, ClutterContent, and ClutterActor where needed, so
that developers trying to port their code will have a chance at figuring
out how.
Nobody has been compiling Clutter with profiling enabled in a long time.
UProf itself hasn't been updated in 5 years, and it still depends on
deprecated components like dbus-glib, with no port to GDBus in sight.
The profiling code was moderately useful in the past, but these days
it's probably better to profile Cogl than Clutter itself; timing
information can be extracted by the timestamp on each diagnostic message
that is now available by default in the CLUTTER_NOTE macro, and we can
add ad hoc counters where needed.
Add clutter_x11_set_use_stereo_stage() that can be called
before clutter_init() so that the CoglDisplay we create and all
stages created from that CoglDisplay will be created with a
stereo fbconfig.
This is done in clutter-x11 because of the similarity to the
existing clutter_x11_set_use_argb_visual(), and because it's
not clear without other examples whether the need to have
stereo enabled from before clutter_init() is universal or
somethign specific to GLX.
Cogl required version is increased to 1.20, which has the
required API.
https://bugzilla.gnome.org/show_bug.cgi?id=732706
Added support for Mir, now clutter can natively draw on MirSurfaces.
This depends on latest cogl git.
Run your clutter apps using CLUTTER_BACKEND=mir
Signed-off-by: Emmanuele Bassi <ebassi@gnome.org>
Toolkits may need to paint actors internally outside the normal tree
(for example to create a shadow shape), in which case they need to
control the opacity directly.
https://bugzilla.gnome.org/show_bug.cgi?id=677412
Signed-off-by: Emmanuele Bassi <ebassi@gnome.org>
The _clutter_stage_update_state() function is currently putting events
into the Clutter event queue. This leads to problems in the gdk
backend because there are assumptions upon the numbers of queued
events, and how many of them should be moved from the main event queue
to the ClutterStages' event queues.
This change triggers the processing of the state update events on the
stage directly, so the main event queue retains the expected number of
events.
https://bugzilla.gnome.org/show_bug.cgi?id=744604
If gdk event retrieval has been disabled and gdk's backend is wayland
we must also disable cogl's wayland event dispatching otherwise cogl
will try to dispatch wayland events itself which blocks the main
loop.
https://bugzilla.gnome.org/show_bug.cgi?id=744058
Pointer button events will be received from a device where a button has
been pressed, even though an equivalent button has been pressed (same
button code) on a device connected to the same seat. notify_button()
expects to only be called as if there was only one pointer device
associated with the given seat, so to achieve this, ignore every event
where forwarding it would result in multiple 'pressed' or 'released'
notifications.
https://bugzilla.gnome.org/show_bug.cgi?id=743615
Keyboard key events will be received from a device where a key has
been pressed, even though an equivalent key has been pressed (same
key code) on a device connected to the same seat. notify_key()
expects to only be called as if there was only one keyboard device
associated with the given seat, so to achieve this, ignore every event
where forwarding it would result in multiple 'pressed' or 'released'
notifications.
https://bugzilla.gnome.org/show_bug.cgi?id=743615
We are checking for Cairo ≥ 1.12 and then do an additional check for the
existence of the cairo_surface_set_device_scale() function because there
were no stable releases of Cairo with it. Now that Cairo 1.14 is out, we
can simply bump up the dependency.
libinput's API changed from separate scroll events for vert/horiz scrolling to
a single event that contains both axes if they changed.
Updated by Armin K. to use the discrete axis value for wheel events as done
in Weston.
https://bugzilla.gnome.org/show_bug.cgi?id=742829
We tried once with commit 398a7ac7 and ended up reverting because of
regressions in the input layer and on Wayland.
We should try again, now that those regressions have been fixed.
https://bugzilla.gnome.org/show_bug.cgi?id=734587
The easing state is part of the AnimationInfo structure, which is stored
inside the GObject's datalist. Each instance frees the data stored there
during finalization, so there is no point for us to restore an easing
state (which may or may not be the last one) just to have everything
cleared out once we chain up to GObject's own finalize() implementation.
Bind the preferred size of an actor using a BindConstraint to the
preferred size of the source of the constraint, depending on the
coordinate of the constraint.
Constraints can only update an existing allocation, which means they
live only halfway through the layout management system used by Clutter;
this limitation makes it impossible, for instance, to query the
preferred size of an actor, if the actor is only using constraints to
manage its own size.
And move the only private ClutterConstraint method to it.
This commit also sneaks in a change that makes sense for the debugging
of the update_allocation() method, which checks if the allocation was
effectively changed.
The core pointer concept doesn't really exist anymore in an XI2 world,
so the clutter API is a bit of a mismatch with what X provides. Using
XIGetClientPointer doesn't really help, as far as i can tell the
semantics of XIGetClientPointer are essentially: Whatever the X server
picked when it had to reply with device-dependant data to a query
without a device specifier. Not very useful...
To make matters worse, whether XIGetClientPointer returns a valid
pointer depends on whether there has been a query that forced it to pick
one in the first place, making the whole thing pretty non-deterministic.
This patch changes things around such that instead of using
XIGetClientPointer to determine the core pointer, we simply pick the
first master pointer device. In practise this will essentially always
be the X virtual core pointer.
https://bugzilla.gnome.org/show_bug.cgi?id=729462
XIGetClientPointer() may return the device id '0' when called early.
This patch makes pointer cursors work in nested mutter Wayland
sessions again.
https://bugzilla.gnome.org/show_bug.cgi?id=729462
The installed header should not have private API declarations and
macros. Let's move those into the uninstalled clutter-backend-osx.h
header file instead.
When merging multiple definitions it's possible that the ObjectInfo
fields may get overwritten. Instead of trampling over the fields, we
should reset them only when they actually change — especially the
"is_actor" one, which controls the destruction of the objects when
unmerging happens.
https://bugzilla.gnome.org/show_bug.cgi?id=669743
We want to recompute the content box when changing the content instance,
in case the preferred size is different and the content gravity uses the
preferred size; the change of content with different preferred size and
same gravity should also trigger an implicit transition.
https://bugzilla.gnome.org/show_bug.cgi?id=711182
Some actors want to have a preferred size driven by their content, not
by their children or by their fixed size.
In order to achieve that, we can extend the ClutterRequestMode
enumeration so that clutter_actor_get_preferred_size() defers to the
ClutterContent's own preferred size.
https://bugzilla.gnome.org/show_bug.cgi?id=676326
An easing mode can be set on a frame of a KeyframeTransition.
However, the progress value of the current frame is computed using using
a linear function.
This patch adds a call to clutter_easing_for_mode() to compute
the actual progress value.
Note that parametrized easing modes (bezier and 'step') are not taken
into account.
https://bugzilla.gnome.org/show_bug.cgi?id=740997
If a touchpad is not multitouch, or does not report MT axes (eg. through
the libinput driver), resort to name matching before falling back to
CLUTTER_POINTER_DEVICE.
https://bugzilla.gnome.org/show_bug.cgi?id=741350
In keyboard/mouse wireless combos, it is rather common for the mouse to
claim it contains the multimedia keys, this makes libinput enable both
the pointer and keyboard capabilities on this device, and Clutter thus
to create a keyboard ClutterInputDevice for it.
Ideally clutter devices should be able to reflect their full capabilities,
or maybe account for the fact that certain events can be sent from
seemingly unexpected device types. But this will bring a somewhat better
behavior on such devices.
https://bugzilla.gnome.org/show_bug.cgi?id=740518
Atlasing is fine for smaller textures, but once they get too large its
downsides outweight the benefits. At worst, the larger texture will end
up inside its own atlas, but at worst it will require copying and/or
resizing of an existing atlas.
The cut-off at 512x512 pixels is a bit arbitrary, and we can change it
at any point; it would be nice if we could get the texture limit from
Cogl, and then use a fraction of that size as the cut-off limit. Sadly,
that's not portable, and it's not guaranteed to work either.
For a variety of complicated reasons, ClutterText currently sets fields
on the PangoContext when creating a layout. This causes ClutterText to
behave somewhat erratically in certain cases, since the PangoContext is
currently shared between all actors.
GTK+ creates a PangoContext for every single GtkWidget, so it seems like
we should do the same here.
Move the private code that was previously in clutter-main.c into
clutter-actor.c and clean it up a bit. This gives every actor its own
PangoContext it can mutilate whenever it wants, at its heart's content.
https://bugzilla.gnome.org/show_bug.cgi?id=739050
clutter_set_font_flags already calls clutter_backend_set_font_options,
which emits a signal which our PangoContext listens to, so this is just
duplicate and unneeded code.
https://bugzilla.gnome.org/show_bug.cgi?id=739050
libinput_suspend() will trigger the removal of input devices, but also
the emission of button/key releases pairing everything that is pressed
at that moment. These events are queued, but the ClutterInputDevice
pointers in these will point to invalid memory at the time these are
processed.
Fix this by flushing the event queue, in order to ensure there are no
unprocessed input events after libinput_suspend().
https://bugzilla.gnome.org/show_bug.cgi?id=738520
Just like unmapped children.
Apparently, layers above Clutter allow mapped children without an
allocation, instead of unmapping them. This means we need to ignore
them when computing the paint volume.
Patch originally by: Adel Gadllah <adel.gadllah@gmail.com>
Signed-off by: Emmanuele Bassi <ebassi@gnome.org>
https://bugzilla.gnome.org/show_bug.cgi?id=736682
To support sub-pixel motion events coming from relative events, the
fraction part needs to be stored in the input device state as well. To
do this, simply change the current type from gint to gfloat.
https://bugzilla.gnome.org/show_bug.cgi?id=736413
If gtk_init is called after clutter_init, it can override clutter
AtkUtil implementation. In that situation, we can't say that
the accessibility is enabled, as the root object would be wrong.
In order to provide a way to prevent this:
* clutter_get_accessibility_enabled returns true of false
depending on the current AtkUtil implemented
* cally_accessibility_init always override AtkUtil implementation.
The get_threshold_tigger_egde() method was renamed to fix the typo, but
it obviously broke the ABI. To be fair, nobody in the whole of Debian
was using the symbol, apparently, so it's not like we broke existing
code. Still, it's not nice to break ABI without bumping soname, so let's
put the old symbol back in — obviously, deprecated — as a wrapper to the
newly added one.
If the device manager is created and queried for the client pointer at
a very early stage in application lifetime, the device_id returned would
be 0 as the server hasn't apparently decided yet about the client pointer.
For these situations, doing XSync prior to fetching the client pointer
gets the server to device about the client pointer before we query it.
https://bugzilla.gnome.org/show_bug.cgi?id=735388
When an application sets the scaling factor manually we should mark it as fixed
and not override it when the xsettings change. This matches GDKs behaviour.
In order for this to work we cannot use the same path when setting the value
internally so introduce a _clutter_settings_set_property_internal and use it
for that.
https://bugzilla.gnome.org/show_bug.cgi?id=735244
We need to release the temporary reference we acquired in order for the
signal emission to work.
https://bugzilla.gnome.org/show_bug.cgi?id=734761
Signed-off-by: Emmanuele Bassi <ebassi@gnome.org>
This reverts commit 398a7ac713.
We cannot really use the GDK backend without massive regressions inside
the input layer, like touch events and gestures. The GDK backend is not
entirely up to scratch, and it's late in the cycle.
Let's land this early in 3.15, and get it up to par with X11.
Quite a few people at Guadec complained of pinpoint being broken in
speaker+fullscreen mode, with slides being half displayed. It turns
out that the X11 backend of clutter was being used and this backend
assumes the size of the current monitor is the size of the X screen
(that's not the case with multiple monitors).
To work around the shortcomings of the X11 backend we should probably
position the GDK one before. GDK implements most of the logic the
ClutterStage needs and is probably more tested.
https://bugzilla.gnome.org/show_bug.cgi?id=734587
To get correct premultiplied opacity on a canvas content, white needs
to be assigned to the color that is passed to the texture node. The
content will be very dark for lower opacity values otherwise.
https://bugzilla.gnome.org/show_bug.cgi?id=733385
xkb_state creation has been refactored out of clutter_evdev_set_keyboard_map(),
and used too in clutter_evdev_reclaim_devices(), so the xkb_state is fresh
clean after input is paused/resumed (and keyboard state possibly changed in
between)
https://bugzilla.gnome.org/show_bug.cgi?id=733562
There may be odd situations where full gesture cancellation may be wanted at once
when the first touch is lifted and ::gesture-end is emitted on a gesture action.
Although calling clutter_gesture_action_cancel() within the ::gesture-end handler
causes 2 critical warnings that are otherwise harmless.
https://bugzilla.gnome.org/show_bug.cgi?id=732907
clutter_stage_set_paint_callback() has the disadvantage that it only
works for a single caller, and subsequent callers will overwrite and
break previous callers. Replace it with an ::after-paint signal that is
emitted at the same point - after all painting for the stage is
completed but before the drawing is presented to the screen.
https://bugzilla.gnome.org/show_bug.cgi?id=732342
CLUTTER_ENTER/LEAVE might be processed too, leading to accounting of the
NULL sequence (ie. pointer) in the gesture, and fooling the gesture with
a static extra point that wouldn't go away.
https://bugzilla.gnome.org/show_bug.cgi?id=732235
Until now, touch events sort of rely on XI_Enter/XI_Leave events accompanying
the pointer emulating touch in order to have a stage set on the device, These
events won't happen though if it's not a pointer emulating touch which happens
on the stage, causing touch events to be ignored.
Fix this by ensuring that the input device has a stage on XI_TouchBegin itself,
but only if it's not already set, so we don't possibly steal touch events to
an already interacting stage.
https://bugzilla.gnome.org/show_bug.cgi?id=732234
On X11 the pointer will follow a "pointer emulating" touch sequence, so the
pointer will be effectively left inside the stage after that touch is lifted,
even though the master device stage is unset. This makes pointer events get
ignored until the pointer leaves and enters again the stage.
https://bugzilla.gnome.org/show_bug.cgi?id=732234
The 'state' field should be used for pointer events without button
information. Pointer events that have button information should use
the 'button' field.
https://bugzilla.gnome.org/show_bug.cgi?id=732143
The coordinates translated by the XI2 device manager were being clamped using
the X window size kept by StageX11. However, when the stage is fullscreen,
that size is not updated to the screen size, but kept the same in order to
allow going back to it when the stage goes out of fullscreen.
https://bugzilla.gnome.org/show_bug.cgi?id=731268
The vector of libinput and Wayland pointer axis events are in pointer
motion coordinate space. To convert to clutter's internal representation
the vectors need to be scaled to Xi2 scroll steps.
https://bugzilla.gnome.org/show_bug.cgi?id=723560
And get CLUTTER_EVENT_LEAVE out of the touch event compression logic, as
touches are always implicitly grabbed. If no sequence check is done, only
the last touch update would be emitted, even if multiple sequences got
updated.
https://bugzilla.gnome.org/show_bug.cgi?id=730577
Let's cross fingers and hope nobody notices. If this went unnoticed so far, likely
means this function has never been used. If any complain is raised about this, a
stub function should be added (and marked deprecated).
