From 84496bc63961000e56ffc27cfb49307fe15104d5 Mon Sep 17 00:00:00 2001 From: Boram Park Date: Thu, 30 Jun 2016 21:33:01 +0900 Subject: [PATCH] enhance doxgen document Change-Id: Ie3e787772461d0c7922627176b8be5b9dc394305 --- client/tdm_client.h | 198 +++++++++++++++++++++++++++++++++++++++++++++- client/tdm_client_types.h | 6 +- doc/Doxyfile | 5 +- protocol/tdm.xml | 19 +++-- 4 files changed, 217 insertions(+), 11 deletions(-) diff --git a/client/tdm_client.h b/client/tdm_client.h index 2f1c64f..c64391e 100644 --- a/client/tdm_client.h +++ b/client/tdm_client.h @@ -117,7 +117,7 @@ tdm_error tdm_client_handle_events(tdm_client *client); /** - * @brief Wait for VBLANK + * @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 @@ -137,47 +137,241 @@ tdm_client_wait_vblank(tdm_client *client, char *name, 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 + * @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 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 TDM_ERROR_DPMS_OFF + * when DPMS off. 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 TDM_ERROR_DPMS_OFF when DPMS off. 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. + * @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); diff --git a/client/tdm_client_types.h b/client/tdm_client_types.h index f6f6355..94807ec 100644 --- a/client/tdm_client_types.h +++ b/client/tdm_client_types.h @@ -87,6 +87,10 @@ typedef void tdm_client_output; */ typedef void tdm_client_vblank; +/** + * @brief The client output handler + * @see #tdm_client_output_add_change_handler, #tdm_client_output_remove_change_handler + */ typedef void (*tdm_client_output_change_handler)(tdm_client_output *output, tdm_output_change_type type, @@ -95,7 +99,7 @@ typedef void /** * @brief The client vblank handler - * @see #tdm_client_wait_vblank + * @see #tdm_client_vblank_wait */ typedef void (*tdm_client_vblank_handler)(tdm_client_vblank *vblank, diff --git a/doc/Doxyfile b/doc/Doxyfile index cd3a6a7..a5738ce 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -104,7 +104,10 @@ INPUT = \ include/tdm_helper.h \ include/tdm_list.h \ include/tdm_log.h \ - include/tdm_types.h + include/tdm_types.h \ + include/tdm_common.h \ + client/tdm_client_types.h \ + client/tdm_client.h INPUT_ENCODING = UTF-8 FILE_PATTERNS = RECURSIVE = NO diff --git a/protocol/tdm.xml b/protocol/tdm.xml index 308fe8c..cb161b5 100644 --- a/protocol/tdm.xml +++ b/protocol/tdm.xml @@ -9,13 +9,17 @@ - + + + When the DPMS of connection status of the output is changed, TDM server + will send wl_tdm_output.mode and wl_tdm_output.dpms event. + @@ -43,9 +47,9 @@ - - - + + + @@ -65,9 +69,10 @@ - When wl_tdm_vblank.wait_vblank is called, TDM server will send the wl_tdm_vblank.done - event which is aligned with HW vblank. Even if DPMS is off, it will send - wl_tdm_vblank.done events by using SW timer. + When wl_tdm_vblank.wait_vblank is called, TDM server will send the + wl_tdm_vblank.done event after interval vblanks. If enable_fake == 1, + TDM server will send the done event always. Otherwise, TDM server will + send the done event with TDM error value. -- 2.7.4