TVDisplayControl API

This API provides interfaces for managing stereoscopic 3D effects for television signals.

Modern TVs and projectors can display two images, a left image and a right image, which are displayed to the left and right eyes respectively. This technique creates an illusion of depth, which is perceived by users as a 3D image.

For more information about stereoscopy, see this Wikipedia article.

There are several formats of input images supported by the stereoscopy plugin:

  • Side-by-side: Left and right images are merged into one picture. The left image is at the left side and the right image is at the right side. Both images are scaled to fit in the original image ratio.
  • Top-bottom: Left and right images are merged into one picture. The left image is at the top and the right image is at the bottom. Both images are scaled to fit in the original image ratio.
  • Line-by-line: Left and right images are interlaced by row. The first row belongs to the left image and the second row belongs to the right image, and so on.
  • Vertical-strip: Left and right images are interlaced by column. The first column belongs to the left image and the second column belongs to the right image, and so on.
  • Frame-sequence: Left and right images are interlaced by frames.

Advanced devices are able to computationally generate depth data by processing non-stereoscopic images. Depth data is used to render left and right stereoscopic images from a source image which lacks this information. The quality of such stereoscopic images depends on the computational power used for processing, the algorithms used and the properties of the source data. For more information see this Wikipedia article.

There will be a tizen.tvdisplaycontrol object that allows accessing the functionality of the display control API.

Since: 2.3

Table of Contents

Summary of Interfaces and Methods

Interface Method
DisplayControlManagerObject
DisplayControlManager
void getSupported3DEffectModeList (Mode3DEffectListSupportCallback successCallback, optional ErrorCallback? errorCallback)
Mode3DEffectListSupportCallback
void onsuccess (Display3DEffectMode[] mode3DEffects)

1. Type Definitions

1.1. Display3DEffectMode

An enumerator to indicate 3D effect mode. 
  enum Display3DEffectMode { "OFF", "TOP_BOTTOM", "SIDE_BY_SIDE", "LINE_BY_LINE", "VERTICAL_STRIPE", "FRAME_SEQUENCE", "CHECKER_BD",
    "FROM_2D_TO_3D" };

Since: 2.3

  • OFF - identifier for 3DEffect mode off
  • TOP_BOTTOM - Left image at the top, right image at the bottom
  • SIDE_BY_SIDE - Left image at the left side, right image at the right side
  • LINE_BY_LINE - Left and right image interlaced by row
  • VERTICAL_STRIP - Left and right image interlaced by column
  • FRAME_SEQUENCE - Left and right image interlaced by frame
  • CHECKER_BD - Checkerboard (only for PC or game console sources)
  • FROM_2D_TO_3D - Left and right image computed from non-stereoscopic image

1.2. Display3DModeState

An enumerator to indicate 3D mode state. 
  enum Display3DModeState { "NOT_CONNECTED", "NOT_SUPPORTED", "READY" };

Since: 2.3

  • NOT_CONNECTED - The device (e.g. Blu-ray player) supports 3D mode but a 3D display is not connected.
  • NOT_SUPPORTED - The device does not support 3D mode.
  • READY - The device supports 3D mode and it can display 3D mode.

2. Interfaces

2.1. DisplayControlManagerObject

This interface defines what is instantiated by the tizen object. There will be a tizen.tvdisplaycontrol object that allows the access to the Display Control API. 
  [NoInterfaceObject] interface DisplayControlManagerObject {
    readonly attribute DisplayControlManager tvdisplaycontrol;
  };
  Tizen implements DisplayControlManagerObject;

Since: 2.3

For example, Display Control API provides whether your device supports 3D.

2.2. DisplayControlManager

This interface provides access to the Display Control API functionalities through the tizen.tvdisplaycontrol interface. 
  [NoInterfaceObject] interface DisplayControlManager {
    Display3DEffectMode get3DEffectMode() raises(WebAPIException);
    Display3DModeState is3DModeEnabled() raises(WebAPIException);
    void getSupported3DEffectModeList(Mode3DEffectListSupportCallback successCallback, optional ErrorCallback? errorCallback)
                                      raises(WebAPIException);
  };

Since: 2.3

Methods

get3DEffectMode
Gets the current 3D effect mode. 
Display3DEffectMode get3DEffectMode();

Since: 2.3

Return value:

    Display3DEffectMode: Display3DEffectMode The current mode of 3D effect.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in an unspecified error case.

Code example:

try
{
  var current3Dmode = tizen.tvdisplaycontrol.get3DEffectMode();
  console.log("Current 3D mode: " + current3Dmode);
}
catch (error)
{
  console.log(error.name);
}
is3DModeEnabled
Checks whether playing 3D mode is available or not. 
Display3DModeState is3DModeEnabled();

Since: 2.3

Return value:

    Display3DModeState: Display3DModeState The current state to display 3D contents.

Exceptions:

  • WebAPIException

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type UnknownError in an unspecified error case.

Code example:

try
{
  if (tizen.tvdisplaycontrol.is3DModeEnabled() === "NOT_SUPPORTED")
  {
    console.log("Current device does not support 3D mode");
  }
  else if (tizen.tvdisplaycontrol.is3DModeEnabled() === "READY")
  {
    console.log("Current device supports 3D mode and can display 3D contents, " +
                "maybe it is a 3D TV device or is connected with 3D display device");
  }
  else
  {
    console.log(
        "Current device supports 3D mode but cannot display 3D contents, " +
        "maybe it is a 3D Blu-ray player device which is not connected with 3D display device");
  }
}
catch (error)
{
  console.log(error.name);
}
getSupported3DEffectModeList
Gets the supported 3D effects. 
void getSupported3DEffectModeList(Mode3DEffectListSupportCallback successCallback, optional ErrorCallback? errorCallback);

Since: 2.3

Parameters:

  • successCallback: The method to invoke when a list of supported 3D modes is retrieved successfully.
  • errorCallback [optional] [nullable]: The method to invoke when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to call this method. This type of error is deprecated since Tizen 5.0.

    • with error type NotSupportedError, if this feature is not supported.

Code example:

function successCB(effects)
{
  for (var i = 0; i < effects.length; ++i)
  {
    console.log(effects[i] + ": this mode is supported on a device");
  }
}

function errorCB(error)
{
  console.log("An error occurs when getSupported3DEffectModeList() is invoked, " +
              "name: " + error.name + ", message: " + error.message);
}

try
{
  tizen.tvdisplaycontrol.getSupported3DEffectModeList(successCB, errorCB);
}
catch (error)
{
  console.log(error.name);
}

2.3. Mode3DEffectListSupportCallback

This interface defines a callback when a list of supported 3D modes is retrieved successfully. 
  [Callback=FunctionOnly, NoInterfaceObject] interface Mode3DEffectListSupportCallback {
    void onsuccess(Display3DEffectMode[] mode3DEffects);
  };

Since: 2.3

Methods

onsuccess
Method invoked when the list of 3D modes is retrieved successfully. 
void onsuccess(Display3DEffectMode[] mode3DEffects);

Since: 2.3

Parameters:

  • mode3DEffects: A list of supported 3D effect modes.

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee the running of this application on a device with a TV display control support, define the following requirements in the config file:

  • http://tizen.org/feature/tv.display

    • For more information, see Application Filtering.

    4. Full WebIDL

    module TVDisplayControl {
  enum Display3DEffectMode { "OFF", "TOP_BOTTOM", "SIDE_BY_SIDE", "LINE_BY_LINE", "VERTICAL_STRIPE", "FRAME_SEQUENCE", "CHECKER_BD",
    "FROM_2D_TO_3D" };
  enum Display3DModeState { "NOT_CONNECTED", "NOT_SUPPORTED", "READY" };
  Tizen implements DisplayControlManagerObject;
  [NoInterfaceObject] interface DisplayControlManagerObject {
    readonly attribute DisplayControlManager tvdisplaycontrol;
  };
  [NoInterfaceObject] interface DisplayControlManager {
    Display3DEffectMode get3DEffectMode() raises(WebAPIException);
    Display3DModeState is3DModeEnabled() raises(WebAPIException);
    void getSupported3DEffectModeList(Mode3DEffectListSupportCallback successCallback, optional ErrorCallback? errorCallback)
                                      raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface Mode3DEffectListSupportCallback {
    void onsuccess(Display3DEffectMode[] mode3DEffects);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.