Skip to content

Latest commit

 

History

History
537 lines (401 loc) · 12.1 KB

CompositorPlugin.md

File metadata and controls

537 lines (401 loc) · 12.1 KB
Raw

Compositor Plugin

Version: 1.0

Status: ⚫⚫⚫

Compositor plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the Compositor plugin. It includes detailed specification of its configuration, methods and properties provided.

Case Sensitivity

All identifiers on the interface described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

Compositor gives you controll over what is displayed on screen.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string Plugin instance name (default: Compositor)
classname string Class name: Compositor
locator string Library name: libWPEFrameworkCompositor.so
autostart boolean Determines if the plugin is to be started automatically along with the framework

Methods

The following methods are provided by the Compositor plugin:

Compositor interface methods:

Method Description
putontop Puts client surface on top in z-order
putbelow Puts client surface below another surface
select Directs the input to the given client, disabling all the others

putontop method

Puts client surface on top in z-order.

Description

Use this method to get a client's surface to the top position.

Parameters

Name Type Description
params object
params.client string Client name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Client not found

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.putontop",
    "params": {
        "client": "Netflix"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": null
}

putbelow method

Puts client surface below another surface.

Description

Use this method to reorder client surfaces in the z-order list.

Parameters

Name Type Description
params object
params.client string Client name to change z-order position
params.relative string Client to put the other surface below

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Client(s) not found

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.putbelow",
    "params": {
        "client": "Netflix",
        "relative": "WebKitBrowser"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": null
}

select method

Directs the input to the given client, disabling all the others.

Description

Use this method to direct all inputs to this client. The client that is receiving the inputs prior to this call will nolonger receive it anymore after this call.

Parameters

Name Type Description
params object
params.client string Client name

Result

Name Type Description
result null Always null

Errors

Code Message Description
2 ERROR_UNAVAILABLE Client not found

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.select",
    "params": {
        "client": "Netflix"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": null
}

Properties

The following properties are provided by the Compositor plugin:

Compositor interface properties:

Property Description
resolution Screen resolution
zorder RO List of compositor clients sorted by z-order
geometry Client surface geometry
visiblity WO Client surface visibility
opacity WO Client surface opacity

resolution property

Provides access to the screen resolution.

Description

Use this property to set or retrieve the current resolution of the screen.

Value

Name Type Description
(property) string Screen resolution (must be one of the following: unknown, 480i, 480p, 720p50, 720p60, 1080p24, 1080i50, 1080p50, 1080p60, 2160p50, 2160p60)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown resolution
2 ERROR_UNAVAILABLE Set resolution is not supported or failed
1 ERROR_GENERAL Failed to set resolution

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.resolution"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": "1080p24"
}

Set Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.resolution",
    "params": "1080p24"
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": "null"
}

zorder property

Provides access to the list of compositor clients sorted by z-order.

This property is read-only.

Description

Use this property to retrieve the list of all clients in z-order. Each client has an z-order-value that determines its position with respect to the screen. The ordering is that the top position is closest to the screen, the next z-order-value first behind the top, and so on.

Value

Name Type Description
(property) array List of compositor clients sorted by z-order
(property)[#] string Client name

Errors

Code Message Description
1 ERROR_GENERAL Failed to get z-order

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.zorder"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": [
        "Netflix"
    ]
}

geometry property

Provides access to the client surface geometry.

Description

Use this property to update or retrieve the geometry of a client's surface.

Value

Name Type Description
(property) object Client surface geometry
(property).x number Horizontal coordinate of the surface
(property).y number Vertical coordinate of the surface
(property).width number Surface width
(property).height number Surface height

The client shall be passed as the index to the property, e.g. Compositor.1.geometry@Netflix.

Errors

Code Message Description
2 ERROR_UNAVAILABLE Client not found

Example

Get Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.geometry@Netflix"
}

Get Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": {
        "x": 0,
        "y": 0,
        "width": 1280,
        "height": 720
    }
}

Set Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.geometry@Netflix",
    "params": {
        "x": 0,
        "y": 0,
        "width": 1280,
        "height": 720
    }
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": "null"
}

visiblity property

Provides access to the client surface visibility.

This property is write-only.

Description

Use this property to set the client's surface visibility.

Value

Name Type Description
(property) string Client surface visibility (must be one of the following: visible, hidden)

The client shall be passed as the index to the property, e.g. Compositor.1.visiblity@Netflix.

Errors

Code Message Description
2 ERROR_UNAVAILABLE Client not found

Example

Set Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.visiblity@Netflix",
    "params": "visible"
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": "null"
}

opacity property

Provides access to the client surface opacity.

This property is write-only.

Description

Use this property to set the client's surface opacity level.

Value

Name Type Description
(property) number Opacity level (0 to 255; 0: fully transparent, 255: fully opaque)

The client shall be passed as the index to the property, e.g. Compositor.1.opacity@Netflix.

Errors

Code Message Description
2 ERROR_UNAVAILABLE Client not found

Example

Set Request

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "method": "Compositor.1.opacity@Netflix",
    "params": 127
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 1234567890,
    "result": "null"
}