output, output_damage: add docs

This commit is contained in:
emersion 2018-02-11 13:04:00 +01:00
parent ec837e3c9e
commit 5a8f098eea
No known key found for this signature in database
GPG key ID: 0FDE7BE0E88F5E48
2 changed files with 37 additions and 0 deletions

View file

@ -38,6 +38,15 @@ struct wlr_output_cursor {
struct wlr_output_impl; 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 { struct wlr_output {
const struct wlr_output_impl *impl; const struct wlr_output_impl *impl;
struct wlr_backend *backend; struct wlr_backend *backend;

View file

@ -10,6 +10,14 @@
*/ */
#define WLR_OUTPUT_DAMAGE_PREVIOUS_LEN 2 #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_damage {
struct wlr_output *output; struct wlr_output *output;
@ -32,13 +40,33 @@ struct wlr_output_damage {
struct wlr_output_damage *wlr_output_damage_create(struct wlr_output *output); struct wlr_output_damage *wlr_output_damage_create(struct wlr_output *output);
void wlr_output_damage_destroy(struct wlr_output_damage *output_damage); 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 wlr_output_damage_make_current(struct wlr_output_damage *output_damage,
bool *needs_swap, pixman_region32_t *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, bool wlr_output_damage_swap_buffers(struct wlr_output_damage *output_damage,
struct timespec *when, pixman_region32_t *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, void wlr_output_damage_add(struct wlr_output_damage *output_damage,
pixman_region32_t *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); 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, void wlr_output_damage_add_box(struct wlr_output_damage *output_damage,
struct wlr_box *box); struct wlr_box *box);