From 0a32c81d9c3764c6732bfdc1640ebe676eefcb2c Mon Sep 17 00:00:00 2001 From: Yuxuan Shui Date: Sat, 16 Mar 2019 20:53:36 +0000 Subject: [PATCH] backend interface: improve documentation --- src/backend/backend.h | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/src/backend/backend.h b/src/backend/backend.h index 9d7871a..6c95678 100644 --- a/src/backend/backend.h +++ b/src/backend/backend.h @@ -47,20 +47,24 @@ struct backend_operations { /// Here is how you should choose target window: /// 1) if ps->overlay is not XCB_NONE, use that /// 2) use ps->root otherwise - /// XXX make the target window a parameter + /// TODO make the target window a parameter backend_t *(*init)(session_t *) attr_nonnull(1); - void (*deinit)(backend_t *backend_data) __attribute__((nonnull(1))); + void (*deinit)(backend_t *backend_data) attr_nonnull(1); /// Called when rendering will be stopped for an unknown amount of /// time (e.g. screen is unredirected). Free some resources. + /// + /// Optional, not yet used void (*pause)(backend_t *backend_data, session_t *ps); /// Called before rendering is resumed + /// + /// Optional, not yet used void (*resume)(backend_t *backend_data, session_t *ps); /// Called when root property changed, returns the new /// backend_data. Even if the backend_data changed, all - /// the existing win_data returned by prepare_win should + /// the existing image data returned by this backend should /// remain valid. /// /// Optional @@ -68,10 +72,7 @@ struct backend_operations { // =========== Rendering ============ - /// Called before any compose() calls. - /// - /// Usually the backend should clear the buffer, or paint a background - /// on the buffer (usually the wallpaper). + /// Called before when a new frame starts. /// /// Optional void (*prepare)(backend_t *backend_data, const region_t *reg_damage); @@ -93,15 +94,13 @@ struct backend_operations { void (*fill)(backend_t *backend_data, double r, double g, double b, double a, const region_t *clip); - /// Blur a given region on of the target. + /// Blur a given region of the target. bool (*blur)(backend_t *backend_data, double opacity, const region_t *reg_blur, const region_t *reg_visible) attr_nonnull(1, 3, 4); - /// Present the buffered target picture onto the screen. If target - /// is not buffered, this should be NULL. Otherwise, it should always - /// be non-NULL. + /// Present the back buffer onto the screen. /// - /// Optional + /// Optional if the screen is not buffered void (*present)(backend_t *backend_data) attr_nonnull(1); /** @@ -117,6 +116,7 @@ struct backend_operations { struct xvisual_info fmt, bool owned); /// Create a shadow image based on the parameters + /// Default implementation: default_backend_render_shadow void *(*render_shadow)(backend_t *backend_data, int width, int height, const conv *kernel, double r, double g, double b, double a); @@ -134,12 +134,11 @@ struct backend_operations { // =========== Query =========== - /// Return if a window has transparent content. Guaranteed to only - /// be called after render_win is called. + /// Return if image is not completely opaque. /// /// This function is needed because some backend might change the content of the - /// window (e.g. when using a custom shader with the glx backend), so we only now - /// the transparency after the window is rendered + /// window (e.g. when using a custom shader with the glx backend), so only the + /// backend knows if an image is transparent. bool (*is_image_transparent)(backend_t *backend_data, void *image_data) attr_nonnull(1, 2); @@ -147,6 +146,8 @@ struct backend_operations { /// of. The buffer that has just been `present`ed has a buffer age of 1. /// Everytime `present` is called, buffers get older. Return -1 if the /// buffer is empty. + /// + /// Optional int (*buffer_age)(backend_t *backend_data); /// The maximum number buffer_age might return.