hwc: modify the doxygen of the hwc apis 80/190480/4
authorSooChan Lim <sc1.lim@samsung.com>
Tue, 2 Oct 2018 11:12:18 +0000 (20:12 +0900)
committerSooChan Lim <sc1.lim@samsung.com>
Thu, 4 Oct 2018 04:13:47 +0000 (13:13 +0900)
Change-Id: I275d882f5ac466fd9755ccc9d4f4a1e2b89ec6d2

include/tdm.h
include/tdm_backend.h

index 5f14a4c5cc90c45450e4effb0c5af7dc742b98f1..3f0b89dd67e412467799cd7db366ca030004e795 100644 (file)
@@ -856,10 +856,9 @@ tdm_hwc_get_available_properties(tdm_hwc *hwc, const tdm_prop **props, int *coun
 
 /**
  * @brief Get a target buffer queue
- * @details Buffers from target buffer queue will receive the output of
- * client composition. Window marked as TDM_COMPOSITION_CLIENT or
- * TDM_COMPOSITION_DEVICE_CANDIDATE will be composited into this buffers
- * prior to the call to tdm_output_commit().
+ * @details The client composites the tdm_hwd_windows which have
+ * TDM_COMPOSITE_CLIENT types on the buffer from this target buffer queue.
+ * Then, the client set the buffer by calling tdm_hwc_set_client_target_buffer.
  * @param[in] output A output object
  * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
  * @return A buffer queue
@@ -870,33 +869,12 @@ tdm_hwc_get_client_target_buffer_queue(tdm_hwc *hwc, tdm_error *error);
 
 /**
  * @brief Set the client(relative to the TDM) target buffer
- * @details Sets the buffer which will receive the output of client composition.
- * Window marked as TDM_COMPOSITION_CLIENT or TDM_COMPOSITION_DEVICE_CANDIDATE
- * will be composited into this buffer prior to the call to tdm_output_commit(),
- * and windows not marked as TDM_COMPOSITION_CLIENT and
- * TDM_COMPOSITION_DEVICE_CANDIDATE should be composited with this buffer by the
- * device.
- *
- * The buffer handle provided may be null if no windows are being composited by
- * the client. This must not result in an error (unless an invalid display
- * handle is also provided).
- *
- * The damage parameter describes a buffer damage region as defined in the
- * description of tdm_hwc_window_set_buffer_damage().
- *
- * List of composited hwc_windows (hwc_windows which buffers are presented on #target_buffer)
- * should be passed along with #target_buffer to allow tdm to make the smooth transition
- * from a DEVICE type to a CLIENT type.
- *
- * Should be called before tdm_output_commit() if any of the layers are marked as
- * TDM_COMPOSITION_CLIENT or TDM_COMPOSITION_DEVICE_CANDIDATE. If no layers are
- * so marked, then it is not necessary to call this function. It is not necessary
- * to call tdm_hwc_validate() after changing the target through this function.
+ * @details This function lets the backend know the target buffer.
+ * The target buffer contains the result of the gl composition with the
+ * tdm_hwc_windows which marked as TDM_COMPOSITION_CLIENT.
  * @param[in] hwc A output hwc
  * @param[in] target_buffer The new target buffer
  * @param[in] damage The buffer damage region
- * @param[in] composited_wnds The array of composited hwc_wnds
- * @param[in] num_wnds The size of #composited_wnds array
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  * @since 2.0.0
  */
@@ -905,18 +883,19 @@ tdm_hwc_set_client_target_buffer(tdm_hwc *hwc, tbm_surface_h target_buffer, tdm_
 
 /**
  * @brief Validate the output
- * @details Instructs the device to inspect all of the layer state and
+ * @details Instructs the backend to inspect all of the hw layer state and
  * determine if there are any composition type changes necessary before
- * presenting the output. Permitted changes are described in the definition
- * of tdm_hwc_window_composition_t above.
- * @param[in] output A output object
- * @param[out] num_types The number of composition type changes required by
- * the device; if greater than 0, the client must either set and validate new
- * types, or call tdm_hwc_accept_changes() to accept the changes returned by
- * tdm_hwc_get_changed_composition_types(); must be the same as the number of
- * changes returned by tdm_hwc_get_changed_composition_types (see the
- * declaration of that function for more information); pointer will be non-NULL
- * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ * presenting the hwc.
+ * @param[in] hwc A hwc object
+ * @param[in] composited_wnds the hwc window list which is visible.
+ * @param[in] num_wnds the number of the visible windows in the composited_wnds
+ * @param[out] num_types The number of composition type changes
+ * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ * @remark
+ * The backend has to return the num_types when the assgined comopsite types of
+ * the tdm_hwc_windows in the composited_wnds. If the num_types is greater than
+ * 0, the cleint must get the changed composite types of the tdm_hwc_windows
+ * and change the comopsite types
  * @since 2.0.0
  */
 tdm_error
@@ -925,25 +904,19 @@ tdm_hwc_validate(tdm_hwc *hwc, tdm_hwc_window **composited_wnds, uint32_t num_wn
 
 /**
  * @brief Get changed composition types
- * @details Retrieves the windows for which the device requires a different
- * composition type than had been set prior to the last call to tdm_hwc_validate().
+ * @details Retrieves the windows for which the backend requires a different
+ * composition types that had been set prior to the last call to tdm_hwc_validate().
  * The client will either update its state with these types and call
  * tdm_hwc_accept_changes, or will set new types and attempt to validate the
- * display again.
- * windows and types may be NULL to retrieve the number of elements which
- * will be returned. The number of elements returned must be the same as the
+ * display again. The number of elements returned must be the same as the
  * value returned in num_types from the last call to tdm_hwc_validate().
- * @param[in] output A output object
- * @param[out] num_elements If windows or types were NULL, the number of layers
- * and types which would have been returned; if both were non-NULL, the
- * number of elements returned in layers and types, which must not exceed
- * the value stored in num_elements prior to the call; pointer will be
- * non-NULL
- * @param[in] output A output object
+ * @param[in] hwc A hwc object
+ * @param[out] num_elements the number of hwc_windows
  * @param[out] windows An array of windows
  * @param[out] composition_types An array of composition types, each corresponding
  * to an element of windows
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+ * @remark
  * @since 2.0.0
  */
 tdm_error
@@ -952,17 +925,10 @@ tdm_hwc_get_changed_composition_types(tdm_hwc *hwc, uint32_t *num_elements,
                                                                        tdm_hwc_window_composition *composition_types);
 
 /**
- * @brief Accepts the changes required by the device
- * @details Accepts the changes required by the device from the previous
- * tdm_hwc_validate() call (which may be queried using
- * tdm_hwc_get_chaged_composition_types()) and revalidates the display. This
- * function is equivalent to requesting the changed types from
- * tdm_hwc_get_chaged_composition_types(), setting those types on the
- * corresponding windows, and then calling tdm_hwc_validate again.
- * After this call it must be valid to present this display. Calling this after
- * tdm_hwc_validate() returns 0 changes must succeed with TDM_ERROR_NONE, but
- * should have no other effect.
- * @param[in] output A output object
+ * @brief Accepts the changes required by the backend
+ * @details Accepts the changes required by the backend from the previous
+ * tdm_hwc_validate() and tdm_hwc_get_chaged_composition_types().
+ * @param[in] hwc A hwc object
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  * @since 2.0.0
  */
@@ -984,7 +950,6 @@ tdm_hwc_commit(tdm_hwc *hwc, int sync, tdm_hwc_commit_handler func, void *user_d
 
 /**
  * @brief Destroys the given window.
- * @param[in] output A output object
  * @param[in] window the pointer of the window to destroy
  * @since 2.0.0
  */
@@ -1015,7 +980,7 @@ tdm_hwc_window_release_buffer_queue(tdm_hwc_window *hwc_window, tbm_surface_queu
 
 /**
  * @brief Sets the desired composition type of the given window.
- * @details During tdm_hwc_validate(), the device may request changes to
+ * @details During tdm_hwc_validate(), the backend may request changes to
  * the composition types of any of the layers as described in the definition
  * of tdm_hwc_window_composition_t above.
  * @param[in] hwc_window A window object
@@ -1053,8 +1018,7 @@ tdm_hwc_window_set_buffer_damage(tdm_hwc_window *hwc_window, tdm_region damage);
 
 /**
  * @brief Set the information to a window object
- * @details The information will be applied when the output object of a window
- * object is committed.
+ * @details The information will be applied when the hwc object is committed.
  * @param[in] hwc_window A window object
  * @param[in] info The information
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
@@ -1068,11 +1032,8 @@ tdm_hwc_window_set_info(tdm_hwc_window *hwc_window, tdm_hwc_window_info *info);
  * @details A TBM buffer will be applied when the output object of a layer
  * object is committed.
  * @param[in] hwc_window A window object
- * @param[in] buffer A TDM buffer
+ * @param[in] buffer A TBM buffer
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
- * @return #TDM_ERROR_BUSY if #hwc_window can't be updated right now, this
- * can happen if #hwc_window is involved in the smooth transition from
- * DEVICE to CLIENT, this shouldn't be interpreted like some critical error.
  * @since 2.0.0
  */
 tdm_error
@@ -1080,9 +1041,9 @@ tdm_hwc_window_set_buffer(tdm_hwc_window *hwc_window, tbm_surface_h buffer);
 
 /**
  * @brief Get the property which has a given id.
- * @param[in] hwc window A hwc window object
+ * @param[in] hwc_window A hwc window object
  * @param[in] id The property id
- * @param[out] value The value
+ * @param[out] value The value of the propery id
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  */
 tdm_error
@@ -1090,9 +1051,9 @@ tdm_hwc_window_get_property(tdm_hwc_window *hwc_window, uint32_t id, tdm_value *
 
 /**
  * @brief Set the property which has a given id.
- * @param[in] hwc window  A hwc window object
+ * @param[in] hwc_window  A hwc window object
  * @param[in] id The property id
- * @param[in] value The value
+ * @param[in] value The value of the propery id
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  */
 tdm_error
@@ -1100,7 +1061,7 @@ tdm_hwc_window_set_property(tdm_hwc_window *hwc_window, uint32_t id, tdm_value v
 
 /**
  * @brief Get the constraints of hwc_window
- * @param[in] hwc window A hwc window object
+ * @param[in] hwc_window A hwc window object
  * @param[out] constraints The tdm_hwc_window_constraint types
  * @return #TDM_ERROR_NONE if success. Otherwise, error value.
  */
index 6c5fd92a80a75170c8f9265cb733d60b54b326c6..1ee231a535d2bbf87541212d5204886a597f7a35 100644 (file)
@@ -733,29 +733,12 @@ typedef struct _tdm_func_hwc {
 
        /**
         * @brief Set the client(relative to the TDM) target buffer
-        * @details Sets the buffer which will receive the hwc of client composition.
-        * Window marked as TDM_COMPOSITION_CLIENT or TDM_COMPOSITION_DEVICE_CANDIDATE
-        * will be composited into this buffer prior to the call to hwc_commit(),
-        * and windows not marked as TDM_COMPOSITION_CLIENT and
-        * TDM_COMPOSITION_DEVICE_CANDIDATE should be composited with this buffer by the
-        * device.
-        *
-        * The buffer handle provided may be null if no windows are being composited by
-        * the client. This must not result in an error (unless an invalid display
-        * handle is also provided).
-        *
-        * The damage parameter describes a buffer damage region as defined in the
-        * description of hwc_window_set_buffer_damage().
-        *
-        * Will be called before hwc_commit() if any of the layers are marked as
-        * TDM_COMPOSITION_CLIENT or TDM_COMPOSITION_DEVICE_CANDIDATE. If no layers are
-        * so marked, then it is not necessary to call this function. It is not necessary
-        * to call hwc_validate() after changing the target through this function.
+        * @details This function lets the backend know the target buffer.
+        * The target buffer contains the result of the gl composition with the
+        * tdm_hwc_windows which marked as TDM_COMPOSITION_CLIENT.
         * @param[in] hwc A hwc object
-        * @param[in] target The new target buffer
+        * @param[in] target_buffer The new target buffer
         * @param[in] damage The buffer damage region
-        * @param[in] composited_wnds The array of composited hwc_wnds
-        * @param[in] num_wnds The size of #composited_wnds array
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
         * @since 2.0.0
         */
@@ -765,18 +748,19 @@ typedef struct _tdm_func_hwc {
 
        /**
         * @brief Validate the hwc
-        * @details Instructs the device to inspect all of the layer state and
+        * @details Instructs the backend to inspect all of the hw layer state and
         * determine if there are any composition type changes necessary before
-        * presenting the hwc. Permitted changes are described in the definition
-        * of tdm_composition_t above.
+        * presenting the hwc.
         * @param[in] hwc A hwc object
-        * @param[out] num_types The number of composition type changes required by
-        * the device; if greater than 0, the client must either set and validate new
-        * types, or call hwc_accept_changes() to accept the changes returned by
-        * hwc_get_changed_composition_types(); must be the same as the number of
-        * changes returned by hwc_get_changed_composition_types (see the
-        * declaration of that function for more information); pointer will be non-NULL
+        * @param[in] composited_wnds the hwc window list which is visible.
+        * @param[in] num_wnds the number of the visible windows in the composited_wnds
+        * @param[out] num_types The number of composition type changes
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
+        * @remark
+        * The backend has to return the num_types when the assgined comopsite types of
+        * the tdm_hwc_windows in the composited_wnds. If the num_types is greater than
+        * 0, the cleint must get the changed composite types of the tdm_hwc_windows
+        * and change the comopsite types
         * @since 2.0.0
         */
        tdm_error (*hwc_validate)(tdm_hwc *hwc, tdm_hwc_window **composited_wnds,
@@ -784,23 +768,17 @@ typedef struct _tdm_func_hwc {
 
        /**
         * @brief Get changed composition types
-        * @details Retrieves the windows for which the device requires a different
-        * composition type than had been set prior to the last call to hwc_validate().
+        * @details Retrieves the windows for which the backend requires a different
+        * composition types that had been set prior to the last call to tdm_hwc_validate().
         * The client will either update its state with these types and call
-        * hwc_accept_changes, or will set new types and attempt to validate the
-        * display again.
-        * layers and types may be NULL to retrieve the number of elements which
-        * will be returned. The number of elements returned must be the same as the
-        * value returned in num_types from the last call to hwc_validate().
+        * tdm_hwc_accept_changes, or will set new types and attempt to validate the
+        * display again. The number of elements returned must be the same as the
+        * value returned in num_types from the last call to tdm_hwc_validate().
         * @param[in] hwc A hwc object
-        * @param[out] num_elements If windows or types were NULL, the number of layers
-        * and types which would have been returned; if both were non-NULL, the
-        * number of elements returned in layers and types, which must not exceed
-        * the value stored in num_elements prior to the call; pointer will be
-        * non-NULL
+        * @param[out] num_elements the number of hwc_windows
         * @param[out] windows An array of windows
-        * @param[out] composition_types An array of composition types, each
-        * corresponding to an element of windows
+        * @param[out] composition_types An array of composition types, each corresponding
+        * to an element of windows
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
         * @since 2.0.0
         */
@@ -808,16 +786,9 @@ typedef struct _tdm_func_hwc {
                                                                                                   tdm_hwc_window **hwc_window,
                                                                                                   tdm_hwc_window_composition *composition_types);
        /**
-        * @brief Accepts the changes required by the device
-        * @details Accepts the changes required by the device from the previous
-        * hwc_validate() call (which may be queried using
-        * hwc_get_chaged_composition_types()) and revalidates the display. This
-        * function is equivalent to requesting the changed types from
-        * hwc_get_chaged_composition_types(), setting those types on the
-        * corresponding windows, and then calling hwc_validate again.
-        * After this call it must be valid to present this display. Calling this after
-        * hwc_validate() returns 0 changes must succeed with TDM_ERROR_NONE, but
-        * should have no other effect.
+        * @brief Accepts the changes required by the backend
+        * @details Accepts the changes required by the backend from the previous
+        * tdm_hwc_validate() and tdm_hwc_get_chaged_composition_types().
         * @param[in] hwc A hwc object
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
         * @since 2.0.0
@@ -825,7 +796,7 @@ typedef struct _tdm_func_hwc {
        tdm_error (*hwc_accept_changes)(tdm_hwc *hwc);
 
        /**
-        * @brief Commit changes for a output object
+        * @brief Commit changes for a hwc object
         * @param[in] hwc A hwc object
         * @param[in] sync 0: asynchronous, 1:synchronous
         * @param[in] user_data The user data
@@ -833,11 +804,11 @@ typedef struct _tdm_func_hwc {
         * @see hwc_set_commit_handler, tdm_hwc_commit_handler
         * @remark
         * When this function is called, a backend module @b SHOULD apply the all
-        * changes of the given output object to screen as well as the layer changes
-        * of this output.
+        * changes of the given hwc object to screen as well as the layer changes
+        * of this hwc.
         * If this function returns TDM_ERROR_NONE, a backend module @b SHOULD call
         * a user commit handler with the user data of this function after all
-        * changes of the given output object are applied.
+        * changes of the given hwc object are applied.
         */
        tdm_error (*hwc_commit)(tdm_hwc *hwc, int sync, void *user_data);
 
@@ -863,7 +834,9 @@ typedef struct _tdm_func_hwc_window {
        void (*hwc_window_destroy)(tdm_hwc_window *hwc_window);
 
        /**
-        * @brief Get a buffer queue for the window object
+        * @brief Acquire a buffer queue for the window object
+        * @details These buffers are used to composite by hardware a client content in
+        * the nocomp mode.
         * @param[in] hwc_window A window object
         * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
         * @return A buffer queue
@@ -882,7 +855,7 @@ typedef struct _tdm_func_hwc_window {
 
        /**
         * @brief Sets the desired composition type of the given window.
-        * @details During hwc_validate(), the device may request changes to
+        * @details During hwc_validate(), the backend may request changes to
         * the composition types of any of the layers as described in the definition
         * of tdm_hwc_window_composition_t above.
         * @param[in] hwc_window A window object
@@ -917,8 +890,7 @@ typedef struct _tdm_func_hwc_window {
 
        /**
         * @brief Set the information to a window object
-        * @details The information will be applied when the hwc object
-        * of a layer object is committed.
+        * @details The information will be applied when the hwc object is committed.
         * @param[in] hwc_window A window object
         * @param[in] info The geometry information
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
@@ -940,21 +912,17 @@ typedef struct _tdm_func_hwc_window {
         * @details A TDM buffer will be applied when the hwc object
         * of a layer object is committed.
         * @param[in] hwc_window A window object
-        * @param[in] buffer A TDM buffer
+        * @param[in] buffer A TBM buffer
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
-        *
-        * Implementation should return #TDM_ERROR_BUSY if #hwc_window can't
-        * be updated right now, this won't be interpreted like some critical
-        * error.
         */
        tdm_error (*hwc_window_set_buffer)(tdm_hwc_window *hwc_window,
                                                                           tbm_surface_h buffer);
 
        /**
         * @brief Set the property which has a given id.
-        * @param[in] hwc window  A hwc window object
+        * @param[in] hwc_window  A hwc window object
         * @param[in] id The property id
-        * @param[in] value The value
+        * @param[in] value The value of the propery id
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
         */
        tdm_error (*hwc_window_set_property)(tdm_hwc_window *hwc_window,
@@ -962,9 +930,9 @@ typedef struct _tdm_func_hwc_window {
 
        /**
         * @brief Get the property which has a given id.
-        * @param[in] hwc window A hwc window object
+        * @param[in] hwc_window A hwc window object
         * @param[in] id The property id
-        * @param[out] value The value
+        * @param[out] value The value of the propery id
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
         */
        tdm_error (*hwc_window_get_property)(tdm_hwc_window *hwc_window,
@@ -972,7 +940,7 @@ typedef struct _tdm_func_hwc_window {
 
        /**
         * @brief Get the constraints of hwc_window
-        * @param[in] hwc window A hwc window object
+        * @param[in] hwc_window A hwc window object
         * @param[out] constraints The tdm_hwc_window_constraint types
         * @return #TDM_ERROR_NONE if success. Otherwise, error value.
         */