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.16.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_layer_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_capability = drm_display_get_capability;
  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_capability(),
 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_ */