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_ */