From: Boram Park Date: Wed, 30 Dec 2015 06:00:48 +0000 (+0900) Subject: modify doxygen X-Git-Tag: submit/tizen/20160122.051037~4 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a82fd8f1bd857ca77d455da096af8adbb9f9f7aa;p=platform%2Fcore%2Fuifw%2Flibtdm.git modify doxygen Change-Id: Iad1714e3224f39e4b77452e2fa4456949857711b --- diff --git a/.gitignore b/.gitignore index bd846ae9..49d27e8c 100644 --- a/.gitignore +++ b/.gitignore @@ -22,4 +22,5 @@ stamp-h1 *.la *.lo *~ - +html/ +latex/ diff --git a/doc/Doxyfile b/doc/Doxyfile index a6a2087e..47f90d00 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -98,6 +98,7 @@ WARN_LOGFILE = # Configuration options related to the input files #--------------------------------------------------------------------------- INPUT = \ + doc/tdm_doc.h \ include/tdm.h \ include/tdm_backend.h \ include/tdm_list.h \ diff --git a/doc/tdm_doc.h b/doc/tdm_doc.h new file mode 100644 index 00000000..3bdc3e3c --- /dev/null +++ b/doc/tdm_doc.h @@ -0,0 +1,141 @@ +/************************************************************************** + +libtdm + +Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved. + +Contact: Eunchul Kim , + JinYoung Jeon , + Taeheon Kim , + YoungJun Cho , + SooChan Lim , + Boram Park + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sub license, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice (including the +next paragraph) shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. +IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR +ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +**************************************************************************/ + +#ifndef _TDM_DOC_H_ +#define _TDM_DOC_H_ + +/** + * @mainpage TDM + * @author Boram Park, boram1288.park@samsung.com + * @date Dec 30, 2015 + * @version 1.0.0 + * @par Introduction + * TDM stands for Tizen Display Manager. It's the display HAL layer for tizen + * display server. It offers the frontend APIs(@ref tdm.h) for a frontend user + * and the abstraction interface(@ref tdm_backend.h) for a hardware vendor. + * \n + * @par Objects + * TDM consists of display/output/layer/pp/capture objects. A frontend user can + * get the output/layer/pp/capture hardware information with each object. + * Basically, TDM supposes that all display devices have fixed outputs and + * layers. A frontend user can get these outputs and layers with + * #tdm_display_get_output_count, #tdm_display_get_output, #tdm_output_get_layer_count + * and #tdm_output_get_layer. To get a pp/capture object, however, a frontend + * user need to create a object with #tdm_display_create_pp, #tdm_output_create_capture + * and #tdm_layer_create_capture if available.\n + * \n + * All changes of output/layer/pp/capture objects are applied when committed. + * See #tdm_output_commit, #tdm_pp_commit and #tdm_capture_commit. + * \n + * @par Buffer management + * TDM has its own buffer release mechanism to let an user know when a TDM buffer + * becomes available for a next job. A frontend user can add a user release handler + * to a TDM buffer with #tdm_buffer_add_release_handler, and this handler will be + * called when it's disappered from screen or when pp/capture operation is done. + * \n + * @par Implementing a TDM backend module(for a hardware vendor) + * A backend module @b SHOULD define the global data symbol of which name is + * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data", + * at the initial time and call init() function of #tdm_backend_module. + * A backend module at least @b SHOULD register the #tdm_func_display functions + * to a display object with #tdm_backend_register_func_display() function in initial time.\n + * @code + #include + + static tdm_func_display drm_func_display = + { + drm_display_get_capabilitiy, + ... + drm_display_get_outputs, + ... + drm_output_get_capability, + drm_output_get_layers, + ... + drm_layer_get_capability, + ... + }; + + static tdm_drm_data *drm_data; + + tdm_backend_data* + tdm_drm_init(tdm_display *dpy, tdm_error *error) + { + ... + drm_data = calloc(1, sizeof(tdm_drm_data)); + ... + ret = tdm_backend_register_func_display(dpy, &drm_func_display); + if (ret != TDM_ERROR_NONE) + goto failed; + ... + return (tdm_backend_data*)drm_data; + } + + void + tdm_drm_deinit(tdm_backend_data *bdata) + { + ... + free(bdata); + } + + tdm_backend_module tdm_backend_module_data = + { + "drm", + "Samsung", + TDM_BACKEND_ABI_VERSION, + tdm_drm_init, + tdm_drm_deinit + }; + * @endcode + * \n + * A sample backend source code can be downloaded. + * @code + $ git clone ssh://{user_id}@review.tizen.org:29418/platform/core/uifw/libtdm-drm + * @endcode + * \n + * After loading a TDM backend module, TDM will call @b display_get_capabilitiy(), + * @b display_get_outputs(), @b output_get_capability(), @b output_get_layers(), + * @b layer_get_capability() functions to get the hardware information. That is, + * a TDM backend module @b SHOULD implement these 5 functions basically.\n + * \n + * In addition, if a hardware has a memory-to-memory converting device and the + * capture device, a backend module can register the #tdm_func_pp functions and + * #tdm_func_capture functions with #tdm_backend_register_func_pp() and + * #tdm_backend_register_func_capture().\n + * \n + * The @b "Remarks" part of explains what things should be + * careful for vendor to implement a TDM backend module. + */ + +#endif /* _TDM_DOC_H_ */ diff --git a/include/tdm.h b/include/tdm.h index 3069b3b5..918de100 100644 --- a/include/tdm.h +++ b/include/tdm.h @@ -53,27 +53,6 @@ extern "C" { * @code #include //for a frontend user * @endcode - * @details - * TDM stands for Tizen Display Manager. It's the display HAL layer for tizen - * display server. It offers the frontend APIs(@ref tdm.h) for a frontend user - * and the abstraction interface(@ref tdm_backend.h) for a hardware vendor.\n - * \n - * TDM consists of display/output/layer/pp/capture objects. A frontend user can - * get the output/layer/pp/capture hardware information with each object. - * Basically, TDM supposes that all hardware devices have fixed outputs and - * layers. A frontend user can get these outputs and layers with - * #tdm_display_get_output_count, #tdm_display_get_output, #tdm_output_get_layer_count - * and #tdm_output_get_layer. To get a pp/capture object, however, a frontend - * user need to create a object with #tdm_display_create_pp, #tdm_output_create_capture - * and #tdm_layer_create_capture if available.\n - * \n - * All changes of output/layer/pp/capture objects are applied when commiting. - * See #tdm_output_commit, #tdm_pp_commit and #tdm_capture_commit.\n - * \n - * TDM has its own buffer release mechanism to let an user know when a TDM buffer - * becomes available for a next job. A frontend user can add a user release handler - * to a TDM buffer with #tdm_buffer_add_release_handler, and this handler will be - * called when it's disappered from screen or when pp/capture operation is done. */ /** @@ -420,7 +399,7 @@ tdm_error tdm_layer_get_available_properties(tdm_layer *layer, const tdm_prop * - But the zpos of VIDEO layers will be decided by a backend module side. * - A frontend user only can set the relative zpos to VIDEO layers via #tdm_layer_set_video_pos * - The zpos of video layers is less than GRAPHIC layers or more than GRAPHIC - * layers. ie, -1, -2, 4, 5 (if 0 <= GRAPHIC layer's zpos < 4). + * layers. ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4). * @param[in] layer A layer object * @param[out] zpos The zpos * @return #TDM_ERROR_NONE if success. Otherwise, error value. diff --git a/include/tdm_backend.h b/include/tdm_backend.h index a60441c1..645d0dee 100644 --- a/include/tdm_backend.h +++ b/include/tdm_backend.h @@ -58,15 +58,12 @@ extern "C" { * @details * The init() function of #tdm_backend_module returns the backend module data. * And it will be passed to display functions of #tdm_func_display. - * @remark It @b SHOULD be freed in the deinit() function of #tdm_backend_module. * @see tdm_backend_module, tdm_backend_module */ typedef void tdm_backend_data; /** * @brief The display capabilities structure of a backend module - * @remark A backend module @b SHOULD fill this structure to let frontend know the - * backend display capabilities. * @see The display_get_capabilitiy() function of #tdm_func_display */ typedef struct _tdm_caps_display @@ -76,11 +73,6 @@ typedef struct _tdm_caps_display /** * @brief The capabilities structure of a output object - * @details - * If a output device has the size restriction, a backend module can let a user - * know it with min_w, min_h, max_w, max_h, preferred_align variables. - * @remark A backend module @b SHOULD fill this structure to let frontend know the - * backend output capabilities. * @see The output_get_capability() function of #tdm_func_display */ typedef struct _tdm_caps_output @@ -90,10 +82,10 @@ typedef struct _tdm_caps_output unsigned int type_id; /**< The connection type id */ unsigned int mode_count; /**< The count of available modes */ - tdm_output_mode *modes; /**< The array of available modes */ + tdm_output_mode *modes; /**< The @b newly-allocated array of modes. will be freed in frontend. */ unsigned int prop_count; /**< The count of available properties */ - tdm_prop *props; /**< The array of available properties */ + tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */ unsigned int mmWidth; /**< The physical width (milimeter) */ unsigned int mmHeight; /**< The physical height (milimeter) */ @@ -108,8 +100,6 @@ typedef struct _tdm_caps_output /** * @brief The capabilities structure of a layer object - * @remark A backend module @b SHOULD fill this structure to let frontend know the - * backend layer capabilities. * @see The layer_get_capability() function of #tdm_func_display */ typedef struct _tdm_caps_layer @@ -118,27 +108,28 @@ typedef struct _tdm_caps_layer /** * The z-order - * - The zpos of GRAPHIC layers starts from 0, and it is @b non-changeable.\n - * - The zpos of VIDEO layers is less than graphic layers or more than graphic layers. - * ie, -1, -2, 4, 5 (if 0 <= GRAPHIC layer's zpos < 4).. It is @b changeable - * by layer_set_video_pos() function of #tdm_func_display + * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts + * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n + * But the zpos of VIDEO layer is changeable by layer_set_video_pos() function + * of #tdm_func_display. And The zpos of VIDEO layers is less than GRAPHIC + * layers or more than GRAPHIC layers. + * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4). + * The zpos of VIDEO layers is @b relative. It doesn't need to start + * from -1 or 4. Let's suppose that there are two VIDEO layers. + * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher + * than -4 VIDEO layer. */ int zpos; unsigned int format_count; /**< The count of available formats */ - tbm_format *formats; /**< The array of available formats */ + tbm_format *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */ unsigned int prop_count; /**< The count of available properties */ - tdm_prop *props; /**< The array of available properties */ + tdm_prop *props; /**< The @b newly-allocated array of properties. will be freed in frontend. */ } tdm_caps_layer; /** * @brief The capabilities structure of a pp object - * @details - * If a pp device has the size restriction, a backend module can let a user - * know it with min_w, min_h, max_w, max_h, preferred_align variables. - * @remark A backend module @b SHOULD fill this structure to let frontend know the - * backend pp capabilities if pp is available. * @see The display_get_pp_capability() function of #tdm_func_display */ typedef struct _tdm_caps_pp @@ -146,7 +137,7 @@ typedef struct _tdm_caps_pp tdm_pp_capability capabilities; /**< The capabilities of pp */ unsigned int format_count; /**< The count of available formats */ - tbm_format *formats; /**< The array of available formats */ + tbm_format *formats; /**< The @b newly-allocated array. will be freed in frontend. */ int min_w; /**< The minimun width. -1 means "not defined" */ int min_h; /**< The minimun height. -1 means "not defined" */ @@ -157,11 +148,6 @@ typedef struct _tdm_caps_pp /** * @brief The capabilities structure of a capture object - * @details - * If a capture device has the size restriction, a backend module can let a user - * know it with min_w, min_h, max_w, max_h, preferred_align variables. - * @remark A backend module @b SHOULD fill this structure to let frontend know the - * backend capture capabilities if capture is available. * @see The display_get_capture_capability() function of #tdm_func_display */ typedef struct _tdm_caps_capture @@ -169,7 +155,7 @@ typedef struct _tdm_caps_capture tdm_capture_capability capabilities; /**< The capabilities of capture */ unsigned int format_count; /**< The count of available formats */ - tbm_format *formats; /**< The array of available formats */ + tbm_format *formats; /**< The @b newly-allocated array of formats. will be freed in frontend. */ int min_w; /**< The minimun width. -1 means "not defined" */ int min_h; /**< The minimun height. -1 means "not defined" */ @@ -185,63 +171,118 @@ typedef struct _tdm_func_display { /** * @brief Get the display capabilities of a backend module - * @details TDM calls this function at the initial time. And at the update time also. - * #tdm_caps_display containes the max layer count information, etc. * @param[in] bdata The backend module data * @param[out] caps The display capabilities of a backend module * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @remark + * A backend module @b SHOULD implement this function. TDM calls this function + * not only at the initial time, but also at the update time when new output + * is connected.\n + * If a hardware has the restriction of the number of max usable layer count, + * a backend module can set the max count to max_layer_count of #tdm_caps_display + * structure. Otherwise, set -1. */ tdm_error (*display_get_capabilitiy)(tdm_backend_data *bdata, tdm_caps_display *caps); /** * @brief Get the pp capabilities of a backend module - * @details This function can be NULL if a backend module doesn't have the pp capability. - * TDM calls this function at the initial time if available. And at the update time also. - * #tdm_caps_pp containes avaiable formats, size restriction information, etc. * @param[in] bdata The backend module data * @param[out] caps The pp capabilities of a backend module * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see tdm_backend_register_func_pp + * @remark + * TDM calls this function not only at the initial time, but also at the update + * time when new output is connected.\n + * A backend module doesn't need to implement this function if a hardware + * doesn't have the memory-to-memory converting device. Otherwise, a backend module + * @b SHOULD fill the #tdm_caps_pp data. #tdm_caps_pp contains the hardware + * restriction information which a converting device can handle. ie, format, size, etc. */ tdm_error (*display_get_pp_capability)(tdm_backend_data *bdata, tdm_caps_pp *caps); /** * @brief Get the capture capabilities of a backend module - * @details This function can be NULL if a backend module doesn't have the capture capability. - * TDM calls this function at the initial time if available. And at the update time also. - * #tdm_caps_capture containes avaiable formats, size restriction information, etc. * @param[in] bdata The backend module data * @param[out] caps The capture capabilities of a backend module * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see tdm_backend_register_func_capture + * @remark + * TDM calls this function not only at the initial time, but also at the update + * time when new output is connected.\n + * A backend module doesn't need to implement this function if a hardware + * doesn't have the capture device. Otherwise, a backend module @b SHOULD fill the + * #tdm_caps_capture data. #tdm_caps_capture contains the hardware restriction + * information which a capture device can handle. ie, format, size, etc. */ tdm_error (*display_get_capture_capability)(tdm_backend_data *bdata, tdm_caps_capture *caps); /** * @brief Get a output array of a backend module - * @details A backend module @b SHOULD return the newly-allocated output array. - * it will be freed in frontend. * @param[in] bdata The backend module data * @param[out] count The count of outputs * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. - * @return A output array which is newly-allocated + * @return A output array which is @b newly-allocated * @see tdm_backend_register_func_capture + * @remark + * A backend module @b SHOULD implement this function. TDM calls this function + * not only at the initial time, but also at the update time when new output + * is connected.\n + * A backend module @b SHOULD return the @b newly-allocated array which contains + * "tdm_output*" data. It will be freed in frontend. + * @par Example + * @code + tdm_output** + drm_display_get_outputs(tdm_backend_data *bdata, int *count, tdm_error *error) + { + tdm_drm_data *drm_data = bdata; + tdm_drm_output_data *output_data = NULL; + tdm_output **outputs; + int i; + + (*count) = 0; + LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link) + (*count)++; + + if ((*count) == 0) + { + if (error) *error = TDM_ERROR_NONE; + return NULL; + } + + // will be freed in frontend + outputs = calloc(*count, sizeof(tdm_drm_output_data*)); + if (!outputs) + { + (*count) = 0; + if (error) *error = TDM_ERROR_OUT_OF_MEMORY; + return NULL; + } + + i = 0; + LIST_FOR_EACH_ENTRY(output_data, &drm_data->output_list, link) + outputs[i++] = output_data; + + if (error) *error = TDM_ERROR_NONE; + + return outputs; + } + * @endcode */ tdm_output **(*display_get_outputs)(tdm_backend_data *bdata, int *count, tdm_error *error); /** * @brief Get the file descriptor of a backend module - * @details If a backend module handles one more fds, a backend module can return epoll's fd - * which is watching backend device fds. * @param[in] bdata The backend module data * @param[out] fd The fd of a backend module * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see display_handle_events() function of #tdm_func_display + * @remark + * A backend module can return epoll's fd which is watching the backend device one more fds. */ tdm_error (*display_get_fd)(tdm_backend_data *bdata, int *fd); /** - * @brief Handle the events which happen on the fd of a backend module + * @brief Handle the events which happens on the fd of a backend module * @param[in] bdata The backend module data * @return #TDM_ERROR_NONE if success. Otherwise, error value. */ @@ -253,26 +294,38 @@ typedef struct _tdm_func_display * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. * @return A pp object * @see pp_destroy() function of #tdm_func_pp + * @remark + * A backend module doesn't need to implement this function if a hardware + * doesn't have the memory-to-memory converting device. */ tdm_pp* (*display_create_pp)(tdm_backend_data *bdata, tdm_error *error); /** * @brief Get the capabilities of a output object - * #tdm_caps_output containes connection, modes, avaiable properties, size restriction information, etc. * @param[in] output A output object * @param[out] caps The capabilities of a output object * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @remark + * A backend module @b SHOULD implement this function. TDM calls this function + * not only at the initial time, but also at the update time when new output + * is connected.\n + * #tdm_caps_output contains connection status, modes, avaiable properties, + * size restriction information, etc. */ tdm_error (*output_get_capability)(tdm_output *output, tdm_caps_output *caps); /** * @brief Get a layer array of a output object - * @details A backend module @b SHOULD return the newly-allocated layer array. - * it will be freed in frontend. * @param[in] output A output object * @param[out] count The count of layers * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. - * @return A layer array which is newly-allocated + * @return A layer array which is @b newly-allocated + * @remark + * A backend module @b SHOULD implement this function. TDM calls this function + * not only at the initial time, but also at the update time when new output + * is connected.\n + * A backend module @b SHOULD return the @b newly-allocated array which contains + * "tdm_layer*" data. It will be freed in frontend. */ tdm_layer **(*output_get_layers)(tdm_output *output, int *count, tdm_error *error); @@ -296,14 +349,14 @@ typedef struct _tdm_func_display /** * @brief Wait for VBLANK - * @remark After interval vblanks, a backend module @b SHOULD call a user - * vblank handler. * @param[in] output A output object * @param[in] interval vblank interval * @param[in] sync 0: asynchronous, 1:synchronous * @param[in] user_data The user data * @return #TDM_ERROR_NONE if success. Otherwise, error value. - * @see #tdm_output_vblank_handler + * @see output_set_vblank_handler, tdm_output_vblank_handler + * @remark + * A backend module @b SHOULD call a user vblank handler after interval vblanks. */ tdm_error (*output_wait_vblank)(tdm_output *output, int interval, int sync, void *user_data); @@ -317,12 +370,14 @@ typedef struct _tdm_func_display /** * @brief Commit changes for a output object - * @remark After all change of a output object are applied, a backend module - * @b SHOULD call a user commit handler. * @param[in] output A output object * @param[in] sync 0: asynchronous, 1:synchronous * @param[in] user_data The user data * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @see output_set_commit_handler, tdm_output_commit_handler + * @remark + * A backend module @b SHOULD call a user commit handler after all change of + * a output object are applied. */ tdm_error (*output_commit)(tdm_output *output, int sync, void *user_data); @@ -372,15 +427,22 @@ typedef struct _tdm_func_display * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. * @return A capture object * @see capture_destroy() function of #tdm_func_capture + * @remark + * A backend module doesn't need to implement this function if a hardware + * doesn't have the capture device. */ tdm_capture *(*output_create_capture)(tdm_output *output, tdm_error *error); /** * @brief Get the capabilities of a layer object - * #tdm_caps_layer containes avaiable formats/properties, zpos information, etc. * @param[in] layer A layer object * @param[out] caps The capabilities of a layer object * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @remark + * A backend module @b SHOULD implement this function. TDM calls this function + * not only at the initial time, but also at the update time when new output + * is connected.\n + * #tdm_caps_layer contains avaiable formats/properties, zpos information, etc. */ tdm_error (*layer_get_capability)(tdm_layer *layer, tdm_caps_layer *caps); @@ -404,12 +466,13 @@ typedef struct _tdm_func_display /** * @brief Set the geometry information to a layer object - * @details The geometry information will be applied when the output object - * of a layer object is committed. * @param[in] layer A layer object * @param[in] info The geometry information * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see output_commit() function of #tdm_func_display + * @remark + * A backend module would apply the geometry information when the output object + * of a layer object is committed. */ tdm_error (*layer_set_info)(tdm_layer *layer, tdm_info_layer *info); @@ -423,32 +486,45 @@ typedef struct _tdm_func_display /** * @brief Set a TDM buffer to a layer object - * @details A TDM buffer will be applied when the output object - * of a layer object is committed. * @param[in] layer A layer object * @param[in] buffer A TDM buffer * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see output_commit() function of #tdm_func_display + * @remark + * A backend module would apply a TDM buffer when the output object + * of a layer object is committed. */ tdm_error (*layer_set_buffer)(tdm_layer *layer, tbm_surface_h buffer); /** * @brief Unset a TDM buffer from a layer object - * @details When this function is called, a current showing buffer will be - * disappeared from screen. Then nothing is showing on a layer object. * @param[in] layer A layer object * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @remark + * A backend module @b SHOULD hide the current showing buffer from screen. + * If needed, cleanup a layer object resource. */ tdm_error (*layer_unset_buffer)(tdm_layer *layer); /** * @brief Set the zpos for a VIDEO layer object - * @details Especially this function is for a VIDEO layer. The zpos of - * GRAPHIC layers can't be changed. * @param[in] layer A layer object * @param[in] zpos z-order * @return #TDM_ERROR_NONE if success. Otherwise, error value. - * @see tdm_layer_capability + * @see tdm_caps_layer, tdm_layer_capability + * @remark + * A backend module doesn't need to implement this function if a backend + * module doesn't have VIDEO layers.\n + * This function is for VIDEO layers. + * GRAPHIC layers are non-changeable. The zpos of GRAPHIC layers starts + * from 0. If there are 4 GRAPHIC layers, The zpos SHOULD be 0, 1, 2, 3.\n + * But the zpos of VIDEO layer is changeable. And The zpos of VIDEO layers + * is less than GRAPHIC layers or more than GRAPHIC layers. + * ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4). + * The zpos of VIDEO layers is @b relative. It doesn't need to start + * from -1 or 4. Let's suppose that there are two VIDEO layers. + * One has -2 zpos. Another has -4 zpos. Then -2 Video layer is higher + * than -4 VIDEO layer. */ tdm_error (*layer_set_video_pos)(tdm_layer *layer, int zpos); @@ -458,6 +534,9 @@ typedef struct _tdm_func_display * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. * @return A capture object * @see capture_destroy() function of #tdm_func_capture + * @remark + * A backend module doesn't need to implement this function if a hardware + * doesn't have the capture device. */ tdm_capture *(*layer_create_capture)(tdm_layer *layer, tdm_error *error); } tdm_func_display; @@ -481,25 +560,29 @@ typedef struct _tdm_func_pp /** * @brief Set the geometry information to a pp object - * @details The geometry information will be applied when the pp object is committed. * @param[in] pp A pp object * @param[in] info The geometry information * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see pp_commit() function of #tdm_func_pp + * @remark + * A backend module would apply the geometry information when committed. */ tdm_error (*pp_set_info)(tdm_pp *pp, tdm_info_pp *info); /** * @brief Attach a source buffer and a destination buffer to a pp object - * @details When pp_commit() function is called, a backend module converts - * the image of a source buffer to a destination buffer. * @param[in] pp A pp object * @param[in] src A source buffer * @param[in] dst A destination buffer * @return #TDM_ERROR_NONE if success. Otherwise, error value. - * @see tdm_pp_done_handler * @see pp_set_info() function of #tdm_func_pp * @see pp_commit() function of #tdm_func_pp + * @see pp_set_done_handler, tdm_pp_done_handler + * @remark + * A backend module converts the image of a source buffer to a destination + * buffer when committed. The size/crop/transform information is set via + * #pp_set_info() of #tdm_func_pp. When done, a backend module @b SHOULD + * return the source/destination buffer via tdm_pp_done_handler. */ tdm_error (*pp_attach)(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst); @@ -516,7 +599,8 @@ typedef struct _tdm_func_pp * @param[in] func A user done handler * @param[in] user_data user data * @return #TDM_ERROR_NONE if success. Otherwise, error value. - * @remark When pp operation is done, a backend module @b SHOULD call #tdm_pp_done_handler. + * @remark + * A backend module @b SHOULD call #tdm_pp_done_handler when converintg a image is done. */ tdm_error (*pp_set_done_handler)(tdm_pp *pp, tdm_pp_done_handler func, void *user_data); } tdm_func_pp; @@ -541,11 +625,12 @@ typedef struct _tdm_func_capture /** * @brief Set the geometry information to a capture object - * @details The geometry information will be applied when the capture object is committed. * @param[in] capture A capture object * @param[in] info The geometry information * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see capture_commit() function of #tdm_func_capture + * @remark + * A backend module would apply the geometry information when committed. */ tdm_error (*capture_set_info)(tdm_capture *capture, tdm_info_capture *info); @@ -556,8 +641,14 @@ typedef struct _tdm_func_capture * @param[in] capture A capture object * @param[in] buffer A TDM buffer * @return #TDM_ERROR_NONE if success. Otherwise, error value. - * @see tdm_capture_done_handler + * @see capture_set_info() function of #tdm_func_capture * @see capture_commit() function of #tdm_func_capture + * @see capture_set_done_handler, tdm_capture_done_handler + * @remark + * A backend module dumps a output or a layer to to a TDM buffer when + * committed. The size/crop/transform information is set via #capture_set_info() + * of #tdm_func_capture. When done, a backend module @b SHOULD return the TDM + * buffer via tdm_capture_done_handler. */ tdm_error (*capture_attach)(tdm_capture *capture, tbm_surface_h buffer); @@ -574,7 +665,8 @@ typedef struct _tdm_func_capture * @param[in] func A user done handler * @param[in] user_data user data * @return #TDM_ERROR_NONE if success. Otherwise, error value. - * @remark When capture operation is done, a backend module @b SHOULD call #tdm_capture_done_handler. + * @remark + * A backend module @b SHOULD call #tdm_capture_done_handler when capture operation is done. */ tdm_error (*capture_set_done_handler)(tdm_capture *capture, tdm_capture_done_handler func, void *user_data); } tdm_func_capture; @@ -600,7 +692,7 @@ typedef struct _tdm_func_capture /** * @brief The backend module information of the entry point to initialize a TDM * backend module. - * @details + * @remark * A backend module @b SHOULD define the global data symbol of which name is * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data", * at the initial time and call init() function of #tdm_backend_module. @@ -629,36 +721,36 @@ typedef struct _tdm_backend_module /** * @brief Register the backend display functions to a display - * @details - * A backend module @b SHOULD set the backend display functions at least. * @param[in] dpy A display object * @param[in] func_display display functions * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see tdm_backend_register_func_pp, tdm_backend_register_func_capture + * @remarks + * A backend module @b SHOULD set the backend display functions at least. */ tdm_error tdm_backend_register_func_display(tdm_display *dpy, tdm_func_display *func_display); /** * @brief Register the backend pp functions to a display - * @details - * A backend module can skip to register the backend pp functions - * if hardware device doesn't supports the memory to memory converting. * @param[in] dpy A display object * @param[in] func_pp pp functions * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see tdm_backend_register_func_display, tdm_backend_register_func_capture + * @remark + * A backend module doesn'tcan skip to register the backend pp functions + * if a hardware doesn't have the memory-to-memory converting device. */ tdm_error tdm_backend_register_func_pp(tdm_display *dpy, tdm_func_pp *func_pp); /** * @brief Register the backend capture functions to a display - * @details - * A backend module can skip to register the backend capture functions - * if hardware device doesn't supports the memory to memory converting. * @param[in] dpy A display object * @param[in] func_capture capture functions * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see tdm_backend_register_func_display, tdm_backend_register_func_pp + * @remark + * A backend module can skip to register the backend capture functions + * if a hardware doesn't have the capture device. */ tdm_error tdm_backend_register_func_capture(tdm_display *dpy, tdm_func_capture *func_capture); @@ -671,11 +763,11 @@ tdm_error tdm_backend_register_func_capture(tdm_display *dpy, tdm_func_capture * * TDM will release it immediately when TDM doesn't need it any more. * @param[in] buffer A TDM buffer * @return A buffer itself. Otherwise, NULL. + * @see tdm_buffer_unref_backend * @remark * - This function @b SHOULD be paired with #tdm_buffer_unref_backend. \n * - For example, this function @b SHOULD be called in case that a backend module uses the TDM * buffer of a layer for capturing a output or a layer to avoid tearing issue. - * @see tdm_buffer_unref_backend */ tbm_surface_h tdm_buffer_ref_backend(tbm_surface_h buffer); @@ -696,15 +788,15 @@ typedef void (*tdm_buffer_destroy_handler)(tbm_surface_h buffer, void *user_data /** * @brief Add a destroy handler to a TDM buffer - * @details - * A backend module can add a TDM buffer destroy handler to a TDM buffer which - * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will - * be called. * @param[in] buffer A TDM buffer * @param[in] func A destroy handler * @param[in] user_data user data * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see tdm_buffer_remove_destroy_handler + * @remark + * A backend module can add a TDM buffer destroy handler to a TDM buffer which + * is a #tbm_surface_h object. When the TDM buffer is destroyed, this handler will + * be called. */ tdm_error tdm_buffer_add_destroy_handler(tbm_surface_h buffer, tdm_buffer_destroy_handler func, void *user_data); diff --git a/include/tdm_types.h b/include/tdm_types.h index 33c8488a..120137a0 100644 --- a/include/tdm_types.h +++ b/include/tdm_types.h @@ -160,10 +160,6 @@ typedef enum * - But in case that s vendor wants to handle a video by their own way, * a backend module offer VIDEO layers. And a display server will pass a video * buffer to a VIDEO layer without converting. - * - GRAPHIC layers have fixed zpos. But the zpos of VIDEO layer will be decided - * by a backend module side. - * - The frontend only can set the relative zpos to - * VIDEO layers via layer_set_video_pos() function of #tdm_func_display */ typedef enum {