TDM

From Tizen Wiki
Jump to: navigation, search

Background

Tizen 2.x which has x window system has the display porting layer, such as x video driver(DDX). However, there is no proper porting layer in tizen 3.0 which has the wayland window system. Enlightenment as a tizen 3.0 wayland display server has the DRM backend only. To support many vendor devices which don’t support DRM interface, we need the new display porting layer.

Moreover, in tizen 2.x, it is kind of difficult to implement a x video driver for vendor who doesn’t have the knowledge and experience of X window system. To make it easy, we also need new display porting layer in tizen platform side.

Introduction

TDM stands for Tizen Display Manager. Tizen Display Manager (TDM) provides the display device abstraction interface for the display server, such like a X server and a wayland server, to allow the direct access to graphics hardware in a safe and efficient manner as a display HAL. The primary goal of TDM is the unification of display hardware management procedures in user space.

The display server, as a compositor, composites application windows to a framebuffer and shows the result image on screen with TDM. If possible, the display server can show an application window on screen directly. In case of playing a video, the display server can do the color space conversion, scaling and rotating and show the result image on screen.

TDM offers the unified interface for the display server to do these operations on various chipset devices.

  • TDM includes
  1. The frontend APIs for the display server (tdm.h)
  2. The abstraction interface for vendor(backend) modules (tdm_backend.h)


Objects

  • TDM consists of display, output, layer, pp, capture objects. Below is a description of each object.
object description
display A singleton object in entire system. A display object has a list of output objects.
output Each output object represents a monitor. And an output object has a list of layer objects.
layer Each layer object represents a hardware plane(overlay), such like graphic, video plane, etc. A framebuffer can be displayed via a layer object.
pp A pp object represents a memory-to-memory converting hardware device which can do the color space conversion, scaling and rotating if supported. For example, the display server will use a pp object to convert a video buffer and show it on screen.
capture A capture object represents a capture hardware device if supported.


  • A TDM backend module offers these objects to the display server with the hardware specific information of them.
object information
display output list, available hardware device(m2m converting device, capture device)
output layer list, maker, model, name, connection type/status, mode list, properties, physical size, subpixel, size(min/max/referred-align-width)
layer capabilities, zpos, format list, property list
pp capabilities, format list, size(min/max/preferred-align-width)
capture capabilities, format list, size(min/max/preferred-align-width)


Display Capability

typedef enum {
	TDM_DISPLAY_CAPABILITY_PP       = (1 << 0), /**< if hardware supports pp operation */
	TDM_DISPLAY_CAPABILITY_CAPTURE  = (1 << 1), /**< if hardware supports capture operation */
} tdm_display_capability;


Layer Capability

typedef enum {
	TDM_LAYER_CAPABILITY_CURSOR         = (1 << 0), /**< cursor */
	TDM_LAYER_CAPABILITY_PRIMARY        = (1 << 1), /**< primary */
	TDM_LAYER_CAPABILITY_OVERLAY        = (1 << 2), /**< overlay */
	TDM_LAYER_CAPABILITY_GRAPHIC        = (1 << 4), /**< graphic */
	TDM_LAYER_CAPABILITY_VIDEO          = (1 << 5), /**< video */
	TDM_LAYER_CAPABILITY_SCALE          = (1 << 8), /**< if a layer has scale capability  */
	TDM_LAYER_CAPABILITY_TRANSFORM      = (1 << 9), /**< if a layer has transform capability  */
	TDM_LAYER_CAPABILITY_SCANOUT        = (1 << 10), /**< if a layer allows a scanout buffer only */
	TDM_LAYER_CAPABILITY_RESEVED_MEMORY = (1 << 11), /**< if a layer allows a reserved buffer only */
	TDM_LAYER_CAPABILITY_NO_CROP        = (1 << 12), /**< if a layer has no cropping capability */
} tdm_layer_capability;

These layer capabilities consist of three groups. And a layer object can have capabilities by combining these three groups.

  1. CURSOR, PRIMARY, OVERLAY – the role of layer object
  2. GRAPHIC, VIDEO – the buffer type of layer object
  3. SCALE, TRANSFORM, SCANOUT, RESERVED_MEMORY, NO_CROP – the ability of layer object


  • CURSOR, PRIMARY, OVERLAY : Necessary. A layer object SHOULD have only one capability of these. But these can’t be combined together
  • GRAPHIC, VIDEO : Necessary. A layer object SHOULD have only one capability of these. But these can’t be combined together
  • Others : Not necessary. A layer object can have one more capabilities of these if hardware supports.


For example,

/* wrong usage */
capabilities = TDM_LAYER_CAPABILITY_PRIMARY;                                 // There is no buffer type capability. Should have one of GRAPHIC and VIDEO
capabilities = TDM_LAYER_CAPABILITY_GRAPHIC;                                 // There is no role capability. Should have one of CURSOR, PRIMARY and OVERLAY
capabilities = TDM_LAYER_CAPABILITY_PRIMARY | TDM_LAYER_CAPABILITY_CURSOR;   // Can’t be combined together among the role capability
capabilities = TDM_LAYER_CAPABILITY_GRAPHIC | TDM_LAYER_CAPABILITY_VIDEO;    // Can’t be combined together among the buffer type capability

/* correct usage */
capabilities = TDM_LAYER_CAPABILITY_CURSOR  | TDM_LAYER_CAPABILITY_GRAPHIC;
capabilities = TDM_LAYER_CAPABILITY_PRIMARY | TDM_LAYER_CAPABILITY_GRAPHIC;
capabilities = TDM_LAYER_CAPABILITY_OVERLAY | TDM_LAYER_CAPABILITY_GRAPHIC;
capabilities = TDM_LAYER_CAPABILITY_OVERLAY | TDM_LAYER_CAPABILITY_GRAPHIC | TDM_LAYER_CAPABILITY_SCALE;
capabilities = TDM_LAYER_CAPABILITY_OVERLAY | TDM_LAYER_CAPABILITY_GRAPHIC | TDM_LAYER_CAPABILITY_SCALE | TDM_LAYER_CAPABILITY_TRANSFORM;

/* special layer for video */
capabilities = TDM_LAYER_CAPABILITY_OVERLAY | TDM_LAYER_CAPABILITY_VIDEO;
TDM_LAYER_CAPABILITY_VIDEO

This is a special layer capability. The TDM backend can provide this VIDEO layer to handle video buffers inside the TDM backend for itself.

Normally, when video is played in tizen platform, video buffer is converted into graphic buffer by using a PP object for color space conversion, scaling and rotating. And the converted graphic buffer is output to GRAPHIC layer. However, if a TDM backend provides a VIDEO layer, the tizen platform will directly pass the video buffer to the VIDEO layer without any conversion and modification. In this case, the TDM backend module has the responsibility for displaying the video buffer on the screen.

The VIDEO layer should do color space conversion, scaling and rotating for itself to output video buffers on screen.

Layer Zpos

Tdm-layer-zpos.png

All layer objects have zpos(z-order). A TDM backend module decides the zpos of each layer object.
The zpos of GRAPHIC layers is non-changeable and starts from 0. If there are 4 GRAPHIC layers, the zpos of each GRAPHIC layer SHOULD be 0, 1, 2 and 3.
The zpos of VIDEO layers is changeable and relative. If there are 4 GRAPHIC layers, the zpos of each VIDEO layer SHOULD be under 0 or over 3. ie, ..., -2, -1 or 4, 5, ...

Porting Guide

See 3.0_Porting_Guide/Graphics_and_UI/TDM.

Sequence

Initialization

Tdm-initialization.png

Find a connected output

Tdm-find-a-output.png

Mode setting

Tdm-mode-setting.png

Show a framebuffer on screen

Tdm-showing-buffer.png

Convert a video buffer to a graphic buffer

Tdm-converting.png

Capture a output

Tdm-capture.png