[PATCH 2/2] compositor: Document routines relating to idle behavior

[Pekka Paalanen]

Hi Bryce

On Fri, 11 Dec 2015 13:11:38 -0800
Bryce Harrington <bryce at osg.samsung.com> wrote:

> Signed-off-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
>  src/compositor.c | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 46 insertions(+)
> 
> diff --git a/src/compositor.c b/src/compositor.c
> index 254e9e4..3e1f588 100644
> --- a/src/compositor.c
> +++ b/src/compositor.c
> @@ -3817,6 +3817,11 @@ bind_subcompositor(struct wl_client *client,
>  				       compositor, NULL);
>  }
>  
> +/** Set a DPMS mode on all of the compositor's outputs
> + *
> + * \param compositor The compositor instance
> + * \param state The DPMS state the outputs will be set to
> + */

Ok.

>  static void
>  weston_compositor_dpms(struct weston_compositor *compositor,
>  		       enum dpms_enum state)
> @@ -3828,6 +3833,17 @@ weston_compositor_dpms(struct weston_compositor *compositor,
>  			output->set_dpms(output, state);
>  }
>  
> +/** Restores the compositor to active status
> + *
> + * \param compositor The compositor instance
> + *
> + * If the compositor was in a sleeping mode, all outputs are powered
> + * back on via DPMS.  Otherwise if the compositor was inactive
> + * (idle/locked, offscreen, or sleeping) then the compositor's wake
> + * signal will fire.
> + *
> + * Resets the idle timer by one second.

Should be: Restarts the idle timer.

> + */
>  WL_EXPORT void
>  weston_compositor_wake(struct weston_compositor *compositor)
>  {
> @@ -3852,6 +3868,17 @@ weston_compositor_wake(struct weston_compositor *compositor)
>  	}
>  }
>  
> +/** Turns off rendering and frame events for the compositor.
> + *
> + * \param compositor The compositor instance
> + *
> + * This is used for example to prevent further rendering while the
> + * compositor is shutting down.
> + *

Add: Stops the idle timer.

Checking the call sites of this function, this seems to be mostly used
when VT-switching away. The shutdown-path is good to mention because
it's not calling this function but still uses offscreen mode.

> + * \note When offscreen state is entered, outputs will be powered
> + * back on if they were sleeping (in DPMS off mode), even though
> + * no rendering will be performed.
> + */
>  WL_EXPORT void
>  weston_compositor_offscreen(struct weston_compositor *compositor)
>  {
> @@ -3867,6 +3894,14 @@ weston_compositor_offscreen(struct weston_compositor *compositor)
>  	}
>  }
>  
> +/** Powers down all attached output devices
> + *
> + * \param compositor The compositor instance
> + *

Add: Stops the idle timer.

> + * Causes rendering to the outputs to cease, and no frame events to be
> + * sent.  Only powers down the outputs if the compositor is not already
> + * in sleep mode.
> + */
>  WL_EXPORT void
>  weston_compositor_sleep(struct weston_compositor *compositor)
>  {
> @@ -3878,6 +3913,17 @@ weston_compositor_sleep(struct weston_compositor *compositor)
>  	weston_compositor_dpms(compositor, WESTON_DPMS_OFF);
>  }
>  
> +/** Sets compositor to idle mode
> + *
> + * \param data The compositor instance
> + *

Add: This is called by the idle timer firing.

> + * Once the compositor is in idle mode it requires a wake action
> + * (e.g. via weston_compositor_wake()) to restore it.  The compositor's
> + * idle_signal will be triggered when the idle event occurs.
> + *
> + * Idleness can be inhibited by setting the compositor's idle_inhibit
> + * property.
> + */
>  static int
>  idle_handler(void *data)
>  {

Looks good, no factual errors except that "one second". The other
comments are just adding detail.

With these or equivalent changes:
Reviewed-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20151222/5fb35b9a/attachment.sig>