aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoremersion <contact@emersion.fr>2018-02-11 13:04:00 +0100
committeremersion <contact@emersion.fr>2018-02-11 13:04:00 +0100
commit5a8f098eea1637213d29a6ec831bcebc11c92aaa (patch)
tree6f31633cb5ecc8ef290b190736569c25e8d0a312
parentec837e3c9e08a8334fa7093d7f39af2a2f11e122 (diff)
output, output_damage: add docs
-rw-r--r--include/wlr/types/wlr_output.h9
-rw-r--r--include/wlr/types/wlr_output_damage.h28
2 files changed, 37 insertions, 0 deletions
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);