四，libweston输出管理

Posted 2022-01-01 小B伏枥

一、输出管理

        Libweston 输出API主要围绕两个概念，分别是weston_head和weston_output。weston_head作为一个连接器或者监视器；而weston_output作为一个合成状态机，用于产生相关内容并最终呈现倒weston_head上去。如果backend允许，可以同时使用多个head和output。在这种情况下，所有的head具有相同的时间和内容（也就是说这些head共享framebuffer）。

        libweston会根据物理连接器来自动创建和销毁head。创建，热插拔时间或者其他head相关的改变可以通过  weston_compositor_add_heads_changed_listener()来监听。需要注意的是，断开一个连接器并不意味head被销毁。当连接器消失时才会销毁head。

一些虚拟或者嵌套的backend会提供backend相关的，特有的API来控制head的创建和销毁。这种情况下，head不在作为任何物理设备的连接器或者监视器。但是可以作为一个窗口系统中的一个窗口。

        libweston用户需要明确地根据需求来创建和销毁output。创建一个新的outpu或者点亮一个head，你需要创建一个output，然后关联一个head，并进行相关的配置，最终通过weston_output_enable()来使能output。

        一个处于使能状态的output可以被重新配置。但是这部分在将来可能会做出调整。你可以通过weston_output_disable()来关闭一个output然后重置它，但是会引起一些故障。

二、API

2.1 heads

        一个weston_head对象就是一个head。

        一个head可以在驱动硬件的时候作为一个监视器，也可以是一个窗口系统中的窗口，后者虚拟概念。但本质上一个head就是你呈现图像的地方。这个图像由head关联的weston_output产生。

        在显示设备中，一个head作为计算机系统的一个显示连接器而不是一个连接到连接器的实实在在的监视器。一个head携带了监视器信息，如品牌，型号，EDID和可能的视频模式，DPMS模式和背光控制。

        就Wayland协议而言，一个head对应一个wl_output。如果一个weston_outpu有多个head。就意味着这些head是克隆而来的。每个head在wl_registry中作为一个独立的wl_output。

        Head可以动态的产生和消失，主要是由于DisplayPort Multi-Stream Transport。窗口和虚拟的output也通常是动态的。

        head由libweston持有，并且分配他们的生命周期。一些backend可能提供一些特有的接口来创建和销毁head。但是硬件backend如DRM-backend，有他们自己来管理创建和销毁head。

        一个weston_head必须关联到一个weston_output中。可以通过适应weston_output_attach_head()，weston_head_detach()函数来进行管理。

其他相关函数和成员如下：

struct weston_head *weston_head_from_resource(struct wl_resource *resource)

Get the backing object of wl_output.

Parameters

resource – A wl_output protocol object.

Returns

The backing object (user data) of a wl_resource representing a wl_output protocol object.

void weston_head_init(struct weston_head *head, const char *name)

Initialize a pre-allocated weston_head.

The head will be safe to attach, detach and release.

The name is used in logs, and can be used by compositors as a configuration identifier.

Parameters

• head – The head to initialize.

• name – The head name, e.g. the connector name or equivalent.

void weston_head_detach(struct weston_head *head)

Detach a head from its output.

It is safe to detach a non-attached head.

If the head is attached to an enabled output and the output will be left with no heads, the output will be disabled.

See

weston_output_disable

Parameters

head – The head to detach.

void weston_head_release(struct weston_head *head)

Destroy a head.

Destroys the head. The caller is responsible for freeing the memory pointed to by head.

Parameters

head – The head to be released.

void weston_head_set_monitor_strings(struct weston_head *head, const char *make, const char *model, const char *serialno)

Store monitor make, model and serial number.

This may set the device_changed flag.

Parameters

• head – The head to modify.

• make – The monitor make. If EDID is available, the PNP ID. Otherwise any string, or NULL for none.

• model – The monitor model or name, or a made-up string, or NULL for none.

• serialno – The monitor serial number, a made-up string, or NULL for none.

void weston_head_set_non_desktop(struct weston_head *head, bool non_desktop)

Store display non-desktop status.

Parameters

• head – The head to modify.

• non_desktop – Whether the head connects to a non-desktop display.

void weston_head_set_transform(struct weston_head *head, uint32_t transform)

Store display transformation.

This may set the device_changed flag.

Parameters

• head – The head to modify.

• transform – The transformation to apply for this head

void weston_head_set_physical_size(struct weston_head *head, int32_t mm_width, int32_t mm_height)

Store physical image size.

This may set the device_changed flag.

Parameters

• head – The head to modify.

• mm_width – Image area width in millimeters.

• mm_height – Image area height in millimeters.

void weston_head_set_subpixel(struct weston_head *head, enum wl_output_subpixel sp)

Store monitor sub-pixel layout.

This may set the device_changed flag.

Parameters

• head – The head to modify.

• sp – Sub-pixel layout. The possible values are:

  • WL_OUTPUT_SUBPIXEL_UNKNOWN,

  • WL_OUTPUT_SUBPIXEL_NONE,

  • WL_OUTPUT_SUBPIXEL_HORIZONTAL_RGB,

  • WL_OUTPUT_SUBPIXEL_HORIZONTAL_BGR,

  • WL_OUTPUT_SUBPIXEL_VERTICAL_RGB,

  • WL_OUTPUT_SUBPIXEL_VERTICAL_BGR

void weston_head_set_internal(struct weston_head *head)

Mark the monitor as internal.

This is used for embedded screens, like laptop panels.

By default a head is external. The type is often inferred from the physical connector type.

Parameters

head – The head to mark as internal.

void weston_head_set_connection_status(struct weston_head *head, bool connected)

Store connector status.

Connectors are created as disconnected. This function can be used to set the connector status.

The status should be set to true when a physical connector is connected to a video sink device like a monitor and to false when the connector is disconnected. For nested backends, the connection status should reflect the connection to the parent display server.

When the connection status changes, it schedules a call to the heads_changed hook and sets the device_changed flag.

See

weston_compositor_set_heads_changed_cb

Parameters

• head – The head to modify.

• connected – Whether the head is connected.

bool weston_head_is_connected(struct weston_head *head)

Is the head currently connected?

Returns true if the head is physically connected to a monitor, or in case of a nested backend returns true when there is a connection to the parent display server.

This is independent from the head being enabled.

See

weston_head_is_enabled

Parameters

head – The head to query.

Returns

Connection status.

bool weston_head_is_enabled(struct weston_head *head)

Is the head currently enabled?

Returns true if the head is currently transmitting a video stream.

This is independent of the head being connected.

See

weston_head_is_connected

Parameters

head – The head to query.

Returns

Video status.

bool weston_head_is_device_changed(struct weston_head *head)

Has the device information changed?

The information about the connected display device, e.g. a monitor, may change without being disconnected in between. Changing information causes a call to the heads_changed hook.

The information includes make, model, serial number, physical size, and sub-pixel type. The connection status is also included.

See

weston_head_reset_device_changed, weston_compositor_set_heads_changed_cb

Parameters

head – The head to query.

Returns

True if the device information has changed since last reset.

bool weston_head_is_non_desktop(struct weston_head *head)

Does the head represent a non-desktop display?

Non-desktop heads are not attached to outputs by default. This stops weston from extending the desktop onto head mounted displays.

Parameters

head – The head to query.

Returns

True if the device is a non-desktop display.

void weston_head_reset_device_changed(struct weston_head *head)

Acknowledge device information change.

Clears the device changed flag on this head. When a compositor has processed device information, it should call this to be able to notice further changes.

See

weston_head_is_device_changed

Parameters

head – The head to acknowledge.

const char *weston_head_get_name(struct weston_head *head)

Get the name of a head.

The name depends on the backend. The DRM backend uses connector names, other backends may use hardcoded names or user-given names.

Parameters

head – The head to query.

Returns

The head’s name, not NULL.

struct weston_output *weston_head_get_output(struct weston_head *head)

Get the output the head is attached to.

Parameters

head – The head to query.

Returns

The output the head is attached to, or NULL if detached.

uint32_t weston_head_get_transform(struct weston_head *head)

Get the head’s native transformation.

A weston_head may have a ‘native’ transform provided by the backend. Examples include panels which are physically rotated, where the rotation is recorded and described as part of the system configuration. This call will return any known native transform for the head.

Parameters

head – The head to query.

Returns

The head’s native transform, as a WL_OUTPUT_TRANSFORM_* value

void weston_head_add_destroy_listener(struct weston_head *head, struct wl_listener *listener)

Add destroy callback for a head.

Heads may get destroyed for various reasons by the backends. If a head is attached to an output, the compositor should listen for head destruction and reconfigure or destroy the output if necessary.

The destroy callbacks will be called on weston_head destruction before any automatic detaching from an associated weston_output and before any weston_head information is lost.

The data argument to the notify callback is the weston_head being destroyed.

Parameters

• head – The head to watch for.

• listener – The listener to add. The notify member must be set.

struct wl_listener *weston_head_get_destroy_listener(struct weston_head *head, wl_notify_func_t notify)

Look up destroy listener for a head.

This looks up the previously added destroy listener struct based on the notify function it has. The listener can be used to access user data through container_of().

See

wl_signal_get()

Parameters

• head – The head to query.

• notify – The notify function used used for the added destroy listener.

Returns

The listener, or NULL if not found.

struct weston_head

#include <libweston.h>

Represents a head, usually a display connector.

See Heads.

Public Members

struct weston_compositor *compositor

owning compositor

struct wl_list compositor_link

in weston_compositor::head_list

struct wl_signal destroy_signal

destroy callbacks

struct weston_output *output

the output driving this head

struct wl_list output_link

in weston_output::head_list

struct wl_list resource_list

wl_output protocol objects

struct wl_global *global

wl_output global

struct wl_list xdg_output_resource_list

xdg_output protocol objects

int32_t mm_width

physical image width in mm

int32_t mm_height

physical image height in mm

uint32_t transform

WL_OUTPUT_TRANSFORM enum to apply to match native orientation.

char *make

monitor manufacturer (PNP ID)

char *model

monitor model

char *serial_number

monitor serial

uint32_t subpixel

enum wl_output_subpixel

bool connection_internal

embedded monitor (e.g.

laptop)

bool device_changed

monitor information has changed

char *name

head name, e.g.

connector name

bool connected

is physically connected

bool non_desktop

non-desktop display, e.g.

HMD

enum weston_hdcp_protection current_protection

Current content protection status.

2.2 Outputs

        一个weston_output决定一个全局合成器哪部分将会被合成到一张图片当中去。且该图片将会被发送给head。

        一个output对象负责帧缓冲的管理、损坏跟踪、显示计时、以及重置状态机。output的属性包含视频模式，输出尺寸以及输出转换等。

        在显示硬件设备中，一个weston_output代表着一个CRTC（阴极射线管控制器Cathode Ray Tube Controller）。

        一个weston_output的生命周期由libweston使用者来控制。

        当至少一个weston_head被成功关联后，你可以通过合成器创建一个weston_output对象，并通过weston_output_enable()来使能该output。

        可以通过weston_output_disable()函数逆转前面的操作。

        其他函数和成员信息，如下：

int weston_output_mode_set_native(struct weston_output *output, struct weston_mode *mode, int32_t scale)

int weston_output_mode_switch_to_native(struct weston_output *output)

int weston_output_mode_switch_to_temporary(struct weston_output *output, struct weston_mode *mode, int32_t scale)

void weston_output_damage(struct weston_output *output)

void weston_output_finish_frame(struct weston_output *output, const struct timespec *stamp, uint32_t presented_flags)

void weston_output_schedule_repaint(struct weston_output *output)

static void weston_output_emit_heads_changed(struct weston_output *output)

Send output heads changed signal.

Notify that the enabled output gained and/or lost heads, or that the associated heads may have changed their connection status. This does not include cases where the output becomes enabled or disabled. The registered callbacks are called after the change has successfully happened.

If connection status change causes the compositor to attach or detach a head to an enabled output, the registered callbacks may be called multiple times.

Parameters

output – The output that changed.

struct weston_head *weston_output_iterate_heads(struct weston_output *output, struct weston_head *iter)

Iterate over attached heads.

Returns all heads currently attached to the output.

You can iterate over all heads as follows:

struct weston_head *head = NULL;

while ((head = weston_output_iterate_heads(output, head))) 
        ...

If you cause iter to be removed from the list, you cannot use it to continue iterating. Removing any other item is safe.

Parameters

• output – The output whose heads to iterate.

• iter – The iterator, or NULL for start.

Returns

The next attached head in the list.

int weston_output_attach_head(struct weston_output *output, struct weston_head *head)

Attach a head to an output.

Attaches the given head to the output. All heads of an output are clones and share the resolution and timings.

Cloning heads this way uses less resources than creating an output for each head, but is not always possible due to environment, driver and hardware limitations.

On failure, the head remains unattached. Success of this function does not guarantee the output configuration is actually valid. The final checks are made on weston_output_enable() unless the output was already enabled.

Parameters

• output – The output to attach to.

• head – The head that is not yet attached.

Returns

0 on success, -1 on failure.

void weston_output_move(struct weston_output *output, int x, int y)

void weston_output_transform_coordinate(struct weston_output *output, double device_x, double device_y, double *x, double *y)

Transform device coordinates into global coordinates.

Transforms coordinates from the device coordinate space (physical pixel units) to the global coordinate space (logical pixel units). This takes into account output transform and scale.

Parameters

• output – the weston_output object

• device_x – [in] X coordinate in device units.

• device_y – [in] Y coordinate in device units.

• x – [out] X coordinate in the global space.

• y – [out] Y coordinate in the global space.

void weston_output_set_scale(struct weston_output *output, int32_t scale)

Sets the output scale for a given output.

It only supports setting scale for an output that is not enabled and it can only be ran once.

Parameters

• output – The weston_output object that the scale is set for.

• scale – Scale factor for the given output.

void weston_output_set_transform(struct weston_output *output, uint32_t transform)

Sets the output transform for a given output.

Refer to wl_output::transform section located at Appendix A. Wayland Protocol Specification for list of values that can be passed to this function.

Parameters

• output – The weston_output object that the transform is set for.

• transform – Transform value for the given output.

bool weston_output_set_color_profile(struct weston_output *output, struct weston_color_profile *cprof)

Set output’s color profile.

Calling this function changes the color profile of the output. This causes all existing weston_color_transform objects related to this output via paint nodes to be unreferenced and later re-created on demand.

This function may not be called from within weston_output_repaint().

On failure, nothing is changed.

Parameters

• output – The output to change.

• cprof – The color profile to set. Can be NULL for default sRGB profile.

Returns

True on success, or false on failure.

void weston_output_init(struct weston_output *output, struct weston_compositor *compositor, const char *name)

Initializes a weston_output object with enough data so an output can be configured.

Sets initial values for fields that are expected to be configured either by compositors or backends.

The name is used in logs, and can be used by compositors as a configuration identifier.

Parameters

• output – The weston_output object to initialize

• compositor – The compositor instance.

• name – Name for the output (the string is copied).

static char *weston_output_create_heads_string(struct weston_output *output)

Create a string with the attached heads’ names.

The string must be free()’d.

int weston_output_enable(struct weston_output *output)

Constructs a weston_output object that can be used by the compositor.

Output coordinates are calculated and each new output is by default assigned to the right of previous one.

Sets up the transformation, zoom, and geometry of the output using the properties that need to be configured by the compositor.

Establishes a repaint timer for the output with the relevant display object’s event loop. See output_repaint_timer_handler().

The output is assigned an ID. Weston can support up to 32 distinct outputs, with IDs numbered from 0-31; the compositor’s output_id_pool is referred to and used to find the first available ID number, and then this ID is marked as used in output_id_pool.

The output is also assigned a Wayland global with the wl_output external interface.

Backend specific function is called to set up the output output.

Output is added to the compositor’s output list

If the backend specific function fails, the weston_output object is returned to a state it was before calling this function and is added to the compositor’s pending_output_list in case it needs to be reconfigured or just so it can be destroyed at shutdown.

0 is returned on success, -1 on failure.

Parameters

output – The weston_output object that needs to be enabled. Must not be enabled already. Must have at least one head attached.

void weston_output_disable(struct weston_output *output)

Converts a weston_output object to a pending output state, so it can be configured again or destroyed.

Calls a backend specific function to disable an output, in case such function exists.

The backend specific disable function may choose to postpone the disabling by returning a negative value, in which case this function returns early. In that case the backend will guarantee the output will be disabled soon by the backend calling this function again. One must not attempt to re-enable the output until that happens.

Otherwise, if the output is being used by the compositor, it is removed from weston’s output_list (see weston_compositor_remove_output()) and is returned to a state it was before weston_output_enable() was ran (see weston_output_enable_undo()).

See weston_output_init() for more information on the state output is returned to.

If the output has never been enabled yet, this function can still be called to ensure that the output is actually turned off rather than left in the state it was discovered in.

Parameters

output – The weston_output object that needs to be disabled.

void weston_output_add_destroy_listener(struct weston_output *output, struct wl_listener *listener)

Add destroy callback for an output.

The listener callback will be called when user destroys an output. This may be delayed by a backend in some cases. The main purpose of the listener is to allow hooking up custom data to the output. The custom data can be fetched via weston_output_get_destroy_listener() followed by container_of().

The data argument to the notify callback is the weston_output being destroyed.

Note

This is for the final destruction of an output, not when it gets disabled. If you want to keep track of enabled outputs, this is not it.

Parameters

• output – The output to watch.

• listener – The listener to add. The notify member must be set.

struct wl_listener *weston_output_get_destroy_listener(struct weston_output *output, wl_notify_func_t notify)

Look up destroy listener for an output.

This looks up the previously added destroy listener struct based on the notify function it has. The listener can be used to access user data through container_of().

See

wl_signal_get() weston_output_add_destroy_listener()

Parameters

• output – The output to query.

• notify – The notify function used used for the added destroy listener.

Returns

The listener, or NULL if not found.

void weston_output_release(struct weston_output *output)

Uninitialize an output.

Removes the output from the list of enabled outputs if necessary, but does not call the backend’s output disable function. The output will no longer be in the list of pending outputs either.

All fields of weston_output become uninitialized, i.e. should not be used anymore. The caller can free the memory after this.

void weston_output_destroy(struct weston_output *output)

Destroy an output.

The heads attached to the given output are detached and become unused again.

It is not necessary to explicitly destroy all outputs at compositor exit. weston_compositor_destroy() will automatically destroy any remaining outputs.

Parameters

output – The output to destroy.

struct weston_head *weston_output_get_first_head(struct weston_output *output)

When you need a head…

This function is a hack, used until all code has been converted to become multi-head aware.

Parameters

output – The weston_output whose head to get.

Returns

The first head in the output’s list.

struct weston_output

#include <libweston.h>

Content producer for heads.

See Outputs.

Public Types

enum [anonymous]

State of the repaint loop.

Values:

enumerator REPAINT_NOT_SCHEDULED

idle; no repaint will occur

enumerator REPAINT_BEGIN_FROM_IDLE

start_repaint_loop scheduled

enumerator REPAINT_SCHEDULED

repaint is scheduled to occur

enumerator REPAINT_AWAITING_COMPLETION

last repaint not yet finished

Public Members

uint32_t id

char *name

struct wl_signal user_destroy_signal

Matches the lifetime from the user perspective.

void *renderer_state

struct wl_list link

struct weston_compositor *compositor

struct wl_list paint_node_list

struct weston_matrix matrix

From global to output buffer coordinates.

struct weston_matrix inverse_matrix

From output buffer to global coordinates.

struct wl_list animation_list

int32_t x

int32_t y

int32_t width

int32_t height

struct wl_list paint_node_z_order_list

List of paint nodes in z-order, from top to bottom, maybe pruned.

struct weston_paint_node::z_order_link

pixman_region32_t region

Output area in global coordinates, simple rect.

bool repaint_needed

True if damage has occurred since the last repaint for this output; if set, a repaint will eventually occur.

bool repainted

Used only between repaint_begin and repaint_cancel.

enum weston_output::[anonymous] repaint_status

State of the repaint loop.

struct timespec next_repaint

If repaint_status is REPAINT_SCHEDULED, contains the time the next repaint should be run.

struct wl_event_source *idle_repaint_source

For cancelling the idle_repaint callback on output destruction.

struct weston_output_zoom zoom

int dirty

struct wl_signal frame_signal

struct wl_signal destroy_signal

sent when disabled

int move_x

int move_y

struct timespec frame_time

uint64_t msc

int disable_planes

int destroying

struct wl_list feedback_list

uint32_t transform

int32_t native_scale

int32_t current_scale

int32_t original_scale

struct weston_mode *native_mode

struct weston_mode *current_mode

struct weston_mode *original_mode

struct wl_list mode_list

struct wl_list head_list

List of driven weston_heads.

enum weston_hdcp_protection desired_protection

enum weston_hdcp_protection current_protection

bool allow_protection

int (*start_repaint_loop)(struct weston_output *output)

int (*repaint)(struct weston_output *output, pixman_region32_t *damage, void *repaint_data)

void (*destroy)(struct weston_output *output)

void (*assign_planes)(struct weston_output *output, void *repaint_data)

int (*switch_mode)(struct weston_output *output, struct weston_mode *mode)

int32_t backlight_current

void (*set_backlight)(struct weston_output *output, uint32_t value)

void (*set_dpms)(struct weston_output *output, enum dpms_enum level)

uint16_t gamma_size

void (*set_gamma)(struct weston_output *output, uint16_t size, uint16_t *r, uint16_t *g, uint16_t *b)

bool enabled

is in the output_list, not pending list

int scale

struct weston_color_profile *color_profile

struct weston_color_transform *from_sRGB_to_output

struct weston_color_transform *from_sRGB_to_blend

struct weston_color_transform *from_blend_to_output

bool from_blend_to_output_by_

以上是关于四，libweston输出管理的主要内容，如果未能解决你的问题，请参考以下文章

三，libweston合成器API

SpringCloud系列四：Eureka 服务发现框架（定义 Eureka 服务端Eureka 服务信息Eureka 发现管理Eureka 安全配置Eureka-HA(高可用) 机制Eur(代码片段

php Yoast SEO规范输出的代码片段

php Yoast SEO规范输出的代码片段

使用 Git 来管理 Xcode 中的代码片段

massCode 一款优秀的开源代码片段管理器