From 9db9793f336c66ceb40c7a46d0cff21d9c6ec010 Mon Sep 17 00:00:00 2001 From: Daniel van Vugt Date: Fri, 31 Aug 2018 15:11:54 +0800 Subject: [PATCH] clutter: Clarify clutter_stage_get_actor_at_pos docs When a user moves their cursor the perceived behaviour is that it will pick what is under the cursor. However this isn't how picking works. Picking does a virtual redraw of the screen, so in some cases what gets picked isn't the same as what the user could see on the previous frame. It more represents what will be drawn on the next frame than what is on screen at present. It may be unsafe to change these semantics, and they are useful anyway. Just document it better. https://gitlab.gnome.org/GNOME/mutter/merge_requests/214 --- clutter/clutter/clutter-stage.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/clutter/clutter/clutter-stage.c b/clutter/clutter/clutter-stage.c index 0975f2f90..f5189c5c8 100644 --- a/clutter/clutter/clutter-stage.c +++ b/clutter/clutter/clutter-stage.c @@ -3031,7 +3031,11 @@ clutter_stage_read_pixels (ClutterStage *stage, * @y: Y coordinate to check * * Checks the scene at the coordinates @x and @y and returns a pointer - * to the #ClutterActor at those coordinates. + * to the #ClutterActor at those coordinates. The result is the actor which + * would be at the specified location on the next redraw, and is not + * necessarily that which was there on the previous redraw. This allows the + * function to perform chronologically correctly after any queued changes to + * the scene, and even if nothing has been drawn. * * By using @pick_mode it is possible to control which actors will be * painted and thus available.