1 /**************************************************************************
5 Copyright 2015 Samsung Electronics co., Ltd. All Rights Reserved.
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>
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:
22 The above copyright notice and this permission notice (including the
23 next paragraph) shall be included in all copies or substantial portions
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.
34 **************************************************************************/
40 #include <tbm_surface.h>
41 #include <tbm_surface_queue.h>
42 #include <tbm_surface_internal.h>
44 #include "tdm_types.h"
52 * @brief The header file for a frontend user.
55 #include <tdm.h> //for a frontend user
60 * @brief The display capability enumeration
64 TDM_DISPLAY_CAPABILITY_PP = (1<<0), /**< if hardware supports pp operation */
65 TDM_DISPLAY_CAPABILITY_CAPTURE = (1<<1), /**< if hardware supports capture operation */
66 } tdm_display_capability;
69 * @brief Initialize a display object
70 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
71 * @return A display object
72 * @see tdm_display_deinit
75 tdm_display_init(tdm_error *error);
78 * @brief Deinitialize a display object
79 * @param[in] dpy A display object
80 * @see tdm_display_init
83 tdm_display_deinit(tdm_display *dpy);
86 * @brief Update a display object
88 * When new output is connected, a frontend user need to call this function.
89 * And a frontend user can the new output information with tdm_output_get_xxx functions.
90 * @param[in] dpy A display object
91 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
94 tdm_display_update(tdm_display *dpy);
97 * @brief Get the file descriptor
98 * @details TDM handles the events of fd with #tdm_display_handle_events.
99 * @param[in] dpy A display object
100 * @param[out] fd The file descriptor
101 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
102 * @see tdm_display_handle_events
105 tdm_display_get_fd(tdm_display *dpy, int *fd);
108 * @brief Handle the events
109 * @param[in] dpy A display object
110 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
111 * @see tdm_display_get_fd
114 tdm_display_handle_events(tdm_display *dpy);
117 * @brief Get the capabilities of a display object.
118 * @details A frontend user can get whether TDM supports pp/capture functionality with this function.
119 * @param[in] dpy A display object
120 * @param[out] capabilities The capabilities of a display object
121 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
124 tdm_display_get_capabilities(tdm_display *dpy,
125 tdm_display_capability *capabilities);
128 * @brief Get the pp capabilities of a display object.
129 * @param[in] dpy A display object
130 * @param[out] capabilities The pp capabilities
131 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
134 tdm_display_get_pp_capabilities(tdm_display *dpy,
135 tdm_pp_capability *capabilities);
138 * @brief Get the pp available format array of a display object.
139 * @param[in] dpy A display object
140 * @param[out] formats The pp available format array
141 * @param[out] count The count of formats
142 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
145 tdm_display_get_pp_available_formats(tdm_display *dpy,
146 const tbm_format **formats, int *count);
149 * @brief Get the pp available size of a display object.
150 * @details -1 means that a TDM backend module doesn't define the value.
151 * @param[in] dpy A display object
152 * @param[out] min_w The minimum width which TDM can handle
153 * @param[out] min_h The minimum height which TDM can handle
154 * @param[out] max_w The maximum width which TDM can handle
155 * @param[out] max_h The maximum height which TDM can handle
156 * @param[out] preferred_align The preferred align width which TDM can handle
157 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
160 tdm_display_get_pp_available_size(tdm_display *dpy, int *min_w, int *min_h,
161 int *max_w, int *max_h, int *preferred_align);
164 * @brief Get the capture capabilities of a display object.
165 * @param[in] dpy A display object
166 * @param[out] capabilities The capture capabilities
167 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
170 tdm_display_get_capture_capabilities(tdm_display *dpy,
171 tdm_capture_capability *capabilities);
174 * @brief Get the capture available format array of a display object.
175 * @param[in] dpy A display object
176 * @param[out] formats The capture available format array
177 * @param[out] count The count of formats
178 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
181 tdm_display_get_catpure_available_formats(tdm_display *dpy,
182 const tbm_format **formats, int *count);
185 * @brief Get the output counts which a display object has.
186 * @param[in] dpy A display object
187 * @param[out] count The count of outputs
188 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
189 * @see tdm_display_get_output
192 tdm_display_get_output_count(tdm_display *dpy, int *count);
195 * @brief Get a output object which has the given index.
196 * @param[in] dpy A display object
197 * @param[in] index The index of a output object
198 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
199 * @return A output object if success. Otherwise, NULL.
200 * @see tdm_display_get_output_count
203 tdm_display_get_output(tdm_display *dpy, int index, tdm_error *error);
206 * @brief Create a pp object.
207 * @param[in] dpy A display object
208 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
209 * @return A pp object if success. Otherwise, NULL.
210 * @see tdm_pp_destroy
213 tdm_display_create_pp(tdm_display *dpy, tdm_error *error);
216 * @brief Get the model information of a output object.
217 * @param[in] output A output object
218 * @param[out] maker The output maker.
219 * @param[out] model The output model.
220 * @param[out] name The output name.
221 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
224 tdm_output_get_model_info(tdm_output *output, const char **maker,
225 const char **model, const char **name);
228 * @brief Get the connection status of a output object.
229 * @param[in] output A output object
230 * @param[out] status The connection status.
231 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
234 tdm_output_get_conn_status(tdm_output *output, tdm_output_conn_status *status);
237 * @brief Get the connection type of a output object.
238 * @param[in] output A output object
239 * @param[out] type The connection type.
240 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
243 tdm_output_get_output_type(tdm_output *output, tdm_output_type *type);
246 * @brief Get the layer counts which a output object has.
247 * @param[in] output A output object
248 * @param[out] count The count of layers
249 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
250 * @see tdm_output_get_layer
253 tdm_output_get_layer_count(tdm_output *output, int *count);
256 * @brief Get a layer object which has the given index.
257 * @param[in] output A output object
258 * @param[in] index The index of a layer object
259 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
260 * @return A layer object if success. Otherwise, NULL.
261 * @see tdm_output_get_layer_count
264 tdm_output_get_layer(tdm_output *output, int index, tdm_error *error);
267 * @brief Get the available property array of a output object.
268 * @param[in] output A output object
269 * @param[out] props The available property array
270 * @param[out] count The count of properties
271 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
274 tdm_output_get_available_properties(tdm_output *output, const tdm_prop **props,
278 * @brief Get the available mode array of a output object.
279 * @param[in] output A output object
280 * @param[out] modes The available mode array
281 * @param[out] count The count of modes
282 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
285 tdm_output_get_available_modes(tdm_output *output,
286 const tdm_output_mode **modes, int *count);
289 * @brief Get the available size of a output object.
290 * @details -1 means that a TDM backend module doesn't define the value.
291 * @param[in] output A output object
292 * @param[out] min_w The minimum width which TDM can handle
293 * @param[out] min_h The minimum height which TDM can handle
294 * @param[out] max_w The maximum width which TDM can handle
295 * @param[out] max_h The maximum height which TDM can handle
296 * @param[out] preferred_align The preferred align width which TDM can handle
297 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
300 tdm_output_get_available_size(tdm_output *output, int *min_w, int *min_h,
301 int *max_w, int *max_h, int *preferred_align);
304 * @brief Get the physical size of a output object.
305 * @param[in] output A output object
306 * @param[out] mmWidth The milimeter width
307 * @param[out] mmHeight The milimeter height
308 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
311 tdm_output_get_physical_size(tdm_output *output, unsigned int *mmWidth,
312 unsigned int *mmHeight);
315 * @brief Get the subpixel of a output object.
316 * @param[in] output A output object
317 * @param[out] subpixel The subpixel
318 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
321 tdm_output_get_subpixel(tdm_output *output, unsigned int *subpixel);
324 * @brief Get the pipe of a output object.
325 * @param[in] output A output object
326 * @param[out] pipe The pipe
327 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
330 tdm_output_get_pipe(tdm_output *output, unsigned int *pipe);
333 * @brief Set the property which has a given id.
334 * @param[in] output A output object
335 * @param[in] id The property id
336 * @param[in] value The value
337 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
340 tdm_output_set_property(tdm_output *output, unsigned int id, tdm_value value);
343 * @brief Get the property which has a given id
344 * @param[in] output A output object
345 * @param[in] id The property id
346 * @param[out] value The value
347 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
350 tdm_output_get_property(tdm_output *output, unsigned int id, tdm_value *value);
353 * @brief Wait for VBLANK
354 * @details After interval vblanks, a user vblank handler will be called.
355 * @param[in] output A output object
356 * @param[in] interval vblank interval
357 * @param[in] sync 0: asynchronous, 1:synchronous
358 * @param[in] func A user vblank handler
359 * @param[in] user_data The user data
360 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
361 * @see #tdm_output_vblank_handler
364 tdm_output_wait_vblank(tdm_output *output, int interval, int sync,
365 tdm_output_vblank_handler func, void *user_data);
368 * @brief Commit changes for a output object
369 * @details After all change of a output object are applied, a user commit handler
371 * @param[in] output A output object
372 * @param[in] sync 0: asynchronous, 1:synchronous
373 * @param[in] func A user commit handler
374 * @param[in] user_data The user data
375 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
378 tdm_output_commit(tdm_output *output, int sync, tdm_output_commit_handler func,
382 * @brief Set one of available modes of a output object
383 * @param[in] output A output object
384 * @param[in] mode A output mode
385 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
388 tdm_output_set_mode(tdm_output *output, const tdm_output_mode *mode);
391 * @brief Get the mode of a output object
392 * @param[in] output A output object
393 * @param[out] mode A output mode
394 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
397 tdm_output_get_mode(tdm_output *output, const tdm_output_mode **mode);
400 * @brief Set DPMS of a output object
401 * @param[in] output A output object
402 * @param[in] dpms_value DPMS value
403 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
406 tdm_output_set_dpms(tdm_output *output, tdm_output_dpms dpms_value);
409 * @brief Get DPMS of a output object
410 * @param[in] output A output object
411 * @param[out] dpms_value DPMS value
412 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
415 tdm_output_get_dpms(tdm_output *output, tdm_output_dpms *dpms_value);
418 * @brief Create a capture object of a output object
419 * @param[in] output A output object
420 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
421 * @return A capture object
422 * @see tdm_capture_destroy
425 tdm_output_create_capture(tdm_output *output, tdm_error *error);
428 * @brief Get the capabilities of a layer object.
429 * @param[in] layer A layer object
430 * @param[out] capabilities The capabilities of a layer object
431 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
434 tdm_layer_get_capabilities(tdm_layer *layer,
435 tdm_layer_capability *capabilities);
438 * @brief Get the available format array of a layer object.
439 * @param[in] layer A layer object
440 * @param[out] formats The available format array
441 * @param[out] count The count of formats
442 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
445 tdm_layer_get_available_formats(tdm_layer *layer, const tbm_format **formats,
449 * @brief Get the available property array of a layer object.
450 * @param[in] layer A layer object
451 * @param[out] props The available property array
452 * @param[out] count The count of properties
453 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
456 tdm_layer_get_available_properties(tdm_layer *layer, const tdm_prop **props,
460 * @brief Get the zpos of a layer object.
462 * - GRAPHIC layers have fixed zpos. It starts from 0. It's @b non-changeable.
463 * - But the zpos of VIDEO layers will be decided by a backend module side.
464 * - A frontend user only can set the relative zpos to VIDEO layers via #tdm_layer_set_video_pos
465 * - The zpos of video layers is less than GRAPHIC layers or more than GRAPHIC
466 * layers. ie, ..., -2, -1, 4, 5, ... (if 0 <= GRAPHIC layer's zpos < 4).
467 * @param[in] layer A layer object
468 * @param[out] zpos The zpos
469 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
470 * @see tdm_layer_set_video_pos, tdm_layer_capability
473 tdm_layer_get_zpos(tdm_layer *layer, unsigned int *zpos);
476 * @brief Set the property which has a given id.
477 * @param[in] layer A layer object
478 * @param[in] id The property id
479 * @param[in] value The value
480 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
483 tdm_layer_set_property(tdm_layer *layer, unsigned int id, tdm_value value);
486 * @brief Get the property which has a given id.
487 * @param[in] layer A layer object
488 * @param[in] id The property id
489 * @param[out] value The value
490 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
493 tdm_layer_get_property(tdm_layer *layer, unsigned int id, tdm_value *value);
496 * @brief Set the geometry information to a layer object
497 * @details The geometry information will be applied when the output object
498 * of a layer object is committed.
499 * @param[in] layer A layer object
500 * @param[in] info The geometry information
501 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
502 * @see tdm_output_commit
505 tdm_layer_set_info(tdm_layer *layer, tdm_info_layer *info);
508 * @brief Get the geometry information to a layer object
509 * @param[in] layer A layer object
510 * @param[out] info The geometry information
511 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
514 tdm_layer_get_info(tdm_layer *layer, tdm_info_layer *info);
517 * @brief Set a TDM buffer to a layer object
518 * @details A TDM buffer will be applied when the output object
519 * of a layer object is committed.
520 * @param[in] layer A layer object
521 * @param[in] buffer A TDM buffer
522 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
523 * @see tdm_output_commit
526 tdm_layer_set_buffer(tdm_layer *layer, tbm_surface_h buffer);
529 * @brief Unset a TDM buffer from a layer object
530 * @details When this function is called, a current showing buffer will be
531 * disappeared from screen. Then nothing is showing on a layer object.
532 * @param[in] layer A layer object
533 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
536 tdm_layer_unset_buffer(tdm_layer *layer);
539 * @brief Set a TBM surface_queue to a layer object
540 * @details A TBM surface_queue will be applied when the output object
541 * of a layer object is committed. and TDM layer will be automatically updated
542 * @param[in] layer A layer object
543 * @param[in] buffer_queue A TBM surface_queue
544 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
545 * @see tdm_output_commit
548 tdm_layer_set_buffer_queue(tdm_layer *layer, tbm_surface_queue_h buffer_queue);
551 * @brief Unset a TBM surface_queue from a layer object
552 * @details When this function is called, a current surface_queue will be
553 * disappeared from screen. Then nothing is showing on a layer object.
554 * @param[in] layer A layer object
555 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
558 tdm_layer_unset_buffer_queue(tdm_layer *layer);
561 * @brief Check wheter a layer object is available for a frontend user to use.
562 * @details A layer object is not usable if a TDM buffer is showing on screen
563 * via this layer object. By calling #tdm_layer_unset_buffer, this layer object
564 * will become usable.
565 * @param[in] layer A layer object
566 * @param[out] usable 1 if usable, 0 if not usable
567 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
570 tdm_layer_is_usable(tdm_layer *layer, unsigned int *usable);
573 * @brief Set the relative zpos to a VIDEO layer object
574 * @details The zpos value is less than the minimum zpos of GRAPHIC layers, or
575 * it is more than the maximum zpos of GRAPHIC layers.
576 * @param[in] layer A VIDEO layer object
577 * @param[in] zpos The zpos
578 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
579 * @see tdm_layer_get_zpos, tdm_layer_capability
582 tdm_layer_set_video_pos(tdm_layer *layer, int zpos);
585 * @brief Create a capture object of a layer object
586 * @param[in] layer A layer object
587 * @param[out] error #TDM_ERROR_NONE if success. Otherwise, error value.
588 * @return A capture object
589 * @see tdm_capture_destroy
592 tdm_layer_create_capture(tdm_layer *layer, tdm_error *error);
595 * @brief Destroy a pp object
596 * @param[in] pp A pp object
597 * @see tdm_display_create_pp
600 tdm_pp_destroy(tdm_pp *pp);
603 * @brief Set the geometry information to a pp object
604 * @param[in] pp A pp object
605 * @param[in] info The geometry information
606 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
610 tdm_pp_set_info(tdm_pp *pp, tdm_info_pp *info);
613 * @brief Attach a source buffer and a destination buffer to a pp object
614 * @param[in] pp A pp object
615 * @param[in] src A source buffer
616 * @param[in] dst A destination buffer
617 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
618 * @see tdm_pp_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
621 tdm_pp_attach(tdm_pp *pp, tbm_surface_h src, tbm_surface_h dst);
624 * @brief Commit changes for a pp object
625 * @param[in] pp A pp object
626 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
629 tdm_pp_commit(tdm_pp *pp);
632 * @brief Destroy a capture object
633 * @param[in] capture A capture object
634 * @see tdm_output_create_capture, tdm_layer_create_capture
637 tdm_capture_destroy(tdm_capture *capture);
640 * @brief Set the geometry information to a capture object
641 * @param[in] capture A capture object
642 * @param[in] info The geometry information
643 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
644 * @see tdm_capture_commit
647 tdm_capture_set_info(tdm_capture *capture, tdm_info_capture *info);
650 * @brief Attach a TDM buffer to a capture object
651 * @param[in] capture A capture object
652 * @param[in] buffer A TDM buffer
653 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
654 * @see tdm_capture_commit, tdm_buffer_add_release_handler, tdm_buffer_release_handler
657 tdm_capture_attach(tdm_capture *capture, tbm_surface_h buffer);
660 * @brief Commit changes for a capture object
661 * @param[in] capture A capture object
662 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
665 tdm_capture_commit(tdm_capture *capture);
668 * @brief The release handler of a TDM buffer
669 * @param[in] buffer A TDM buffer
670 * @param[in] user_data user data
671 * @see tdm_buffer_add_release_handler, tdm_buffer_remove_release_handler
673 typedef void (*tdm_buffer_release_handler)(tbm_surface_h buffer,
677 * @brief Add a release handler to a TDM buffer
679 * TDM has its own buffer release mechanism to let an frontend user know when a TDM buffer
680 * becomes available for a next job. A TDM buffer can be used for TDM to show
681 * it on screen or to capture an output and a layer. After all operations,
682 * TDM will release it immediately when TDM doesn't need it any more.
683 * @param[in] buffer A TDM buffer
684 * @param[in] func A release handler
685 * @param[in] user_data user data
686 * @return #TDM_ERROR_NONE if success. Otherwise, error value.
687 * @see tdm_buffer_remove_release_handler
690 tdm_buffer_add_release_handler(tbm_surface_h buffer,
691 tdm_buffer_release_handler func, void *user_data);
694 * @brief Remove a release handler from a TDM buffer
695 * @param[in] buffer A TDM buffer
696 * @param[in] func A release handler
697 * @param[in] user_data user data
698 * @see tdm_buffer_add_release_handler
701 tdm_buffer_remove_release_handler(tbm_surface_h buffer,
702 tdm_buffer_release_handler func, void *user_data);