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       Mar 17, 2016
  43  * @version    1.1.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,
  73  * #tdm_func_output, #tdm_func_layer functions to a display object via
  74  * #tdm_backend_register_func_display(), #tdm_backend_register_func_output(),
  75  * #tdm_backend_register_func_layer() functions in initial time.\n
  76  * @code
  77     #include <tdm_backend.h>
  78
  79     static tdm_drm_data *drm_data;
  80
  81     tdm_backend_data*
  82     tdm_drm_init(tdm_display *dpy, tdm_error *error)
  83     {
  84         tdm_func_display drm_func_display;
  85         tdm_func_output drm_func_output;
  86         tdm_func_layer drm_func_layer;
  87
  88         ...
  89         drm_data = calloc(1, sizeof(tdm_drm_data));
  90         ...
  91
  92         memset(&drm_func_display, 0, sizeof(drm_func_display));
  93         drm_func_display.display_get_capabilitiy = drm_display_get_capabilitiy;
  94         ...
  95         ret = tdm_backend_register_func_display(dpy, &drm_func_display);
  96         if (ret != TDM_ERROR_NONE)
  97             goto failed;
  98
  99         memset(&drm_func_output, 0, sizeof(drm_func_output));
 100         drm_func_output.output_get_capability = drm_output_get_capability;
 101         ...
 102         ret = tdm_backend_register_func_output(dpy, &drm_func_output);
 103         if (ret != TDM_ERROR_NONE)
 104             goto failed;
 105
 106         memset(&drm_func_layer, 0, sizeof(drm_func_layer));
 107         drm_func_layer.layer_get_capability = drm_layer_get_capability;
 108         ...
 109         ret = tdm_backend_register_func_layer(dpy, &drm_func_layer);
 110         if (ret != TDM_ERROR_NONE)
 111             goto failed;
 112         ...
 113         return (tdm_backend_data*)drm_data;
 114     }
 115
 116     void
 117     tdm_drm_deinit(tdm_backend_data *bdata)
 118     {
 119         ...
 120         free(bdata);
 121     }
 122
 123     tdm_backend_module tdm_backend_module_data =
 124     {
 125         "drm",
 126         "Samsung",
 127         TDM_BACKEND_ABI_VERSION,
 128         tdm_drm_init,
 129         tdm_drm_deinit
 130     };
 131  * @endcode
 132  * \n
 133  * A sample backend source code can be downloaded.
 134  * @code
 135  $ git clone ssh://{user_id}@review.tizen.org:29418/platform/core/uifw/libtdm-drm
 136  * @endcode
 137  * \n
 138  * After loading a TDM backend module, TDM will call @b display_get_capabilitiy(),
 139  * @b display_get_outputs(), @b output_get_capability(), @b output_get_layers(),
 140  * @b layer_get_capability() functions to get the hardware information. That is,
 141  * a TDM backend module @b SHOULD implement these 5 functions basically.\n
 142  * \n
 143  * In addition, if a hardware has a memory-to-memory converting device and the
 144  * capture device, a backend module can register the #tdm_func_pp functions and
 145  * #tdm_func_capture functions with #tdm_backend_register_func_pp() and
 146  * #tdm_backend_register_func_capture().\n
 147  * \n
 148  * The @b "Remarks" part of <tdm_backend.h> explains what things should be
 149  * careful for vendor to implement a TDM backend module.
 150  */
 151
 152 #endif /* _TDM_DOC_H_ */