change the argument name.
[platform/core/uifw/libtbm.git] / src / tbm_bufmgr_backend.h
1 /**************************************************************************
2
3 libtbm
4
5 Copyright 2012 Samsung Electronics co., Ltd. All Rights Reserved.
6
7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
8 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
9
10 Permission is hereby granted, free of charge, to any person obtaining a
11 copy of this software and associated documentation files (the
12 "Software"), to deal in the Software without restriction, including
13 without limitation the rights to use, copy, modify, merge, publish,
14 distribute, sub license, and/or sell copies of the Software, and to
15 permit persons to whom the Software is furnished to do so, subject to
16 the following conditions:
17
18 The above copyright notice and this permission notice (including the
19 next paragraph) shall be included in all copies or substantial portions
20 of the Software.
21
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
23 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
25 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
27 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
28 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29
30 **************************************************************************/
31
32 /*
33  * This file is referenced by the xf86Module.h in xorg server.
34  */
35
36 #ifndef _TBM_BUFMGR_BACKEND_H_
37 #define _TBM_BUFMGR_BACKEND_H_
38
39 #include <tbm_bufmgr.h>
40 #include <pthread.h>
41
42 /**
43  * \file tbm_bufmgr_backend.h
44  * \brief backend header for Tizen Buffer Manager
45  *   This header is for the implementation of the TBM backend module.
46  */
47
48 #define ABI_MINOR_MASK          0x0000FFFF
49 #define ABI_MAJOR_MASK          0xFFFF0000
50 #define GET_ABI_MINOR(v)        ((v) & ABI_MINOR_MASK)
51 #define GET_ABI_MAJOR(v)        (((v) & ABI_MAJOR_MASK) >> 16)
52
53 /*
54  * ABI versions.  Each version has a major and minor revision.  Modules
55  * using lower minor revisions must work with servers of a higher minor
56  * revision.  There is no compatibility between different major revisions.
57  * Whenever the ABI_ANSIC_VERSION is changed, the others must also be
58  * changed.  The minor revision mask is 0x0000FFFF and the major revision
59  * mask is 0xFFFF0000.
60  */
61 #define SET_ABI_VERSION(maj, min) \
62                 ((((maj) << 16) & ABI_MAJOR_MASK) | ((min) & ABI_MINOR_MASK))
63
64 #define TBM_ABI_VERSION SET_ABI_VERSION(1, 1) /**< current abi vertion  */
65
66 typedef struct _tbm_bufmgr_backend *tbm_bufmgr_backend;
67
68 /**
69  * @brief TBM backend functions
70  *  the set of function pointers for the backend module of TBM.
71  */
72 struct _tbm_bufmgr_backend {
73         int flags;
74
75         void *priv;     /**< bufmgr private */
76
77         /**
78         * @brief deinitialize the bufmgr private.
79         * @param[in] priv : the private of the bufmgr
80         */
81         void (*bufmgr_deinit)(void *priv);
82
83         /**
84         * @brief get the size of a bo.
85         * @param[in] bo : the buffer object
86         * @return size if this function succeeds, otherwise 0.
87         */
88         int (*bo_size)(tbm_bo bo);
89
90         /**
91         * @brief allocate the buffer object
92         * @param[in] bo : the buffer object
93         * @param[in] size : the size of buffer object
94         * @param[in] flags : the flags of memory type
95         * @return pointer of the bo private.
96         */
97         void *(*bo_alloc)(tbm_bo bo, int size, int flags);
98
99         /**
100         * @brief free the buffer object.
101         * @param[in] bo : the buffer object
102         */
103         void (*bo_free)(tbm_bo bo);
104
105         /**
106         * @brief import the buffer object associated with the key.
107         * @remarks If the backend doesn't support a buffer sharing by tbm key,
108                         fucntion pointer must be set to NULL.
109         * @param[in] bo : the buffer object
110         * @param[in] key : the key associated with the buffer object
111         * @return pointer of the bo private.
112         */
113         void *(*bo_import)(tbm_bo bo, unsigned int key);
114
115         /**
116         * @brief export the buffer object
117         * @remarks If the backend doesn't support a buffer sharing by tbm key,
118                         fucntion pointer must be set to NULL.
119         * @param[in] bo : the buffer object
120         * @return key associated with the buffer object
121         */
122         unsigned int (*bo_export)(tbm_bo bo);
123
124         /**
125         * @brief get the tbm_bo_handle according to the device type.
126         * @param[in] bo : the buffer object
127         * @param[in] device : the device type to get a handle
128         * @return the handle of the buffer object
129         */
130         tbm_bo_handle(*bo_get_handle)(tbm_bo bo, int device);
131
132         /**
133         * @brief map the buffer object according to the device type and the option.
134         * @param[in] bo : the buffer object
135         * @param[in] device : the device type to get a handle
136         * @param[in] opt : the option to access the buffer object
137         * @return the handle of the buffer object
138         */
139         tbm_bo_handle(*bo_map)(tbm_bo bo, int device, int opt);
140
141         /**
142         * @brief unmap the buffer object.
143         * @param[in] bo : the buffer object
144         * @return 1 if this function succeeds, otherwise 0.
145         */
146         int (*bo_unmap)(tbm_bo bo);
147
148         /**
149         * @brief unlock the buffer object.
150         * @param[in] bo : the buffer object
151         * @return 1 if this function succeeds, otherwise 0.
152         * @remark This function pointer could be null. (default: use the tizen global lock)
153         */
154         int (*bo_unlock)(tbm_bo bo);
155
156         /**
157         * @brief lock the buffer object with a device and an opt.
158         * @param[in] bo : the buffer object
159         * @param[in] device : the device type to get a handle
160         * @param[in] opt : the option to access the buffer object
161         * @return 1 if this function succeeds, otherwise 0.
162         * @remark This function pointer could be null. (default: use the tizen global lock)
163         */
164         int (*bo_lock)(tbm_bo bo, int device, int opt);
165
166         /**
167         * @brief query the formats list and the num to be supported by backend.
168         * @param[out] **formats : format array list. this array has to be allocated by backend funtion
169         * @param[out] *num : the number of the formats to be supported by backend
170         * @return 1 if this function succeeds, otherwise 0.
171         */
172         int (*surface_supported_format)(uint32_t **formats, uint32_t *num);
173
174         /**
175         * @brief get the plane data of the surface.
176         * @param[in] width : the width of the surface
177         * @param[in] height : the height of the surface
178         * @param[in] format : the format of the surface
179         * @param[in] plane_idx : the format of the surface
180         * @param[out] size : the size of the plane
181         * @param[out] offset : the offset of the plane
182         * @param[out] pitch : the pitch of the plane
183         * @param[out] bo_idx : the bo index of the plane
184         * @return 1 if this function succeeds, otherwise 0.
185         */
186         int (*surface_get_plane_data)(int width, int height,
187                                       tbm_format format, int plane_idx, uint32_t *size, uint32_t *offset,
188                                       uint32_t *pitch, int *bo_idx);
189
190         /**
191         * @brief import the buffer object associated with the prime fd.
192         * @remarks tbm_fd must be free by user.
193         * @remarks If the backend doesn't support a buffer sharing by tbm fd,
194                         fucntion pointer must be set to NULL.
195         * @param[in] bo : the buffer object
196         * @param[in] fd : the prime fd associated with the buffer object
197         * @return pointer of the bo private.
198         */
199         void *(*bo_import_fd)(tbm_bo bo, tbm_fd fd);
200
201         /**
202         * @brief export the buffer object
203         * @remarks tbm_fd must be free by user.
204         * @remarks If the backend doesn't support a buffer sharing by tbm fd,
205                         fucntion pointer must be set to NULL.
206         * @param[in] bo : the buffer object
207         * @return tbm_fd associated with the buffer object
208         */
209         tbm_fd (*bo_export_fd)(tbm_bo bo);
210
211         /**
212         * @brief get the tbm flags of memory type
213         * @param[in] bo : the buffer object
214         * @see #TBM_BO_FLAGS
215         * @return tbm flags of memory type is this function succeeds, otherwise 0.
216         */
217         int (*bo_get_flags)(tbm_bo bo);
218
219         /**
220         * @brief get(bind) the native display
221         * @param[in] bufmgr : the buffer object
222         * @param[in] native_display : the native display
223         * @return 1 if this function succeeds, otherwise 0.
224         */
225         int (*bufmgr_bind_native_display)(tbm_bufmgr bufmgr, void *native_display);
226
227         /**
228         * @brief allocate the buffer object for tbm surface
229         * @param[in] bo : the buffer object
230         * @param[in] width : the width of surface
231         * @param[in] height : the height of surface
232         * @param[in] format : the format of surface
233         * @param[in] flags : the flags of memory type
234         * @param[in] bo_idx : the index of bo in surface
235         * @return pointer of the bo private.
236         */
237         void * (*surface_bo_alloc)(tbm_bo bo, int width, int height, int format, int flags, int bo_idx);
238
239         /* Padding for future extension */
240         void (*reserved1)(void);
241         void (*reserved2)(void);
242         void (*reserved3)(void);
243         void (*reserved4)(void);
244         void (*reserved5)(void);
245         void (*reserved6)(void);
246 };
247
248 /**
249  * @brief tbm module information
250  *  data type for the module information
251  */
252 typedef struct {
253         const char *modname;               /**< name of module, e.g. "foo" */
254         const char *vendor;                        /**< vendor specific string */
255         unsigned long abiversion;          /**< ABI version */
256 } TBMModuleVersionInfo;
257
258 typedef int (*ModuleInitProc) (tbm_bufmgr, int);
259
260 #define MODULEINITPPROTO(func) int func(tbm_bufmgr, int) /**< prototype for init symbol of bakcend module */
261
262 /**
263  * @brief tbm module data
264  *  data type for the entry point of the backend module
265  */
266 typedef struct {
267         TBMModuleVersionInfo *vers;     /**< tbm module informtaion */
268         ModuleInitProc init;            /**< init function of a backend module */
269 } TBMModuleData;
270
271 tbm_bufmgr_backend tbm_backend_alloc(void);
272 void tbm_backend_free(tbm_bufmgr_backend backend);
273 int tbm_backend_init(tbm_bufmgr bufmgr, tbm_bufmgr_backend backend);
274
275 void *tbm_backend_get_bufmgr_priv(tbm_bo bo);
276 void *tbm_backend_get_priv_from_bufmgr(tbm_bufmgr bufmgr);
277 void *tbm_backend_get_bo_priv(tbm_bo bo);
278 int tbm_backend_is_display_server(void);
279
280 #endif                                                  /* _TBM_BUFMGR_BACKEND_H_ */