Display 服务
辅助头文件:
#include "brookesia/service_helper/media/display.hpp"辅助类:
esp_brookesia::service::helper::Display
概述
brookesia_service_display 管理显示输出、显示源、活动源仲裁、帧提交、触摸手势和背光控制。
核心职责
注册显示源,并把帧路由到活动物理输出。
提供输出/源发现和活动源选择服务函数。
暴露触摸手势事件和绑定输出的背光操作。
集成位置
该组件是 ESP-Brookesia 发布组件清单中的独立组件,可通过 ESP-IDF 组件依赖集成,并与同层框架组件按需组合。
服务接口
函数
GetOutputs
描述
Get display outputs.
执行要求
是否需要调度器: 不需要
参数
无。
返回值
类型:
Array描述: Example: [{"id":1,"name":"Output0","width":240,"height":240,"pixel_format":"RGB565","slot":"HalPanel","panel_instance":"Display:Panel0","group_id":"main_display","touch":{"id":1,"name":"Touch0","instance":"Display:Touch0","max_points":5,"operation_mode":"Interrupt"},"backlight":{"instance":"Display:Backlight0","on_off_supported":true}}]
Schema JSON
展开查看 JSON
{
"name": "GetOutputs",
"description": "Get display outputs.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [{\"id\":1,\"name\":\"Output0\",\"width\":240,\"height\":240,\"pixel_format\":\"RGB565\",\"slot\":\"HalPanel\",\"panel_instance\":\"Display:Panel0\",\"group_id\":\"main_display\",\"touch\":{\"id\":1,\"name\":\"Touch0\",\"instance\":\"Display:Touch0\",\"max_points\":5,\"operation_mode\":\"Interrupt\"},\"backlight\":{\"instance\":\"Display:Backlight0\",\"on_off_supported\":true}}]"
}
}
CLI 命令
svc_call Display GetOutputs
GetSources
描述
Get registered display sources.
执行要求
是否需要调度器: 不需要
参数
无。
返回值
类型:
Array描述: Example: [{"id":1,"name":"LVGL","role":"gui","preferred_outputs":["Output0"],"priority":0}]
Schema JSON
展开查看 JSON
{
"name": "GetSources",
"description": "Get registered display sources.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [{\"id\":1,\"name\":\"LVGL\",\"role\":\"gui\",\"preferred_outputs\":[\"Output0\"],\"priority\":0}]"
}
}
CLI 命令
svc_call Display GetSources
RegisterSource
描述
Register a display source. Example source: {"id":0,"name":"LVGL","role":"gui","preferred_outputs":["Output0"],"priority":0}
执行要求
是否需要调度器: 不需要
参数
Source类型:
Object是否必填: 必填
描述: Display source info object. The id field is assigned by Display service.
返回值
类型:
Number描述: Registered display source id.
Schema JSON
展开查看 JSON
{
"name": "RegisterSource",
"description": "Register a display source. Example source: {\"id\":0,\"name\":\"LVGL\",\"role\":\"gui\",\"preferred_outputs\":[\"Output0\"],\"priority\":0}",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "Source",
"description": "Display source info object. The id field is assigned by Display service.",
"type": "Object",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Number",
"description": "Registered display source id."
}
}
CLI 命令
svc_call Display RegisterSource {"Source":null}
UnregisterSource
描述
Unregister a named display source.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Display source name.
Schema JSON
展开查看 JSON
{
"name": "UnregisterSource",
"description": "Unregister a named display source.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Display source name.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call Display UnregisterSource {"SourceName":null}
RequestOutput
描述
Request permission for a source to draw to one output.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Registered source name.
OutputName类型:
String是否必填: 可选
默认值:
""描述: Display output name. Empty string uses the first output.
Schema JSON
展开查看 JSON
{
"name": "RequestOutput",
"description": "Request permission for a source to draw to one output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Registered source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Display output name. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": null
}
CLI 命令
svc_call Display RequestOutput {"SourceName":null,"OutputName":null}
ReleaseOutput
描述
Release a source's request for one output.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String是否必填: 必填
描述: Registered source name.
OutputName类型:
String是否必填: 可选
默认值:
""描述: Display output name. Empty string uses the first output.
Schema JSON
展开查看 JSON
{
"name": "ReleaseOutput",
"description": "Release a source's request for one output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "SourceName",
"description": "Registered source name.",
"type": "String",
"required": true,
"default_value": null
},
{
"name": "OutputName",
"description": "Display output name. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": null
}
CLI 命令
svc_call Display ReleaseOutput {"SourceName":null,"OutputName":null}
SetActiveSource
描述
Grant one display output to a named source. Empty source name clears the active source.
执行要求
是否需要调度器: 需要
参数
OutputName类型:
String是否必填: 可选
默认值:
""描述: Display output name, for example Output0. Empty string uses the first output.
SourceName类型:
String是否必填: 必填
描述: Registered source name, or empty string to clear.
Schema JSON
展开查看 JSON
{
"name": "SetActiveSource",
"description": "Grant one display output to a named source. Empty source name clears the active source.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
},
{
"name": "SourceName",
"description": "Registered source name, or empty string to clear.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call Display SetActiveSource {"OutputName":null,"SourceName":null}
GetActiveSource
描述
Get the active source name for one display output. Returns empty string when no source is active.
执行要求
是否需要调度器: 需要
参数
OutputName类型:
String是否必填: 可选
默认值:
""描述: Display output name, for example Output0. Empty string uses the first output.
返回值
类型:
String描述: Active source name, or an empty string when no source is active.
Schema JSON
展开查看 JSON
{
"name": "GetActiveSource",
"description": "Get the active source name for one display output. Returns empty string when no source is active.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": {
"type": "String",
"description": "Active source name, or an empty string when no source is active."
}
}
CLI 命令
svc_call Display GetActiveSource {"OutputName":null}
SetActiveSourceRole
描述
Grant one display output to the first registered source with the specified role.
执行要求
是否需要调度器: 需要
参数
OutputName类型:
String是否必填: 可选
默认值:
""描述: Display output name, for example Output0. Empty string uses the first output.
Role类型:
String是否必填: 必填
描述: Registered source role.
Schema JSON
展开查看 JSON
{
"name": "SetActiveSourceRole",
"description": "Grant one display output to the first registered source with the specified role.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
},
{
"name": "Role",
"description": "Registered source role.",
"type": "String",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call Display SetActiveSourceRole {"OutputName":null,"Role":null}
GetActiveRole
描述
Get the active source role for one display output. Returns empty string when no source is active.
执行要求
是否需要调度器: 需要
参数
OutputName类型:
String是否必填: 可选
默认值:
""描述: Display output name, for example Output0. Empty string uses the first output.
返回值
类型:
String描述: Active source role, or an empty string when no source is active.
Schema JSON
展开查看 JSON
{
"name": "GetActiveRole",
"description": "Get the active source role for one display output. Returns empty string when no source is active.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputName",
"description": "Display output name, for example Output0. Empty string uses the first output.",
"type": "String",
"required": false,
"default_value": ""
}
],
"return_value": {
"type": "String",
"description": "Active source role, or an empty string when no source is active."
}
}
CLI 命令
svc_call Display GetActiveRole {"OutputName":null}
GetSourceRoles
描述
Get registered display source roles, de-duplicated in first-registration order.
执行要求
是否需要调度器: 不需要
参数
无。
返回值
类型:
Array描述: Example: ["gui","video"]
Schema JSON
展开查看 JSON
{
"name": "GetSourceRoles",
"description": "Get registered display source roles, de-duplicated in first-registration order.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [],
"return_value": {
"type": "Array",
"description": "Example: [\"gui\",\"video\"]"
}
}
CLI 命令
svc_call Display GetSourceRoles
SetTouchGestureConfig
描述
Configure touch gesture detection for one output. Example config: {"enabled":false,"detect_period_ms":20,"direction_lock_enabled":true,"release_debounce_ms":40,"threshold":{"direction_vertical":0,"direction_horizon":0,"direction_angle":45,"horizontal_edge":0,"vertical_edge":0,"duration_short_ms":220,"speed_slow_px_per_ms":6.000000238418579E-1}}
执行要求
是否需要调度器: 不需要
参数
OutputId类型:
Number是否必填: 必填
描述: Runtime Display output id from GetOutputs().
Config类型:
Object是否必填: 可选
默认值:
{"enabled":false,"detect_period_ms":20,"direction_lock_enabled":true,"release_debounce_ms":40,"threshold":{"direction_vertical":0,"direction_horizon":0,"direction_angle":45,"horizontal_edge":0,"vertical_edge":0,"duration_short_ms":220,"speed_slow_px_per_ms":6.000000238418579E-1}}描述: Gesture configuration object. Zero threshold fields use output defaults.
Schema JSON
展开查看 JSON
{
"name": "SetTouchGestureConfig",
"description": "Configure touch gesture detection for one output. Example config: {\"enabled\":false,\"detect_period_ms\":20,\"direction_lock_enabled\":true,\"release_debounce_ms\":40,\"threshold\":{\"direction_vertical\":0,\"direction_horizon\":0,\"direction_angle\":45,\"horizontal_edge\":0,\"vertical_edge\":0,\"duration_short_ms\":220,\"speed_slow_px_per_ms\":6.000000238418579E-1}}",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
},
{
"name": "Config",
"description": "Gesture configuration object. Zero threshold fields use output defaults.",
"type": "Object",
"required": false,
"default_value": {
"enabled": false,
"detect_period_ms": 20,
"direction_lock_enabled": true,
"release_debounce_ms": 40,
"threshold": {
"direction_vertical": 0,
"direction_horizon": 0,
"direction_angle": 45,
"horizontal_edge": 0,
"vertical_edge": 0,
"duration_short_ms": 220,
"speed_slow_px_per_ms": 0.6000000238418579
}
}
}
],
"return_value": null
}
CLI 命令
svc_call Display SetTouchGestureConfig {"OutputId":null,"Config":null}
GetTouchGestureConfig
描述
Get touch gesture config for one output.
执行要求
是否需要调度器: 不需要
参数
OutputId类型:
Number是否必填: 必填
描述: Runtime Display output id from GetOutputs().
返回值
类型:
Object描述: Example: {"enabled":false,"detect_period_ms":20,"direction_lock_enabled":true,"release_debounce_ms":40,"threshold":{"direction_vertical":0,"direction_horizon":0,"direction_angle":45,"horizontal_edge":0,"vertical_edge":0,"duration_short_ms":220,"speed_slow_px_per_ms":6.000000238418579E-1}}
Schema JSON
展开查看 JSON
{
"name": "GetTouchGestureConfig",
"description": "Get touch gesture config for one output.",
"require_scheduler": false,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Object",
"description": "Example: {\"enabled\":false,\"detect_period_ms\":20,\"direction_lock_enabled\":true,\"release_debounce_ms\":40,\"threshold\":{\"direction_vertical\":0,\"direction_horizon\":0,\"direction_angle\":45,\"horizontal_edge\":0,\"vertical_edge\":0,\"duration_short_ms\":220,\"speed_slow_px_per_ms\":6.000000238418579E-1}}"
}
}
CLI 命令
svc_call Display GetTouchGestureConfig {"OutputId":null}
SetBacklightBrightness
描述
Set backlight brightness percentage for one display output.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number是否必填: 必填
描述: Runtime Display output id from GetOutputs().
Brightness类型:
Number是否必填: 必填
描述: Backlight brightness percentage in range [0, 100].
Schema JSON
展开查看 JSON
{
"name": "SetBacklightBrightness",
"description": "Set backlight brightness percentage for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
},
{
"name": "Brightness",
"description": "Backlight brightness percentage in range [0, 100].",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call Display SetBacklightBrightness {"OutputId":null,"Brightness":null}
GetBacklightBrightness
描述
Get backlight brightness percentage for one display output.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number是否必填: 必填
描述: Runtime Display output id from GetOutputs().
返回值
类型:
Number描述: Backlight brightness percentage in range [0, 100].
Schema JSON
展开查看 JSON
{
"name": "GetBacklightBrightness",
"description": "Get backlight brightness percentage for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Number",
"description": "Backlight brightness percentage in range [0, 100]."
}
}
CLI 命令
svc_call Display GetBacklightBrightness {"OutputId":null}
SetBacklightOnOff
描述
Turn the backlight on or off for one display output.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number是否必填: 必填
描述: Runtime Display output id from GetOutputs().
On类型:
Boolean是否必填: 必填
描述: True to turn on the backlight, false to turn it off.
Schema JSON
展开查看 JSON
{
"name": "SetBacklightOnOff",
"description": "Turn the backlight on or off for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
},
{
"name": "On",
"description": "True to turn on the backlight, false to turn it off.",
"type": "Boolean",
"required": true,
"default_value": null
}
],
"return_value": null
}
CLI 命令
svc_call Display SetBacklightOnOff {"OutputId":null,"On":null}
GetBacklightOnOff
描述
Get whether the backlight is enabled for one display output.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number是否必填: 必填
描述: Runtime Display output id from GetOutputs().
返回值
类型:
Boolean描述: True when backlight is enabled, false otherwise.
Schema JSON
展开查看 JSON
{
"name": "GetBacklightOnOff",
"description": "Get whether the backlight is enabled for one display output.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs().",
"type": "Number",
"required": true,
"default_value": null
}
],
"return_value": {
"type": "Boolean",
"description": "True when backlight is enabled, false otherwise."
}
}
CLI 命令
svc_call Display GetBacklightOnOff {"OutputId":null}
LoadData
描述
Load persisted Display state. OutputId 0 loads all backlight-bound outputs.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number是否必填: 可选
默认值:
0E0描述: Runtime Display output id from GetOutputs(), or 0 for all outputs.
Schema JSON
展开查看 JSON
{
"name": "LoadData",
"description": "Load persisted Display state. OutputId 0 loads all backlight-bound outputs.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs(), or 0 for all outputs.",
"type": "Number",
"required": false,
"default_value": 0.0
}
],
"return_value": null
}
CLI 命令
svc_call Display LoadData {"OutputId":null}
ResetData
描述
Reset persisted Display state. OutputId 0 resets all backlight-bound outputs.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number是否必填: 可选
默认值:
0E0描述: Runtime Display output id from GetOutputs(), or 0 for all outputs.
Schema JSON
展开查看 JSON
{
"name": "ResetData",
"description": "Reset persisted Display state. OutputId 0 resets all backlight-bound outputs.",
"require_scheduler": true,
"default_timeout_ms": null,
"parameters": [
{
"name": "OutputId",
"description": "Runtime Display output id from GetOutputs(), or 0 for all outputs.",
"type": "Number",
"required": false,
"default_value": 0.0
}
],
"return_value": null
}
CLI 命令
svc_call Display ResetData {"OutputId":null}
事件
SourceStateChanged
描述
A display source state changed relative to an output.
执行要求
是否需要调度器: 不需要
参数
SourceName类型:
String描述: Source name.
OutputName类型:
String描述: Output name, or empty string for source-global changes.
State类型:
String描述: New source state.
Schema JSON
展开查看 JSON
{
"name": "SourceStateChanged",
"description": "A display source state changed relative to an output.",
"require_scheduler": false,
"items": [
{
"name": "SourceName",
"description": "Source name.",
"type": "String"
},
{
"name": "OutputName",
"description": "Output name, or empty string for source-global changes.",
"type": "String"
},
{
"name": "State",
"description": "New source state.",
"type": "String"
}
]
}
CLI 命令
svc_subscribe Display SourceStateChanged
ActiveSourceChanged
描述
The active source for an output changed.
执行要求
是否需要调度器: 不需要
参数
OutputName类型:
String描述: Output name.
SourceName类型:
String描述: Active source name, or empty string when cleared.
Schema JSON
展开查看 JSON
{
"name": "ActiveSourceChanged",
"description": "The active source for an output changed.",
"require_scheduler": false,
"items": [
{
"name": "OutputName",
"description": "Output name.",
"type": "String"
},
{
"name": "SourceName",
"description": "Active source name, or empty string when cleared.",
"type": "String"
}
]
}
CLI 命令
svc_subscribe Display ActiveSourceChanged
OutputRegistered
描述
A dynamic display output was registered.
执行要求
是否需要调度器: 不需要
参数
Info类型:
Object描述: Registered output info.
Schema JSON
展开查看 JSON
{
"name": "OutputRegistered",
"description": "A dynamic display output was registered.",
"require_scheduler": false,
"items": [
{
"name": "Info",
"description": "Registered output info.",
"type": "Object"
}
]
}
CLI 命令
svc_subscribe Display OutputRegistered
OutputUnregistered
描述
A dynamic display output was unregistered.
执行要求
是否需要调度器: 不需要
参数
OutputName类型:
String描述: Display output name.
Schema JSON
展开查看 JSON
{
"name": "OutputUnregistered",
"description": "A dynamic display output was unregistered.",
"require_scheduler": false,
"items": [
{
"name": "OutputName",
"description": "Display output name.",
"type": "String"
}
]
}
CLI 命令
svc_subscribe Display OutputUnregistered
TouchGesture
描述
A display output touch gesture changed state.
执行要求
是否需要调度器: 不需要
参数
Info类型:
Object描述: Gesture event payload.
Schema JSON
展开查看 JSON
{
"name": "TouchGesture",
"description": "A display output touch gesture changed state.",
"require_scheduler": false,
"items": [
{
"name": "Info",
"description": "Gesture event payload.",
"type": "Object"
}
]
}
CLI 命令
svc_subscribe Display TouchGesture
BacklightBrightnessChanged
描述
The backlight brightness for an output changed.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number描述: Runtime Display output id.
OutputName类型:
String描述: Output name.
Brightness类型:
Number描述: Current target backlight brightness percentage [0, 100].
Schema JSON
展开查看 JSON
{
"name": "BacklightBrightnessChanged",
"description": "The backlight brightness for an output changed.",
"require_scheduler": true,
"items": [
{
"name": "OutputId",
"description": "Runtime Display output id.",
"type": "Number"
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String"
},
{
"name": "Brightness",
"description": "Current target backlight brightness percentage [0, 100].",
"type": "Number"
}
]
}
CLI 命令
svc_subscribe Display BacklightBrightnessChanged
BacklightOnOffChanged
描述
The backlight on/off state for an output changed.
执行要求
是否需要调度器: 需要
参数
OutputId类型:
Number描述: Runtime Display output id.
OutputName类型:
String描述: Output name.
IsOn类型:
Boolean描述: Whether display backlight is currently on. True if on, false if off.
Schema JSON
展开查看 JSON
{
"name": "BacklightOnOffChanged",
"description": "The backlight on/off state for an output changed.",
"require_scheduler": true,
"items": [
{
"name": "OutputId",
"description": "Runtime Display output id.",
"type": "Number"
},
{
"name": "OutputName",
"description": "Output name.",
"type": "String"
},
{
"name": "IsOn",
"description": "Whether display backlight is currently on. True if on, false if off.",
"type": "Boolean"
}
]
}
CLI 命令
svc_subscribe Display BacklightOnOffChanged