From 5a8f098eea1637213d29a6ec831bcebc11c92aaa Mon Sep 17 00:00:00 2001 From: emersion Date: Sun, 11 Feb 2018 13:04:00 +0100 Subject: output, output_damage: add docs --- include/wlr/types/wlr_output.h | 9 +++++++++ include/wlr/types/wlr_output_damage.h | 28 ++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/include/wlr/types/wlr_output.h b/include/wlr/types/wlr_output.h index a653d527..8eed06fe 100644 --- a/include/wlr/types/wlr_output.h +++ b/include/wlr/types/wlr_output.h @@ -38,6 +38,15 @@ struct wlr_output_cursor { struct wlr_output_impl; +/** + * A compositor output region. This typically corresponds to a monitor that + * displays part of the compositor space. + * + * Compositors should listen to the `frame` event to render an output. They + * should call `wlr_output_make_current`, render and then call + * `wlr_output_swap_buffers`. No rendering should happen outside a `frame` event + * handler. + */ struct wlr_output { const struct wlr_output_impl *impl; struct wlr_backend *backend; diff --git a/include/wlr/types/wlr_output_damage.h b/include/wlr/types/wlr_output_damage.h index eadbff29..ec5fcd0d 100644 --- a/include/wlr/types/wlr_output_damage.h +++ b/include/wlr/types/wlr_output_damage.h @@ -10,6 +10,14 @@ */ #define WLR_OUTPUT_DAMAGE_PREVIOUS_LEN 2 +/** + * Tracks damage for an output. + * + * When a `frame` event is emitted, `wlr_output_damage_make_current` should be + * called. If necessary, the output should be repainted and + * `wlr_output_damage_swap_buffers` should be called. No rendering should happen + * outside a `frame` event handler. + */ struct wlr_output_damage { struct wlr_output *output; @@ -32,13 +40,33 @@ struct wlr_output_damage { struct wlr_output_damage *wlr_output_damage_create(struct wlr_output *output); void wlr_output_damage_destroy(struct wlr_output_damage *output_damage); +/** + * Makes the output rendering context current. `needs_swap` is set to true if + * `wlr_output_damage_swap_buffers` needs to be called. The region of the output + * that needs to be repainted is added to `damage`. + */ bool wlr_output_damage_make_current(struct wlr_output_damage *output_damage, bool *needs_swap, pixman_region32_t *damage); +/** + * Swaps the output buffers. If the time of the frame isn't known, set `when` to + * NULL. + * + * Swapping buffers schedules a `frame` event. + */ bool wlr_output_damage_swap_buffers(struct wlr_output_damage *output_damage, struct timespec *when, pixman_region32_t *damage); +/** + * Accumulates damage and schedules a `frame` event. + */ void wlr_output_damage_add(struct wlr_output_damage *output_damage, pixman_region32_t *damage); +/** + * Damages the whole output and schedules a `frame` event. + */ void wlr_output_damage_add_whole(struct wlr_output_damage *output_damage); +/** + * Accumulates damage from a box and schedules a `frame` event. + */ void wlr_output_damage_add_box(struct wlr_output_damage *output_damage, struct wlr_box *box); -- cgit v1.2.3