From 196da58a4a9f39f5a6d328c9ec0487cfff01f210 Mon Sep 17 00:00:00 2001 From: Junkyeong Kim Date: Fri, 23 Sep 2016 22:53:43 +0900 Subject: [PATCH] add comment for eom.xml Change-Id: I6b2fea443e50d1b6b4a3aeed3858c7f94210c97b Signed-off-by: Junkyeong Kim --- src/wayland/protocol/eom-client-protocol.h | 159 ++++++++++++++++++++--------- src/wayland/protocol/eom-protocol.c | 25 +++++ src/wayland/protocol/eom.xml | 131 +++++++++++++++++++----- 3 files changed, 242 insertions(+), 73 deletions(-) diff --git a/src/wayland/protocol/eom-client-protocol.h b/src/wayland/protocol/eom-client-protocol.h index 27dbc21..c88784e 100644 --- a/src/wayland/protocol/eom-client-protocol.h +++ b/src/wayland/protocol/eom-client-protocol.h @@ -1,3 +1,28 @@ +/* + * Copyright 2016 Samsung Electronics co., Ltd. All Rights Reserved. + * + * Permission to use, copy, modify, distribute, and sell this + * software and its documentation for any purpose is hereby granted + * without fee, provided that\n the above copyright notice appear in + * all copies and that both that copyright notice and this permission + * notice appear in supporting documentation, and that the name of + * the copyright holders not be used in advertising or publicity + * pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no + * representations about the suitability of this software for any + * purpose. It is provided "as is" without express or implied + * warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY + * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN + * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + * ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + * THIS SOFTWARE. + */ + #ifndef WL_EOM_CLIENT_PROTOCOL_H #define WL_EOM_CLIENT_PROTOCOL_H @@ -31,33 +56,33 @@ enum wl_eom_error { #ifndef WL_EOM_TYPE_ENUM #define WL_EOM_TYPE_ENUM /** - * wl_eom_type - connector type of the external output + * wl_eom_type - connector type * @WL_EOM_TYPE_NONE: none * @WL_EOM_TYPE_VGA: VGA output connector type - * @WL_EOM_TYPE_DIVI: VGA output connector type - * @WL_EOM_TYPE_DIVD: VGA output connector type - * @WL_EOM_TYPE_DIVA: VGA output connector type - * @WL_EOM_TYPE_COMPOSITE: VGA output connector type - * @WL_EOM_TYPE_SVIDEO: VGA output connector type - * @WL_EOM_TYPE_LVDS: VGA output connector type - * @WL_EOM_TYPE_COMPONENT: VGA output connector type - * @WL_EOM_TYPE_9PINDIN: VGA output connector type - * @WL_EOM_TYPE_DISPLAYPORT: VGA output connector type - * @WL_EOM_TYPE_HDMIA: VGA output connector type - * @WL_EOM_TYPE_HDMIB: VGA output connector type - * @WL_EOM_TYPE_TV: VGA output connector type - * @WL_EOM_TYPE_EDP: VGA output connector type - * @WL_EOM_TYPE_VIRTUAL: VGA output connector type - * @WL_EOM_TYPE_DSI: VGA output connector type + * @WL_EOM_TYPE_DVII: DVI-I output connector type + * @WL_EOM_TYPE_DVID: DVI-D output connector type + * @WL_EOM_TYPE_DVIA: DVI-A output connector type + * @WL_EOM_TYPE_COMPOSITE: Composite output connector type + * @WL_EOM_TYPE_SVIDEO: S-Video output connector type + * @WL_EOM_TYPE_LVDS: LVDS output connector type + * @WL_EOM_TYPE_COMPONENT: Component output connector type + * @WL_EOM_TYPE_9PINDIN: 9 pin DIN output connector type + * @WL_EOM_TYPE_DISPLAYPORT: DisplayPort output connector type + * @WL_EOM_TYPE_HDMIA: HDMI type A output connector type + * @WL_EOM_TYPE_HDMIB: HDMI type B output connector type + * @WL_EOM_TYPE_TV: TV output connector type + * @WL_EOM_TYPE_EDP: eDP output connector type + * @WL_EOM_TYPE_VIRTUAL: Virtual output connector type + * @WL_EOM_TYPE_DSI: DSI output connector type * - * ***** TODO ****** + * Define several connectors type of the external outputs */ enum wl_eom_type { WL_EOM_TYPE_NONE = 0, WL_EOM_TYPE_VGA = 1, - WL_EOM_TYPE_DIVI = 2, - WL_EOM_TYPE_DIVD = 3, - WL_EOM_TYPE_DIVA = 4, + WL_EOM_TYPE_DVII = 2, + WL_EOM_TYPE_DVID = 3, + WL_EOM_TYPE_DVIA = 4, WL_EOM_TYPE_COMPOSITE = 5, WL_EOM_TYPE_SVIDEO = 6, WL_EOM_TYPE_LVDS = 7, @@ -81,7 +106,7 @@ enum wl_eom_type { * @WL_EOM_STATUS_CONNECTION: output connected * @WL_EOM_STATUS_DISCONNECTION: output disconnected * - * ***** TODO ****** + * The status of external output is connected or not. */ enum wl_eom_status { WL_EOM_STATUS_NONE = 0, @@ -98,7 +123,9 @@ enum wl_eom_status { * @WL_EOM_MODE_MIRROR: mirror mode * @WL_EOM_MODE_PRESENTATION: presentation mode * - * ***** TODO ****** + * There are two modes for external output. Mirror mode is showing main + * display screen to external output. Presentation mode is showing app's + * specific buffer contents to external output. */ enum wl_eom_mode { WL_EOM_MODE_NONE = 0, @@ -113,15 +140,25 @@ enum wl_eom_mode { * wl_eom_attribute - attribute of the external output * @WL_EOM_ATTRIBUTE_NONE: none * @WL_EOM_ATTRIBUTE_NORMAL: nomal attribute - * @WL_EOM_ATTRIBUTE_EXCLUSIVE_SHARED: exclusive shared attribute + * @WL_EOM_ATTRIBUTE_EXCLUSIVE_SHARE: exclusive share attribute * @WL_EOM_ATTRIBUTE_EXCLUSIVE: exclusive attribute * - * ***** TODO ****** + * Application can use external output by attribute. + * + * If application succeed to set attribute and set external output window, + * the external output's mode will be changed to Presentation mode. + * + * Attribute has priority. If attribute is set to normal, it can be changed + * by normal, exclusive_share, exclusive. If attribute is set to + * exclusive_share, it can be changed by exclusive_share, exclusive. If + * attribute is set to exclusive, it cannot be changed by other + * application. If application which set attribute is quit or set to none, + * the mode will be changed to Mirror if connected. */ enum wl_eom_attribute { WL_EOM_ATTRIBUTE_NONE = 0, WL_EOM_ATTRIBUTE_NORMAL = 1, - WL_EOM_ATTRIBUTE_EXCLUSIVE_SHARED = 2, + WL_EOM_ATTRIBUTE_EXCLUSIVE_SHARE = 2, WL_EOM_ATTRIBUTE_EXCLUSIVE = 3, }; #endif /* WL_EOM_ATTRIBUTE_ENUM */ @@ -135,7 +172,15 @@ enum wl_eom_attribute { * @WL_EOM_ATTRIBUTE_STATE_INACTIVE: attribute is inactive on the output * @WL_EOM_ATTRIBUTE_STATE_LOST: the connection of output is lost * - * ***** TODO ****** + * It means the state of attribute. The applicatoin which set attribute + * successful can get state. + * + * Active means the external window is set to external output succefully. + * So application can use that window. Inactive means cannot use external + * output, because of dissconnecting or some other reasons. But if + * connected again, the application can use external output. Lost means the + * application is lost it's right to external output by other application's + * attribute set. */ enum wl_eom_attribute_state { WL_EOM_ATTRIBUTE_STATE_NONE = 0, @@ -146,26 +191,30 @@ enum wl_eom_attribute_state { #endif /* WL_EOM_ATTRIBUTE_STATE_ENUM */ /** - * wl_eom - an interface to get the information of the external outputs - * @output_count: (none) - * @output_info: (none) - * @output_type: (none) - * @output_mode: (none) - * @output_attribute: (none) - * @output_set_window: (none) + * wl_eom - an interface for external outputs + * @output_count: external output count + * @output_info: + * @output_type: output type and connection info + * @output_mode: output mode info + * @output_attribute: output attribute info + * @output_set_window: reslut of set_window * - * ***** TODO ****** + * An interface to get information of external outputs and to use + * external outputs. */ struct wl_eom_listener { /** - * output_count - (none) + * output_count - external output count * @count: (none) + * + * Get the number of external output devices that are supported + * by this device. */ void (*output_count)(void *data, struct wl_eom *wl_eom, uint32_t count); /** - * output_info - (none) + * output_info - * @output_id: (none) * @type: (none) * @mode: (none) @@ -178,6 +227,14 @@ struct wl_eom_listener { * @attribute: (none) * @attribute_state: (none) * @error: (none) + * + * Send information of specific external output to client. + * + * Output_id is numbering of external outputs. It is fixed when + * booting time. The type, mode attribute, attribute_state is + * mentioned above. The w and h is the resolution of external + * output. The w_mm and h_mm is the physical size of external + * output. The unit is mm. */ void (*output_info)(void *data, struct wl_eom *wl_eom, @@ -194,10 +251,12 @@ struct wl_eom_listener { uint32_t attribute_state, uint32_t error); /** - * output_type - (none) + * output_type - output type and connection info * @output_id: (none) * @type: (none) * @status: (none) + * + * Send information of output type and connection. */ void (*output_type)(void *data, struct wl_eom *wl_eom, @@ -205,20 +264,24 @@ struct wl_eom_listener { uint32_t type, uint32_t status); /** - * output_mode - (none) + * output_mode - output mode info * @output_id: (none) * @mode: (none) + * + * Send information of output mode. */ void (*output_mode)(void *data, struct wl_eom *wl_eom, uint32_t output_id, uint32_t mode); /** - * output_attribute - (none) + * output_attribute - output attribute info * @output_id: (none) * @attribute: (none) * @attribute_state: (none) * @error: (none) + * + * Send information of output attribute and attribute state. */ void (*output_attribute)(void *data, struct wl_eom *wl_eom, @@ -227,16 +290,18 @@ struct wl_eom_listener { uint32_t attribute_state, uint32_t error); /** - * output_set_window - (none) + * output_set_window - reslut of set_window * @output_id: (none) * @error: (none) + * + * Send the result of set_window to client. */ void (*output_set_window)(void *data, struct wl_eom *wl_eom, uint32_t output_id, uint32_t error); }; -/*LCOV_EXCL_START*/ + static inline int wl_eom_add_listener(struct wl_eom *wl_eom, const struct wl_eom_listener *listener, void *data) @@ -244,7 +309,7 @@ wl_eom_add_listener(struct wl_eom *wl_eom, return wl_proxy_add_listener((struct wl_proxy *) wl_eom, (void (**)(void)) listener, data); } -/*LCOV_EXCL_STOP*/ + #define WL_EOM_SET_ATTRIBUTE 0 #define WL_EOM_SET_XDG_WINDOW 1 #define WL_EOM_SET_SHELL_WINDOW 2 @@ -278,30 +343,28 @@ wl_eom_destroy(struct wl_eom *wl_eom) { wl_proxy_destroy((struct wl_proxy *) wl_eom); } -/*LCOV_EXCL_START*/ + static inline void wl_eom_set_attribute(struct wl_eom *wl_eom, uint32_t output_id, uint32_t attribute) { wl_proxy_marshal((struct wl_proxy *) wl_eom, WL_EOM_SET_ATTRIBUTE, output_id, attribute); } -/*LCOV_EXCL_STOP*/ -/*LCOV_EXCL_START*/ + static inline void wl_eom_set_xdg_window(struct wl_eom *wl_eom, uint32_t output_id, struct xdg_surface *surface) { wl_proxy_marshal((struct wl_proxy *) wl_eom, WL_EOM_SET_XDG_WINDOW, output_id, surface); } -/*LCOV_EXCL_STOP*/ -/*LCOV_EXCL_START*/ + static inline void wl_eom_set_shell_window(struct wl_eom *wl_eom, uint32_t output_id, struct wl_shell_surface *surface) { wl_proxy_marshal((struct wl_proxy *) wl_eom, WL_EOM_SET_SHELL_WINDOW, output_id, surface); } -/*LCOV_EXCL_STOP*/ + static inline void wl_eom_get_output_info(struct wl_eom *wl_eom, uint32_t output_id) { diff --git a/src/wayland/protocol/eom-protocol.c b/src/wayland/protocol/eom-protocol.c index b0b38d5..3ca9b25 100644 --- a/src/wayland/protocol/eom-protocol.c +++ b/src/wayland/protocol/eom-protocol.c @@ -1,3 +1,28 @@ +/* + * Copyright 2016 Samsung Electronics co., Ltd. All Rights Reserved. + * + * Permission to use, copy, modify, distribute, and sell this + * software and its documentation for any purpose is hereby granted + * without fee, provided that\n the above copyright notice appear in + * all copies and that both that copyright notice and this permission + * notice appear in supporting documentation, and that the name of + * the copyright holders not be used in advertising or publicity + * pertaining to distribution of the software without specific, + * written prior permission. The copyright holders make no + * representations about the suitability of this software for any + * purpose. It is provided "as is" without express or implied + * warranty. + * + * THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + * SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + * FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY + * SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN + * AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + * ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + * THIS SOFTWARE. + */ + #include #include #include "wayland-util.h" diff --git a/src/wayland/protocol/eom.xml b/src/wayland/protocol/eom.xml index 2ea8e15..b1fd312 100644 --- a/src/wayland/protocol/eom.xml +++ b/src/wayland/protocol/eom.xml @@ -1,7 +1,34 @@ + + + + Copyright 2016 Samsung Electronics co., Ltd. All Rights Reserved. + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that\n the above copyright notice appear in + all copies and that both that copyright notice and this permission + notice appear in supporting documentation, and that the name of + the copyright holders not be used in advertising or publicity + pertaining to distribution of the software without specific, + written prior permission. The copyright holders make no + representations about the suitability of this software for any + purpose. It is provided "as is" without express or implied + warranty. + + THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS + SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY + SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN + AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, + ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF + THIS SOFTWARE. + + - - ***** TODO ****** + + An interface to get information of external outputs and to use external outputs. @@ -12,31 +39,31 @@ - - ***** TODO ****** + + Define several connectors type of the external outputs - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + - ***** TODO ****** + The status of external output is connected or not. @@ -45,7 +72,9 @@ - ***** TODO ****** + There are two modes for external output. + Mirror mode is showing main display screen to external output. + Presentation mode is showing app's specific buffer contents to external output. @@ -54,17 +83,34 @@ - ***** TODO ****** + Application can use external output by attribute. + + If application succeed to set attribute and set external output window, + the external output's mode will be changed to Presentation mode. + + Attribute has priority. + If attribute is set to normal, it can be changed by normal, exclusive_share, exclusive. + If attribute is set to exclusive_share, it can be changed by exclusive_share, exclusive. + If attribute is set to exclusive, it cannot be changed by other application. + If application which set attribute is quit or set to none, + the mode will be changed to Mirror if connected. - + - ***** TODO ****** + It means the state of attribute. + The applicatoin which set attribute successful can get state. + + Active means the external window is set to external output succefully. + So application can use that window. + Inactive means cannot use external output, because of dissconnecting or some other reasons. + But if connected again, the application can use external output. + Lost means the application is lost it's right to external output by other application's attribute set. @@ -73,29 +119,52 @@ + + Application can have right to external output by set_attribute. + + + Use xdg_shell_surface to external output. + + + Use shell_surface to external output. + + + Request to server to send information of specific external output to client by output id. + + + Get the number of external output devices that are supported by this device. + + + Send information of specific external output to client. + + Output_id is numbering of external outputs. It is fixed when booting time. + The type, mode attribute, attribute_state is mentioned above. + The w and h is the resolution of external output. + The w_mm and h_mm is the physical size of external output. The unit is mm. + @@ -111,17 +180,26 @@ + + Send information of output type and connection. + + + Send information of output mode. + + + Send information of output attribute and attribute state. + @@ -129,10 +207,13 @@ + + Send the result of set_window to client. + - + -- 2.7.4