commit 0c8be16

view: Add some documentation

  1@@ -42,6 +42,12 @@ enum
  2     SWC_VIEW_EVENT_SCREENS_CHANGED
  3 };
  4 
  5+/**
  6+ * This structure contains data sent along with a view's events.
  7+ *
  8+ * Extra data correspending to the particular event is stored in the
  9+ * corresponding struct inside the union.
 10+ */
 11 struct swc_view_event_data
 12 {
 13     struct swc_view * view;
 14@@ -59,6 +65,18 @@ struct swc_view_event_data
 15     };
 16 };
 17 
 18+/**
 19+ * A view represents a component that can display buffers to the user.
 20+ *
 21+ * For example, each output contains a view residing in its framebuffer plane
 22+ * that is used to scan out buffers. Additionally, the compositor creates views
 23+ * dynamically for each surface it displays, compositing them into a single
 24+ * buffer, which it can then attach to the previously mentioned view.
 25+ *
 26+ * This abstraction allows various components of swc to connect in a general
 27+ * way, allowing operations like setting the output view of a surface directly
 28+ * to an output's framebuffer plane, bypassing the compositor.
 29+ */
 30 struct swc_view
 31 {
 32     const struct swc_view_impl * impl;
 33@@ -72,28 +90,76 @@ struct swc_view
 34     struct wl_listener buffer_destroy_listener;
 35 };
 36 
 37+/**
 38+ * Every view must have an implementation containing these functions.
 39+ *
 40+ * For descriptions, see the corresponding swc_view_* function.
 41+ */
 42 struct swc_view_impl
 43 {
 44-    /* Called when the view should present a new frame. */
 45     bool (* update)(struct swc_view * view);
 46-
 47-    /* Called when a new buffer is attached to the view. */
 48     bool (* attach)(struct swc_view * view, struct swc_buffer * buffer);
 49-
 50     bool (* move)(struct swc_view * view, int32_t x, int32_t y);
 51 
 52+    /**
 53+     * This function indicates to the view that it is about to be resized.
 54+     *
 55+     * The view can use this function to do any necessary damage calculations
 56+     * with the geometry of the view before the resize occurs.
 57+     */
 58     void (* resize)(struct swc_view * view);
 59 };
 60 
 61+/**
 62+ * Initialize a new view with the specified implementation.
 63+ */
 64 void swc_view_initialize(struct swc_view * view,
 65                          const struct swc_view_impl * impl);
 66 
 67+/**
 68+ * Release any resources associated with this view.
 69+ */
 70 void swc_view_finalize(struct swc_view * view);
 71 
 72+/**
 73+ * Attach a new buffer to the view.
 74+ *
 75+ * If buffer is NULL, the previous buffer is removed from the view.
 76+ *
 77+ * @return Whether or not the buffer was successfully attached to the view.
 78+ */
 79 bool swc_view_attach(struct swc_view * view, struct swc_buffer * buffer);
 80+
 81+/**
 82+ * Display a new frame consisting of the currently attached buffer.
 83+ *
 84+ * @return Whether or not the update succeeds.
 85+ */
 86 bool swc_view_update(struct swc_view * view);
 87+
 88+/**
 89+ * Move the view to the specified coordinates, if supported.
 90+ *
 91+ * @return Whether or not the move succeeds.
 92+ */
 93 bool swc_view_move(struct swc_view * view, int32_t x, int32_t y);
 94+
 95+/**
 96+ * Set the visibility flag of the view.
 97+ *
 98+ * This retains the view's geometry, but indicates that it will not be shown
 99+ * when the next frame is finished. This is useful when an unmapped or
100+ * minimized state is desired.
101+ */
102 void swc_view_set_visibility(struct swc_view * view, bool visible);
103+
104+/**
105+ * Send a new frame event through the view's event signal.
106+ *
107+ * This should be called by the view itself when the next frame is visible to
108+ * the user. If time information is not available, swc_time() can be passed
109+ * instead.
110+ */
111 void swc_view_frame(struct swc_view * view, uint32_t time);
112 
113 #endif