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  * @date       Dec 30, 2015
  43  * @version    1.0.0
  44  * @par Introduction
  45  * TDM stands for Tizen Display Manager. It's the display HAL layer for tizen
  46  * display server. It offers the frontend APIs(@ref tdm.h) for a frontend user
  47  * and the abstraction interface(@ref tdm_backend.h) for a hardware vendor.
  48  * \n
  49  * @par Objects
  50  * TDM consists of display/output/layer/pp/capture objects. A frontend user can
  51  * get the output/layer/pp/capture hardware information with each object.
  52  * Basically, TDM supposes that all display devices have fixed outputs and
  53  * layers. A frontend user can get these outputs and layers with
  54  * #tdm_display_get_output_count, #tdm_display_get_output, #tdm_output_get_layer_count
  55  * and #tdm_output_get_layer. To get a pp/capture object, however, a frontend
  56  * user need to create a object with #tdm_display_create_pp, #tdm_output_create_capture
  57  * and #tdm_layer_create_capture if available.\n
  58  * \n
  59  * All changes of output/layer/pp/capture objects are applied when committed.
  60  * See #tdm_output_commit, #tdm_pp_commit and #tdm_capture_commit.
  61  * \n
  62  * @par Buffer management
  63  * TDM has its own buffer release mechanism to let an user know when a TDM buffer
  64  * becomes available for a next job. A frontend user can add a user release handler
  65  * to a TDM buffer with #tdm_buffer_add_release_handler, and this handler will be
  66  * called when it's disappered from screen or when pp/capture operation is done.
  67  * \n
  68  * @par Implementing a TDM backend module(for a hardware vendor)
  69  * A backend module @b SHOULD define the global data symbol of which name is
  70  * @b "tdm_backend_module_data". TDM will read this symbol, @b "tdm_backend_module_data",
  71  * at the initial time and call init() function of #tdm_backend_module.
  72  * A backend module at least @b SHOULD register the #tdm_func_display functions
  73  * to a display object with #tdm_backend_register_func_display() function in initial time.\n
  74  * @code
  75     #include <tdm_backend.h>
  76
  77     static tdm_func_display drm_func_display =
  78     {
  79         drm_display_get_capabilitiy,
  80         ...
  81         drm_display_get_outputs,
  82         ...
  83         drm_output_get_capability,
  84         drm_output_get_layers,
  85         ...
  86         drm_layer_get_capability,
  87         ...
  88     };
  89
  90     static tdm_drm_data *drm_data;
  91
  92     tdm_backend_data*
  93     tdm_drm_init(tdm_display *dpy, tdm_error *error)
  94     {
  95         ...
  96         drm_data = calloc(1, sizeof(tdm_drm_data));
  97         ...
  98         ret = tdm_backend_register_func_display(dpy, &drm_func_display);
  99         if (ret != TDM_ERROR_NONE)
 100             goto failed;
 101         ...
 102         return (tdm_backend_data*)drm_data;
 103     }
 104
 105     void
 106     tdm_drm_deinit(tdm_backend_data *bdata)
 107     {
 108         ...
 109         free(bdata);
 110     }
 111
 112     tdm_backend_module tdm_backend_module_data =
 113     {
 114         "drm",
 115         "Samsung",
 116         TDM_BACKEND_ABI_VERSION,
 117         tdm_drm_init,
 118         tdm_drm_deinit
 119     };
 120  * @endcode
 121  * \n
 122  * A sample backend source code can be downloaded.
 123  * @code
 124  $ git clone ssh://{user_id}@review.tizen.org:29418/platform/core/uifw/libtdm-drm
 125  * @endcode
 126  * \n
 127  * After loading a TDM backend module, TDM will call @b display_get_capabilitiy(),
 128  * @b display_get_outputs(), @b output_get_capability(), @b output_get_layers(),
 129  * @b layer_get_capability() functions to get the hardware information. That is,
 130  * a TDM backend module @b SHOULD implement these 5 functions basically.\n
 131  * \n
 132  * In addition, if a hardware has a memory-to-memory converting device and the
 133  * capture device, a backend module can register the #tdm_func_pp functions and
 134  * #tdm_func_capture functions with #tdm_backend_register_func_pp() and
 135  * #tdm_backend_register_func_capture().\n
 136  * \n
 137  * The @b "Remarks" part of <tdm_backend.h> explains what things should be
 138  * careful for vendor to implement a TDM backend module.
 139  */
 140
 141 #endif /* _TDM_DOC_H_ */