Skip to main content
Version: 2.1

output somewm-only

An output represents a connected monitor or a nested/headless display. It persists across disable/enable cycles until the output is removed. Its screen exists only while enabled.

Output vs Screen​

outputscreen
RepresentsPhysical connector (HDMI-A-1, DP-2, eDP-1)Logical display area
LifecyclePlug to unplugEnable to disable
Persists across disable/enableYesNo (destroyed and recreated)
Use forHardware identification, display configurationTags, clients, wibars

A single output can have zero or one screen. When the output is enabled, output.screen points to the active screen. When disabled, output.screen is nil but the output object remains valid.

Accessing Outputs​

-- Get output by index (1-based)
local o = output[1]

-- Get output by connector name
local o = output.get_by_name("HDMI-A-1")

-- Total output count (enabled + disabled)
local count = output.count()

-- Iterate all outputs
for o in output do
print(o.name, o.enabled)
end

-- From a screen
local o = screen.primary.output

Properties​

Hardware Identification​

PropertyTypeAccessDescription
namestringreadConnector name (e.g., "HDMI-A-1", "eDP-1")
descriptionstring/nilreadHuman-readable description from EDID
makestring/nilreadManufacturer name from EDID
modelstring/nilreadModel name from EDID
serialstring/nilreadSerial number from EDID
physical_widthnumberreadPhysical width in millimeters
physical_heightnumberreadPhysical height in millimeters
local o = output[1]
print(o.name) -- "HDMI-A-1"
print(o.make) -- "Dell" or nil
print(o.model) -- "U2723QE" or nil
print(o.serial) -- "ABC1234" or nil
print(o.physical_width) -- 597 (mm)

Display State​

PropertyTypeAccessDescription
enabledbooleanread/writeWhether the output is active
scalenumberread/writeOutput scale factor (0.1 to 10.0)
transformnumber/stringread/writeRotation/flip (see values below)
modetablewriteSet {width, height, refresh?}. Refresh is in millihertz. Read current_mode to inspect it
positiontableread/writeLayout position {x, y}
adaptive_syncbooleanread/writeVariable refresh rate (VRR/FreeSync)
local o = output[1]
o.scale = 1.5

Mode, transform, and adaptive-sync changes depend on backend and monitor support. A failed commit raises a Lua error.

Transform Values​

The transform property accepts both integers (Wayland protocol values) and strings:

IntegerStringEffect
0"normal"No transformation
1"90"90 degrees counter-clockwise
2"180"180 degrees
3"270"270 degrees counter-clockwise
4"flipped"Horizontal flip
5"flipped-90"Flip + 90 degrees
6"flipped-180"Flip + 180 degrees
7"flipped-270"Flip + 270 degrees

Reading transform always returns an integer. Setting it accepts either form.

Mode Information​

PropertyTypeAccessDescription
modestablereadAll supported modes
current_modetable/nilreadActive advertised mode. Nil if disabled or using a custom mode, including many nested/headless outputs

Each mode is {width, height, refresh, preferred}. Width and height are physical pixels. Refresh is millihertz, so 60000 means 60 Hz. Setting a mode requires a listed resolution. An omitted or zero refresh selects the first matching resolution, otherwise the closest listed refresh is used.

-- List all supported modes
for _, m in ipairs(o.modes) do
local flag = m.preferred and " (preferred)" or ""
print(m.width .. "x" .. m.height .. "@" .. m.refresh .. flag)
end

-- Current active mode
local m = o.current_mode
if m then
print("Running at " .. m.width .. "x" .. m.height)
end

Object References​

PropertyTypeAccessDescription
screenscreen/nilreadAssociated screen (nil when disabled)
validbooleanreadFalse after physical disconnect
virtualbooleanreadTrue for headless or nested outputs
-- Navigate from output to screen and back
local o = output[1]
local s = o.screen -- the screen for this output
if s then assert(s.output == o) end

After removal, only o.valid remains readable. Other property access raises invalid object.

Methods​

Class Methods​

-- Count all connected outputs (enabled + disabled)
output.count()

-- Find output by connector name
output.get_by_name("HDMI-A-1") -- returns output or nil

-- Numeric indexing
local first = output[1]
local second = output(2)

-- Iterate
for o in output do print(o.name) end

Instance Methods​

-- Connect to instance signals
local handler = function(o) print(o.scale) end
o:connect_signal("property::scale", handler)
o:disconnect_signal("property::scale", handler)
o:emit_signal("my-custom-signal")

Signals​

Class Signals​

SignalArgumentsDescription
addedoOutput connected, after initial screen setup. o.screen is nil if disabled
removedoOutput disconnected. Fires while output is still valid (properties readable).

Instance Signals​

SignalArgumentsDescription
property::enabledoOutput enabled or disabled
property::scaleoScale factor changed
property::transformoRotation/flip changed
property::modeoResolution changed
property::positionoLayout position changed
property::adaptive_syncoVRR toggled
property::screenoScreen link changed (nil to screen, or screen to nil)

Compositor and external output-management changes queue property signals. Lua setters generally deliver them inline. See signal dispatch for exceptions.

Output-management changes made by tools such as wlr-randr also emit property signals. Connecting a class added handler immediately calls it for existing outputs as well as future ones.

Common Patterns​

Per-Output Configuration​

See Multi-monitor setup for connector-specific scale, position, tags, and wibars. request::desktop_decoration can run before output.added, so tag creation must not depend on data first populated in added.

Identify Monitor Hardware​

for o in output do
print(o.name, o.make, o.model, o.serial)
end

React to External Tool Changes​

output[1]:connect_signal("property::scale", function(o)
print(o.name, o.scale)
end)

Detect Hotplug​

output.connect_signal("added", function(o)
print("Available:", o.name, o.screen and o.screen.index)
end)

output.connect_signal("removed", function(o)
print("Removed:", o.name)
end)
output[1]:connect_signal("property::screen", function(o)
print(o.name, o.screen and o.screen.index)
end)

See Also​