From 290f3091e6c43d7b9ff26250109e55b20054aa83 Mon Sep 17 00:00:00 2001 From: SooChan Lim Date: Tue, 8 May 2018 17:52:32 +0900 Subject: [PATCH] backend: modify the comments on the header file. Change-Id: Ie8f972382d6fe07b934b7dff18a937bf1eb08a5b --- src/tbm_backend.h | 118 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 61 insertions(+), 57 deletions(-) diff --git a/src/tbm_backend.h b/src/tbm_backend.h index a86d35d..b315720 100644 --- a/src/tbm_backend.h +++ b/src/tbm_backend.h @@ -55,7 +55,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * ABI versions. Each version has a major and minor revision. Modules * using lower minor revisions must work with servers of a higher minor * revision. There is no compatibility between different major revisions. - * Whenever the ABI_ANSIC_VERSION is changed, the others must also be + * Whenever the ABI_MAJOR_VERSION is changed, the others must also be * changed. The minor revision mask is 0x0000FFFF and the major revision * mask is 0xFFFF0000. */ @@ -68,7 +68,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. #define TBM_BACKEND_ABI_LATEST_VERSION TBM_BACKEND_ABI_VERSION_3_0 /**< the latest version of the tbm backend abi */ /** - * @brief The backend module data + * @brief The backend bufmgr data * @details * The init() function of #tbm_backend_module returns the backend module data. * This handle will be used in #tbm_backend_bufmgr_func. @@ -101,6 +101,10 @@ typedef struct _tbm_backend_bo_func tbm_backend_bo_func; struct _tbm_backend_bufmgr_func { /** * @brief Get the capabilities of a buffer manager + * @remarks The backend must support the TBM_BUFMGR_CAPABILITY_SHARE_FD. + * TBM_BUFMGR_CAPABILITY_SHARE_KEY will help you do debugging to + * develop the platform because the tbm_key will be the unique + * identification of the tbm_bo memory in the system. * @param[in] bufmgr_data The backend module data * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. * @return the capabilities of a backend modul @@ -110,7 +114,7 @@ struct _tbm_backend_bufmgr_func { /** * @brief set(bind) the native display - * @param[in] bufmgr_data The backend module data + * @param[in] bufmgr_data The backend bufmgr data * @param[in] native_display : the native display (wl_display in wayland window system) * @return #TBM_ERROR_NONE if success. Otherwise, error value. */ @@ -119,7 +123,7 @@ struct _tbm_backend_bufmgr_func { /** * @brief get the formats list and the num to be supported by backend. - * @param[in] bufmgr_data The backend module data + * @param[in] bufmgr_data The backend bufmgr data * @param[out] **formats : format array list. it is allocated by backend funtion * @param[out] *num : the number of the formats to be supported by backend * @return #TBM_ERROR_NONE if success. Otherwise, error value. @@ -128,16 +132,16 @@ struct _tbm_backend_bufmgr_func { uint32_t **formats, uint32_t *num); /** - * @brief get the plane data of the surface. - * @param[in] bufmgr_data The backend module data + * @brief get the plane data of the plane_idx according to the format. + * @param[in] bufmgr_data The backend bufmgr data * @param[in] format : the format of the surface - * @param[in] plane_idx : the format of the surface - * @param[in] width : the width of the surface - * @param[in] height : the height of the surface - * @param[out] size : the size of the plane - * @param[out] offset : the offset of the plane - * @param[out] pitch : the pitch of the plane - * @param[out] bo_idx : the bo index of the plane + * @param[in] plane_idx : the index of the plane + * @param[in] width : the width of the surface with the format + * @param[in] height : the height of the surface with the format + * @param[out] size : the size of the plane index + * @param[out] offset : the offset of the plane index at the bo index + * @param[out] pitch : the pitch of the plane index + * @param[out] bo_idx : the bo index of the plane index * @return #TBM_ERROR_NONE if success. Otherwise, error value. */ tbm_error_e (*bufmgr_get_plane_data)(tbm_backend_bufmgr_data *bufmgr_data, @@ -146,54 +150,54 @@ struct _tbm_backend_bufmgr_func { uint32_t *pitch, int *bo_idx); /** - * @brief allocate the bo_data of the tbm_backend - * @param[in] bufmgr_data The backend module data - * @param[in] size : the size of buffer object - * @param[in] flags : the flags of memory type + * @brief allocate the bo data of the tbm_backend + * @param[in] bufmgr_data The backend bufmgr data + * @param[in] size : the size of bo data + * @param[in] mem_types : the memory types * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. * @return pointer of the bo_data of the tbm backend. */ tbm_backend_bo_data *(*bufmgr_alloc_bo)(tbm_backend_bufmgr_data *bufmgr_data, - unsigned int size, tbm_bo_memory_type mem_type, + unsigned int size, tbm_bo_memory_type mem_types, tbm_error_e *error); /** - * @brief allocate the buffer object for tbm surface - * @param[in] bo : the buffer object - * @param[in] width : the width of surface - * @param[in] height : the height of surface - * @param[in] format : the format of surface - * @param[in] flags : the flags of memory type - * @param[in] bo_idx : the index of bo in surface + * @brief allocate the bo data of the bo index according to the format + * @param[in] bufmgr_data The backend bufmgr data + * @param[in] width : the width of the surface with the format + * @param[in] height : the height of the surface with the format + * @param[in] format : the format of the surface + * @param[in] mem_types : the memory types + * @param[in] bo_idx : the bo index of the surface * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return pointer of the bo_data of the tbm backend. + * @return pointer of the bo data of the tbm backend. */ tbm_backend_bo_data *(*bufmgr_alloc_bo_with_format)(tbm_backend_bufmgr_data *bufmgr_data, int format, int bo_idx, int width, - int height, tbm_bo_memory_type mem_type, + int height, tbm_bo_memory_type mem_types, tbm_error_e *error); /** - * @brief import the buffer object associated with the prime fd. + * @brief import the bo data associated with the tdm_fd(prime fd). * @remarks tbm_fd must be free by user. - * @remarks If the backend doesn't support a buffer sharing by tbm fd, - * fucntion pointer must be set to NULL. - * @param[in] bufmgr_data The backend module data - * @param[in] fd : the prime fd associated with the buffer object + * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd) + * among the processes is the essential feature to run the graphic rendering. + * @param[in] bufmgr_data The backend bufmgr data + * @param[in] fd : the tdm_fd(prime fd) associated with the bo data * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return pointer of the bo_data of the tbm backend. + * @return pointer of the bo data of the tbm backend. */ tbm_backend_bo_data *(*bufmgr_import_fd)(tbm_backend_bufmgr_data *bufmgr_data, tbm_fd fd, tbm_error_e *error); /** - * @brief import the buffer object associated with the key. + * @brief import the bo data associated with the tdm_key. * @remarks If the backend doesn't support a buffer sharing by tbm key, - fucntion pointer must be set to NULL. - * @param[in] bufmgr_data The backend module data - * @param[in] key : the key associated with the buffer object + * fucntion pointer must be set to NULL. + * @param[in] bufmgr_data The backend bufmgr data + * @param[in] key : the tdm_key associated with the bo data * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return pointer of the bo_data of the tbm backend. + * @return pointer of the bo data of the tbm backend. */ tbm_backend_bo_data *(*bufmgr_import_key)(tbm_backend_bufmgr_data *bufmgr_data, tbm_key key, tbm_error_e *error); @@ -212,14 +216,14 @@ struct _tbm_backend_bufmgr_func { */ struct _tbm_backend_bo_func { /** - * @brief free the buffer object. + * @brief free the bo data. * @param[in] bo_data : the bo data of the tbm backend * @return #TBM_ERROR_NONE if success. Otherwise, error value. */ void (*bo_free)(tbm_backend_bo_data *bo_data); /** - * @brief get the size of a bo. + * @brief get the size of a bo data. * @param[in] bo_data : the bo data of the tbm backend * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. * @return size if this function succeeds, otherwise 0. @@ -227,7 +231,7 @@ struct _tbm_backend_bo_func { int (*bo_get_size)(tbm_backend_bo_data *bo_data, tbm_error_e *error); /** - * @brief get the tbm memory type + * @brief get the tbm memory types * @param[in] bo_data : the bo data of the tbm backend * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. * @see #TBM_BO_FLAGS #tbm_bo_memory_type @@ -241,34 +245,34 @@ struct _tbm_backend_bo_func { * @param[in] bo_data : the bo data of the tbm backend * @param[in] device : the device type to get a handle * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return the handle of the buffer object + * @return the handle of the bo data */ tbm_bo_handle (*bo_get_handle)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device, tbm_error_e *error); /** - * @brief map the buffer object according to the device type and the option. + * @brief map the bo data according to the device type and the option. * @param[in] bo_data : the bo data of the tbm backend * @param[in] device : the device type to get a handle - * @param[in] opt : the option to access the buffer object + * @param[in] opt : the option to access the bo data * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return the handle of the buffer object + * @return the handle of the bo data */ tbm_bo_handle (*bo_map)(tbm_backend_bo_data *bo_data, tbm_bo_device_type device, tbm_bo_access_option opt, tbm_error_e *error); /** - * @brief unmap the buffer object. + * @brief unmap the bo data. * @param[in] bo_data : the bo data of the tbm backend * @return #TBM_ERROR_NONE if success. Otherwise, error value. */ tbm_error_e (*bo_unmap)(tbm_backend_bo_data *bo_data); /** - * @brief lock the buffer object with a device and an opt. + * @brief lock the bo data with a device and an opt. * @param[in] bo_data : the bo data of the tbm backend * @param[in] device : the device type to get a handle - * @param[in] opt : the option to access the buffer object + * @param[in] opt : the option to access the bo data * @return #TBM_ERROR_NONE if success. Otherwise, error value. * @remark This function pointer could be null. */ @@ -276,7 +280,7 @@ struct _tbm_backend_bo_func { tbm_bo_access_option opt); /** - * @brief unlock the buffer object. + * @brief unlock the bo data. * @param[in] bo_data : the bo data of the tbm backend * @return #TBM_ERROR_NONE if success. Otherwise, error value. * @remark This function pointer could be null. @@ -284,23 +288,23 @@ struct _tbm_backend_bo_func { tbm_error_e (*bo_unlock)(tbm_backend_bo_data *bo_data); /** - * @brief export the buffer object + * @brief export the bo data to the tdm_fd(prime fd) * @remarks tbm_fd must be free by user. - * @remarks If the backend doesn't support a buffer sharing by tbm fd, - fucntion pointer must be set to NULL. + * @remarks It must be supported at the backend module. To sharing the tdm_fd(prime fd) + * among the processes is the essential feature to run the graphic rendering. * @param[in] bo_data : the bo data of the tbm backend * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return tbm_fd associated with the buffer object + * @return tbm_fd associated with the bo data */ tbm_fd (*bo_export_fd)(tbm_backend_bo_data *bo_data, tbm_error_e *error); /** - * @brief export the buffer object + * @brief export the bo data to the tdm_key * @remarks If the backend doesn't support a buffer sharing by tbm key, - fucntion pointer must be set to NULL. - * @param[in] bo : the buffer object + * fucntion pointer must be set to NULL. + * @param[in] bo_data : the bo data of the tbm backend * @param[out] error #TBM_ERROR_NONE if success. Otherwise, error value. - * @return key associated with the buffer object + * @return key associated with the bo data */ tbm_key (*bo_export_key)(tbm_backend_bo_data *bo_data, tbm_error_e *error); -- 2.7.4