aboutsummaryrefslogtreecommitdiff
path: root/include
diff options
context:
space:
mode:
authorSimon Ser <contact@emersion.fr>2020-06-19 17:44:32 +0200
committerDrew DeVault <sir@cmpwn.com>2020-06-30 08:03:58 -0600
commitc611a8f7e7df7a10b434500760dfbcfdf2817413 (patch)
tree839309ff9ec5cc52836549944756cc3453d2331f /include
parent45c0877e3433f2b057f9125a8bc735057e088e6c (diff)
output: add backend docs
Diffstat (limited to 'include')
-rw-r--r--include/wlr/interfaces/wlr_output.h99
1 files changed, 98 insertions, 1 deletions
diff --git a/include/wlr/interfaces/wlr_output.h b/include/wlr/interfaces/wlr_output.h
index 13c9e6dc..6d8da2a5 100644
--- a/include/wlr/interfaces/wlr_output.h
+++ b/include/wlr/interfaces/wlr_output.h
@@ -14,31 +14,128 @@
#include <wlr/types/wlr_box.h>
#include <wlr/types/wlr_output.h>
+/**
+ * A backend implementation of wlr_output.
+ *
+ * The functions commit, attach_render and rollback_render are mandatory. Other
+ * functions are optional.
+ */
struct wlr_output_impl {
+ /**
+ * Set the output cursor plane image.
+ *
+ * The parameters describe the image texture, its scale and its transform.
+ * If the scale and transform doesn't match the output's, the backend is
+ * responsible for scaling and transforming the texture appropriately.
+ * If texture is NULL, the cursor should be hidden.
+ *
+ * The hotspot indicates the offset that needs to be applied to the
+ * top-left corner of the image to match the cursor position. In other
+ * words, the image should be displayed at (x - hotspot_x, y - hotspot_y).
+ *
+ * If update_texture is true, all parameters need to be taken into account.
+ * If update_texture is false, only the hotspot is to be updated.
+ */
bool (*set_cursor)(struct wlr_output *output, struct wlr_texture *texture,
float scale, enum wl_output_transform transform,
int32_t hotspot_x, int32_t hotspot_y, bool update_texture);
+ /**
+ * Set the output cursor plane position.
+ *
+ * The position is relative to the cursor hotspot, see set_cursor.
+ */
bool (*move_cursor)(struct wlr_output *output, int x, int y);
+ /**
+ * Cleanup backend-specific resources tied to the output.
+ */
void (*destroy)(struct wlr_output *output);
+ /**
+ * Make the output's back-buffer current for the renderer.
+ *
+ * buffer_age must be set to the buffer age in number of frames, or -1 if
+ * unknown.
+ */
bool (*attach_render)(struct wlr_output *output, int *buffer_age);
+ /**
+ * Unset the current renderer's buffer.
+ *
+ * This is the opposite of attach_render.
+ */
+ void (*rollback_render)(struct wlr_output *output);
+ /**
+ * Check that the pending output state is a valid configuration.
+ *
+ * If this function returns true, commit can only fail due to a runtime
+ * error.
+ */
bool (*test)(struct wlr_output *output);
+ /**
+ * Commit the pending output state.
+ *
+ * If a buffer has been attached, a frame event is scheduled.
+ */
bool (*commit)(struct wlr_output *output);
- void (*rollback_render)(struct wlr_output *output);
+ /**
+ * Get the maximum number of gamma LUT elements for each channel.
+ *
+ * Zero can be returned if the output doesn't support gamma LUTs.
+ */
size_t (*get_gamma_size)(struct wlr_output *output);
+ /**
+ * Export the output's current back-buffer as a DMA-BUF.
+ */
bool (*export_dmabuf)(struct wlr_output *output,
struct wlr_dmabuf_attributes *attribs);
};
+/**
+ * Initialize a new output.
+ */
void wlr_output_init(struct wlr_output *output, struct wlr_backend *backend,
const struct wlr_output_impl *impl, struct wl_display *display);
+/**
+ * Update the current output mode.
+ *
+ * The backend must call this function when the mode is updated to notify
+ * compositors about the change.
+ */
void wlr_output_update_mode(struct wlr_output *output,
struct wlr_output_mode *mode);
+/**
+ * Update the current output custom mode.
+ *
+ * The backend must call this function when the mode is updated to notify
+ * compositors about the change.
+ */
void wlr_output_update_custom_mode(struct wlr_output *output, int32_t width,
int32_t height, int32_t refresh);
+/**
+ * Update the current output status.
+ *
+ * The backend must call this function when the status is updated to notify
+ * compositors about the change.
+ */
void wlr_output_update_enabled(struct wlr_output *output, bool enabled);
+/**
+ * Notify compositors that they need to submit a new frame in order to apply
+ * output changes.
+ */
void wlr_output_update_needs_frame(struct wlr_output *output);
+/**
+ * Notify compositors that the output needs to be fully repainted.
+ */
void wlr_output_damage_whole(struct wlr_output *output);
+/**
+ * Send a frame event.
+ *
+ * See wlr_output.events.frame.
+ */
void wlr_output_send_frame(struct wlr_output *output);
+/**
+ * Send a present event.
+ *
+ * See wlr_output.events.present.
+ */
void wlr_output_send_present(struct wlr_output *output,
struct wlr_output_event_present *event);