wlr_output_management_unstable_v1

• # zwlr_output_manager_v1

  This interface is a manager that allows reading and writing the current output device configuration. Output devices that display pixels (e.g. a physical monitor or a virtual output in a window) are represented as heads. Heads cannot be created nor destroyed by the client, but they can be enabled or disabled and their properties can be changed. Each head may have one or more available modes. Whenever a head appears (e.g. a monitor is plugged in), it will be advertised via the head event. Immediately after the output manager is bound, all current heads are advertised. Whenever a head's properties change, the relevant wlr_output_head events will be sent. Not all head properties will be sent: only properties that have changed need to. Whenever a head disappears (e.g. a monitor is unplugged), a wlr_output_head.finished event will be sent. After one or more heads appear, change or disappear, the done event will be sent. It carries a serial which can be used in a create_configuration request to update heads properties. The information obtained from this protocol should only be used for output configuration purposes. This protocol is not designed to be a generic output property advertisement protocol for regular clients. Instead, protocols such as xdg-output should be used.

  Requests

  • #

    create_configuration

    create a new output configuration object
    struct zwlr_output_configuration_v1* zwlr_output_manager_v1_create_configuration(

    struct zwlr_output_manager_v1* zwlr_output_manager_v1,

    uint32_t serial

    )
    Create a new output configuration object. This allows to update head properties.
  • #

    stop

    stop sending events
    void zwlr_output_manager_v1_stop(

    struct zwlr_output_manager_v1* zwlr_output_manager_v1

    )
    Indicates the client no longer wishes to receive events for output configuration changes. However the compositor may emit further events, until the finished event is emitted. The client must not send any more requests after this one.

  Events

  • #

    head

    introduce a new head
    struct zwlr_output_head_v1* head
    This event introduces a new head. This happens whenever a new head appears (e.g. a monitor is plugged in) or after the output manager is bound.
  • #

    done

    sent all information about current configuration
    uint32_t serial /* current configuration serial */
    This event is sent after all information has been sent after binding to the output manager object and after any subsequent changes. This applies to child head and mode objects as well. In other words, this event is sent whenever a head or mode is created or destroyed and whenever one of their properties has been changed. Not all state is re-sent each time the current configuration changes: only the actual changes are sent. This allows changes to the output configuration to be seen as atomic, even if they happen via multiple events. A serial is sent to be used in a future create_configuration request.
  • #

    finished

    the compositor has finished with the manager
    This event indicates that the compositor is done sending manager events. The compositor will destroy the object immediately after sending this event, so it will become invalid and the client should release any resources associated with it.

• # zwlr_output_head_v1

  A head is an output device. The difference between a wl_output object and a head is that heads are advertised even if they are turned off. A head object only advertises properties and cannot be used directly to change them. A head has some read-only properties: modes, name, description and physical_size. These cannot be changed by clients. Other properties can be updated via a wlr_output_configuration object. Properties sent via this interface are applied atomically via the wlr_output_manager.done event. No guarantees are made regarding the order in which properties are sent.

  Events

  • #

    name

    head name
    const char* name
    This event describes the head name. The naming convention is compositor defined, but limited to alphanumeric characters and dashes (-). Each name is unique among all wlr_output_head objects, but if a wlr_output_head object is destroyed the same name may be reused later. The names will also remain consistent across sessions with the same hardware and software configuration. Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do not assume that the name is a reflection of an underlying DRM connector, X11 connection, etc. If the compositor implements the xdg-output protocol and this head is enabled, the xdg_output.name event must report the same name. The name event is sent after a wlr_output_head object is created. This event is only sent once per object, and the name does not change over the lifetime of the wlr_output_head object.
  • #

    description

    head description
    const char* description
    This event describes a human-readable description of the head. The description is a UTF-8 string with no convention defined for its contents. Examples might include 'Foocorp 11" Display' or 'Virtual X11 output via :1'. However, do not assume that the name is a reflection of the make, model, serial of the underlying DRM connector or the display name of the underlying X11 connection, etc. If the compositor implements xdg-output and this head is enabled, the xdg_output.description must report the same description. The description event is sent after a wlr_output_head object is created. This event is only sent once per object, and the description does not change over the lifetime of the wlr_output_head object.
  • #

    physical_size

    head physical size
    int32_t width /* width in millimeters of the output */
    int32_t height /* height in millimeters of the output */
    This event describes the physical size of the head. This event is only sent if the head has a physical size (e.g. is not a projector or a virtual device).
  • #

    mode

    introduce a mode
    struct zwlr_output_mode_v1* mode
    This event introduces a mode for this head. It is sent once per supported mode.
  • #

    enabled

    head is enabled or disabled
    int32_t enabled /* zero if disabled, non-zero if enabled */
    This event describes whether the head is enabled. A disabled head is not mapped to a region of the global compositor space. When a head is disabled, some properties (current_mode, position, transform and scale) are irrelevant.
  • #

    current_mode

    current mode
    struct zwlr_output_mode_v1* mode
    This event describes the mode currently in use for this head. It is only sent if the output is enabled.
  • #

    position

    current position
    int32_t x /* x position within the global compositor space */
    int32_t y /* y position within the global compositor space */
    This events describes the position of the head in the global compositor space. It is only sent if the output is enabled.
  • #

    transform

    current transformation
    int32_t transform
    This event describes the transformation currently applied to the head. It is only sent if the output is enabled.
  • #

    scale

    current scale
    wl_fixed_t scale
    This events describes the scale of the head in the global compositor space. It is only sent if the output is enabled.
  • #

    finished

    the head has been destroyed
    The compositor will destroy the object immediately after sending this event, so it will become invalid and the client should release any resources associated with it.
  • #

    make

    head manufacturer
    const char* make
    This event describes the manufacturer of the head. This must report the same make as the wl_output interface does in its geometry event. Together with the model and serial_number events the purpose is to allow clients to recognize heads from previous sessions and for example load head-specific configurations back. It is not guaranteed this event will be ever sent. A reason for that can be that the compositor does not have information about the make of the head or the definition of a make is not sensible in the current setup, for example in a virtual session. Clients can still try to identify the head by available information from other events but should be aware that there is an increased risk of false positives. It is not recommended to display the make string in UI to users. For that the string provided by the description event should be preferred.
  • #

    model

    head model
    const char* model
    This event describes the model of the head. This must report the same model as the wl_output interface does in its geometry event. Together with the make and serial_number events the purpose is to allow clients to recognize heads from previous sessions and for example load head-specific configurations back. It is not guaranteed this event will be ever sent. A reason for that can be that the compositor does not have information about the model of the head or the definition of a model is not sensible in the current setup, for example in a virtual session. Clients can still try to identify the head by available information from other events but should be aware that there is an increased risk of false positives. It is not recommended to display the model string in UI to users. For that the string provided by the description event should be preferred.
  • #

    serial_number

    head serial number
    const char* serial_number
    This event describes the serial number of the head. Together with the make and model events the purpose is to allow clients to recognize heads from previous sessions and for example load head- specific configurations back. It is not guaranteed this event will be ever sent. A reason for that can be that the compositor does not have information about the serial number of the head or the definition of a serial number is not sensible in the current setup. Clients can still try to identify the head by available information from other events but should be aware that there is an increased risk of false positives. It is not recommended to display the serial_number string in UI to users. For that the string provided by the description event should be preferred.

• # zwlr_output_mode_v1

  This object describes an output mode. Some heads don't support output modes, in which case modes won't be advertised. Properties sent via this interface are applied atomically via the wlr_output_manager.done event. No guarantees are made regarding the order in which properties are sent.

  Events

  • #

    size

    mode size
    int32_t width /* width of the mode in hardware units */
    int32_t height /* height of the mode in hardware units */
    This event describes the mode size. The size is given in physical hardware units of the output device. This is not necessarily the same as the output size in the global compositor space. For instance, the output may be scaled or transformed.
  • #

    refresh

    mode refresh rate
    int32_t refresh /* vertical refresh rate in mHz */
    This event describes the mode's fixed vertical refresh rate. It is only sent if the mode has a fixed refresh rate.
  • #

    preferred

    mode is preferred
    This event advertises this mode as preferred.
  • #

    finished

    the mode has been destroyed
    The compositor will destroy the object immediately after sending this event, so it will become invalid and the client should release any resources associated with it.

• # zwlr_output_configuration_v1

  This object is used by the client to describe a full output configuration. First, the client needs to setup the output configuration. Each head can be either enabled (and configured) or disabled. It is a protocol error to send two enable_head or disable_head requests with the same head. It is a protocol error to omit a head in a configuration. Then, the client can apply or test the configuration. The compositor will then reply with a succeeded, failed or cancelled event. Finally the client should destroy the configuration object.

  Requests

  • #

    enable_head

    enable and configure a head
    struct zwlr_output_configuration_head_v1* zwlr_output_configuration_v1_enable_head(

    struct zwlr_output_configuration_v1* zwlr_output_configuration_v1,

    struct zwlr_output_head_v1* head /* the head to be enabled */

    )
    Enable a head. This request creates a head configuration object that can be used to change the head's properties.
  • #

    disable_head

    disable a head
    void zwlr_output_configuration_v1_disable_head(

    struct zwlr_output_configuration_v1* zwlr_output_configuration_v1,

    struct zwlr_output_head_v1* head /* the head to be disabled */

    )
    Disable a head.
  • #

    apply

    apply the configuration
    void zwlr_output_configuration_v1_apply(

    struct zwlr_output_configuration_v1* zwlr_output_configuration_v1

    )
    Apply the new output configuration. In case the configuration is successfully applied, there is no guarantee that the new output state matches completely the requested configuration. For instance, a compositor might round the scale if it doesn't support fractional scaling. After this request has been sent, the compositor must respond with an succeeded, failed or cancelled event. Sending a request that isn't the destructor is a protocol error.
  • #

    test

    test the configuration
    void zwlr_output_configuration_v1_test(

    struct zwlr_output_configuration_v1* zwlr_output_configuration_v1

    )
    Test the new output configuration. The configuration won't be applied, but will only be validated. Even if the compositor succeeds to test a configuration, applying it may fail. After this request has been sent, the compositor must respond with an succeeded, failed or cancelled event. Sending a request that isn't the destructor is a protocol error.
  • #

    destroy

    destroy the output configuration
    void zwlr_output_configuration_v1_destroy(

    struct zwlr_output_configuration_v1* zwlr_output_configuration_v1

    )
    Using this request a client can tell the compositor that it is not going to use the configuration object anymore. Any changes to the outputs that have not been applied will be discarded. This request also destroys wlr_output_configuration_head objects created via this object.

  Events

  • #

    succeeded

    configuration changes succeeded
    Sent after the compositor has successfully applied the changes or tested them. Upon receiving this event, the client should destroy this object. If the current configuration has changed, events to describe the changes will be sent followed by a wlr_output_manager.done event.
  • #

    failed

    configuration changes failed
    Sent if the compositor rejects the changes or failed to apply them. The compositor should revert any changes made by the apply request that triggered this event. Upon receiving this event, the client should destroy this object.
  • #

    cancelled

    configuration has been cancelled
    Sent if the compositor cancels the configuration because the state of an output changed and the client has outdated information (e.g. after an output has been hotplugged). The client can create a new configuration with a newer serial and try again. Upon receiving this event, the client should destroy this object.

  Enums

  • #

    error
    ZWLR_OUTPUT_CONFIGURATION_V1_ERROR_ALREADY_CONFIGURED_HEAD /* head has been configured twice */
    ZWLR_OUTPUT_CONFIGURATION_V1_ERROR_UNCONFIGURED_HEAD /* head has not been configured */
    ZWLR_OUTPUT_CONFIGURATION_V1_ERROR_ALREADY_USED /* request sent after configuration has been applied or tested */

• # zwlr_output_configuration_head_v1

  This object is used by the client to update a single head's configuration. It is a protocol error to set the same property twice.

  Requests

  • #

    set_mode

    set the mode
    void zwlr_output_configuration_head_v1_set_mode(

    struct zwlr_output_configuration_head_v1* zwlr_output_configuration_head_v1,

    struct zwlr_output_mode_v1* mode

    )
    This request sets the head's mode.
  • #

    set_custom_mode

    set a custom mode
    void zwlr_output_configuration_head_v1_set_custom_mode(

    struct zwlr_output_configuration_head_v1* zwlr_output_configuration_head_v1,

    int32_t width, /* width of the mode in hardware units */

    int32_t height, /* height of the mode in hardware units */

    int32_t refresh /* vertical refresh rate in mHz or zero */

    )
    This request assigns a custom mode to the head. The size is given in physical hardware units of the output device. If set to zero, the refresh rate is unspecified. It is a protocol error to set both a mode and a custom mode.
  • #

    set_position

    set the position
    void zwlr_output_configuration_head_v1_set_position(

    struct zwlr_output_configuration_head_v1* zwlr_output_configuration_head_v1,

    int32_t x, /* x position in the global compositor space */

    int32_t y /* y position in the global compositor space */

    )
    This request sets the head's position in the global compositor space.
  • #

    set_transform

    set the transform
    void zwlr_output_configuration_head_v1_set_transform(

    struct zwlr_output_configuration_head_v1* zwlr_output_configuration_head_v1,

    int32_t transform

    )
    This request sets the head's transform.
  • #

    set_scale

    set the scale
    void zwlr_output_configuration_head_v1_set_scale(

    struct zwlr_output_configuration_head_v1* zwlr_output_configuration_head_v1,

    wl_fixed_t scale

    )
    This request sets the head's scale.

  Enums

  • #

    error
    ZWLR_OUTPUT_CONFIGURATION_HEAD_V1_ERROR_ALREADY_SET /* property has already been set */
    ZWLR_OUTPUT_CONFIGURATION_HEAD_V1_ERROR_INVALID_MODE /* mode doesn't belong to head */
    ZWLR_OUTPUT_CONFIGURATION_HEAD_V1_ERROR_INVALID_CUSTOM_MODE /* mode is invalid */
    ZWLR_OUTPUT_CONFIGURATION_HEAD_V1_ERROR_INVALID_TRANSFORM /* transform value outside enum */
    ZWLR_OUTPUT_CONFIGURATION_HEAD_V1_ERROR_INVALID_SCALE /* scale negative or zero */

Copyright Info