com.webos.service.videooutput

Note
com.webos.service.videooutput has been added from webOS OSE 1.6.0.

API Summary

Connects the video source to the video output device and also controls post-processing and scaling on the video device. The service exposes methods that make the HAL calls to connect source to sink and position output as needed.

Note: Application developers must not use this service directly.

Overview of the API

This service is responsible for connecting the input pipeline to the backend video. The Media Framework is responsible for determining the life cycle of a connection and pipeline policy (which application is in foreground and has focus, resources, and so on). Media Framework uses VideoOutput APIs to achieve connection and video post-processing.

  • VideoOutput does NOT have policy.
  • It provides API to connect video source (frames from decoder and so on) to video plane.
  • It provides the HAL abstraction for the backend (i.e. VideoOutput will work with HAL or KMS/DRM or other hardware abstraction layer)  
  • It provides the interface for H/W video post-processing and scaling. The post-processing functionality will be implemented with a plugin design to allow various degrees of functionality based on product.

Direct use of videooutputd by application developers is strongly discouraged. Instead, the modules of media framework like UMS, LSM are supposed to use these APIs.

Methods

connect

Description

Connects a video source to a video sink

Parameters

Name

Required

Type

Description

sourceRequiredString

Video source. 

Possible values are:

  • VDEC : It describes source of video decoder
sourcePortOptionalNumber (int8_t)

Video port number.

Note: For VDEC, the possible values are 0 and 1.

sinkRequiredString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are: 

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
contextOptionalString

Registered pipeline ID.

appIdOptionalString

Registered application ID.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details.
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

planeIDRequiredNumber (int8_t)

Numeric plane ID of the sink.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/connect '{"source": "VDEC", "sourcePort":0, "sink":"DISP0_MAIN"}'

 

Response:

{
    "planeID": 44,
    "returnValue": true
}

disconnect

Description

Disconnects video from sink.

Parameters

Name

Required

Type

Description

sinkRequiredString

Video sink.

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are: 

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
contextOptionalString

Specifies registered pipeline ID

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/disconnect '{"sink":"DISP0_MAIN"}'

 

Response:

{
    "returnValue": true
}

getStatus

Description

Lists all video sinks and their status.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Subscribe for notifications when value changes. Possible values are:

  • true - Get notifications
  • false - Notifications are not required

Note: This returns one entry for each video sink

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

subscribedOptionalBoolean

If it is subscribed, subscribed will contain true.
If it is not subscribed, subscribed will contain false.

videoOptionalObject array: Video

See "Video" object.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/getStatus '{"subscribe":true}'

 

Response:

{
    "video": [
        {
            "connected": true,
            "displayOutput": {
                "width": 1280,
                "height": 720,
                "x": 0,
                "y": 0
            },
            "connectedSource": "VDEC",
            "fullScreen": false,
            "frameRate": 24,
            "muted": true,
            "connectedSourcePort": 0,
            "zOrder": 0,
            "width": 1280,
            "contentType": "movie",
            "opacity": 255,
            "height": 720,
            "videoInfo": null,
            "sourceInput": {
                "width": 854,
                "height": 480,
                "x": 0,
                "y": 0
            },
            "sink": "DISP0_MAIN",
            "context": "_TMnGr2TKCjdpKL",
            "scanType": "progressive"
        },
        {
            "connected": false,
            "displayOutput": {
                "width": 0,
                "height": 0,
                "x": 0,
                "y": 0
            },
            "connectedSource": null,
            "fullScreen": false,
            "frameRate": 0,
            "muted": true,
            "connectedSourcePort": 0,
            "zOrder": 1,
            "width": 0,
            "contentType": "unknown",
            "opacity": 255,
            "height": 0,
            "videoInfo": null,
            "sourceInput": {
                "width": 0,
                "height": 0,
                "x": 0,
                "y": 0
            },
            "sink": "DISP0_SUB0",
            "context": "",
            "scanType": "unknown"
        },
        {
            "connected": false,
            "displayOutput": {
                "width": 0,
                "height": 0,
                "x": 0,
                "y": 0
            },
            "connectedSource": null,
            "fullScreen": false,
            "frameRate": 0,
            "muted": true,
            "connectedSourcePort": 0,
            "zOrder": 2,
            "width": 0,
            "contentType": "unknown",
            "opacity": 255,
            "height": 0,
            "videoInfo": null,
            "sourceInput": {
                "width": 0,
                "height": 0,
                "x": 0,
                "y": 0
            },
            "sink": "DISP0_SUB1",
            "context": "",
            "scanType": "unknown"
        },
        {
            "connected": false,
            "displayOutput": {
                "width": 0,
                "height": 0,
                "x": 0,
                "y": 0
            },
            "connectedSource": null,
            "fullScreen": false,
            "frameRate": 0,
            "muted": true,
            "connectedSourcePort": 0,
            "zOrder": 3,
            "width": 0,
            "contentType": "unknown",
            "opacity": 255,
            "height": 0,
            "videoInfo": null,
            "sourceInput": {
                "width": 0,
                "height": 0,
                "x": 0,
                "y": 0
            },
            "sink": "DISP0_SUB2",
            "context": "",
            "scanType": "unknown"
        }
    ],
    "subscribed": true,
    "returnValue": true
}
 

register

Description

Registers pipeline ID to videooutputd.

Note: If this API is required to be called, make sure it is called before the connect API call.

Parameters

Name

Required

Type

Description

contextRequiredString

Pipeline ID for registration.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/register '{"context":"_rf8D3OiiIsX6Wk"}'

 

Response:

{
    "returnValue": true
}

setVideoData

Description

Sets video data needed for playback.

Parameters

Name

Required

Type

Description

contentTypeOptionalString

Type of media content.

Possible values are:

  • movie
  • photo
  • atsc30
  • dtv
  • hdmi
  • atv
  • av
  • component
contextOptionalString

Registered pipeline ID.

frameRateRequiredNumber (double)

Video frame rate.

widthRequiredNumber (uint32_t)

Video frame width.

heightRequiredNumber (uint32_t)

Video frame height.

scanTypeOptionalString

Type of scan. Possible values are:

  • progressive
  • interlaced
sinkRequiredString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are:

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/setVideoData '{"sink":"DISP0_MAIN","frameRate":24,"width":854,"height":480}'

 

Response:

{
    "returnValue": true
}

unregister

Description

Unregisters pipeline ID from videooutputd.

Parameters

Name

Required

Type

Description

contextRequiredString

Registered pipeline ID.

Call Returns

Name

Required

Type

Description

returnValueRequiredString

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/unregister '{"context":"_fkluA2iyTUgqNM"}'

 

Response:

{
    "returnValue": true
}

display/getOutputCapabilities

Description

Helper method to query the set video limits

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
numPlanesRequiredNumber (int8_t)

Total hardware planes available on the platform for rendering

planesRequiredObject array: Planes

See "Planes" object.

errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/getOutputCapabilities '{}'

 

Response:

{
    "numPlanes": 4,
    "planes": [
        {
            "maxDownscaleSize": {
                "width": 0,
                "height": 0
            },
            "sinkId": "DISP0_MAIN",
            "maxUpscaleSize": {
                "width": 1920,
                "height": 1080
            }
        },
        {
            "maxDownscaleSize": {
                "width": 0,
                "height": 0
            },
            "sinkId": "DISP0_SUB0",
            "maxUpscaleSize": {
                "width": 1920,
                "height": 1080
            }
        },
        {
            "maxDownscaleSize": {
                "width": 0,
                "height": 0
            },
            "sinkId": "DISP0_SUB1",
            "maxUpscaleSize": {
                "width": 1920,
                "height": 1080
            }
        },
        {
            "maxDownscaleSize": {
                "width": 0,
                "height": 0
            },
            "sinkId": "DISP0_SUB2",
            "maxUpscaleSize": {
                "width": 1920,
                "height": 1080
            }
        }
    ],
    "returnValue": true
}

display/getParam

Description

Gets information of parameters for video sinks to render video frames

Parameters

Name

Required

Type

Description

commandRequiredString

Type of command.

Possible values are:

  • DRMResources - Get DRM/KMS related information.
  • NumConnector - Get the number of connected displays.
sinkOptionalString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are:

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

sinkOptionalString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are:

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
planeIdOptionalNumber (int32_t)

Numeric plane ID of the sink.

crtcIdOptionalNumber (int32_t)

Numeric crtc ID of the sink.

connIdOptionalNumber (int32_t)

Numeric connector ID of the sink.

numConnectorOptionalNumber (int32_t)

Number of connected displays

Example

Example 1 - Get DRM/KMS related information

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/getParam '{"command":"DRMResources","sink":"DISP0_MAIN"}'

 

Response:

{
    "planeId": 44,
    "sink": "DISP0_MAIN",
    "crtcId": 43,
    "returnValue": true,
    "connId": 19
}
 

Example 2 - Get the number of connected displays

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/getParam '{"command":"NumConnector"}'

 

Response:

{
    "numConnector": 1,
    "returnValue": true
}

display/setCompositing

Description

Sets compositing parameters for the video sinks.

This maps directly to adapter call and changes the compositing parameters for both video outputs simultaneously.

Parameters

Name

Required

Type

Description

composeOrderRequiredObject array: ComposeOrder

See "ComposeOrder" object.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example:

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/setCompositing '{
   "composeOrder":[
      {
         "sink":"DISP0_MAIN",
         "opacity":255,
         "zOrder":0
      },
      {
         "sink":"DISP0_SUB0",
         "opacity":255,
         "zOrder":1
      },
      {
         "sink":"DISP0_SUB1",
         "opacity":255,
         "zOrder":2
      },
      {
         "sink":"DISP0_SUB2",
         "opacity":255,
         "zOrder":3
      }
   ]
}'

 

Response:

{
    "returnValue": true
}

display/setDisplayWindow

Description

Setup video output location on the screen for specified sink.

Parameters

Name

Required

Type

Description

sinkRequiredString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are:

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
fullScreenRequiredBoolean

Indicates whether the output is fullscreen.

Possible values are:

  • true: output is fullscreen
  • false: use data from displayOuput
sourceInputOptionalObject: VideoRect

Source input rectangle.

Note: Full video frame if not set.

displayOutputOptionalObject: VideoRect

Display output rectangle.

Note: Required if fullscreen is false.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorMessage" fields for details
errorCodeOptionalNumber (int8_t)

The error code for the failed operation.

errorMessageOptionalString

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example 1: Verify video position and size is correctly changed - the video should be placed in bottom right corner:

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/setDisplayWindow '{
   "sink":"DISP0_MAIN",
   "fullScreen":false,
   "displayOutput":{
      "x":1000,
      "y":500,
      "width":920,
      "height":580
   }
}'

 

Response:

{
    "returnValue": true
}
 

Example 2: Verify video source rect is correctly changed - the video should be zoomed in to center 2x:

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/setDisplayWindow '{
   "sink":"DISP0_MAIN",
   "fullScreen":false,
   "displayOutput":{
      "x":1000,
      "y":500,
      "width":1280,
      "height":720
   },
   "sourceInput":{
      "x":80,
      "y":60,
      "width":640,
      "height":360
   }
}'

 

Response:

{
    "returnValue": true
}
 

Example 3: Verify full-screen mode:

# luna-send -n 1 -f luna://com.webos.service.videooutput/display/setDisplayWindow '{"sink":"DISP0_MAIN", "fullScreen":true}'

 

Response:

{
    "returnValue": true
}

Objects

Video

Object to represent the status of video sinks.

Name

Required

Type

Description

connectedRequiredBoolean

Specifies a video source is connected to a video sink

connectedSourceRequiredString

Video source connected.

Note: Returns 'null' if not connected.

connectedSourcePortRequiredNumber (int8_t)

Port of the source to which sink is connected

contentTypeOptionalString

Type of media content. Possible values are:

  • movie
  • photo
  • atsc30
  • dtv
  • hdmi
  • atv
  • av
  • component
contextOptionalString

Specifies registered pipeline ID

displayOutputRequiredObject: VideoRect

Specifies display output location.

frameRateRequiredNumber (double)

Frame rate of video.

fullscreenRequiredBoolean

Possible values are:

  • true: If output is fullscreen
  • false: If otherwise
heightRequiredNumber (int16_t)

Frame height of video.

mutedRequiredBoolean

Possible values are:

  • true: Video is on mute
  • false: Video is not on mute
opacityRequiredNumber (int8_t)

Possible values are in the range of 0..255.

  • 0 = Highest transparency value
  • 255 = Highest opacity value
scanTypeRequiredString

Type of scan. Possible values are:

  • progressive
  • interlaced
sinkRequiredString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the id values above.

Possible values are: 

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
sourceInputRequiredObject: VideoRect

Specifies source or input cropping location.

widthRequiredNumber (int16_t)

Frame width of video.

zOrderRequiredNumber (int8_t)

Possible values are:

  • int (0..3) - relative order from Main, Sub0, Sub1, Sub2

VideoRect

Object to represent the video window coordinates.

Name

Required

Type

Description

xRequiredNumber (int32_t)

Horizontal offset from top left of the screen or origin (0,0)

yRequiredNumber (int32_t)

Vertical offset from top left of the screen

widthRequiredNumber (int32_t)

Width of the video window

heightRequiredNumber (int32_t)

Height of the video window

Planes

Object to represent video planes and available size of scaling.

Name

Required

Type

Description

sinkIdRequiredString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the ID values above.

Possible values are:

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
maxDownscaleSizeRequiredObject: VideoSize

See "VideoSize" object.

maxUpscaleSizeRequiredObject: VideoSize

See "VideoSize" object.

VideoSize

Object to represent video size.

Name

Required

Type

Description

widthRequiredNumber (int16_t)

Width of the video window

heightRequiredNumber (int16_t)

Height of the video window

ComposeOrder

Object to represent compositing parameters for the video sinks.

Name

Required

Type

Description

sinkRequiredString

Video sink. 

Each value corresponds to overlay plane ID of display. For example, raspberrypi have overlay planes whose IDs are 44, 45, 46, 47. Each possible string value corresponds to the id values above.

Possible values are:

  • DISP0_MAIN
  • DISP0_SUB0
  • DISP0_SUB1
  • DISP0_SUB2
opacityRequiredNumber (int32_t)

Opacity value. 

Value can be between 0 and 255, where:

  • 0 - Highest transparency value.
  • 255 - Highest opacity value.
zOrderRequiredNumber (int32_t)

Relative order between Main and Sub.

Value can be between 0 and 3, where:

  • 0 - bottom
  • 3 - top

API Error Codes Reference

Error Code

Error Text

Error Description

1Unknown error

Unknown error.

10Not implemented

Not implemented.

20Driver error while executing the command

Driver error while executing the command.

100Video not connected

Video not connected.

Contents