1 /**************************************************************************
5 Copyright 2014 Samsung Electronics co., Ltd. All Rights Reserved.
7 Contact: SooChan Lim <sc1.lim@samsung.com>, Sangjin Lee <lsj119@samsung.com>
8 Inpyo Kang <mantiger@samsung.com>, Dongyeon Kim <dy5.kim@samsung.com>
9 Boram Park <boram1288.park@samsung.com>, Changyeon Lee <cyeon.lee@samsung.com>
11 Permission is hereby granted, free of charge, to any person obtaining a
12 copy of this software and associated documentation files (the
13 "Software"), to deal in the Software without restriction, including
14 without limitation the rights to use, copy, modify, merge, publish,
15 distribute, sub license, and/or sell copies of the Software, and to
16 permit persons to whom the Software is furnished to do so, subject to
17 the following conditions:
19 The above copyright notice and this permission notice (including the
20 next paragraph) shall be included in all copies or substantial portions
23 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
24 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
25 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
26 IN NO EVENT SHALL PRECISION INSIGHT AND/OR ITS SUPPLIERS BE LIABLE FOR
27 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
28 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
29 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
31 **************************************************************************/
33 #ifndef _TBM_SURFACE_H_
34 #define _TBM_SURFACE_H_
37 * @addtogroup CAPI_UI_TBM_SURFACE_MODULE
49 * @brief Enumeration for tbm_surface error type.
50 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
53 TBM_SURFACE_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
54 TBM_SURFACE_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
55 TBM_SURFACE_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid Operation */
56 } tbm_surface_error_e;
59 * @brief Definition for the max number of TBM surface plane.
60 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
62 #define TBM_SURF_PLANE_MAX 4
64 /* option to map the tbm_surface */
66 * @brief Definition for the access option to read.
67 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
69 #define TBM_SURF_OPTION_READ (1 << 0)
71 * @brief Definition for the access option to write.
72 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
74 #define TBM_SURF_OPTION_WRITE (1 << 1)
77 * @brief Definition for the TBM plane struct.
78 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
80 typedef struct _tbm_surface_plane {
81 unsigned char *ptr; /**< Plane pointer */
82 uint32_t size; /**< Plane size */
83 uint32_t offset; /**< Plane offset */
84 uint32_t stride; /**< Plane stride */
86 void *reserved1; /**< Reserved pointer1 */
87 void *reserved2; /**< Reserved pointer2 */
88 void *reserved3; /**< Reserved pointer3 */
89 } tbm_surface_plane_s;
92 * @brief Definition for the TBM surface information struct.
93 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
95 typedef struct _tbm_surface_info {
96 uint32_t width; /**< TBM surface width */
97 uint32_t height; /**< TBM surface height */
98 tbm_format format; /**< TBM surface format*/
99 uint32_t bpp; /**< TBM surface bbp */
100 uint32_t size; /**< TBM surface size */
102 uint32_t num_planes; /**< The number of planes */
103 tbm_surface_plane_s planes[TBM_SURF_PLANE_MAX]; /**< Array of planes */
105 void *reserved4; /**< Reserved pointer4 */
106 void *reserved5; /**< Reserved pointer5 */
107 void *reserved6; /**< Reserved pointer6 */
108 } tbm_surface_info_s;
115 * @brief Queries surface format list and number of format supported by the system.
116 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
118 * @remarks You must release the formats using free().
120 * @param[out] formats The format array which the system can support \n
121 * This pointer has to be freed by user.
122 * @param[out] num The number of formats
124 * @return #TBM_SURFACE_ERROR_NONE if this function succeeds,
125 * otherwise an error status value
127 * @retval #TBM_SURFACE_ERROR_NONE Success
128 * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION Invalid operation
132 #include <tbm_surface.h>
137 tbm_surface_error_e tse;
139 tse = tbm_surface_query_formats (&formats, &format_num))
141 for( i = 0 ; i < format_num ; i++)
143 if (formats[i] == TBM_FORMAT_RGB332)
150 int tbm_surface_query_formats(uint32_t **formats, uint32_t *num);
153 * @brief Creates the tbm_surface.
154 * @details This function creates the tbm_surface with the given width, height, and format.
156 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
158 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
160 * @param[in] width The width of surface
161 * @param[in] height The height of surface
162 * @param[in] format The format of surface
164 * @return #tbm_surface_h on success,
167 * @retval #tbm_surface_h The TBM surface handle
169 * @exception #TBM_SURFACE_ERROR_NONE Success
170 * @exception #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
171 * @exception #TBM_SURFACE_ERROR_INVALID_OPERATION Invalid operation
173 * @see tbm_surface_destroy()
177 #include <tbm_surface.h>
179 tbm_surface_h surface;
181 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
185 tbm_surface_destroy (surface);
188 tbm_surface_h tbm_surface_create(int width, int height, tbm_format format);
191 * @brief Destroys the tbm_surface.
192 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
194 * @param[in] surface The #tbm_surface_h
196 * @return #TBM_SURFACE_ERROR_NONE on success,
197 * otherwise an error status value
199 * @retval #TBM_SURFACE_ERROR_NONE Success
200 * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
202 * @see tbm_surface_create()
206 #include <tbm_surface.h>
208 tbm_surface_h surface;
210 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
214 tbm_surface_destroy (surface);
217 int tbm_surface_destroy(tbm_surface_h surface);
220 * @brief Maps the tbm_surface according to the access option.
221 * @details After mapping tbm_surface, the information of tbm_surface is assigned in #tbm_surface_info_s struct. \n
222 * The information of tbm_surface has width, height, format, bpp, size, number of planes and information of planes. \n
223 * The information of planes has stride, offset, size and pointer of plane. \n
224 * #TBM_SURF_OPTION_READ indicates access option to read. \n
225 * #TBM_SURF_OPTION_WRITE indicates access option to write.
227 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
229 * @param[in] surface The #tbm_surface_h
230 * @param[in] opt The option to access the tbm_surface
231 * @param[out] info The information of the tbm_surface
233 * @return #TBM_SURFACE_ERROR_NONE on success,
234 * otherwise an error status value
236 * @retval #TBM_SURFACE_ERROR_NONE Success
237 * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
238 * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION Invalid operation
240 * @see tbm_surface_unmap();
244 #include <tbm_surface.h>
246 tbm_surface_h surface;
247 tbm_surface_info_s info;
250 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
251 ret = tbm_surface_map (surface, TBM_SURF_OPTION_WRITE|TBM_SURF_OPTION_READ, &info);
255 tbm_surface_unmap (surface);
256 tbm_surface_destroy (surface);
259 int tbm_surface_map(tbm_surface_h surface, int opt, tbm_surface_info_s *info);
262 * @brief Unmaps the tbm_surface.
263 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
265 * @param[in] surface The #tbm_surface_h
267 * @return #TBM_SURFACE_ERROR_NONE on success,
268 * otherwise an error status value
270 * @retval #TBM_SURFACE_ERROR_NONE Success
271 * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
273 * @see tbm_surface_map()
277 #include <tbm_surface.h>
279 tbm_surface_h surface;
280 tbm_surface_info_s info;
283 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
284 ret = tbm_surface_map (surface, TBM_SURF_OPTION_WRITE|TBM_SURF_OPTION_READ, &info);
288 tbm_surface_unmap (surface);
289 tbm_surface_destroy (surface);
292 int tbm_surface_unmap(tbm_surface_h surface);
295 * @brief Gets the information of the tbm_surface.
296 * @details The information of tbm_surface is assigned in #tbm_surface_info_s struct. \n
297 * The information of tbm_surface has width, height, format, bpp, size, number of planes and information of planes. \n
298 * The information of planes has stride, offset, size and pointer of plane.
300 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
302 * @param[in] surface The #tbm_surface_h
303 * @param[out] info The information of the tbm_surface
305 * @return #TBM_SURFACE_ERROR_NONE on success,
306 * otherwise an error status value
308 * @retval #TBM_SURFACE_ERROR_NONE Success
309 * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
310 * @retval #TBM_SURFACE_ERROR_INVALID_OPERATION Invalid operation
312 * @see tbm_surface_map()
316 #include <tbm_surface.h>
318 tbm_surface_h surface;
319 tbm_surface_info_s info;
322 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
323 ret = tbm_surface_get_info (surface, &info);
327 tbm_surface_destroy (surface);
330 int tbm_surface_get_info(tbm_surface_h surface, tbm_surface_info_s *info);
333 * @brief Gets the width of the tbm_surface.
334 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
336 * @param[in] surface The #tbm_surface_h
338 * @return The width of the tbm_surface on success,
339 * otherwise an error status value
341 * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
345 #include <tbm_surface.h>
347 tbm_surface_h surface;
350 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
354 width = tbm_surface_get_width (surface);
358 tbm_surface_destroy (surface);
361 int tbm_surface_get_width(tbm_surface_h surface);
364 * @brief Gets the height of the tbm_surface.
365 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
367 * @param[in] surface The #tbm_surface_h
369 * @return The height of the tbm_surface if this function succeeds,
370 * otherwise an error status value
372 * @retval #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
376 #include <tbm_surface.h>
378 tbm_surface_h surface;
381 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
385 height = tbm_surface_get_height (surface);
389 tbm_surface_destroy (surface);
392 int tbm_surface_get_height(tbm_surface_h surface);
395 * @brief Gets the format of the tbm_surface.
396 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
398 * @remark The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
400 * @param[in] surface The #tbm_surface_h
402 * @return The format of the tbm_surface on success,
403 * otherwise @c 0 on failure
405 * @retval #tbm_format The format of surface
407 * @exception #TBM_SURFACE_ERROR_NONE Success
408 * @exception #TBM_SURFACE_ERROR_INVALID_PARAMETER Invalid parameter
412 #include <tbm_surface.h>
414 tbm_surface_s surface;
417 surface = tbm_surface_create (128, 128, TBM_FORMAT_RGB332);
421 format = tbm_surface_get_format (surface);
425 tbm_surface_destroy (surface);
428 tbm_format tbm_surface_get_format(tbm_surface_h surface);
436 #endif /* _TBM_SURFACE_H_ */