From: jinbong.lee Date: Tue, 7 Jan 2025 06:47:47 +0000 (+0900) Subject: Add description for doxygen X-Git-Tag: accepted/tizen/unified/20250109.175139~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=fe5df4828fd8ed2225bf372baa7ef790c52d96a6;p=platform%2Fhal%2Fapi%2Ftdm.git Add description for doxygen Change-Id: Ibc455e92b335f2931f5b6322e6bcd606abf3c043 Signed-off-by: jinbong.lee --- diff --git a/COPYING b/COPYING deleted file mode 100644 index ccee209..0000000 --- a/COPYING +++ /dev/null @@ -1,21 +0,0 @@ -Copyright 2021 Samsung Electronics co., Ltd. All Rights Reserved. - -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. diff --git a/LICENSE b/LICENSE index b28ce08..ccee209 100644 --- a/LICENSE +++ b/LICENSE @@ -1,20 +1,21 @@ +Copyright 2021 Samsung Electronics co., Ltd. All Rights Reserved. -Copyright (c) 2021 Samsung Electronics co., Ltd. All Rights Reserved. +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: -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, sublicense, 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 above copyright notice and this permission notice 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 NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS 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. +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. diff --git a/doc/hal_tdm_doc.h b/doc/hal_tdm_doc.h index 8eb2867..c11329e 100644 --- a/doc/hal_tdm_doc.h +++ b/doc/hal_tdm_doc.h @@ -42,14 +42,14 @@ /** * @defgroup HALAPI_HAL_TDM_MODULE TDM - * @brief The @ref HALAPI_HAL_API_TDM provides functions for managing display server. + * @brief The @ref HALAPI_HAL_TDM_MODULE provides functions for managing display server. * - * @section HALAPI_HAL_API_TDM_HEADER Required Header + * @section HALAPI_HAL_TDM_MODULE_HEADER Required Header * \#include * * @section HALAPI_HAL_TDM_MODULE_OVERVIEW Overview * The TDM functions provides an abstraction interface for display server including: - * - Display server interface to user like getting display capablilities, size, format. + * - Display server interface to user like getting display capabilities, size, format. * - Display control interface like display mode setting, dpms, capture. * * For more information on the TDM features and the macros, see HAL TDM programming guides and tutorials. diff --git a/include/hal-tdm-interface-1.h b/include/hal-tdm-interface-1.h index 9550645..be32abc 100644 --- a/include/hal-tdm-interface-1.h +++ b/include/hal-tdm-interface-1.h @@ -45,137 +45,382 @@ extern "C" { #endif +/** + * @file hal-tdm-interface-1.h + * @brief This file contains the backend interface of TDM, related structures and enumerations. + * @since HAL_MODULE_TDM 1.0 + */ + +/** + * @addtogroup HALAPI_HAL_TDM_MODULE + * @{ + */ + +/** + * @brief The structure type of the tdm backend data. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_backend_data + */ typedef struct _hal_tdm_backend_data hal_tdm_backend_data; +/** + * @brief The structure type of the TDM HAL's display functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_display_funcs + */ typedef struct _hal_tdm_display_funcs hal_tdm_display_funcs; + +/** + * @brief The structure type of the TDM HAL's output functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_output_funcs + */ typedef struct _hal_tdm_output_funcs hal_tdm_output_funcs; + +/** + * @brief The structure type of the TDM HAL's hwc functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_hwc_funcs + */ typedef struct _hal_tdm_hwc_funcs hal_tdm_hwc_funcs; + +/** + * @brief The structure type of the TDM HAL's hwc window functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_hwc_window_funcs + */ typedef struct _hal_tdm_hwc_window_funcs hal_tdm_hwc_window_funcs; + +/** + * @brief The structure type of the TDM HAL's post-processing functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_pp_funcs + */ typedef struct _hal_tdm_pp_funcs hal_tdm_pp_funcs; + +/** + * @brief The structure type of the TDM HAL's capture functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_capture_funcs + */ typedef struct _hal_tdm_capture_funcs hal_tdm_capture_funcs; + +/** + * @brief The structure type of the TDM HAL's virtual output functions for backend. + * @since HAL_MODULE_TDM 1.0 + * @see #_hal_tdm_voutput_funcs + */ typedef struct _hal_tdm_voutput_funcs hal_tdm_voutput_funcs; +/** + * @brief The function for setting master_drm_fd to backend. + * @since HAL_MODULE_TDM 1.0 + * @param[in] master_drm_fd The master drm file descriptor. + * @param[in] user_data The user data for handler. + * @pre hal_tdm_backend_set_master_drm_fd() will invoke this handler. + * @see hal_tdm_backend_set_master_drm_fd(). + * @see hal_tdm_backend_get_master_drm_fd(). + */ typedef hal_tdm_error (*hal_tdm_master_drm_fd_handler)(hal_tdm_fd master_drm_fd, void *user_data); +/** + * @brief The structure type of the tdm backend data. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_backend_data { - hal_tdm_display *display; // handle + hal_tdm_display *display; /**< The handle of display */ - int has_drm_device; + int has_drm_device; /**< The flag of having drm device or not */ struct { - hal_tdm_fd drm_fd; - int is_master; - hal_tdm_master_drm_fd_handler master_drm_fd_func; - void *user_data; + hal_tdm_fd drm_fd; /**< The drm file descriptor */ + int is_master; /**< The flag of master or not */ + hal_tdm_master_drm_fd_handler master_drm_fd_func; /**< The handler function for setting master drm file descriptor. */ + void *user_data; /**< The user data for callback */ } drm_info; - int num_event_sources; - hal_tdm_event_source *event_sources[HAL_TDM_EVENT_SOURCE_MAX]; + int num_event_sources; /**< The number of event source */ + hal_tdm_event_source *event_sources[HAL_TDM_EVENT_SOURCE_MAX]; /**< The event source array */ - hal_tdm_display_funcs *display_funcs; - hal_tdm_output_funcs *output_funcs; - hal_tdm_hwc_funcs *hwc_funcs; - hal_tdm_hwc_window_funcs *hwc_window_funcs; - hal_tdm_pp_funcs *pp_funcs; - hal_tdm_capture_funcs *capture_funcs; - hal_tdm_voutput_funcs *voutput_funcs; + hal_tdm_display_funcs *display_funcs; /**< display functions of backend */ + hal_tdm_output_funcs *output_funcs; /**< output functions of backend */ + hal_tdm_hwc_funcs *hwc_funcs; /**< hwc functions of backend */ + hal_tdm_hwc_window_funcs *hwc_window_funcs; /**< hwc_window functions of backend */ + hal_tdm_pp_funcs *pp_funcs; /**< post-processing functions of backend */ + hal_tdm_capture_funcs *capture_funcs; /**< capture functions of backend */ + hal_tdm_voutput_funcs *voutput_funcs; /**< voutput functions of backend */ }; +/** + * @brief The structure type of the TDM HAL's display functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_display_funcs { + /**< Get the display capabilities of hal_tdm_display. */ hal_tdm_error (*display_get_capability)(hal_tdm_display *display, hal_tdm_caps_display *caps); + + /**< Get the post-processing capabilities of hal_tdm_display. */ hal_tdm_error (*display_get_pp_capability)(hal_tdm_display *display, hal_tdm_caps_pp *caps); + + /**< Get the capture capabilities of the hal_tdm_display. */ hal_tdm_error (*display_get_capture_capability)(hal_tdm_display *display, hal_tdm_caps_capture *caps); + + /**< Get the output array of hal_tdm_display. */ hal_tdm_output **(*display_get_outputs)(hal_tdm_display *display, int *count, hal_tdm_error *error); + + /**< Get the file descriptor of hal_tdm_display. */ hal_tdm_error (*display_get_fd)(hal_tdm_display *display, int *fd); + + /**< Handle the events which happens on the fd of hal_tdm_display. */ hal_tdm_error (*display_handle_events)(hal_tdm_display *display); + + /**< Create the post-processing object of hal_tdm_display. */ hal_tdm_pp *(*display_create_pp)(hal_tdm_display *display, hal_tdm_error *error); + + /**< Create the virtual output object of hal_tdm_display. */ hal_tdm_voutput *(*display_voutput_create)(hal_tdm_display *display, const char *name, hal_tdm_error *error); }; +/** + * @brief The structure type of the TDM HAL's output functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_output_funcs { + /**< Get the capabilities of the hal_tdm_output object. */ hal_tdm_error (*output_get_capability)(hal_tdm_output *output, hal_tdm_caps_output *caps); + + /**< Set the output's property which has the given id. */ hal_tdm_error (*output_set_property)(hal_tdm_output *output, unsigned int id, hal_tdm_value value); + + /**< Get the output's property which has the given id. */ hal_tdm_error (*output_get_property)(hal_tdm_output *output, unsigned int id, hal_tdm_value *value); + + /**< Wait for VBLANK of output. */ hal_tdm_error (*output_wait_vblank)(hal_tdm_output *output, int interval, int sync, void *user_data); + + /**< Set the handler of vblank. */ hal_tdm_error (*output_set_vblank_handler)(hal_tdm_output *output, hal_tdm_output_vblank_handler func); + + /**< Set DPMS of the output object synchronously. */ hal_tdm_error (*output_set_dpms)(hal_tdm_output *output, hal_tdm_output_dpms dpms_value); + + /**< Get DPMS of the output object. */ hal_tdm_error (*output_get_dpms)(hal_tdm_output *output, hal_tdm_output_dpms *dpms_value); + + /**< Set one of available modes of the output object. */ hal_tdm_error (*output_set_mode)(hal_tdm_output *output, const hal_tdm_output_mode *mode); + + /**< Get the mode of the output object. */ hal_tdm_error (*output_get_mode)(hal_tdm_output *output, const hal_tdm_output_mode **mode); + + /**< Create the capture object from the output object. */ hal_tdm_capture *(*output_create_capture)(hal_tdm_output *output, hal_tdm_error *error); + + /**< Set the output connection status handler. */ hal_tdm_error (*output_set_status_handler)(hal_tdm_output *output, hal_tdm_output_status_handler func, void *user_data); + + /**< Set the output's dpms handler. */ hal_tdm_error (*output_set_dpms_handler)(hal_tdm_output *output, hal_tdm_output_dpms_handler func, void *user_data); + + /**< Set DPMS of the output object asynchronously. */ hal_tdm_error (*output_set_dpms_async)(hal_tdm_output *output, hal_tdm_output_dpms dpms_value, int *sync); + + /**< Get the hwc object of the output object. */ hal_tdm_hwc *(*output_get_hwc)(hal_tdm_output *output, hal_tdm_error *error); + + /**< Set the mirror image of the src_output to the output. */ hal_tdm_error (*output_set_mirror)(hal_tdm_output *output, hal_tdm_output *src_output, hal_tdm_transform transform); + + /**< Unset the mirror image. */ hal_tdm_error (*output_unset_mirror)(hal_tdm_output *output); }; +/** + * @brief The structure type of the TDM HAL's virtual output functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_voutput_funcs { + /**< Destroy the virtual output object of the backend module. */ hal_tdm_error (*voutput_destroy)(hal_tdm_voutput *voutput); + + /**< Set available modes of the virtual output object. */ hal_tdm_error (*voutput_set_available_mode)(hal_tdm_voutput *voutput, const hal_tdm_output_mode *modes, int count); + + /**< Set physical size(mm) of the virtual output object. */ hal_tdm_error (*voutput_set_physical_size)(hal_tdm_voutput *voutput, unsigned int mmwidth, unsigned int mmheight); + + /**< Set connect status of the virtual output object. */ hal_tdm_error (*voutput_connect)(hal_tdm_voutput *voutput); + + /**< Set disconnect status of the virtual output object. */ hal_tdm_error (*voutput_disconnect)(hal_tdm_voutput *voutput); + + /**< Get output object from virtual output object. */ hal_tdm_output *(*voutput_get_output)(hal_tdm_voutput *voutput, hal_tdm_error *error); + + /**< Set the user commit function */ hal_tdm_error (*voutput_set_commit_func)(hal_tdm_voutput *voutput, hal_tdm_voutput_commit_handler commit_func); + + /**< Notify commit done to backend. */ hal_tdm_error (*voutput_commit_done)(hal_tdm_voutput *voutput); + + /**< Set target buffer queue flag of the virtual output's hwc object */ hal_tdm_error (*voutput_set_target_buffer_queue_flag)(hal_tdm_voutput *voutput, int flags); }; +/** + * @brief The structure type of the TDM HAL's hwc functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_hwc_funcs { + /**< Create a new window on the given hwc. */ hal_tdm_hwc_window *(*hwc_create_window)(hal_tdm_hwc *hwc, hal_tdm_error *error); + + /**< Get video the supported format array for the hwc windows of the hwc object. */ hal_tdm_error (*hwc_get_video_supported_formats)(hal_tdm_hwc *hwc, const tbm_format **formats, int *count); + + /**< Get the available video property array of the hwc object. */ hal_tdm_error (*hwc_get_video_available_properties)(hal_tdm_hwc *hwc, const hal_tdm_prop **props, int *count); + + /**< Get the hwc capabilities. */ hal_tdm_error (*hwc_get_capabilities)(hal_tdm_hwc *hwc, hal_tdm_hwc_capability *capabilities); + + /**< Get the available property array of the hwc object. */ hal_tdm_error (*hwc_get_available_properties)(hal_tdm_hwc *hwc, const hal_tdm_prop **props, int *count); + + /**< Get the client target buffer queue. */ tbm_surface_queue_h (*hwc_get_client_target_buffer_queue)(hal_tdm_hwc *hwc, hal_tdm_error *error); + + /**< Set the client target buffer. */ hal_tdm_error (*hwc_set_client_target_buffer)(hal_tdm_hwc *hwc, tbm_surface_h target_buffer, hal_tdm_region damage); + + /**< Set the acquire fence of client target buffer. */ hal_tdm_error (*hwc_set_client_target_acquire_fence)(hal_tdm_hwc *hwc, int acquire_fence); + + /**< Validate the hwc. */ hal_tdm_error (*hwc_validate)(hal_tdm_hwc *hwc, hal_tdm_hwc_window **composited_wnds, uint32_t num_wnds, uint32_t *num_types); + + /**< Get changed composition types. */ hal_tdm_error (*hwc_get_changed_composition_types)(hal_tdm_hwc *hwc, uint32_t *num_elements, hal_tdm_hwc_window **hwc_window, hal_tdm_hwc_window_composition *composition_types); + + /**< Accepts the validation required by the backend. */ hal_tdm_error (*hwc_accept_validation)(hal_tdm_hwc *hwc); + + /**< Commit changes for the hwc object. */ hal_tdm_error (*hwc_commit)(hal_tdm_hwc *hwc, int sync, void *user_data); + + /**< Set the user commit handler. */ hal_tdm_error (*hwc_set_commit_handler)(hal_tdm_hwc *hwc, hal_tdm_hwc_commit_handler func); + + /**< Get commit fence. */ hal_tdm_error (*hwc_get_commit_fence)(hal_tdm_hwc *hwc, int *commit_fence); + + /**< Get release fences. */ hal_tdm_error (*hwc_get_release_fences)(hal_tdm_hwc *hwc, uint32_t *num_elements, hal_tdm_hwc_window **hwc_windows, int *release_fences); + + /**< Set the property which has the given id on the hwc object. */ hal_tdm_error (*hwc_set_property)(hal_tdm_hwc *hwc, uint32_t id, hal_tdm_value value); + + /**< Get the property which has the given id on the hwc object. */ hal_tdm_error (*hwc_get_property)(hal_tdm_hwc *hwc, uint32_t id, hal_tdm_value *value); + + /**< Get the commit interval. */ hal_tdm_error (*hwc_get_commit_interval)(hal_tdm_hwc *hwc, hal_tdm_hwc_commit_interval *interval); + + /**< Set the information of the client target buffer. */ hal_tdm_error (*hwc_set_client_target_buffer_info)(hal_tdm_hwc *hwc, hal_tdm_hwc_window_info *info); }; +/** + * @brief The structure type of the TDM HAL's hwc window functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_hwc_window_funcs { + /**< Destroys the given window. */ void (*hwc_window_destroy)(hal_tdm_hwc_window *hwc_window); + + /**< Acquire the buffer queue handle for the window object. */ tbm_surface_queue_h (*hwc_window_acquire_buffer_queue)(hal_tdm_hwc_window *hwc_window, hal_tdm_error *error); + + /**< Release the buffer queue for the window object. */ void (*hwc_window_release_buffer_queue)(hal_tdm_hwc_window *hwc_window, tbm_surface_queue_h queue); + + /**< Sets the desired composition type of the given window. */ hal_tdm_error (*hwc_window_set_composition_type)(hal_tdm_hwc_window *hwc_window, hal_tdm_hwc_window_composition composition_type); + + /**< Set the buffer damage. */ hal_tdm_error (*hwc_window_set_buffer_damage)(hal_tdm_hwc_window *hwc_window, hal_tdm_region damage); + + /**< Set the information to the window object. */ hal_tdm_error (*hwc_window_set_info)(hal_tdm_hwc_window *hwc_window, hal_tdm_hwc_window_info *info); + + /**< Set the TDM buffer to the window object. */ hal_tdm_error (*hwc_window_set_buffer)(hal_tdm_hwc_window *hwc_window, tbm_surface_h buffer); + + /**< Set the property which has the given id. */ hal_tdm_error (*hwc_window_set_property)(hal_tdm_hwc_window *hwc_window, uint32_t id, hal_tdm_value value); + + /**< Get the property which has the given id. */ hal_tdm_error (*hwc_window_get_property)(hal_tdm_hwc_window *hwc_window, uint32_t id, hal_tdm_value *value); + + /**< Get the constraints of hwc_window. */ hal_tdm_error (*hwc_window_get_constraints)(hal_tdm_hwc_window *hwc_window, int *constraints); + + /**< Set the name of hwc_window. */ hal_tdm_error (*hwc_window_set_name)(hal_tdm_hwc_window *hwc_window, const char *name); + + /**< Set the cursor image to hwc_window. */ hal_tdm_error (*hwc_window_set_cursor_image)(hal_tdm_hwc_window *hwc_window, int width, int height, int stride, void *ptr); + + /**< Set the acquire fence of hwc_window. */ hal_tdm_error (*hwc_window_set_acquire_fence)(hal_tdm_hwc_window *hwc_window, int acquire_fence); }; +/** + * @brief The structure type of the TDM HAL's post-processing functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ struct _hal_tdm_pp_funcs { + /**< Destroy the post-processing object. */ void (*pp_destroy)(hal_tdm_pp *pp); + + /**< Set the geometry information to the post-processing object. */ hal_tdm_error (*pp_set_info)(hal_tdm_pp *pp, hal_tdm_info_pp *info); + + /**< Attach the source buffer and the destination buffer to the post-processing object. */ hal_tdm_error (*pp_attach)(hal_tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst); + + /**< Commit changes for the post-processing object. */ hal_tdm_error (*pp_commit)(hal_tdm_pp *pp); + + /**< Set the processing done handler to the post-processing object. */ hal_tdm_error (*pp_set_done_handler)(hal_tdm_pp *pp, hal_tdm_pp_done_handler func, void *user_data); }; +/** + * @brief The structure type of the TDM HAL's capture functions for backend. + * @since HAL_MODULE_TDM 1.0 + */ typedef struct _hal_tdm_capture_funcs { + /**< Destroy the capture object. */ void (*capture_destroy)(hal_tdm_capture *capture); + + /**< Set the geometry information to the capture object. */ hal_tdm_error (*capture_set_info)(hal_tdm_capture *capture, hal_tdm_info_capture *info); + + /**< Attach the TDM buffer to the capture object */ hal_tdm_error (*capture_attach)(hal_tdm_capture *capture, tbm_surface_h buffer); + + /**< Commit changes for the capture object. */ hal_tdm_error (*capture_commit)(hal_tdm_capture *capture); + + /**< Set the capture done handler to the capture object. */ hal_tdm_error (*capture_set_done_handler)(hal_tdm_capture *capture, hal_tdm_capture_done_handler func, void *user_data); } hal_tdm_capture_funcs; +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/include/hal-tdm-types.h b/include/hal-tdm-types.h index 754d062..01c22d7 100644 --- a/include/hal-tdm-types.h +++ b/include/hal-tdm-types.h @@ -46,36 +46,56 @@ extern "C" { /** * @file hal-tdm-types.h * @brief The header file which defines Enumerations and Structures for frontend and backend. - * @details - * Both frontend(@ref hal-tdm.h) and backend(@ref hal-tdm-interface.h) header files + * @since HAL_MODULE_TDM 1.0 + * @details Both frontend(@ref hal-tdm.h) and backend(@ref hal-tdm-interface.h) header files * include @ref hal-tdm-types.h * @par Example * @code - * #include //for a frontend user + * #include //for the frontend user * @endcode * @code - * #include //for a vendor to implement a backend module + * #include //for vendor to implement the backend module * @endcode */ + /** + * @addtogroup HALAPI_HAL_TDM_MODULE + * @{ + */ + +/** + * @brief Definition of Max Name Length in HAL_TDM_MODULE. + * @since HAL_MODULE_TDM 1.0 + */ #define HAL_TDM_NAME_LEN 64 + +/** + * @brief Definition of Max Path Length in HAL_TDM_MODULE. + * @since HAL_MODULE_TDM 1.0 + */ #define HAL_TDM_PATH_LEN 1024 + +/** + * @brief Definition of Max count of event source in HAL_TDM_MODULE. + * @since HAL_MODULE_TDM 1.0 + */ #define HAL_TDM_EVENT_SOURCE_MAX 3 /** * @brief The error enumeration + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - HAL_TDM_ERROR_NONE = 0, /**< none */ - HAL_TDM_ERROR_BAD_REQUEST = -1, /**< bad request */ - HAL_TDM_ERROR_OPERATION_FAILED = -2, /**< operaion failed */ - HAL_TDM_ERROR_INVALID_PARAMETER = -3, /**< wrong input parameter */ - HAL_TDM_ERROR_PERMISSION_DENIED = -4, /**< access denied */ - HAL_TDM_ERROR_BUSY = -5, /**< hardware resource busy */ - HAL_TDM_ERROR_OUT_OF_MEMORY = -6, /**< no free memory */ - HAL_TDM_ERROR_BAD_MODULE = -7, /**< bad backend module */ - HAL_TDM_ERROR_NOT_IMPLEMENTED = -8, /**< not implemented */ - HAL_TDM_ERROR_NO_CAPABILITY = -9, /**< no capability */ + HAL_TDM_ERROR_NONE = 0, /**< none */ + HAL_TDM_ERROR_BAD_REQUEST = -1, /**< bad request */ + HAL_TDM_ERROR_OPERATION_FAILED = -2, /**< operation failed */ + HAL_TDM_ERROR_INVALID_PARAMETER = -3, /**< wrong input parameter */ + HAL_TDM_ERROR_PERMISSION_DENIED = -4, /**< access denied */ + HAL_TDM_ERROR_BUSY = -5, /**< hardware resource busy */ + HAL_TDM_ERROR_OUT_OF_MEMORY = -6, /**< no free memory */ + HAL_TDM_ERROR_BAD_MODULE = -7, /**< bad backend module */ + HAL_TDM_ERROR_NOT_IMPLEMENTED = -8, /**< not implemented */ + HAL_TDM_ERROR_NO_CAPABILITY = -9, /**< no capability */ HAL_TDM_ERROR_DPMS_OFF = -10, /**< dpms off */ HAL_TDM_ERROR_OUTPUT_DISCONNECTED = -11, /**< output disconnected */ HAL_TDM_ERROR_PROTOCOL_ERROR = -12, /**< protocol error */ @@ -85,6 +105,7 @@ typedef enum { /** * @brief The transform enumeration(rotate, flip) + * @since HAL_MODULE_TDM 1.0 */ typedef enum { HAL_TDM_TRANSFORM_NORMAL = 0, /**< no transform */ @@ -99,48 +120,51 @@ typedef enum { /** * @brief The output capability enumeration - * @details - * If a backend module provides #HAL_TDM_OUTPUT_CAPABILITY_EXTENDED_DPMS, we can set - * an extended DPMS mode to an output which a backend module supports. + * @since HAL_MODULE_TDM 1.0 + * @details If the backend module provides #HAL_TDM_OUTPUT_CAPABILITY_EXTENDED_DPMS, + * we can set an extended DPMS mode to an output which the backend module supports. * Don't use the low-4bit for an extended DPMS mode value. It's used for default * DPMS modes. */ typedef enum { - HAL_TDM_OUTPUT_CAPABILITY_ASYNC_DPMS = (1 << 0), /**< if a outupt supports asynchronous DPMS operation */ - HAL_TDM_OUTPUT_CAPABILITY_HWC = (1 << 1), /**< if a outupt supports hwc operation */ - HAL_TDM_OUTPUT_CAPABILITY_EXTENDED_DPMS = (1 << 2), /**< if a outupt supports extended DPMS operation */ - HAL_TDM_OUTPUT_CAPABILITY_MIRROR = (1 << 3), /**< if a outupt supports the displying mirror image of the src_output */ - HAL_TDM_OUTPUT_CAPABILITY_NO_HW_VBLANK = (1 << 4), /**< if a outupt doesn't support hw vblank */ + HAL_TDM_OUTPUT_CAPABILITY_ASYNC_DPMS = (1 << 0), /**< The capability about output supports asynchronous DPMS operation */ + HAL_TDM_OUTPUT_CAPABILITY_HWC = (1 << 1), /**< The capability about output supports hwc operation */ + HAL_TDM_OUTPUT_CAPABILITY_EXTENDED_DPMS = (1 << 2), /**< The capability about output supports extended DPMS operation */ + HAL_TDM_OUTPUT_CAPABILITY_MIRROR = (1 << 3), /**< The capability about output supports the displaying mirror image of the src_output */ + HAL_TDM_OUTPUT_CAPABILITY_NO_HW_VBLANK = (1 << 4), /**< The capability about output doesn't support hw vblank */ } hal_tdm_output_capability; /** - * @brief The pp capability enumeration + * @brief The PP(post-processing) capability enumeration + * @since HAL_MODULE_TDM 1.0 * @details The scale, transform and CSC functionalities seem the default functions of PP. - * If hardware device doesn't support one of them, we'd better let a developer know - * what a backend doesn't support like TDM_PP_CAPABILITY_NO_CSC. + * If hardware device doesn't support one of them, we'd better let the developer know + * what the backend doesn't support like #HAL_TDM_PP_CAPABILITY_NO_CSC. */ typedef enum { - HAL_TDM_PP_CAPABILITY_SYNC = (1 << 0), /**< The pp device supports synchronous operation */ - HAL_TDM_PP_CAPABILITY_ASYNC = (1 << 1), /**< The pp device supports asynchronous operation */ - HAL_TDM_PP_CAPABILITY_SCANOUT = (1 << 4), /**< The pp device supports only scanout buffer */ - HAL_TDM_PP_CAPABILITY_NO_CSC = (1 << 5), /**< The pp device doesn't support Color Space Conversion */ - HAL_TDM_PP_CAPABILITY_NO_TRANSFORM_ROTATION = (1 << 6), /**< The pp device doesn't support rotation transform */ + HAL_TDM_PP_CAPABILITY_SYNC = (1 << 0), /**< The post-processing device supports synchronous operation */ + HAL_TDM_PP_CAPABILITY_ASYNC = (1 << 1), /**< The post-processing device supports asynchronous operation */ + HAL_TDM_PP_CAPABILITY_SCANOUT = (1 << 4), /**< The post-processing device supports only scanout buffer */ + HAL_TDM_PP_CAPABILITY_NO_CSC = (1 << 5), /**< The post-processing device doesn't support Color Space Conversion */ + HAL_TDM_PP_CAPABILITY_NO_TRANSFORM_ROTATION = (1 << 6), /**< The post-processing device doesn't support rotation transform */ } hal_tdm_pp_capability; /** * @brief The capture capability enumeration + * @since HAL_MODULE_TDM 1.0 * @details The scale, transform and CSC functionalities seem the default functions of capture. - * If hardware device doesn't support one of them, we'd better let a developer know - * what a backend doesn't support like TDM_PP_CAPABILITY_NO_CSC. + * If hardware device doesn't support one of them, we'd better let the developer know + * what the backend doesn't support like #HAL_TDM_PP_CAPABILITY_NO_CSC. */ typedef enum { - HAL_TDM_CAPTURE_CAPABILITY_OUTPUT = (1 << 0), /**< The capture device supports to dump a output */ + HAL_TDM_CAPTURE_CAPABILITY_OUTPUT = (1 << 0), /**< The capture device supports to dump the output */ HAL_TDM_CAPTURE_CAPABILITY_ONESHOT = (1 << 4), /**< The capture device supports oneshot dump */ - HAL_TDM_CAPTURE_CAPABILITY_STREAM = (1 << 5), /**< The capture device supports streamp sump */ + HAL_TDM_CAPTURE_CAPABILITY_STREAM = (1 << 5), /**< The capture device supports stream dump */ } hal_tdm_capture_capability; /** * @brief The capture type enumeration + * @since HAL_MODULE_TDM 1.0 */ typedef enum { HAL_TDM_CAPTURE_TYPE_ONESHOT = (1 << 0), /**< The oneshot capture */ @@ -148,24 +172,27 @@ typedef enum { } hal_tdm_capture_type; /** - * @brief The output change enumeration of #tdm_output_change_handler + * @brief The output change enumeration of #hal_tdm_output_change_handler + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - HAL_TDM_OUTPUT_CHANGE_CONNECTION = (1 << 0), /**< connection chagne */ - HAL_TDM_OUTPUT_CHANGE_DPMS = (1 << 1), /**< dpms change */ + HAL_TDM_OUTPUT_CHANGE_CONNECTION = (1 << 0), /**< The type of connection is changed */ + HAL_TDM_OUTPUT_CHANGE_DPMS = (1 << 1), /**< The type of dpms is changed */ } hal_tdm_output_change_type; /** * @brief The output connection status enumeration + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - HAL_TDM_OUTPUT_CONN_STATUS_DISCONNECTED, /**< output disconnected */ - HAL_TDM_OUTPUT_CONN_STATUS_CONNECTED, /**< output connected */ - HAL_TDM_OUTPUT_CONN_STATUS_MODE_SETTED, /**< output connected and setted a mode */ + HAL_TDM_OUTPUT_CONN_STATUS_DISCONNECTED, /**< The output disconnected */ + HAL_TDM_OUTPUT_CONN_STATUS_CONNECTED, /**< The output connected */ + HAL_TDM_OUTPUT_CONN_STATUS_MODE_SETTED, /**< The output connected and setted the mode */ } hal_tdm_output_conn_status; /** * @brief The output connection status enumeration + * @since HAL_MODULE_TDM 1.0 * @details bit compatible with the libdrm definitions. */ typedef enum { @@ -190,6 +217,7 @@ typedef enum { /** * @brief The DPMS enumeration + * @since HAL_MODULE_TDM 1.0 * @details bit compatible with the libdrm definitions. */ typedef enum { @@ -202,196 +230,226 @@ typedef enum { /** * @brief The output mode type enumeration + * @since HAL_MODULE_TDM 1.0 * @details bit compatible with the libdrm definitions. */ typedef enum { - HAL_TDM_OUTPUT_MODE_TYPE_BUILTIN = (1 << 0), - HAL_TDM_OUTPUT_MODE_TYPE_CLOCK_C = ((1 << 1) | HAL_TDM_OUTPUT_MODE_TYPE_BUILTIN), - HAL_TDM_OUTPUT_MODE_TYPE_CRTC_C = ((1 << 2) | HAL_TDM_OUTPUT_MODE_TYPE_BUILTIN), - HAL_TDM_OUTPUT_MODE_TYPE_PREFERRED = (1 << 3), - HAL_TDM_OUTPUT_MODE_TYPE_DEFAULT = (1 << 4), - HAL_TDM_OUTPUT_MODE_TYPE_USERDEF = (1 << 5), - HAL_TDM_OUTPUT_MODE_TYPE_DRIVER = (1 << 6), + HAL_TDM_OUTPUT_MODE_TYPE_BUILTIN = (1 << 0), /**< DRM_MODE_TYPE_BUILTIN */ + HAL_TDM_OUTPUT_MODE_TYPE_CLOCK_C = ((1 << 1) | HAL_TDM_OUTPUT_MODE_TYPE_BUILTIN), /**< DRM_MODE_TYPE_CLOCK_C */ + HAL_TDM_OUTPUT_MODE_TYPE_CRTC_C = ((1 << 2) | HAL_TDM_OUTPUT_MODE_TYPE_BUILTIN), /**< DRM_MODE_TYPE_CRTC_C */ + HAL_TDM_OUTPUT_MODE_TYPE_PREFERRED = (1 << 3), /**< DRM_MODE_TYPE_PREFERRED */ + HAL_TDM_OUTPUT_MODE_TYPE_DEFAULT = (1 << 4), /**< DRM_MODE_TYPE_DEFAULT */ + HAL_TDM_OUTPUT_MODE_TYPE_USERDEF = (1 << 5), /**< DRM_MODE_TYPE_USERDEF */ + HAL_TDM_OUTPUT_MODE_TYPE_DRIVER = (1 << 6), /**< DRM_MODE_TYPE_DRIVER */ } hal_tdm_output_mode_type; /** * @brief The output mode flag enumeration + * @since HAL_MODULE_TDM 1.0 * @details bit compatible with the libdrm definitions. */ typedef enum { - HAL_TDM_OUTPUT_MODE_FLAG_PHSYNC = (1 << 0), - HAL_TDM_OUTPUT_MODE_FLAG_NHSYNC = (1 << 1), - HAL_TDM_OUTPUT_MODE_FLAG_PVSYNC = (1 << 2), - HAL_TDM_OUTPUT_MODE_FLAG_NVSYNC = (1 << 3), - HAL_TDM_OUTPUT_MODE_FLAG_INTERLACE = (1 << 4), - HAL_TDM_OUTPUT_MODE_FLAG_DBLSCAN = (1 << 5), - HAL_TDM_OUTPUT_MODE_FLAG_CSYNC = (1 << 6), - HAL_TDM_OUTPUT_MODE_FLAG_PCSYNC = (1 << 7), - HAL_TDM_OUTPUT_MODE_FLAG_NCSYNC = (1 << 8), - HAL_TDM_OUTPUT_MODE_FLAG_HSKEW = (1 << 9), /* hskew provided */ - HAL_TDM_OUTPUT_MODE_FLAG_BCAST = (1 << 10), - HAL_TDM_OUTPUT_MODE_FLAG_PIXMUX = (1 << 11), - HAL_TDM_OUTPUT_MODE_FLAG_DBLCLK = (1 << 12), - HAL_TDM_OUTPUT_MODE_FLAG_CLKDIV2 = (1 << 13), + HAL_TDM_OUTPUT_MODE_FLAG_PHSYNC = (1 << 0), /**< DRM_MODE_FLAG_PHSYNC : horizontal sync is active high. */ + HAL_TDM_OUTPUT_MODE_FLAG_NHSYNC = (1 << 1), /**< DRM_MODE_FLAG_NHSYNC : horizontal sync is active low. */ + HAL_TDM_OUTPUT_MODE_FLAG_PVSYNC = (1 << 2), /**< DRM_MODE_FLAG_PVSYNC : vertical sync is active high. */ + HAL_TDM_OUTPUT_MODE_FLAG_NVSYNC = (1 << 3), /**< DRM_MODE_FLAG_NVSYNC : vertical sync is active low. */ + HAL_TDM_OUTPUT_MODE_FLAG_INTERLACE = (1 << 4), /**< DRM_MODE_FLAG_INTERLACE : mode is interlaced. */ + HAL_TDM_OUTPUT_MODE_FLAG_DBLSCAN = (1 << 5), /**< DRM_MODE_FLAG_DBLSCAN : mode uses doublescan. */ + HAL_TDM_OUTPUT_MODE_FLAG_CSYNC = (1 << 6), /**< DRM_MODE_FLAG_CSYNC : mode uses composite sync. */ + HAL_TDM_OUTPUT_MODE_FLAG_PCSYNC = (1 << 7), /**< DRM_MODE_FLAG_PCSYNC : composite sync is active high. */ + HAL_TDM_OUTPUT_MODE_FLAG_NCSYNC = (1 << 8), /**< DRM_MODE_FLAG_NCSYNC : composite sync is active low. */ + HAL_TDM_OUTPUT_MODE_FLAG_HSKEW = (1 << 9), /**< DRM_MODE_FLAG_HSKEW : hskew provided. */ + HAL_TDM_OUTPUT_MODE_FLAG_BCAST = (1 << 10), /**< DRM_MODE_FLAG_BCAST : @deprecated Deprecated since HAL_MODULE_TDM 1.0 */ + HAL_TDM_OUTPUT_MODE_FLAG_PIXMUX = (1 << 11), /**< DRM_MODE_FLAG_PIXMUX : @deprecated Deprecated since HAL_MODULE_TDM 1.0 */ + HAL_TDM_OUTPUT_MODE_FLAG_DBLCLK = (1 << 12), /**< DRM_MODE_FLAG_DBLCLK : double-clocked mode. */ + HAL_TDM_OUTPUT_MODE_FLAG_CLKDIV2 = (1 << 13), /**< DRM_MODE_FLAG_CLKDIV2 : half-clocked mode. */ } hal_tdm_output_mode_flag; -/* +/** * @brief The hwc video capability enumeration - * @since 2.7.0 + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - HAL_TDM_HWC_CAPABILITY_VIDEO_STREAM = (1 << 1), /**< if a hwc has video stream capability */ - HAL_TDM_HWC_CAPABILITY_VIDEO_SCALE = (1 << 2), /**< if a hwc allows to scale the video buffer */ - HAL_TDM_HWC_CAPABILITY_VIDEO_TRANSFORM = (1 << 3), /**< if a hwc allows video to transform the video buffer */ - HAL_TDM_HWC_CAPABILITY_VIDEO_SCANOUT = (1 << 4), /**< if a hwc allows video to accept the scanout buffer only */ - HAL_TDM_HWC_CAPABILITY_FENCE = (1 << 5), /**< if a hwc allows fence */ + HAL_TDM_HWC_CAPABILITY_VIDEO_STREAM = (1 << 1), /**< The capability about the hwc has video stream capability */ + HAL_TDM_HWC_CAPABILITY_VIDEO_SCALE = (1 << 2), /**< The capability about the hwc allows to scale the video buffer */ + HAL_TDM_HWC_CAPABILITY_VIDEO_TRANSFORM = (1 << 3), /**< The capability about the hwc allows video to transform the video buffer */ + HAL_TDM_HWC_CAPABILITY_VIDEO_SCANOUT = (1 << 4), /**< The capability about the hwc allows video to accept the scanout buffer only */ + HAL_TDM_HWC_CAPABILITY_FENCE = (1 << 5), /**< The capability about the hwc allows fence */ } hal_tdm_hwc_capability; /** * @brief The size structure + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_size { - unsigned int h; /**< width */ - unsigned int v; /**< height */ + unsigned int h; /**< The horizontal buffer size, width */ + unsigned int v; /**< The vertical buffer size, height */ } hal_tdm_size; /** - * @brief The pos structure + * @brief The posistion structure + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_pos { - unsigned int x; - unsigned int y; - unsigned int w; - unsigned int h; + unsigned int x; /**< The x(left) position */ + unsigned int y; /**< The y(top) position */ + unsigned int w; /**< The width */ + unsigned int h; /**< The height */ } hal_tdm_pos; /** * @brief The tdm value type enumeration + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - HAL_TDM_VALUE_TYPE_UNKNOWN, - HAL_TDM_VALUE_TYPE_PTR, - HAL_TDM_VALUE_TYPE_INT32, - HAL_TDM_VALUE_TYPE_UINT32, - HAL_TDM_VALUE_TYPE_INT64, - HAL_TDM_VALUE_TYPE_UINT64, + HAL_TDM_VALUE_TYPE_UNKNOWN, /**< The unknown type of value for variable */ + HAL_TDM_VALUE_TYPE_PTR, /**< The pointer type of value for variable */ + HAL_TDM_VALUE_TYPE_INT32, /**< The 32bit integer type of value for variable */ + HAL_TDM_VALUE_TYPE_UINT32, /**< The 32bit unsigned integer type of value for variable */ + HAL_TDM_VALUE_TYPE_INT64, /**< The 64bit integer type of value for variable */ + HAL_TDM_VALUE_TYPE_UINT64, /**< The 64bit unsigned integer type of value for variable */ } hal_tdm_value_type; /** - * @brief The value union + * @brief The tdm's union value + * @since HAL_MODULE_TDM 1.0 */ typedef union { - void *ptr; - int32_t s32; - uint32_t u32; - int64_t s64; - uint64_t u64; + void *ptr; /**< The union value as pointer type */ + int32_t s32; /**< The union value as 32bit integer type */ + uint32_t u32; /**< The union value as 32bit unsigned integer type */ + int64_t s64; /**< The union value as 64bit integer type */ + uint64_t u64; /**< The union value as 64bit unsigned integer type */ } hal_tdm_value; +/** + * @brief The mask of hal_tdm_event_loop_fd_handler + * @since HAL_MODULE_TDM 1.0 + * @see hal_tdm_event_loop_fd_handler + * @see hal_tdm_event_source + */ typedef enum { - HAL_TDM_EVENT_LOOP_READABLE = (1 << 0), - HAL_TDM_EVENT_LOOP_WRITABLE = (1 << 1), - HAL_TDM_EVENT_LOOP_HANGUP = (1 << 2), - HAL_TDM_EVENT_LOOP_ERROR = (1 << 3), + HAL_TDM_EVENT_LOOP_READABLE = (1 << 0), /**< The mask for READABLE event */ + HAL_TDM_EVENT_LOOP_WRITABLE = (1 << 1), /**< The mask for WRITABLE event */ + HAL_TDM_EVENT_LOOP_HANGUP = (1 << 2), /**< The mask for HANGUP event */ + HAL_TDM_EVENT_LOOP_ERROR = (1 << 3), /**< The mask for ERROR event */ } hal_tdm_event_loop_mask; /** * @brief The display capability enumeration + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - HAL_TDM_DISPLAY_CAPABILITY_PP = (1 << 0), /**< if hardware supports pp operation */ - HAL_TDM_DISPLAY_CAPABILITY_CAPTURE = (1 << 1), /**< if hardware supports capture operation */ + HAL_TDM_DISPLAY_CAPABILITY_PP = (1 << 0), /**< The flag about hardware supports post-processing operation */ + HAL_TDM_DISPLAY_CAPABILITY_CAPTURE = (1 << 1), /**< The flag about hardware supports capture operation */ } hal_tdm_display_capability; /** - * @brief The display capability enumeration + * @brief The display capability structure for CAPTURE + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_caps_display { int max_layer_count; /**< The maximum layer count */ } hal_tdm_caps_display; /** - * @brief The output mode structure + * @brief The output mode structure compatible with drm_mode_modeinfo in drm-uapi. + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_output_mode { - unsigned int clock; - unsigned int hdisplay, hsync_start, hsync_end, htotal, hskew; - unsigned int vdisplay, vsync_start, vsync_end, vtotal, vscan; - unsigned int vrefresh; - unsigned int flags; - unsigned int type; - char name[HAL_TDM_NAME_LEN]; + unsigned int clock; /**< The pixel clock in kHz */ + unsigned int hdisplay; /**< The horizontal display size */ + unsigned int hsync_start; /**< The horizontal sync start */ + unsigned int hsync_end; /**< The horizontal sync end */ + unsigned int htotal; /**< The horizontal total size */ + unsigned int hskew; /**< The horizontal skew */ + unsigned int vdisplay; /**< The vertical display size */ + unsigned int vsync_start; /**< The vertical sync start */ + unsigned int vsync_end; /**< The vertical sync end */ + unsigned int vtotal; /**< The vertical total size */ + unsigned int vscan; /**< The vertical scan */ + unsigned int vrefresh; /**< The approximate vertical refresh rate in Hz */ + unsigned int flags; /**< The bitmask of misc. flags, see DRM_MODE_FLAG_* defines */ + unsigned int type; /**< The bitmask of type flags, see DRM_MODE_TYPE_* defines */ + char name[HAL_TDM_NAME_LEN]; /**< The string describing the mode resolution */ } hal_tdm_output_mode; /** - * @brief The property structure + * @brief The property structure of tdm + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_prop { - unsigned int id; - char name[HAL_TDM_NAME_LEN]; - hal_tdm_value_type type; + unsigned int id; /**< The identifier of property */ + char name[HAL_TDM_NAME_LEN]; /**< The name of property */ + hal_tdm_value_type type; /**< The value type of property */ } hal_tdm_prop; /** - * @brief The info config structure + * @brief The info config structure for window, layer. + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_info_config { - hal_tdm_size size; - hal_tdm_pos pos; - tbm_format format; + hal_tdm_size size; /**< The buffer size */ + hal_tdm_pos pos; /**< The position or logical image size */ + tbm_format format; /**< The pixel format */ } hal_tdm_info_config; /** * @brief The region structure + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_region { - unsigned int num_rects; - hal_tdm_pos const *rects; + unsigned int num_rects; /**< The number of rects */ + hal_tdm_pos const *rects; /**< The array of rect information */ } hal_tdm_region; /** - * @brief The hwc window info structure + * @brief The hwc window info structure to composite. + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_hwc_window_info { - hal_tdm_info_config src_config; - hal_tdm_pos dst_pos; - hal_tdm_transform transform; + hal_tdm_info_config src_config; /**< The hwc windows information of client */ + hal_tdm_pos dst_pos; /**< The destination rectangular information (left, top, width, height) */ + hal_tdm_transform transform; /**< The transform information (source to destination)*/ } hal_tdm_hwc_window_info; /** - * @brief The pp info structre + * @brief The information structre to use post-processing + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_info_pp { - hal_tdm_info_config src_config; - hal_tdm_info_config dst_config; - hal_tdm_transform transform; - int sync; - int flags; + hal_tdm_info_config src_config; /**< The source window's inforamtion */ + hal_tdm_info_config dst_config; /**< The destination window's inforamtion */ + hal_tdm_transform transform; /**< The window transform information (source to destination)*/ + int sync; /**< The option for synchronos return or not when post-processing is done*/ + int flags; /**< The Additional information to use private information. */ } hal_tdm_info_pp; /** * @brief The capture info structre + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_info_capture { - hal_tdm_info_config dst_config; - hal_tdm_transform transform; - hal_tdm_capture_type type; - int frequency; - int flags; + hal_tdm_info_config dst_config; /**< The window's coordnate & size inforamtion to capture */ + hal_tdm_transform transform; /**< The window's transform inforamtion to capture */ + hal_tdm_capture_type type; /**< The capture type one-shot or stream */ + int frequency; /**< The vertical refresh rate in Hz */ + int flags; /**< The Additional information to use private information. */ } hal_tdm_info_capture; /** - * @brief Possible composition types for a given window + * @brief Possible composition types for the given window + * @since HAL_MODULE_TDM 1.0 */ typedef enum { - /** The composition type for an invisible window. The value by default. + /**< The composition type for an invisible window. The value by default. * * The backend ignores windows of this type. */ HAL_TDM_HWC_WIN_COMPOSITION_NONE = 0, - /** The compostion type for an window to be compsoited by the client. + /**< The compostion type for an window to be compsoited by the client. * * When the client sets this composition type, * the backend MUST NOT modify this composition type into other types. @@ -403,7 +461,7 @@ typedef enum { */ HAL_TDM_HWC_WIN_COMPOSITION_CLIENT = 1, - /** The compostion type for an window to be set to the hw overlay. + /**< The compostion type for an window to be set to the hw overlay. * * The client sets this composition type to the visible windows before requesting * the tdm_hwc_validate. @@ -414,7 +472,7 @@ typedef enum { */ HAL_TDM_HWC_WIN_COMPOSITION_DEVICE = 3, - /** The compostion type for an window to be set to the cursor hw overlay. + /**< The compostion type for an window to be set to the cursor hw overlay. * * The client sets this composition type to the cursor window before requesting * the tdm_hwc_validate. @@ -423,7 +481,7 @@ typedef enum { */ HAL_TDM_HWC_WIN_COMPOSITION_CURSOR = 4, - /** The compostion type for an window to be set to the video hw overlay. + /**< The compostion type for an window to be set to the video hw overlay. * * The client sets this composition type to the video window before requesting * the tdm_hwc_validate. @@ -434,9 +492,15 @@ typedef enum { HAL_TDM_HWC_WIN_COMPOSITION_VIDEO = 5, } hal_tdm_hwc_window_composition; +/** + * @brief HWC's composition mode for specific buffer. + * @since HAL_MODULE_TDM 1.0 + */ typedef enum { + /**< Default mode of HWC's composition. */ HAL_TDM_HWC_WIN_CONSTRAINT_NONE = 0, - /** If the client needs to render to a specific buffer for compositing + + /**< If the client needs to render to the specific buffer for compositing * with TDM_HWC_WIN_COMPOSITION_DEVICE, the backend needs to set * TDM_HWC_WIN_CONSTRAINT_BUFFER_QUEUE to hwc_window until the hwc_window is not * TDM_HWC_WIN_COMPOSITION_DEVICE. The client gets the tbm_surface_queue_h through @@ -446,9 +510,15 @@ typedef enum { HAL_TDM_HWC_WIN_CONSTRAINT_BUFFER_QUEUE = (1 << 0), } hal_tdm_hwc_window_constraint; +/** + * @brief HWC's composition interval + * @since HAL_MODULE_TDM 1.0 + */ typedef enum { + /**< Default interval of HWC's composition. */ HAL_TDM_HWC_COMMIT_INTERVAL_NONE = 0, - /** If this interval is set by tdm backend, the compositor call commit per vblank + + /**< If this interval is set by tdm backend, the compositor call commit per vblank * even if the handler of commit isn't called. */ HAL_TDM_HWC_COMMIT_INTERVAL_VBLANK = 1, @@ -456,84 +526,111 @@ typedef enum { /** * @brief The tdm fd + * @since HAL_MODULE_TDM 1.0 */ typedef int hal_tdm_fd; /** * @brief The tdm display object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_display; /** * @brief The tdm backend object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_module; /** * @brief The tdm output object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_output; /** * @brief The tdm voutput object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_voutput; /** * @brief The tdm hwc object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_hwc; /** * @brief The tdm hwc window object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_hwc_window; /** * @brief The tdm capture object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_capture; /** * @brief The tdm pp object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_pp; /** * @brief The tdm vblank object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_vblank; /** * @brief The tdm backend object + * @since HAL_MODULE_TDM 1.0 */ typedef void hal_tdm_backend; /** * @brief The event_loop_fd handler + * @since HAL_MODULE_TDM 1.0 * @details This handler will be called when the output object is * createed in runtime. + * @param[in] event_fd The file descriptor of event. + * @param[in] mask The mask of event_fd. + * @param[in] user_data The user data. */ typedef hal_tdm_error (*hal_tdm_event_loop_fd_handler)(int event_fd, hal_tdm_event_loop_mask mask, void *user_data); /** * @brief The output create handler + * @since HAL_MODULE_TDM 1.0 * @details This handler will be called when the output object is * createed in runtime. + * @param[in] dpy The pointer of hal_tdm_display. + * @param[in] output The pointer of output. + * @param[in] user_data The user data */ typedef void (*hal_tdm_output_create_handler)(hal_tdm_display *dpy, hal_tdm_output *output, void *user_data); /** * @brief The output destroy handler + * @since HAL_MODULE_TDM 1.0 * @details This handler will be called when the output object is * destroied in runtime. + * @param[in] output The pointer of output. + * @param[in] user_data The user data. */ typedef void (*hal_tdm_output_destroy_handler)(hal_tdm_output *output, void *user_data); /** * @brief The output change handler - * @details This handler will be called when the status of a output object is + * @since HAL_MODULE_TDM 1.0 + * @details This handler will be called when the status of the output object is * changed in runtime. + * @param[in] output The pointer of output. + * @param[in] type The output change enumeration. + * @param[in] value The tdm's union value. + * @param[in] user_data The user data. */ typedef void (*hal_tdm_output_change_handler)(hal_tdm_output *output, hal_tdm_output_change_type type, @@ -542,6 +639,12 @@ typedef void (*hal_tdm_output_change_handler)(hal_tdm_output *output, /** * @brief The vblank handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The pointer of output. + * @param[in] sequence The number of frame used as sequence. + * @param[in] tv_sec The second of time when vsync is occurred. + * @param[in] tv_usec The micro second of time when vsync is occurred. + * @param[in] user_data The user data. * @see output_set_vblank_handler() function of #hal_tdm_display_funcs */ typedef void (*hal_tdm_output_vblank_handler)(hal_tdm_output *output, unsigned int sequence, @@ -550,6 +653,12 @@ typedef void (*hal_tdm_output_vblank_handler)(hal_tdm_output *output, unsigned i /** * @brief The output commit handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The pointer of output. + * @param[in] sequence The number of frame used as sequence. + * @param[in] tv_sec The second of time when commit is occurred. + * @param[in] tv_usec The micro second of time when commit is occurred. + * @param[in] user_data The user data. * @see output_set_commit_handler() function of #hal_tdm_display_funcs */ typedef void (*hal_tdm_output_commit_handler)(hal_tdm_output *output, unsigned int sequence, @@ -558,41 +667,71 @@ typedef void (*hal_tdm_output_commit_handler)(hal_tdm_output *output, unsigned i /** * @brief The output mode change request handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The pointer of output. + * @param[in] index The index of avaliable modes + * @param[in] user_data The user data. */ typedef void (*hal_tdm_output_mode_change_request_handler)(hal_tdm_output *output, unsigned int index, void *user_data); /** * @brief The output status handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The pointer of output. + * @param[in] status The connection status + * @param[in] user_data The user data. */ typedef void (*hal_tdm_output_status_handler)(hal_tdm_output *output, hal_tdm_output_conn_status status, void *user_data); /** * @brief The output dpms handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The pointer of output. + * @param[in] dpms The DPMS value + * @param[in] user_data The user data. */ typedef void (*hal_tdm_output_dpms_handler)(hal_tdm_output *output, hal_tdm_output_dpms dpms, void *user_data); /** - * @brief The done handler of a pp object + * @brief The done handler of the pp object + * @since HAL_MODULE_TDM 1.0 + * @param[in] pp The pointer of post-processing object. + * @param[in] src The source handle of tbm_surface. + * @param[in] dst The destination handle of tbm_surface. + * @param[in] user_data The user data. */ typedef void (*hal_tdm_pp_done_handler)(hal_tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst, void *user_data); /** - * @brief The done handler of a capture object + * @brief The done handler of the capture object + * @since HAL_MODULE_TDM 1.0 + * @param[in] capture The pointer of capture object. + * @param[in] buffer The handle of tbm_surface. + * @param[in] user_data The user data. */ typedef void (*hal_tdm_capture_done_handler)(hal_tdm_capture *capture, tbm_surface_h buffer, void *user_data); /** - * @brief The create handler of a vblank object + * @brief The create handler of the vblank object + * @since HAL_MODULE_TDM 1.0 + * @param[in] vblank The pointer of vblank object. + * @param[in] user_data The user data. */ typedef void (*hal_tdm_vblank_create_handler)(hal_tdm_vblank *vblank, void *user_data); /** * @brief The hwc commit handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The pointer of hwc object. + * @param[in] sequence The number of frame used as sequence. + * @param[in] tv_sec The second of time when hwc's commit is occurred. + * @param[in] tv_usec The micro second of time when hwc's commit is occurred. + * @param[in] user_data The user data. * @see hwc_set_commit_handler() function of #hal_tdm_hwc_funcs */ typedef void (*hal_tdm_hwc_commit_handler)(hal_tdm_hwc *hwc, unsigned int sequence, @@ -601,6 +740,12 @@ typedef void (*hal_tdm_hwc_commit_handler)(hal_tdm_hwc *hwc, unsigned int sequen /** * @brief The voutput commit handler + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The pointer of hwc object. + * @param[in] voutput The number of frame used as sequence. + * @param[in] tv_sec The second of time when hwc's commit is occurred. + * @param[in] tv_usec The micro second of time when hwc's commit is occurred. + * @param[in] user_data The user data. */ typedef void (*hal_tdm_voutput_commit_handler)(hal_tdm_voutput *voutput, unsigned int sequence, unsigned int tv_sec, unsigned int tv_usec, @@ -608,18 +753,26 @@ typedef void (*hal_tdm_voutput_commit_handler)(hal_tdm_voutput *voutput, unsigne /** * @brief The voutput commit function + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The number of frame used as sequence. + * @param[in] buffer The handle of tbm_surface. */ typedef void (*hal_tdm_voutput_commit_func)(hal_tdm_voutput *voutput, tbm_surface_h buffer); /** - * @brief The event source information + * @brief The structure for event source information. + * @since HAL_MODULE_TDM 1.0 */ typedef struct _hal_tdm_event_source { - int event_fd; - hal_tdm_event_loop_fd_handler func; - void *user_data; + int event_fd; /**< The file descriptor of event. */ + hal_tdm_event_loop_fd_handler func; /**< The handler function of tdm_even_loop */ + void *user_data; /**< The user data. */ } hal_tdm_event_source; +/** + * @brief The structure for output's capabilities. + * @since HAL_MODULE_TDM 1.0 + */ typedef struct _hal_tdm_caps_output { char maker[HAL_TDM_NAME_LEN]; /**< The output maker */ char model[HAL_TDM_NAME_LEN]; /**< The output model */ @@ -654,6 +807,10 @@ typedef struct _hal_tdm_caps_output { int cursor_preferred_align; /**< The prefered align. @since 1.5.0 */ } hal_tdm_caps_output; +/** + * @brief The structure for post-processing's capabilities. + * @since HAL_MODULE_TDM 1.0 + */ typedef struct _hal_tdm_caps_pp { hal_tdm_pp_capability capabilities; /**< The capabilities of pp */ unsigned int format_count; /**< The count of available formats */ @@ -664,9 +821,13 @@ typedef struct _hal_tdm_caps_pp { int max_h; /**< The maximum height */ int preferred_align; /**< The prefered align */ int preferred_align_vertical; /**< The prefered align vertical */ - int max_attach_count; /**< The attach count which a PP object can handle. */ + int max_attach_count; /**< The attach count which the PP object can handle. */ } hal_tdm_caps_pp; +/** + * @brief The structure for capture's capabilities. + * @since HAL_MODULE_TDM 1.0 + */ typedef struct _hal_tdm_caps_capture { hal_tdm_capture_capability capabilities; /**< The capabilities of capture */ unsigned int format_count; /**< The count of available formats */ @@ -676,9 +837,13 @@ typedef struct _hal_tdm_caps_capture { int max_w; /**< The maximum width */ int max_h; /**< The maximum height */ int preferred_align; /**< The prefered align */ - int max_attach_count; /**< The attach count which a capture object can handle. */ + int max_attach_count; /**< The attach count which the capture object can handle. */ } hal_tdm_caps_capture; +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/include/hal-tdm.h b/include/hal-tdm.h index 37168fa..1f0ac30 100644 --- a/include/hal-tdm.h +++ b/include/hal-tdm.h @@ -43,111 +43,1017 @@ extern "C" { #include #include "hal-tdm-types.h" -/* hal_tdm */ -hal_tdm_backend *hal_tdm_get_backend(hal_tdm_error *error); -hal_tdm_error hal_tdm_put_backend(hal_tdm_backend *backend); - -/* tdm_backend_data */ -hal_tdm_display *hal_tdm_backend_get_display(hal_tdm_backend *backend, hal_tdm_error *error); -int hal_tdm_backend_has_drm_device(hal_tdm_backend *backend, hal_tdm_error *error); -hal_tdm_fd hal_tdm_backend_get_master_drm_fd(hal_tdm_backend *backend, hal_tdm_error *error); -hal_tdm_error hal_tdm_backend_set_master_drm_fd(hal_tdm_backend *backend, hal_tdm_fd master_drm_fd); -hal_tdm_event_source **hal_tdm_backend_get_event_sources(hal_tdm_backend *backend, int *num_event_sources, hal_tdm_error *error); -char *hal_tdm_backend_get_name(hal_tdm_backend *backend); -char *hal_tdm_backend_get_vendor(hal_tdm_backend *backend); -unsigned long hal_tdm_backend_get_abi_version(hal_tdm_backend *backend); - -/* tdm_display_funcs */ -hal_tdm_error hal_tdm_display_get_capability(hal_tdm_display *display, hal_tdm_caps_display *caps); -hal_tdm_error hal_tdm_display_get_pp_capability(hal_tdm_display *display, hal_tdm_caps_pp *caps); -hal_tdm_error hal_tdm_display_get_capture_capability(hal_tdm_display *display, hal_tdm_caps_capture *caps); +/** + * @file hal-tdm.h + * @brief This file contains the Tizen TDM HAL interface API, related structures and enumerations. + * @since HAL_MODULE_TBM 1.0 + */ + +/** + * @addtogroup HALAPI_HAL_TDM_MODULE + * @{ + */ + +/** + * @brief Get the hal_tdm_backend object. + * @since HAL_MODULE_TDM 1.0 + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The hal_tdm_backend object if success, otherwise NULL. + */ +hal_tdm_backend *hal_tdm_get_backend(hal_tdm_error *error); + +/** + * @brief Put the hal_tdm_backend object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_put_backend(hal_tdm_backend *backend); + +/** + * @brief Get the hal_tdm_display from backend object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The hal_tdm_display object if success, otherwise NULL. + */ +hal_tdm_display *hal_tdm_backend_get_display(hal_tdm_backend *backend, hal_tdm_error *error); + +/** + * @brief Check the hal_tdm_backend has drm_device or not. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return 1 if success, otherwise 0. + */ +int hal_tdm_backend_has_drm_device(hal_tdm_backend *backend, hal_tdm_error *error); + +/** + * @brief Get the master file descriptor from backend module. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return master hal_tdm_fd if success, otherwise error value. + */ +hal_tdm_fd hal_tdm_backend_get_master_drm_fd(hal_tdm_backend *backend, hal_tdm_error *error); + +/** + * @brief Set the master file descriptor to backend module. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @param[out] ermaster_drm_fd The master hal_tdm_fd. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_backend_set_master_drm_fd(hal_tdm_backend *backend, hal_tdm_fd master_drm_fd); + +/** + * @brief Get the hal_event_source array from backend module. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @param[out] num_event_sources The number of hal_event_sources. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The pointer of hal_tdm_event_source array, otherwise NULL. + */ +hal_tdm_event_source **hal_tdm_backend_get_event_sources(hal_tdm_backend *backend, int *num_event_sources, hal_tdm_error *error); + +/** + * @brief Get the name of hal_tdm_backend. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @return The pointer of name string, otherwise NULL. + */ +char *hal_tdm_backend_get_name(hal_tdm_backend *backend); + +/** + * @brief Get the name of hal_tdm_backend's vendor. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @return The pointer of name string, otherwise NULL. + */ +char *hal_tdm_backend_get_vendor(hal_tdm_backend *backend); + +/** + * @brief Get the ABI version of hal_tdm_backend. + * @since HAL_MODULE_TDM 1.0 + * @param[in] backend The handle of hal_tdm_backend. + * @return The ABI version of hal_tdm_backend. + */ +unsigned long hal_tdm_backend_get_abi_version(hal_tdm_backend *backend); + +/** + * @brief Get the display capabilities of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @param[out] caps The display capabilities of hal_tdm_display object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The 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. + * If the hardware has the restriction of the number of max usable layer count, + * the backend module can set the max count to max_layer_count of #hal_tdm_caps_display + * structure. + */ +hal_tdm_error hal_tdm_display_get_capability(hal_tdm_display *display, hal_tdm_caps_display *caps); + +/** + * @brief Get the post-processing capabilities of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @param[out] caps The post-processing capabilities of hal_tdm_display object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_display_create_pp() + * @remark + * TDM calls this function not only at the initial time, but also at the update + * time when new output is connected. + * The backend module doesn't need to implement this function if the hardware + * doesn't have the memory-to-memory converting device, otherwise the backend module + * @b SHOULD fill the #hal_tdm_caps_pp data. #hal_tdm_caps_pp contains the hardware + * restriction information which the converting device can handle. ie, format, size, etc. + */ +hal_tdm_error hal_tdm_display_get_pp_capability(hal_tdm_display *display, hal_tdm_caps_pp *caps); + +/** + * @brief Get the capture capabilities of the hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @param[out] caps The capture capabilities of hal_tdm_display object. + * @return #HAL_TDM_ERROR_NONE if success. otherwise error value. + * @see hal_tdm_output_create_capture() + * @remark + * TDM calls this function not only at the initial time, but also at the update + * time when new output is connected. + * The backend module doesn't need to implement this function if the hardware + * doesn't have the capture device, otherwise the backend module @b SHOULD fill the + * #hal_tdm_caps_capture data. #hal_tdm_caps_capture contains the hardware restriction + * information which the capture device can handle. ie, format, size, etc. + */ +hal_tdm_error hal_tdm_display_get_capture_capability(hal_tdm_display *display, hal_tdm_caps_capture *caps); + +/** + * @brief Get the output array of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @param[out] count The count of outputs. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The output array which is @b newly-allocated + * @see hal_tdm_output_create_capture() + * @remark + * The 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. + * The backend module @b SHOULD return the @b newly-allocated array which contains + * "tdm_output*" data. It will be freed in frontend. + */ hal_tdm_output **hal_tdm_display_get_outputs(hal_tdm_display *display, int *count, hal_tdm_error *error); -hal_tdm_error hal_tdm_display_get_fd(hal_tdm_display *display, int *fd); -hal_tdm_error hal_tdm_display_handle_events(hal_tdm_display *display); -hal_tdm_pp *hal_tdm_display_create_pp(hal_tdm_display *display, hal_tdm_error *error); + +/** + * @brief Get the file descriptor of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @param[out] fd The fd of the backend module. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_display_handle_events() + * @remark + * The backend module can return epoll's fd which is watching the backend device one more fds. + */ +hal_tdm_error hal_tdm_display_get_fd(hal_tdm_display *display, int *fd); + +/** + * @brief Handle the events which happens on the fd of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_display_handle_events(hal_tdm_display *display); + +/** + * @brief Create the post-processing object of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The pointer of the post-processing object. + * @see hal_tdm_pp_destroy() + * @remark + * The backend module doesn't need to implement this function if the hardware + * doesn't have the memory-to-memory converting device. + */ +hal_tdm_pp *hal_tdm_display_create_pp(hal_tdm_display *display, hal_tdm_error *error); + +/** + * @brief Create the virtual output object of hal_tdm_display. + * @since HAL_MODULE_TDM 1.0 + * @param[in] display The pointer of hal_tdm_display object. + * @param[in] name The output name + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The hal_tdm_voutput object + * @see hal_tdm_voutput_destroy() + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ hal_tdm_voutput *hal_tdm_display_voutput_create(hal_tdm_display *display, const char *name, hal_tdm_error *error); -/* output_funcs */ -hal_tdm_error hal_tdm_output_get_capability(hal_tdm_output *output, hal_tdm_caps_output *caps); -hal_tdm_error hal_tdm_output_set_property(hal_tdm_output *output, unsigned int id, hal_tdm_value value); -hal_tdm_error hal_tdm_output_get_property(hal_tdm_output *output, unsigned int id, hal_tdm_value *value); -hal_tdm_error hal_tdm_output_wait_vblank(hal_tdm_output *output, int interval, int sync, void *user_data); -hal_tdm_error hal_tdm_output_set_vblank_handler(hal_tdm_output *output, hal_tdm_output_vblank_handler func); -hal_tdm_error hal_tdm_output_commit(hal_tdm_output *output, int sync, void *user_data); // TODO: DEPRECATED. NOT SUPPORTED~!!!! -hal_tdm_error hal_tdm_output_set_commit_handler(hal_tdm_output *output, hal_tdm_output_commit_handler func); // TODO: DEPRECATED. NOT SUPPORTED~!!!! -hal_tdm_error hal_tdm_output_set_dpms(hal_tdm_output *output, hal_tdm_output_dpms dpms_value); -hal_tdm_error hal_tdm_output_get_dpms(hal_tdm_output *output, hal_tdm_output_dpms *dpms_value); -hal_tdm_error hal_tdm_output_set_mode(hal_tdm_output *output, const hal_tdm_output_mode *mode); -hal_tdm_error hal_tdm_output_get_mode(hal_tdm_output *output, const hal_tdm_output_mode **mode); +/** + * @brief Get the capabilities of the hal_tdm_output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The hal_tdm_output object. + * @param[out] caps The capabilities of the output object + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The 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. + * #hal_tdm_caps_output contains connection status, modes, avaiable properties, + * size restriction information, etc. + */ +hal_tdm_error hal_tdm_output_get_capability(hal_tdm_output *output, hal_tdm_caps_output *caps); + +/** + * @brief Set the output's property which has the given id. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] id The property id. + * @param[in] value The value. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_set_property(hal_tdm_output *output, unsigned int id, hal_tdm_value value); + +/** + * @brief Get the output's property which has the given id. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] id The property id. + * @param[out] value The value. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_get_property(hal_tdm_output *output, unsigned int id, hal_tdm_value *value); + +/** + * @brief Wait for VBLANK of output. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] interval The vblank's interval. + * @param[in] sync 0: asynchronous, 1:synchronous. + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_output_set_vblank_handler(), hal_tdm_output_vblank_handler + * @remark + * If this function returns HAL_TDM_ERROR_NONE, the backend module @b SHOULD call + * the user vblank handler with the user data of this function after interval + * vblanks. + */ +hal_tdm_error hal_tdm_output_wait_vblank(hal_tdm_output *output, int interval, int sync, void *user_data); + +/** + * @brief Set the user handler of vblank. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] func The user handler of vblank. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_set_vblank_handler(hal_tdm_output *output, hal_tdm_output_vblank_handler func); + +/** + * @brief Commit changes to the output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] sync 0: asynchronous, 1:synchronous + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_output_set_commit_handler(), hal_tdm_output_commit_handler + * @remark + * When this function is called, the backend module @b SHOULD apply the all + * changes of the given output object to screen as well as the layer changes + * of this output. + * If this function returns HAL_TDM_ERROR_NONE, the backend module @b SHOULD call + * the user commit handler with the user data of this function after all + * changes of the given output object are applied. + * TODO: DEPRECATED. NOT SUPPORTED. + */ +hal_tdm_error hal_tdm_output_commit(hal_tdm_output *output, int sync, void *user_data); + +/** + * @brief Set the user commit handler. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] func The user commit handler. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * TODO: DEPRECATED. NOT SUPPORTED. + */ +hal_tdm_error hal_tdm_output_set_commit_handler(hal_tdm_output *output, hal_tdm_output_commit_handler func); + +/** + * @brief Set DPMS of the output object synchronously. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] dpms_value The DPMS value. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_set_dpms(hal_tdm_output *output, hal_tdm_output_dpms dpms_value); + +/** + * @brief Get DPMS of the output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[out] dpms_value The DPMS value. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_get_dpms(hal_tdm_output *output, hal_tdm_output_dpms *dpms_value); + +/** + * @brief Set one of available modes of the output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] mode The output mode. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_set_mode(hal_tdm_output *output, const hal_tdm_output_mode *mode); + +/** + * @brief Get the mode of the output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[out] mode The output mode. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_output_get_mode(hal_tdm_output *output, const hal_tdm_output_mode **mode); + +/** + * @brief Create the capture object from the output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The capture object. + * @see hal_tdm_capture_destroy() + * @remark + * The backend module doesn't need to implement this function if the hardware + * doesn't have the capture device. + */ hal_tdm_capture *hal_tdm_output_create_capture(hal_tdm_output *output, hal_tdm_error *error); -hal_tdm_error hal_tdm_output_set_status_handler(hal_tdm_output *output, hal_tdm_output_status_handler func, void *user_data); -hal_tdm_error hal_tdm_output_set_dpms_handler(hal_tdm_output *output, hal_tdm_output_dpms_handler func, void *user_data); -hal_tdm_error hal_tdm_output_set_dpms_async(hal_tdm_output *output, hal_tdm_output_dpms dpms_value, int *sync); -hal_tdm_hwc *hal_tdm_output_get_hwc(hal_tdm_output *output, hal_tdm_error *error); -hal_tdm_error hal_tdm_output_set_mirror(hal_tdm_output *output, hal_tdm_output *src_output, hal_tdm_transform transform); -hal_tdm_error hal_tdm_output_unset_mirror(hal_tdm_output *output); - -/* voutput_funcs */ -hal_tdm_error hal_tdm_voutput_destroy(hal_tdm_voutput *voutput); -hal_tdm_error hal_tdm_voutput_set_available_mode(hal_tdm_voutput *voutput, const hal_tdm_output_mode *modes, int count); -hal_tdm_error hal_tdm_voutput_set_physical_size(hal_tdm_voutput *voutput, unsigned int mmwidth, unsigned int mmheight); -hal_tdm_error hal_tdm_voutput_connect(hal_tdm_voutput *voutput); -hal_tdm_error hal_tdm_voutput_disconnect(hal_tdm_voutput *voutput); + +/** + * @brief Set the output connection status handler. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] func The output status handler. + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark The backend module need to call the output status handler when the + * output connection status has been changed to let the TDM frontend know + * the change. + */ +hal_tdm_error hal_tdm_output_set_status_handler(hal_tdm_output *output, hal_tdm_output_status_handler func, void *user_data); + +/** + * @brief Set the output's dpms handler. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] func The output dpms handler. + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_output_set_dpms_async(), #HAL_TDM_OUTPUT_CAPABILITY_ASYNC_DPMS + * @details This function can be NULL if an output doesn't support asynchronous + * DPMS control. Otherwise, the backend module needs to call the output dpms handler + * to let the TDM frontend know the output DPMS change indeed. + */ +hal_tdm_error hal_tdm_output_set_dpms_handler(hal_tdm_output *output, hal_tdm_output_dpms_handler func, void *user_data); + +/** + * @brief Set DPMS of the output object asynchronously. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[in] dpms_value DPMS value. + * @param[out] sync The flag for sync call. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_output_set_dpms_handler(), #HAL_TDM_OUTPUT_CAPABILITY_ASYNC_DPMS + * @details This function can be NULL if an output doesn't support asynchronous + * DPMS control. Otherwise, an output should have #HAL_TDM_OUTPUT_CAPABILITY_ASYNC_DPMS + * flags which #output_get_capability returns. And if the output dpms handler is added with + * hal_tdm_output_set_dpms_handler(), the backend module needs to call the output dpms handler + * to let the TDM frontend know the output DPMS change indeed. + */ +hal_tdm_error hal_tdm_output_set_dpms_async(hal_tdm_output *output, hal_tdm_output_dpms dpms_value, int *sync); + +/** + * @brief Get the hwc object of the output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The hwc object + */ +hal_tdm_hwc *hal_tdm_output_get_hwc(hal_tdm_output *output, hal_tdm_error *error); + +/** + * @brief Set the mirror image of the src_output to the output. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object to display the src_output image. + * @param[in] src_output The src output object of which image is displayed on the output. + * @param[in] transform The transform value. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_output_set_mirror(), #HAL_TDM_OUTPUT_CAPABILITY_MIRROR + * @details This function set the mirro image of the src_output to the output. + * If there is the hardware or the implementation to display the mirror image + * of the src_output to the output, the backend does it in this function. + * If the backend output gets the ability of the mirror displaying, it has to + * set the #HAL_TDM_OUTPUT_CAPABILITY_MIRROR on the output capability. + */ +hal_tdm_error hal_tdm_output_set_mirror(hal_tdm_output *output, hal_tdm_output *src_output, hal_tdm_transform transform); + +/** + * @brief Unset the mirror image. + * @since HAL_MODULE_TDM 1.0 + * @param[in] output The output object to display the src_output image. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_output_set_mirror(), #HAL_TDM_OUTPUT_CAPABILITY_MIRROR + * @details This function unset the mirro image of the output. + */ +hal_tdm_error hal_tdm_output_unset_mirror(hal_tdm_output *output); + +/** + * @brief Destroy the virtual output object of the backend module. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @return #HALTDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_display_voutput_create() + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_destroy(hal_tdm_voutput *voutput); + +/** + * @brief Set available modes of the virtual output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @param[in] modes The modes of voutput. + * @param[in] count The count of modes. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_set_available_mode(hal_tdm_voutput *voutput, const hal_tdm_output_mode *modes, int count); + +/** + * @brief Set physical size(mm) of the virtual output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @param[in] mmwidth The width of voutput. + * @param[in] mmheight The height of voutput. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_set_physical_size(hal_tdm_voutput *voutput, unsigned int mmwidth, unsigned int mmheight); + +/** + * @brief Set connect status of the virtual output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_connect(hal_tdm_voutput *voutput); + +/** + * @brief Set disconnect status of the virtual output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_disconnect(hal_tdm_voutput *voutput); + +/** + * @brief Get output object from virtual output object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The tdm_output object + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ hal_tdm_output *hal_tdm_voutput_get_output(hal_tdm_voutput *voutput, hal_tdm_error *error); -hal_tdm_error hal_tdm_voutput_set_commit_func(hal_tdm_voutput *voutput, hal_tdm_voutput_commit_handler commit_func); -hal_tdm_error hal_tdm_voutput_commit_done(hal_tdm_voutput *voutput); -hal_tdm_error hal_tdm_voutput_set_target_buffer_queue_flag(hal_tdm_voutput *voutput, int flags); -/* hwc_funcs */ +/** + * @brief Set the user commit function + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object + * @param[in] func The user voutput commit function + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + * If virtual output's output_commit is executed, call this voutput commit func. + */ +hal_tdm_error hal_tdm_voutput_set_commit_func(hal_tdm_voutput *voutput, hal_tdm_voutput_commit_handler commit_func); + +/** + * @brief Notify commit done to backend. + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_commit_done(hal_tdm_voutput *voutput); + +/** + * @brief Set target buffer queue flag of the virtual output's hwc object + * @since HAL_MODULE_TDM 1.0 + * @param[in] voutput The voutput object + * @param[in] flags Flags of target buffer queue + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module doesn't need to implement this function if doesn't support virtual output. + */ +hal_tdm_error hal_tdm_voutput_set_target_buffer_queue_flag(hal_tdm_voutput *voutput, int flags); + +/** + * @brief Create a new window on the given hwc. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The created window object + */ hal_tdm_hwc_window *hal_tdm_hwc_create_window(hal_tdm_hwc *hwc, hal_tdm_error *error); -hal_tdm_error hal_tdm_hwc_get_video_supported_formats(hal_tdm_hwc *hwc, const tbm_format **formats, int *count); -hal_tdm_error hal_tdm_hwc_get_video_available_properties(hal_tdm_hwc *hwc, const hal_tdm_prop **props, int *count); -hal_tdm_error hal_tdm_hwc_get_capabilities(hal_tdm_hwc *hwc, hal_tdm_hwc_capability *capabilities); -hal_tdm_error hal_tdm_hwc_get_available_properties(hal_tdm_hwc *hwc, const hal_tdm_prop **props, int *count); + +/** + * @brief Get video the supported format array for the hwc windows of the hwc object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] formats The available format array. + * @param[out] count The count of formats. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_get_video_supported_formats(hal_tdm_hwc *hwc, const tbm_format **formats, int *count); + +/** + * @brief Get the available video property array of the hwc object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] props The available video property array. + * @param[out] count The count of video properties. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_get_video_available_properties(hal_tdm_hwc *hwc, const hal_tdm_prop **props, int *count); + +/** + * @brief Get the hwc capabilities. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] capabilities The hwc hwc capability. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_get_capabilities(hal_tdm_hwc *hwc, hal_tdm_hwc_capability *capabilities); + +/** + * @brief Get the available property array of the hwc object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] props The available property array. + * @param[out] count The count of properties. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_get_available_properties(hal_tdm_hwc *hwc, const hal_tdm_prop **props, int *count); + +/** + * @brief Get the client(relative to the TDM) target buffer queue. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The buffer queue + */ tbm_surface_queue_h hal_tdm_hwc_get_client_target_buffer_queue(hal_tdm_hwc *hwc, hal_tdm_error *error); -hal_tdm_error hal_tdm_hwc_set_client_target_buffer(hal_tdm_hwc *hwc, tbm_surface_h target_buffer, hal_tdm_region damage); -hal_tdm_error hal_tdm_hwc_set_client_target_buffer_info(hal_tdm_hwc *hwc, hal_tdm_hwc_window_info *info); -hal_tdm_error hal_tdm_hwc_set_client_target_acquire_fence(hal_tdm_hwc *hwc, int acquire_fence); -hal_tdm_error hal_tdm_hwc_validate(hal_tdm_hwc *hwc, hal_tdm_hwc_window **composited_wnds, uint32_t num_wnds, uint32_t *num_types); -hal_tdm_error hal_tdm_hwc_get_changed_composition_types(hal_tdm_hwc *hwc, uint32_t *num_elements, hal_tdm_hwc_window **hwc_window, hal_tdm_hwc_window_composition *composition_types); -hal_tdm_error hal_tdm_hwc_accept_validation(hal_tdm_hwc *hwc); -hal_tdm_error hal_tdm_hwc_commit(hal_tdm_hwc *hwc, int sync, void *user_data); -hal_tdm_error hal_tdm_hwc_set_commit_handler(hal_tdm_hwc *hwc, hal_tdm_hwc_commit_handler func); -hal_tdm_error hal_tdm_hwc_get_commit_fence(hal_tdm_hwc *hwc, int *commit_fence); -hal_tdm_error hal_tdm_hwc_get_release_fences(hal_tdm_hwc *hwc, uint32_t *num_elements, hal_tdm_hwc_window **hwc_windows, int *release_fences); -hal_tdm_error hal_tdm_hwc_set_property(hal_tdm_hwc *hwc, uint32_t id, hal_tdm_value value); -hal_tdm_error hal_tdm_hwc_get_property(hal_tdm_hwc *hwc, uint32_t id, hal_tdm_value *value); -hal_tdm_error hal_tdm_hwc_get_commit_interval(hal_tdm_hwc *hwc, hal_tdm_hwc_commit_interval *interval); - -/* hwc_window_funcs */ -void hal_tdm_hwc_window_destroy(hal_tdm_hwc_window *hwc_window); + +/** + * @brief Set the client(relative to the TDM) target buffer. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[in] target_buffer The new target buffer. + * @param[in] damage The buffer damage region. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @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_HWC_WIN_COMPOSITION_CLIENT. + */ +hal_tdm_error hal_tdm_hwc_set_client_target_buffer(hal_tdm_hwc *hwc, tbm_surface_h target_buffer, hal_tdm_region damage); + +/** + * @brief Set the information of the client(relative to the TDM) target buffer. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The output hwc. + * @param[in] info The information. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_set_client_target_buffer_info(hal_tdm_hwc *hwc, hal_tdm_hwc_window_info *info); + +/** + * @brief Set the acquire fence of client(relative to the TDM) target buffer. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The output hwc. + * @param[in] acquire_fence The acquire fence fd of target. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details ownership of the acquire fence fd is transfered and + * backend must close the acquire fence fd when it is no longer needed. + */ +hal_tdm_error hal_tdm_hwc_set_client_target_acquire_fence(hal_tdm_hwc *hwc, int acquire_fence); + +/** + * @brief Validate the hwc. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The 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 #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @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. + * @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 + */ +hal_tdm_error hal_tdm_hwc_validate(hal_tdm_hwc *hwc, hal_tdm_hwc_window **composited_wnds, uint32_t num_wnds, uint32_t *num_types); + +/** + * @brief Get changed composition types. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] num_elements The number of hwc_windows. + * @param[out] windows The array of windows. + * @param[out] composition_types The array of composition types, each corresponding to an element of windows. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details Retrieves the windows for which the backend requires the 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_validation, 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(). + */ +hal_tdm_error hal_tdm_hwc_get_changed_composition_types(hal_tdm_hwc *hwc, uint32_t *num_elements, hal_tdm_hwc_window **hwc_window, hal_tdm_hwc_window_composition *composition_types); + +/** + * @brief Accepts the validation required by the backend. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details Accepts the validation required by the backend from the previous + * tdm_hwc_validate() and tdm_hwc_get_chaged_composition_types(). + */ +hal_tdm_error hal_tdm_hwc_accept_validation(hal_tdm_hwc *hwc); + +/** + * @brief Commit changes for the hwc object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[in] sync 0: asynchronous, 1:synchronous + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_hwc_set_commit_handler(), hal_tdm_hwc_commit_handler + * @remark + * When this function is called, the backend module @b SHOULD apply the all + * changes of the given hwc object to screen as well as the layer changes + * of this hwc. + * If this function returns TDM_ERROR_NONE, the backend module @b SHOULD call + * user commit handler with the user data of this function after all + * changes of the given hwc object are applied. + */ +hal_tdm_error hal_tdm_hwc_commit(hal_tdm_hwc *hwc, int sync, void *user_data); + +/** + * @brief Set the user commit handler. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[in] func The user commit handler. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_set_commit_handler(hal_tdm_hwc *hwc, hal_tdm_hwc_commit_handler func); + +/** + * @brief Get commit fence. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] commit_fence The commit fence fd of tdm_hwc_commit + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details After all change of the window object are applied to last tdm_hwc_commit, + * the fence is signaled. + * ownership of the commit fence fd is transfered and + * backend must dup the commit fence fd if the commit fence is continued used it in backend. + */ +hal_tdm_error hal_tdm_hwc_get_commit_fence(hal_tdm_hwc *hwc, int *commit_fence); + +/** + * @brief Get release fences. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] num_elements The number of hwc_windows. + * @param[out] hwc_windows An array of windows. + * @param[out] release_fences An array of release fences, each corresponding to an element of windows. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details Retrieves the windows which the backend requires setting the release fences + * the release fence is signaled when the backend is no longer using previous buffer. + * ownership of the release fence fd is transfered and + * backend must dup the release fence fd if the release fence is continued used it in backend. + */ +hal_tdm_error hal_tdm_hwc_get_release_fences(hal_tdm_hwc *hwc, uint32_t *num_elements, hal_tdm_hwc_window **hwc_windows, int *release_fences); + +/** + * @brief Set the property which has the given id on the hwc object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[in] id The property id. + * @param[in] value The value of the property id. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_set_property(hal_tdm_hwc *hwc, uint32_t id, hal_tdm_value value); + +/** + * @brief Get the property which has the given id on the hwc object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[in] id The property id. + * @param[in] value The value of the property id. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_get_property(hal_tdm_hwc *hwc, uint32_t id, hal_tdm_value *value); + +/** + * @brief Get the commit interval. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc The hwc object. + * @param[out] interval The commit interval of backend. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_get_commit_interval(hal_tdm_hwc *hwc, hal_tdm_hwc_commit_interval *interval); + +/** + * @brief Destroys the given window. + * @since HAL_MODULE_TDM 1.0 + * @param[in] window The pointer of the window to destroy. + */ +void hal_tdm_hwc_window_destroy(hal_tdm_hwc_window *hwc_window); + +/** + * @brief Acquire buffer queue handle for the window object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The window object. + * @param[out] error #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @return The handle of buffer queue. + * @details These buffers are used to composite by hardware client content in + * the nocomp mode. + */ tbm_surface_queue_h hal_tdm_hwc_window_acquire_buffer_queue(hal_tdm_hwc_window *hwc_window, hal_tdm_error *error); -void hal_tdm_hwc_window_release_buffer_queue(hal_tdm_hwc_window *hwc_window, tbm_surface_queue_h queue); -hal_tdm_error hal_tdm_hwc_window_set_composition_type(hal_tdm_hwc_window *hwc_window, hal_tdm_hwc_window_composition composition_type); -hal_tdm_error hal_tdm_hwc_window_set_buffer_damage(hal_tdm_hwc_window *hwc_window, hal_tdm_region damage); -hal_tdm_error hal_tdm_hwc_window_set_info(hal_tdm_hwc_window *hwc_window, hal_tdm_hwc_window_info *info); -hal_tdm_error hal_tdm_hwc_window_set_buffer(hal_tdm_hwc_window *hwc_window, tbm_surface_h buffer); -hal_tdm_error hal_tdm_hwc_window_set_property(hal_tdm_hwc_window *hwc_window, uint32_t id, hal_tdm_value value); -hal_tdm_error hal_tdm_hwc_window_get_property(hal_tdm_hwc_window *hwc_window, uint32_t id, hal_tdm_value *value); -hal_tdm_error hal_tdm_hwc_window_get_constraints(hal_tdm_hwc_window *hwc_window, int *constraints); -hal_tdm_error hal_tdm_hwc_window_set_name(hal_tdm_hwc_window *hwc_window, const char *name); -hal_tdm_error hal_tdm_hwc_window_set_cursor_image(hal_tdm_hwc_window *hwc_window, int width, int height, int stride, void *ptr); -hal_tdm_error hal_tdm_hwc_window_set_acquire_fence(hal_tdm_hwc_window *hwc_window, int acquire_fence); - -/* pp_funcs */ -void hal_tdm_pp_destroy(hal_tdm_pp *pp); + +/** + * @brief Release the buffer queue for the window object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The window object. + * @param[in] queue The tbm buffer queue. + * @details Release buffer queue when the client no longer uses buferrs of queue. + */ +void hal_tdm_hwc_window_release_buffer_queue(hal_tdm_hwc_window *hwc_window, tbm_surface_queue_h queue); + +/** + * @brief Sets the desired composition type of the given window. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The window object. + * @param[in] composition_type The new composition type. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @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. + */ +hal_tdm_error hal_tdm_hwc_window_set_composition_type(hal_tdm_hwc_window *hwc_window, hal_tdm_hwc_window_composition composition_type); + +/** + * @brief Set the buffer damage. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The window object. + * @param[in] damage The new buffer damage region. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details Provides the region of the source buffer which has been modified + * since the last frame. This region does not need to be validated before + * calling hwc_commit(). + * Once set through this function, the damage region remains the same until a + * subsequent call to this function. + * If damage.num_rects > 0, then it may be assumed that any portion of the source + * buffer not covered by one of the rects has not been modified this frame. If + * damage.num_rects == 0, then the whole source buffer must be treated as if it + * has been modified. + * If the layer's contents are not modified relative to the prior frame, damage + * will contain exactly one empty rect([0, 0, 0, 0]). + * The damage rects are relative to the pre-transformed buffer, and their origin + * is the top-left corner. They will not exceed the dimensions of the latched + * buffer. + */ +hal_tdm_error hal_tdm_hwc_window_set_buffer_damage(hal_tdm_hwc_window *hwc_window, hal_tdm_region damage); + +/** + * @brief Set the information to the window object. + * @since HAL_MODULE_TDM 1.0 + * @details The information will be applied when the hwc object is committed. + * @param[in] hwc_window The window object. + * @param[in] info The geometry information. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_window_set_info(hal_tdm_hwc_window *hwc_window, hal_tdm_hwc_window_info *info); + +/** + * @brief Set the TDM buffer to the window object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The window object. + * @param[in] buffer The TBM buffer + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details The TDM buffer will be applied when the hwc object + * of the layer object is committed. + */ +hal_tdm_error hal_tdm_hwc_window_set_buffer(hal_tdm_hwc_window *hwc_window, tbm_surface_h buffer); + +/** + * @brief Set the property which has the given id. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The hwc window object. + * @param[in] id The property id. + * @param[in] value The value of the propery id. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_window_set_property(hal_tdm_hwc_window *hwc_window, uint32_t id, hal_tdm_value value); + +/** + * @brief Get the property which has the given id. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The hwc window object. + * @param[in] id The property id. + * @param[out] value The value of the propery id. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_window_get_property(hal_tdm_hwc_window *hwc_window, uint32_t id, hal_tdm_value *value); + +/** + * @brief Get the constraints of hwc_window. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The hwc window object. + * @param[out] constraints The tdm_hwc_window_constraint types. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_window_get_constraints(hal_tdm_hwc_window *hwc_window, int *constraints); + +/** + * @brief Set the name of hwc_window. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The hwc window object. + * @param[in] name The name of the hwc_window. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_window_set_name(hal_tdm_hwc_window *hwc_window, const char *name); + +/** + * @brief Set the curser image to hwc_window. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The hwc window object. + * @param[in] width The width of the cursor image. + * @param[in] height The height of the cursor image. + * @param[in] stride The stride of the cursor image. + * @param[in] ptr The address of the cursor image. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ +hal_tdm_error hal_tdm_hwc_window_set_cursor_image(hal_tdm_hwc_window *hwc_window, int width, int height, int stride, void *ptr); + +/** + * @brief Set the acquire fence of hwc_window. + * @since HAL_MODULE_TDM 1.0 + * @param[in] hwc_window The hwc window object. + * @param[in] acquire_fence The acquire fence fd of the hwc window object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @details ownership of the acquire fence fd is transfered and + * backend must close the acquire fence fd when it is no longer needed. + */ +hal_tdm_error hal_tdm_hwc_window_set_acquire_fence(hal_tdm_hwc_window *hwc_window, int acquire_fence); + +/** + * @brief Destroy the post-processing object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] pp The post-processing object. + * @see hal_tdm_display_create_pp() + */ +void hal_tdm_pp_destroy(hal_tdm_pp *pp); + +/** + * @brief Set the geometry information to the post-processing object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] pp The post-processing object. + * @param[in] info The geometry information + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_pp_commit() + * @remark + * The backend module would apply the geometry information when committed. + */ hal_tdm_error hal_tdm_pp_set_info(hal_tdm_pp *pp, hal_tdm_info_pp *info); + +/** + * @brief Attach source buffer and destination buffer to the post-processing object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] pp The post-processing object. + * @param[in] src The source buffer. + * @param[in] dst The destination buffer. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_pp_set_info() + * @see hal_tdm_pp_commit() + * @see hal_tdm_pp_set_done_handler(), hal_tdm_pp_done_handler + * @remark + * The backend module converts the image of source buffer to destination + * buffer when committed. The size/crop/transform information is set via + * #hal_tdm_pp_set_info(). When done, the backend module @b SHOULD + * return the source/destination buffer via tdm_pp_done_handler. + */ hal_tdm_error hal_tdm_pp_attach(hal_tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst); + +/** + * @brief Commit changes for the post-processing object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] pp The post-processing object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ hal_tdm_error hal_tdm_pp_commit(hal_tdm_pp *pp); + +/** + * @brief Set the processing done handler to the post-processing object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] pp The post-processing object. + * @param[in] func The processing done handler. + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module @b SHOULD call #hal_tdm_pp_done_handler when converintg image is done. + */ hal_tdm_error hal_tdm_pp_set_done_handler(hal_tdm_pp *pp, hal_tdm_pp_done_handler func, void *user_data); -/* capture_funcs */ +/** + * @brief Destroy the capture object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] capture The capture object. + * @see hal_tdm_output_create_capture() + * @see hal_tdm_layer_create_capture() + */ void hal_tdm_capture_destroy(hal_tdm_capture *capture); + +/** + * @brief Set the geometry information to the capture object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] capture The capture object. + * @param[in] info The geometry information. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_capture_commit() + * @remark + * The backend module would apply the geometry information when committed. + */ hal_tdm_error hal_tdm_capture_set_info(hal_tdm_capture *capture, hal_tdm_info_capture *info); + +/** + * @brief Attach the TDM buffer to the capture object + * @since HAL_MODULE_TDM 1.0 + * @param[in] capture The capture object + * @param[in] buffer The TDM buffer + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @see hal_tdm_capture_set_info() + * @see hal_tdm_capture_commit() + * @see hal_tdm_capture_set_done_handler(), tdm_capture_done_handler + * @details When capture_commit() function is called, the backend module starts + * to dump the output or layer to the TDM buffer. + * @remark + * The backend module starts to dump the output or layer to to the TDM buffer when + * committed. The size/crop/transform information is set via #hal_tdm_capture_set_info() + * When done, the backend module @b SHOULD return the TDM buffer via tdm_capture_done_handler. + */ hal_tdm_error hal_tdm_capture_attach(hal_tdm_capture *capture, tbm_surface_h buffer); + +/** + * @brief Commit changes for the capture object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] capture The capture object. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + */ hal_tdm_error hal_tdm_capture_commit(hal_tdm_capture *capture); + +/** + * @brief Set the capture done handler to the capture object. + * @since HAL_MODULE_TDM 1.0 + * @param[in] capture The capture object. + * @param[in] func The done handler. + * @param[in] user_data The user data. + * @return #HAL_TDM_ERROR_NONE if success, otherwise error value. + * @remark + * The backend module @b SHOULD call #hal_tdm_capture_done_handler when capture operation is done. + */ hal_tdm_error hal_tdm_capture_set_done_handler(hal_tdm_capture *capture, hal_tdm_capture_done_handler func, void *user_data); +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/packaging/hal-api-tdm.spec b/packaging/hal-api-tdm.spec index 757a465..5797155 100644 --- a/packaging/hal-api-tdm.spec +++ b/packaging/hal-api-tdm.spec @@ -65,7 +65,7 @@ rm -rf %{buildroot} ### contain files to package ######### %files -n %{name} %manifest %{name}.manifest -%license COPYING +%license LICENSE %defattr(-,root,root,-) %{_libdir}/hal/*.so* %{_sysconfdir}/hal/%{name}-manifest.xml