swc

commit 0c8be166d3685a99af57b0e04250a5e0f4f8fd99
parent 130d7a798d745cf5e7b788c1b0731ac334503788
Author: Michael Forney <mforney@mforney.org>
Date:   Sat, 25 Jan 2014 01:59:31 -0800

view: Add some documentation

Diffstat:
M
libswc/view.h
 | 
74
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----

1 file changed, 70 insertions(+), 4 deletions(-)
diff --git a/libswc/view.h b/libswc/view.h
@@ -42,6 +42,12 @@ enum
     SWC_VIEW_EVENT_SCREENS_CHANGED
 };
 
+/**
+ * This structure contains data sent along with a view's events.
+ *
+ * Extra data correspending to the particular event is stored in the
+ * corresponding struct inside the union.
+ */
 struct swc_view_event_data
 {
     struct swc_view * view;
@@ -59,6 +65,18 @@ struct swc_view_event_data
     };
 };
 
+/**
+ * A view represents a component that can display buffers to the user.
+ *
+ * For example, each output contains a view residing in its framebuffer plane
+ * that is used to scan out buffers. Additionally, the compositor creates views
+ * dynamically for each surface it displays, compositing them into a single
+ * buffer, which it can then attach to the previously mentioned view.
+ *
+ * This abstraction allows various components of swc to connect in a general
+ * way, allowing operations like setting the output view of a surface directly
+ * to an output's framebuffer plane, bypassing the compositor.
+ */
 struct swc_view
 {
     const struct swc_view_impl * impl;
@@ -72,28 +90,76 @@ struct swc_view
     struct wl_listener buffer_destroy_listener;
 };
 
+/**
+ * Every view must have an implementation containing these functions.
+ *
+ * For descriptions, see the corresponding swc_view_* function.
+ */
 struct swc_view_impl
 {
-    /* Called when the view should present a new frame. */
     bool (* update)(struct swc_view * view);
-
-    /* Called when a new buffer is attached to the view. */
     bool (* attach)(struct swc_view * view, struct swc_buffer * buffer);
-
     bool (* move)(struct swc_view * view, int32_t x, int32_t y);
 
+    /**
+     * This function indicates to the view that it is about to be resized.
+     *
+     * The view can use this function to do any necessary damage calculations
+     * with the geometry of the view before the resize occurs.
+     */
     void (* resize)(struct swc_view * view);
 };
 
+/**
+ * Initialize a new view with the specified implementation.
+ */
 void swc_view_initialize(struct swc_view * view,
                          const struct swc_view_impl * impl);
 
+/**
+ * Release any resources associated with this view.
+ */
 void swc_view_finalize(struct swc_view * view);
 
+/**
+ * Attach a new buffer to the view.
+ *
+ * If buffer is NULL, the previous buffer is removed from the view.
+ *
+ * @return Whether or not the buffer was successfully attached to the view.
+ */
 bool swc_view_attach(struct swc_view * view, struct swc_buffer * buffer);
+
+/**
+ * Display a new frame consisting of the currently attached buffer.
+ *
+ * @return Whether or not the update succeeds.
+ */
 bool swc_view_update(struct swc_view * view);
+
+/**
+ * Move the view to the specified coordinates, if supported.
+ *
+ * @return Whether or not the move succeeds.
+ */
 bool swc_view_move(struct swc_view * view, int32_t x, int32_t y);
+
+/**
+ * Set the visibility flag of the view.
+ *
+ * This retains the view's geometry, but indicates that it will not be shown
+ * when the next frame is finished. This is useful when an unmapped or
+ * minimized state is desired.
+ */
 void swc_view_set_visibility(struct swc_view * view, bool visible);
+
+/**
+ * Send a new frame event through the view's event signal.
+ *
+ * This should be called by the view itself when the next frame is visible to
+ * the user. If time information is not available, swc_time() can be passed
+ * instead.
+ */
 void swc_view_frame(struct swc_view * view, uint32_t time);
 
 #endif