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

Summary of Interfaces and Methods

Interface	Method
DisplayControlManagerObject
DisplayControlManager	Display3DEffectMode get3DEffectMode () Display3DModeState is3DModeEnabled () 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

Privilege level: public

Privilege: http://tizen.org/privilege/tv.display

Return value:

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.
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, in any other error case.

Code example:

 try {
      var current3Dmode = tizen.tvdisplaycontrol.get3DEffectMode()
      console.log("The current 3D mode is " + current3Dmode + ".");
 } catch (error) {
     console.log(error.name);
 }

is3DModeEnabled

Checks whether playing 3D mode is available or not.

Display3DModeState is3DModeEnabled();

Since: 2.3

Privilege level: public

Privilege: http://tizen.org/privilege/tv.display

Return value:

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.
- with error type NotSupportedError, if this feature is not supported.
- with error type UnknownError, in any other error case.

Code example:

 try {
     if (tizen.tvdisplaycontrol.is3DModeEnabled() === "NOT_SUPPORTED") {
         console.log("The current device does not support 3D mode.");
     } else if (tizen.tvdisplaycontrol.is3DModeEnabled() === "READY") {
         console.log("The 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("The current device supports 3D mode but cannot display 3D contents. It may be 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

Privilege level: public

Privilege: http://tizen.org/privilege/tv.display

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.
- 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. Error(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

You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.

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"
    };

    [NoInterfaceObject] interface DisplayControlManagerObject {
        readonly attribute DisplayControlManager tvdisplaycontrol;
    };
    Tizen implements DisplayControlManagerObject;

    [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);
    };

};