--- /dev/null
+/**************************************************************************
+
+libtdm
+
+Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
+
+Contact: Eunchul Kim <chulspro.kim@samsung.com>,
+ JinYoung Jeon <jy0.jeon@samsung.com>,
+ Taeheon Kim <th908.kim@samsung.com>,
+ YoungJun Cho <yj44.cho@samsung.com>,
+ SooChan Lim <sc1.lim@samsung.com>,
+ Boram Park <sc1.lim@samsung.com>
+
+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 <tdm_backend.h>
+
+ 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 <tdm_backend.h> explains what things should be
+ * careful for vendor to implement a TDM backend module.
+ */
+
+#endif /* _TDM_DOC_H_ */
* @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
/**
* @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
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) */
/**
* @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
/**
* 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
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" */
/**
* @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
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" */
{
/**
* @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.
*/
* @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);
/**
* @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);
/**
* @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);
* @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);
/**
* @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);
/**
* @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);
* @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;
/**
* @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);
* @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;
/**
* @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);
* @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);
* @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;
/**
* @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.
/**
* @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);
* 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);
/**
* @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);
projects / platform / core / uifw / libtdm.git / commitdiff