4d60a64abad4bd75403d3c0dbdf3fe5b725e803d
[platform/core/uifw/libtdm.git] / doc / tdm_doc.h
1 /**************************************************************************
2
3 libtdm
4
5 Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
6
7 Contact: Eunchul Kim <chulspro.kim@samsung.com>,
8          JinYoung Jeon <jy0.jeon@samsung.com>,
9          Taeheon Kim <th908.kim@samsung.com>,
10          YoungJun Cho <yj44.cho@samsung.com>,
11          SooChan Lim <sc1.lim@samsung.com>,
12          Boram Park <sc1.lim@samsung.com>
13
14 Permission is hereby granted, free of charge, to any person obtaining a
15 copy of this software and associated documentation files (the
16 "Software"), to deal in the Software without restriction, including
17 without limitation the rights to use, copy, modify, merge, publish,
18 distribute, sub license, and/or sell copies of the Software, and to
19 permit persons to whom the Software is furnished to do so, subject to
20 the following conditions:
21
22 The above copyright notice and this permission notice (including the
23 next paragraph) shall be included in all copies or substantial portions
24 of the Software.
25
26 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
27 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
28 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
29 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
30 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
31 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
32 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
33
34 **************************************************************************/
35
36 #ifndef _TDM_DOC_H_
37 #define _TDM_DOC_H_
38
39 /**
40  * @mainpage TDM
41  * @author     Boram Park, boram1288.park@samsung.com
42  * @version    1.2.0
43  * @par Introduction
44  * TDM stands for Tizen Display Manager. It's the display HAL layer for tizen
45  * display server. It offers the frontend APIs(@ref tdm.h) for a frontend user
46  * and the abstraction interface(@ref tdm_backend.h) for a hardware vendor.
47  * \n
48  * @par Objects
49  * TDM consists of display/output/layer/pp/capture objects. A frontend user can
50  * get the output/layer/pp/capture hardware information with each object.
51  * Basically, TDM supposes that all display devices have fixed outputs and
52  * layers. A frontend user can get these outputs and layers with
53  * #tdm_display_get_output_count, #tdm_display_get_output, #tdm_output_get_layer_count
54  * and #tdm_output_get_layer. To get a pp/capture object, however, a frontend
55  * user need to create a object with #tdm_display_create_pp, #tdm_output_create_capture
56  * and #tdm_layer_create_capture if available.\n
57  * \n
58  * All changes of output/layer/pp/capture objects are applied when committed.
59  * See #tdm_output_commit, #tdm_pp_commit and #tdm_capture_commit.
60  * \n
61  * @par Buffer management
62  * TDM has its own buffer release mechanism to let an user know when a TDM buffer
63  * becomes available for a next job. A frontend user can add a user release handler
64  * to a TDM buffer with #tdm_buffer_add_release_handler, and this handler will be
65  * called when it's disappered from screen or when pp/capture operation is done.
66  * \n
67  * @par Implementing a TDM backend module(for a hardware vendor)
68  * A backend module @b SHOULD define the global data symbol of which name is
69  * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
70  * at the initial time and call init() function of #tdm_backend_module.
71  * A backend module at least @b SHOULD register the #tdm_func_display,
72  * #tdm_func_output, #tdm_func_layer functions to a display object via
73  * #tdm_backend_register_func_display(), #tdm_backend_register_func_output(),
74  * #tdm_backend_register_func_layer() functions in initial time.\n
75  * @code
76     #include <tdm_backend.h>
77
78     static tdm_drm_data *drm_data;
79
80     tdm_backend_data*
81     tdm_drm_init(tdm_display *dpy, tdm_error *error)
82     {
83         tdm_func_display drm_func_display;
84         tdm_func_output drm_func_output;
85         tdm_func_layer drm_func_layer;
86
87         ...
88         drm_data = calloc(1, sizeof(tdm_drm_data));
89         ...
90
91         memset(&drm_func_display, 0, sizeof(drm_func_display));
92         drm_func_display.display_get_capabilitiy = drm_display_get_capabilitiy;
93         ...
94         ret = tdm_backend_register_func_display(dpy, &drm_func_display);
95         if (ret != TDM_ERROR_NONE)
96             goto failed;
97
98         memset(&drm_func_output, 0, sizeof(drm_func_output));
99         drm_func_output.output_get_capability = drm_output_get_capability;
100         ...
101         ret = tdm_backend_register_func_output(dpy, &drm_func_output);
102         if (ret != TDM_ERROR_NONE)
103             goto failed;
104
105         memset(&drm_func_layer, 0, sizeof(drm_func_layer));
106         drm_func_layer.layer_get_capability = drm_layer_get_capability;
107         ...
108         ret = tdm_backend_register_func_layer(dpy, &drm_func_layer);
109         if (ret != TDM_ERROR_NONE)
110             goto failed;
111         ...
112         return (tdm_backend_data*)drm_data;
113     }
114
115     void
116     tdm_drm_deinit(tdm_backend_data *bdata)
117     {
118         ...
119         free(bdata);
120     }
121
122     tdm_backend_module tdm_backend_module_data =
123     {
124         "drm",
125         "Samsung",
126         TDM_BACKEND_SET_ABI_VERSION(1,2),
127         tdm_drm_init,
128         tdm_drm_deinit
129     };
130  * @endcode
131  * \n
132  * A sample backend source code can be downloaded.
133  * @code
134  $ git clone ssh://{user_id}@review.tizen.org:29418/platform/core/uifw/libtdm-drm
135  * @endcode
136  * \n
137  * After loading a TDM backend module, TDM will call @b display_get_capabilitiy(),
138  * @b display_get_outputs(), @b output_get_capability(), @b output_get_layers(),
139  * @b layer_get_capability() functions to get the hardware information. That is,
140  * a TDM backend module @b SHOULD implement these 5 functions basically.\n
141  * \n
142  * In addition, if a hardware has a memory-to-memory converting device and the
143  * capture device, a backend module can register the #tdm_func_pp functions and
144  * #tdm_func_capture functions with #tdm_backend_register_func_pp() and
145  * #tdm_backend_register_func_capture().\n
146  * \n
147  * The @b "Remarks" part of <tdm_backend.h> explains what things should be
148  * careful for vendor to implement a TDM backend module.
149  */
150
151 #endif /* _TDM_DOC_H_ */