[vlc-devel] [PATCH v3 03/10] vout_window: add visibility reporting callbacks

[Alexandre Janniaux]

Those callbacks are meant to be used by vout_window implementations in
environment where the rendering is constrained by the application state.

The design case for those events is iOS where application must not draw
onto its surface when they have been moved to the background, but it
should be generalizable to every cases where the window is in a state
such as no more rendering is needed for it, like in Wayland when the
window is not visible anymore.

To handle these other cases, the reporting function might need to also
report a callback and better handle state change to notify the callback
when the application is back to be visible and has drawn something. This
is currently not implemented for iOS, so not done.
---
 include/vlc_vout_window.h | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/include/vlc_vout_window.h b/include/vlc_vout_window.h
index ea16d4b414..6e492ce0bd 100644
--- a/include/vlc_vout_window.h
+++ b/include/vlc_vout_window.h
@@ -78,6 +78,16 @@ enum vout_window_state {
     VOUT_WINDOW_STATE_BELOW /**< Stacking below (a.k.a. wall paper mode) */,
 };
 
+/**
+ * Window visibility state.
+ *
+ * See also \ref vout_window_ReportVisibilityChanged.
+ */
+enum vout_window_visibility {
+    VOUT_WINDOW_VISIBLE,
+    VOUT_WINDOW_NOT_VISIBLE
+};
+
 /**
  * Window mouse event types.
  *
@@ -289,6 +299,21 @@ struct vout_window_callbacks {
      */
     void (*output_event)(struct vout_window_t *,
                          const char *id, const char *desc);
+
+    /**
+     * Callback for window visibility signalling.
+     *
+     * This callback function (if non-NULL) signals that the window is not
+     * visible anymore and should not be used for rendering after the end of
+     * this function until it is visible again. Typicaly use case of this event
+     * is when the application has been moved to the background and should not
+     * draw anything, or when the frames being sent to the display won't be
+     * used to display anyhting.
+     *
+     * \param visibility the new visibility state of the window
+     */
+    void (*visibility_changed)(struct vout_window_t *,
+                               enum vout_window_visibility visibility);
 };
 
 /**
@@ -692,5 +717,13 @@ static inline void vout_window_ReportOutputDevice(vout_window_t *window,
         window->owner.cbs->output_event(window, id, name);
 }
 
+static inline void
+vout_window_ReportVisibilityChanged(vout_window_t *window,
+                                    enum vout_window_visibility visibility)
+{
+    if (window->owner.cbs->visibility_changed != NULL)
+        window->owner.cbs->visibility_changed(window, visibility);
+}
+
 /** @} */
 #endif /* VLC_VOUT_WINDOW_H */
-- 
2.30.1