X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;ds=sidebyside;f=client%2Ftdm_client.h;h=b52785acb470bcaddc4f2a202263fb6174e5729d;hb=e21703af4902508822f6c9942b94496da4e4342e;hp=06e2c9b10fac0b89da14c2037873e2c93532050d;hpb=187fc69a84a832e0d3b90c8883d83beb948216b3;p=platform%2Fcore%2Fuifw%2Flibtdm.git diff --git a/client/tdm_client.h b/client/tdm_client.h index 06e2c9b..b52785a 100644 --- a/client/tdm_client.h +++ b/client/tdm_client.h @@ -1,41 +1,43 @@ /************************************************************************** - -libtdm - -Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved. - -Contact: Eunchul Kim , - JinYoung Jeon , - Taeheon Kim , - YoungJun Cho , - SooChan Lim , - Boram Park - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sub license, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: - -The above copyright notice and this permission notice (including the -next paragraph) shall be included in all copies or substantial portions -of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. -IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR -ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, -TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - + * + * libtdm + * + * Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved. + * + * Contact: Eunchul Kim , + * JinYoung Jeon , + * Taeheon Kim , + * YoungJun Cho , + * SooChan Lim , + * Boram Park + * + * Permission is hereby granted, free of charge, to any person obtaining a + * copy of this software and associated documentation files (the + * "Software"), to deal in the Software without restriction, including + * without limitation the rights to use, copy, modify, merge, publish, + * distribute, sub license, and/or sell copies of the Software, and to + * permit persons to whom the Software is furnished to do so, subject to + * the following conditions: + * + * The above copyright notice and this permission notice (including the + * next paragraph) shall be included in all copies or substantial portions + * of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. + * IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR + * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + * **************************************************************************/ #ifndef _TDM_CLIENT_H_ #define _TDM_CLIENT_H_ +#include "tdm_client_types.h" + #ifdef __cplusplus extern "C" { #endif @@ -45,44 +47,18 @@ extern "C" { * @brief The header file for a client of TDM. * @par Example * @code - #include //for a client of TDM + * #include //for a client of TDM * @endcode */ /** - * @brief The client error enumeration - */ -typedef enum -{ - TDM_CLIENT_ERROR_NONE = 0, /**< none */ - TDM_CLIENT_ERROR_OPERATION_FAILED = -1, /**< operaion failed */ - TDM_CLIENT_ERROR_INVALID_PARAMETER = -2, /**< wrong input parameter */ - TDM_CLIENT_ERROR_PERMISSION_DENIED = -3, /**< access denied */ - TDM_CLIENT_ERROR_OUT_OF_MEMORY = -4, /**< no free memory */ - TDM_CLIENT_ERROR_DPMS_OFF = -5, /**< dpms off */ -} tdm_client_error; - -/** - * @brief The TDM client object - */ -typedef void *tdm_client; - -/** - * @brief The client vblank handler - * @see #tdm_client_wait_vblank - */ -typedef void -(*tdm_client_vblank_handler)(unsigned int sequence, unsigned int tv_sec, - unsigned int tv_usec, void *user_data); - -/** * @brief Create a TDM client object. - * @param[out] error #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value. + * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. * @return A TDM client object if success. Otherwise, NULL. * @see #tdm_client_destroy */ tdm_client* -tdm_client_create(tdm_client_error *error); +tdm_client_create(tdm_error *error); /** * @brief Destroy a TDM client object @@ -96,52 +72,65 @@ tdm_client_destroy(tdm_client *client); * @brief Get the file descriptor * @param[in] client A TDM client object * @param[out] fd The file descriptor - * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value. + * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see #tdm_client_handle_events * @par Example * @code - #include //for a client of TDM - - err = tdm_client_get_fd(client, &fd); - if (err != TDM_CLIENT_ERROR_NONE) { - //error handling - } - - fds.events = POLLIN; - fds.fd = fd; - fds.revents = 0; - - while(1) { - ret = poll(&fds, 1, -1); - if (ret < 0) { - if (errno == EBUSY) - continue; - else { - //error handling - } - } - - err = tdm_client_handle_events(client); - if (err != TDM_CLIENT_ERROR_NONE) { - //error handling - } - } + * #include //for a client of TDM + * + * err = tdm_client_get_fd(client, &fd); + * if (err != TDM_ERROR_NONE) { + * //error handling + * } + * + * fds.events = POLLIN; + * fds.fd = fd; + * fds.revents = 0; + * + * while(1) { + * ret = poll(&fds, 1, -1); + * if (ret < 0) { + * if (errno == EINTR || errno == EAGAIN) + * continue; + * else { + * //error handling + * } + * } + * + * err = tdm_client_handle_events(client); + * if (err != TDM_ERROR_NONE) { + * //error handling + * } + * } * @endcode */ -tdm_client_error +tdm_error tdm_client_get_fd(tdm_client *client, int *fd); /** * @brief Handle the events of the given file descriptor * @param[in] client A TDM client object - * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value. + * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see #tdm_client_get_fd */ -tdm_client_error +tdm_error tdm_client_handle_events(tdm_client *client); /** - * @brief Wait for VBLANK + * @brief Handle the events of the given file descriptor with millisecond timeout + * @details + * -1: infinite. 0: return immediately. Otherwise, waiting for ms_timeout milliseconds. + * @param[in] client A TDM client object + * @param[in] ms_timeout timeout value. + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @see #tdm_client_get_fd + */ +tdm_error +tdm_client_handle_events_timeout(tdm_client *client, int ms_timeout); + +/** + * @brief @b Deprecated. Wait for VBLANK. + * @deprecated * @details After interval vblanks, a client vblank handler will be called. * If 'sw_timer' param is 1 in case of DPMS off, TDM will use the SW timer and * call a client vblank handler. Otherwise, this function will return error. @@ -152,13 +141,335 @@ tdm_client_handle_events(tdm_client *client); * @param[in] sync 0: asynchronous, 1:synchronous * @param[in] func A client vblank handler * @param[in] user_data The user data - * @return #TDM_CLIENT_ERROR_NONE if success. Otherwise, error value. + * @return #TDM_ERROR_NONE if success. Otherwise, error value. * @see #tdm_client_vblank_handler */ -tdm_client_error +tdm_error tdm_client_wait_vblank(tdm_client *client, char *name, - int sw_timer, int interval, int sync, - tdm_client_vblank_handler func, void *user_data); + int sw_timer, int interval, int sync, + tdm_client_vblank_handler2 func, void *user_data); + +/** + * @brief Get the client output object which has the given name. + * @details + * The client output name can be @b 'primary' or @b 'default' to get the main output. + * @param[in] client The TDM client object + * @param[in] name The name of the TDM client output object + * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. + * @return A client output object if success. Otherwise, NULL. + */ +tdm_client_output* +tdm_client_get_output(tdm_client *client, char *name, tdm_error *error); + +/** + * @brief Add the client output change handler + * @details The handler will be called when the status of a + * client output object is changed. connection, DPMS, etc. + * @param[in] output The client output object + * @param[in] func The client output change handler + * @param[in] user_data The user data + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @par Example + * @code + * #include //for a client of TDM + * + * static void + * _client_output_handler(tdm_client_output *output, tdm_output_change_type type, + * tdm_value value, void *user_data) + * { + * char *conn_str[3] = {"disconnected", "connected", "mode_setted"}; + * char *dpms_str[4] = {"on", "standy", "suspend", "off"}; + * + * if (type == TDM_OUTPUT_CHANGE_CONNECTION) + * printf("output %s.\n", conn_str[value.u32]); + * else if (type == TDM_OUTPUT_CHANGE_DPMS) + * printf("dpms %s.\n", dpms_str[value.u32]); + * } + * ... + * tdm_client_output_add_change_handler(output, _client_output_handler, NULL); + * ... + * tdm_client_output_remove_change_handler(output, _client_output_handler, NULL); + * + * @endcode + */ +tdm_error +tdm_client_output_add_change_handler(tdm_client_output *output, + tdm_client_output_change_handler func, + void *user_data); + +/** + * @brief Remove the client output change handler + * @param[in] output The client output object + * @param[in] func The client output change handler + * @param[in] user_data The user data + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +void +tdm_client_output_remove_change_handler(tdm_client_output *output, + tdm_client_output_change_handler func, + void *user_data); + +/** + * @brief Get the vertical refresh rate of the given client output + * @param[in] output The client output object + * @param[out] refresh The refresh rate + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_output_get_refresh_rate(tdm_client_output *output, unsigned int *refresh); + +/** + * @brief Get the connection status of the given client output + * @param[in] output The client output object + * @param[out] status The connection status + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_output_get_conn_status(tdm_client_output *output, tdm_output_conn_status *status); + +/** + * @brief Get the DPMS value of the given client output + * @param[in] output The client output object + * @param[out] dpms The DPMS value + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_output_get_dpms(tdm_client_output *output, tdm_output_dpms *dpms); + +/** + * @brief Create the client vblank object of the given client output + * @details + * tdm client vblank basically uses the HW vblank resource. Therefore, if HW vblank + * is not available for some reasons, such as output disconnection and dpms off, + * #tdm_client_vblank_wait will return error. If you want it to work propery in spite + * of these reasons, you can use #tdm_client_vblank_set_enable_fake to get SW fake + * vblank events. + * @param[in] output The client output object + * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value. + * @return A client vblank object if success. Otherwise, NULL. + */ +tdm_client_vblank* +tdm_client_output_create_vblank(tdm_client_output *output, tdm_error *error); + +/** + * @brief Destroy the client vblank object + * @param[in] vblank The client vblank object + */ +void +tdm_client_vblank_destroy(tdm_client_vblank *vblank); + +/** + * @brief Set the name to the client vblank object + * @param[in] vblank The client vblank object + * @param[in] name The client vblank name + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_vblank_set_name(tdm_client_vblank *vblank, const char *name); + +/** + * @brief Set the sync value to the client vblank object + * @details + * If sync == 1, the user client vblank handler of #tdm_client_vblank_wait + * will be called before #tdm_client_vblank_wait returns the result. If sync == 0, + * the user client vblank handler of #tdm_client_vblank_wait will be called + * asynchronously after #tdm_client_vblank_wait returns. Default is @b asynchronous. + * @param[in] vblank The client vblank object + * @param[in] sync 0: asynchronous, 1:synchronous + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_vblank_set_sync(tdm_client_vblank *vblank, unsigned int sync); + +/** + * @brief Set the fps to the client vblank object + * @details Default is the @b vertical @b refresh @b rate of the given client output. + * @param[in] vblank The client vblank object + * @param[in] fps more than 0 + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_vblank_set_fps(tdm_client_vblank *vblank, unsigned int fps); + +/** + * @brief Set the offset(milli-second) to the client vblank object + * @details Default is @b 0. + * @param[in] vblank The client vblank object + * @param[in] offset_ms the offset(milli-second) + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_vblank_set_offset(tdm_client_vblank *vblank, int offset_ms); + +/** + * @brief Enable/Disable the fake vblank to the client vblank object + * @details + * If enable_fake == 0, #tdm_client_vblank_wait will return error when HW vblank is + * not available. Otherwise, #tdm_client_vblank_wait will return TDM_ERROR_NONE + * as success. Once #tdm_client_vblank_wait returns TDM_ERROR_NONE, the user client + * vblank handler(#tdm_client_vblank_handler) SHOULD be called after the given + * interval of #tdm_client_vblank_wait. Default is @b disable. + * @param[in] vblank The client vblank object + * @param[in] enable_fake 1:enable, 0:disable + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_vblank_set_enable_fake(tdm_client_vblank *vblank, unsigned int enable_fake); + +/** + * @brief Wait for a vblank + * @details + * This function will return error when HW vblank resource is not available. However, + * #tdm_client_vblank_wait will return TDM_ERROR_NONE as success if + * #tdm_client_vblank_set_enable_fake sets true. Once #tdm_client_vblank_wait + * returns TDM_ERROR_NONE, the user client vblank handler(#tdm_client_vblank_handler) + * SHOULD be called after the given interval. \n + * The sequence value of tdm_client_vblank_handler is the relative value of fps. + * If fps = 10, this sequence value should be increased by 10 during 1 second. + * @param[in] vblank The client vblank object + * @param[in] interval The vblank interval + * @param[in] func The user client vblank handler + * @param[in] user_data The user data + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + * @par Example + * @code + * #include //for a client of TDM + * + * static void + * _client_vblank_handler(tdm_client_vblank *vblank, tdm_error error, unsigned int sequence, + * unsigned int tv_sec, unsigned int tv_usec, void *user_data) + * { + * if (error != TDM_ERROR_NONE) + * //error handling + * } + * + * { + * tdm_client_output *output; + * tdm_client_vblank *vblank; + * tdm_error error; + * struct pollfd fds; + * int fd = -1; + * + * cliet = tdm_client_create(&error); + * if (error != TDM_ERROR_NONE) + * //error handling + * + * output = tdm_client_get_output(client, NULL, &error); + * if (error != TDM_ERROR_NONE) + * //error handling + * + * vblank = tdm_client_output_create_vblank(output, &error); + * if (error != TDM_ERROR_NONE) + * //error handling + * + * tdm_client_vblank_set_enable_fake(vblank, enable_fake); //default: disable + * tdm_client_vblank_set_sync(vblank, 0); //default: async + * tdm_client_vblank_set_fps(vblank, fps); //default: refresh rate of output + * tdm_client_vblank_set_offset(vblank, offset); //default: 0 + * + * error = tdm_client_get_fd(data->client, &fd); + * if (error != TDM_ERROR_NONE) + * //error handling + * + * fds.events = POLLIN; + * fds.fd = fd; + * fds.revents = 0; + * + * while (1) { + * int ret; + * + * error = tdm_client_vblank_wait(vblank, interval, + * _client_vblank_handler, NULL); + * if (error != TDM_ERROR_NONE) + * //error handling + * + * ret = poll(&fds, 1, -1); + * if (ret < 0) { + * if (errno == EINTR || errno == EAGAIN) // normal case + * continue; + * else + * //error handling + * } + * + * error = tdm_client_handle_events(client); + * if (error != TDM_ERROR_NONE) + * //error handling + * } + * + * tdm_client_vblank_destroy(vblank); + * tdm_client_destroy(client); + * } + * @endcode + */ +tdm_error +tdm_client_vblank_wait(tdm_client_vblank *vblank, unsigned int interval, tdm_client_vblank_handler func, void *user_data); + +/** + * @brief Wait for a vblank with the target sequence number + * @details + * This function will return error when HW vblank resource is not available. However, + * #tdm_client_vblank_wait will return TDM_ERROR_NONE as success if + * #tdm_client_vblank_set_enable_fake sets true. Once #tdm_client_vblank_wait_seq + * returns TDM_ERROR_NONE, the user client vblank handler(#tdm_client_vblank_handler) + * SHOULD be called on reaching the target sequence. + * @param[in] vblank The client vblank object + * @param[in] sequence The target sequence number + * @param[in] func The user client vblank handler + * @param[in] user_data The user data + * @return #TDM_ERROR_NONE if success. Otherwise, error value. + */ +tdm_error +tdm_client_vblank_wait_seq(tdm_client_vblank *vblank, unsigned int sequence, tdm_client_vblank_handler func, void *user_data); + +/** + * @brief Check if the client vblank object is waiting a vblank event + * @param[in] vblank The client vblank object + * @return 1 if waiting. 0 if not waiting. + */ +unsigned int +tdm_client_vblank_is_waiting(tdm_client_vblank *vblank); + + +/* Virtual Output */ +tdm_client_voutput * +tdm_client_create_voutput(tdm_client *client, const char *name, tdm_error *error); + +void +tdm_client_voutput_destroy(tdm_client_voutput *voutput); + +tdm_error +tdm_client_voutput_set_available_modes(tdm_client_voutput *voutput, const tdm_client_output_mode *modes, int count); + +tdm_error +tdm_client_voutput_set_physical_size(tdm_client_voutput *voutput, unsigned int mmWidth, unsigned int mmHeight); + +tdm_error +tdm_client_voutput_add_commit_handler(tdm_client_voutput *voutput, tdm_client_voutput_commit_handler func, void *user_data); + +void +tdm_client_voutput_remove_commit_handler(tdm_client_voutput *voutput, tdm_client_voutput_commit_handler func, void *user_data); + +tdm_error +tdm_client_voutput_get_committed_tbm_surface(tdm_client_voutput *voutput, tbm_surface_h surface); + +tdm_error +tdm_client_voutput_commit_done(tdm_client_voutput *voutput); + +tdm_client_output * +tdm_client_voutput_get_client_output(tdm_client_voutput *voutput, tdm_error *error); + +tdm_error +tdm_client_output_get_available_modes(tdm_client_output *output, tdm_client_output_mode **modes, int *count); + +tdm_error +tdm_client_output_set_mode(tdm_client_output *output, int index); + +tdm_error +tdm_client_output_connect(tdm_client_output *output); + +tdm_error +tdm_client_output_disconnect(tdm_client_output *output); +/* End of Virtual Output */ #ifdef __cplusplus }