Product SiteDocumentation Site

A.19. wl_output - compositor output region

An output describes part of the compositor geometry. The compositor works in the 'compositor coordinate system' and an output corresponds to rectangular area in that space that is actually visible. This typically corresponds to a monitor that displays part of the compositor space. This object is published as global during start up, or when a monitor is hotplugged.

A.19.1. Events provided by wl_output

A.19.1.1. wl_output::geometry - properties of the output

The geometry event describes geometric properties of the output. The event is sent when binding to the output object and whenever any of the properties change.

wl_output::geometry arguments

x
Type: int
x position within the global compositor space
y
Type: int
y position within the global compositor space
physical_width
Type: int
width in millimeters of the output
physical_height
Type: int
height in millimeters of the output
subpixel
Type: int
subpixel orientation of the output
make
Type: string
textual description of the manufacturer
model
Type: string
textual description of the model
transform
Type: int
transform that maps framebuffer to output

A.19.1.2. wl_output::mode - advertise available modes for the output

The mode event describes an available mode for the output.
The event is sent when binding to the output object and there will always be one mode, the current mode. The event is sent again if an output changes mode, for the mode that is now current. In other words, the current mode is always the last mode that was received with the current flag set.
The size of a mode 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, as described in wl_output.scale, or transformed , as described in wl_output.transform.

wl_output::mode arguments

flags
Type: uint
bitfield of mode flags
width
Type: int
width of the mode in hardware units
height
Type: int
height of the mode in hardware units
refresh
Type: int
vertical refresh rate in mHz

A.19.1.3. wl_output::done - sent all information about output

This event is sent after all other properties has been sent after binding to the output object and after any other property changes done after that. This allows changes to the output properties to be seen as atomic, even if they happen via multiple events.

A.19.1.4. wl_output::scale - output scaling properties

This event contains scaling geometry information that is not in the geometry event. It may be sent after binding the output object or if the output scale changes later. If it is not sent, the client should assume a scale of 1.
A scale larger than 1 means that the compositor will automatically scale surface buffers by this amount when rendering. This is used for very high resolution displays where applications rendering at the native resolution would be too small to be legible.
It is intended that scaling aware clients track the current output of a surface, and if it is on a scaled output it should use wl_surface.set_buffer_scale with the scale of the output. That way the compositor can avoid scaling the surface, and the client can supply a higher detail image.

wl_output::scale arguments

factor
Type: int
scaling factor of output

A.19.2. Enums provided by wl_output

A.19.2.1. wl_output::subpixel - subpixel geometry information

This enumeration describes how the physical pixels on an output are layed out.

wl_output::subpixel values

unknown
Value: 0
none
Value: 1
horizontal_rgb
Value: 2
horizontal_bgr
Value: 3
vertical_rgb
Value: 4
vertical_bgr
Value: 5

A.19.2.2. wl_output::transform - transform from framebuffer to output

This describes the transform that a compositor will apply to a surface to compensate for the rotation or mirroring of an output device.
The flipped values correspond to an initial flip around a vertical axis followed by rotation.
The purpose is mainly to allow clients render accordingly and tell the compositor, so that for fullscreen surfaces, the compositor will still be able to scan out directly from client surfaces.

wl_output::transform values

normal
Value: 0
90
Value: 1
180
Value: 2
270
Value: 3
flipped
Value: 4
flipped_90
Value: 5
flipped_180
Value: 6
flipped_270
Value: 7

A.19.2.3. wl_output::mode - mode information

These flags describe properties of an output mode. They are used in the flags bitfield of the mode event.

wl_output::mode values

current
Value: 0x1
indicates this is the current mode
preferred
Value: 0x2
indicates this is the preferred mode