Outputs

An output is a connected display. Use outputs to read the layout, display modes, work areas and privacy screens, to follow display changes, to turn privacy screens on or off, and to read the GPU path for this session.

gnoblinctl output list prints the same records from the command line, with --json for machine-readable output.

Read outputs

local renderer = gnoblin.outputs.renderer()
if renderer and not renderer.accelerated then
    -- Avoid enabling expensive visual effects for this session.
end

for _, output in ipairs(gnoblin.outputs.list()) do
    print(output.id, output.mode.width, output.mode.height)
end

During login configuration the output list may not exist yet: list() returns an empty list, and primary(), by_id() and renderer() return nil until Gnoblin publishes the first list.

Live output objects

Like window objects, every read of one output returns the same object, updated with each change:

• output.alive turns false when the display is disconnected or removed.
• output:on(signal, fn) takes "changed" or "closed". A "changed" callback receives the output and the list of changed fields. Listening ends after "closed".
• output:watch(field, fn) calls fn(output, value, old) when a field of the Output record changes, such as scale, mode or privacy_screen.

Both return a subscription with an unsubscribe() method.

local output = gnoblin.outputs.primary()
if output then
    output:watch("scale", function(o, scale, old)
        print(o.id, "scale", old, "->", scale)
    end)
    output:on("closed", function(o)
        print(o.id, "was removed")
    end)
end

Output records

A disabled output has no monitor_id, index, position, size or work area.

monitor_id is the lowest connector name in the logical monitor. Windows and layer surfaces name the same ID in their monitor_id field, and window:move_to_monitor(id) takes it. When two outputs show one cloned logical monitor, both have the same monitor_id.

work_area has x, y, width and height in logical pixels. It is the logical monitor minus the space that panels reserve with exclusive zones, on the active workspace.

The transform values describe the output orientation:

• normal: no rotation or reflection.
• 90, 180, and 270: rotate clockwise by that amount.
• flipped: mirror the output.
• flipped-90, flipped-180, and flipped-270: mirror the output, then apply the named clockwise rotation.

Privacy screens

output.privacy_screen has these fields:

source has one of these values:

• runtime: a runtime override of monitors.privacy_screen set it.
• config: monitors.privacy_screen is set in the Lua configuration.
• system: neither a runtime override nor the configuration sets a value.

The privacy screen request is an override of monitors.privacy_screen. The value is true to turn privacy screens on for this session, or false to turn them off. Revoking the override uses the configured value, or the system preference when the configuration has none.

The compositor keeps one privacy screen request for the whole session and applies it to every output that has a privacy screen. For this reason the request belongs to the session and an Output has no set_privacy_screen method. Note these rules:

• The call raises an error when privacy_screen.available is false on every output.
• A runtime override does not change the system preference.
• A newer override of monitors.privacy_screen replaces an older one.

local privacy = gnoblin.settings.override("monitors.privacy_screen", true)

local primary = gnoblin.outputs.primary()
if primary then
    primary:watch("privacy_screen", function(output, privacy, old)
        print(output.id, "privacy screen enabled:", privacy.enabled)
    end)
end

When the state changes, each affected output raises "changed" with privacy_screen in its changed list.

Output events

changed lists the changed Output fields. The live object updates and runs its own signals and watches before gnoblin.on callbacks run.

Renderer records

Gnoblin reports accelerated = false for the software rasterizers llvmpipe, softpipe, swrast, and Software Rasterizer, and when Mutter reports software rendering. All outputs share one compositor renderer record.

Display configuration such as modes, scale and layout stays with the session display-configuration interface.