Module xrandr

Lua bindings for libxrandr.

Documentation here will extend the official library’s documentation, not replace it. Please take a look at the libxrandr documentation before use, especially the protocol specification and Xrandr.h. Additionally, libxrandr provides man pages locally (packaging depends on the distribution).

Table of contents

Functions

XRRQueryVersion(display) Queries the maximum supported extension version from the server.
XRRQueryExtension(display) Returns the base event codes.
XRRGetScreenInfo(display, window) Queries the screen configuration.
XRRSetScreenConfig(display, config, draw, size_index, rotation, timestamp) Updates the screen configuration.
XRRSetScreenConfigAndRate(display, config, draw, size_index, rotation, rate, timestamp) Updates the screen configuration.
XRRConfigRotations(config) Gets the rotations from a screen config.
XRRConfigTimes(config) Gets the timestamps from a screen config.
XRRConfigSizes(config) Gets the list of sizes from a screen config.
XRRConfigRates(config, size_index) Gets the list or refresh rates from a screen config.
XRRConfigCurrentConfiguration(config) Gets the current size index and rotation from a screen config.
XRRConfigCurrentRate(config) Gets the current refresh rate from a screen config.
XRRGetScreenResources(display, window) Queries the current XRRScreenResources.
XRRGetOutputInfo(display, resources, output) Returns information about the given output.
XRRGetOutputPrimary(display, window) Returns the primary output for the given window.
XRRSetOutputPrimary(display, window, output) Sets the given output as primary for the window.
XRRListOutputProperties(display, output) Returns the list of properties on the given output.
XRRQueryOutputProperty(display, output, property) Returns metadata about an output property.
XRRConfigureOutputProperty(display, output, property, pending, range, values) Sets the metadata for an output property.
XRRChangeOutputProperty(display, output, property, type, mode, data) Changes the value of an output property.
XRRGetOutputProperty(display, output, property, offset, length, delete, pending[, req_type]) Returns the value of an output property.
XRRDeleteOutputProperty(display, output, property) Deletes the property from the given output.
XRRGetCrtcInfo(display, resources, crtc) Returns information about the given CRTC.
XRRSetCrtcConfig(display, resources, crtc, timestamp, x, y, mode, rotation, outputs) Sets CRTC configuration.
XRRSelectInput(display, window, mask) Configures which types of events the X server should enable.
XRRGetScreenSizeRange(display, window) Gets the range of possible screen sizes.
XRRSetScreenSize(display, window, width, height, mm_width, mm_height) Sets the screen size.

Tables

RR_OUTPUT An enum of well-known output property names.
XRRScreenConfiguration This only functions as a marker.
XRRModeFlags This table maps the bitfield to individual booleans.
XRRMode Contrary to the other types in this module, this is provided as an actual Lua table, rather than userdata.
XRRScreenResources
XRROutputInfo
XRRPropertyInfo If pending == true, changes to the property via XRRChangeOutputProperty will be queued until the next call to XRRSetCrtcConfig.
XRRCrtcInfo

Functions

XRRQueryVersion(display)
Queries the maximum supported extension version from the server.

The return values of the major and minor extension version are only defined when the status value is 1. In all other cases, using the version numbers is considered undefined behaviour.

Parameters:

Returns:

  • The request status.
    type number
  • The major extension version.
    type number
  • The minor extension version.
    type number
XRRQueryExtension(display)
Returns the base event codes.

Parameters:

Returns:

  • type boolean
  • The event base code
    type number
  • The error base code
    type number
XRRGetScreenInfo(display, window)
Queries the screen configuration.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window
    type number

Returns:

Usage:

local display = xlib.xlib.XOpenDisplay()
local screen = xlib.DefaultScreen(display)
local root = xlib.RootWindow(display, screen)
local info = xrandr.XRRGetScreenInfo(display, root)
XRRSetScreenConfig(display, config, draw, size_index, rotation, timestamp)
Updates the screen configuration.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • config
    type XRRScreenConfiguration
  • draw
    type Drawable
  • size_index
    type integer
  • rotation
    type number
  • timestamp
    type number

Returns:

  • type number
XRRSetScreenConfigAndRate(display, config, draw, size_index, rotation, rate, timestamp)
Updates the screen configuration.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • config
    type XRRScreenConfiguration
  • draw
    type Drawable
  • size_index
    type integer
  • rotation
    type number
  • rate
    type integer
  • timestamp
    type number

Returns:

  • type number
XRRConfigRotations(config)
Gets the rotations from a screen config.

Parameters:

Returns:

  • rotations
    type number
  • current_rotation
    type number
XRRConfigTimes(config)
Gets the timestamps from a screen config.

Parameters:

Returns:

  • timestamp
    type number
  • config_timestamp
    type number
XRRConfigSizes(config)
Gets the list of sizes from a screen config.

Parameters:

Returns:

XRRConfigRates(config, size_index)
Gets the list or refresh rates from a screen config.

Parameters:

Returns:

XRRConfigCurrentConfiguration(config)
Gets the current size index and rotation from a screen config.

Parameters:

Returns:

  • Index into the return value of XRRConfigSizes
    type number
  • Current rotation
    type number
XRRConfigCurrentRate(config)
Gets the current refresh rate from a screen config.

Parameters:

Returns:

  • type number
XRRGetScreenResources(display, window)
Queries the current XRRScreenResources.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window :  The XID of the window to query.
    type number

Returns:

Usage:

local display = xlib.xlib.XOpenDisplay()
local screen = xlib.DefaultScreen(display)
local root = xlib.RootWindow(display, screen)
local res = xrandr.XRRGetScreenResources(display, root)
XRRGetOutputInfo(display, resources, output)
Returns information about the given output.

This returns a userdatum that wrapping the output info data. Table index operations are supported to retrieve the fields described in XRROutputInfo.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • resources
    type screen_resources
  • output :  The XID of the output to fetch information about.
    type number

Returns:

Usage:

local res = xrandr.XRRGetScreenResources(display, root)
for _, output in ipairs(res.outputs) do
    local info = xrandr.XRRGetOutputInfo(display, res, output)
    printf("%s %s", info.name, info.connection)
end
XRRGetOutputPrimary(display, window)
Returns the primary output for the given window.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window :  The XID of the window to query.
    type number

Returns:

  • The XID of the primary output.
    type number

Usage:

local res = xrandr.XRRGetScreenResources(display, root)
local primary = xrandr.XRRGetOutputPrimary(display, root)
for _, output in ipairs(res.outputs) do
    if output == primary then
      local info = xrandr.XRRGetOutputInfo(display, res, output)
      printf("Primary: %s", info.name)
    end
end
XRRSetOutputPrimary(display, window, output)
Sets the given output as primary for the window.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window :  The XID of the window.
    type number
  • output :  The XID of the output.
    type number
XRRListOutputProperties(display, output)
Returns the list of properties on the given output.

This returns a list of Atoms (mapped to simple integer numbers). Metadata of the property can be queried with using XRRQueryOutputProperty, values with XRRGetOutputProperty.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • output :  The XID of the output.
    type number

Returns:

  • type number
XRRQueryOutputProperty(display, output, property)
Returns metadata about an output property.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • output :  The XID of the output.
    type number
  • property :  An X11 Atom.
    type number

Returns:

XRRConfigureOutputProperty(display, output, property, pending, range, values)
Sets the metadata for an output property.

See XRRPropertyInfo for the semantics of the various metadata fields.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • output :  The XID of the output.
    type number
  • property :  An X11 Atom.
    type number
  • pending
    type boolean
  • range
    type boolean
  • values
    type table
XRRChangeOutputProperty(display, output, property, type, mode, data)
Changes the value of an output property.

The value has to match with the metadata from XRRQueryOutputProperty.

For now, only string values are supported, and they are treated as raw, unsigned byte buffers.

If “append” or “prepend” modes are chosen, the types of the existing and new values must match. For undefined properties, all three modes work the same.

The maximum allowed size of the property data depends on the server implementation, and may change dynamically at runtime or between resets. The lifetime of a property is tied to the output and server, not the client that set it.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • output :  The XID of the output.
    type number
  • property :  An X11 Atom.
    type number
  • type :  An X11 Atom.
    type number
  • mode :  If 1, prepend data. If 2, append data. Otherwise replace data.
    type number or nil
  • data
    type string
XRRGetOutputProperty(display, output, property, offset, length, delete, pending[, req_type])
Returns the value of an output property.

As with XRRChangeOutputProperty, only properties of type string (which maps to Xorg’s XA_STRING from X11/Xatom.h) are currently supported. The req_type property is just a placeholder because of that.

If there is no such property, the function will return nothing.

For properties of unknown length, first call this function with offset == 0, length == 0, and the second return value will report the full length of the value. Then call the function a second time with the desired offset and length.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • output :  The XID of the output.
    type number
  • property :  An X11 Atom.
    type number
  • offset :  The offset at which to start reading the return value.
    type number
  • length :  The amount of bytes (regardless of the element size) to read into the return value.
    type number
  • delete :  If true, delete the property after reading.
    type boolean
  • pending :  If true and there is a pending change for the property, return that change instead of the current value.
    type boolean
  • req_type :  An X11 Atom. Currently ignored and hardcoded to XLib’s XA_STRING.
    type number
    optional

Returns:

  • The data.
    type string
  • The number of elements in the value, as passed when setting the property (see XRRChangeOutputProperty).
    type number
  • The element size of the byte array as passed when setting the property. One of 8, 16, 32.
    type number
  • The number of bytes (regardless of the element size) left in the value.
    type number

Usage:

-- Check the length
local _, length = xrandr.XRRGetOutputProperty(display, output, atom, 0, 0)
local value, nitems, format = xrandr.XRRGetOutputProperty(display, output, atom, 0, length)
print(value) -- may be arbitrary, non-printable bytes. If so, use `nitems` and `format` to interpret it
XRRDeleteOutputProperty(display, output, property)
Deletes the property from the given output.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • output :  The XID of the output.
    type number
  • property :  An X11 Atom.
    type number
XRRGetCrtcInfo(display, resources, crtc)
Returns information about the given CRTC.

This returns a userdatum that wrapping the CRTC info data. Table index operations are supported to retrieve the fields described in XRRCrtcInfo.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • resources
    type screen_resources
  • crtc :  The XID of the CRTC to fetch information about.
    type number

Returns:

Usage:

local res = xrandr.XRRGetScreenResources(display, root)
local info = xrandr.XRRGetCrtcInfo(display, res, res.crtcs[1])
local mode = find_by_id(res.modes, info.mode)
require("pl.pretty").dump(mode)
XRRSetCrtcConfig(display, resources, crtc, timestamp, x, y, mode, rotation, outputs)
Sets CRTC configuration.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • resources
    type screen_resources
  • crtc :  The XID of the CRTC to change.
    type number
  • timestamp
    type number
  • x
    type number
  • y
    type number
  • mode :  The id of the XRRMode to set for this CRTC. If 0 or nil is passed, the CRTC will be disabled.
    type number or nil
  • rotation
    type number
  • outputs :  The list of output XIDs to assign to this CRTC.
    type table

Returns:

  • An X11 Status.
    type number

Usage:

local res = xrandr.XRRGetScreenResources(display, root)
local info = xrandr.XRRGetCrtcInfo(display, res, res.crtcs[1])
local mode = find_by_id(res.modes, info.mode)
local status = xrandr.XRRSetCrtcConfig(
    display,
    res,
    res.crtcs[1],
    info.timestamp,
    info.x,
    info.y,
    res.modes[2].id,
    info.rotation,
    info.outputs
)
XRRSelectInput(display, window, mask)
Configures which types of events the X server should enable.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window
    type number
  • mask
    • screen :  Configure screen change notifications.
      type boolean
    • crtc :  Configure crtc change notifications.
      type boolean
    • output :  Configure output change notifications.
      type boolean
    • output_property :  Configure output property change notifications.
      type boolean
    • provider :  Configure provider change notifications.
      type boolean
    • provider_property :  Configure provider property change notifications.
      type boolean
    • resource :  Configure resource change notifications.
      type boolean

Usage:

-- Enable notifications for CRTCs and outputs
xrandr.XRRSelectInput(display, root, { crtc = true, output = true })
XRRGetScreenSizeRange(display, window)
Gets the range of possible screen sizes.

This returns the minimum and maximum boundaries within which screen sizes may be set.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window
    type number

Returns:

  • status Despite being designated a X11 Status in Xrandr.h, this returns 1 on success.
    type number
  • min_width
    type number
  • min_height
    type number
  • max_width
    type number
  • max_height
    type number
XRRSetScreenSize(display, window, width, height, mm_width, mm_height)
Sets the screen size.

The width and height must be within the ranges returned by XRRGetScreenSizeRange.

Parameters:

  • display :  A display connection opened with xlib.XOpenDisplay.
    type display
  • window
    type number
  • width
    type number
  • height
    type number
  • mm_width :  Physical size of the screen, in millimeters.
    type number
  • mm_height :  Physical size of the screen, in millimeters.
    type number

Tables

RR_OUTPUT
An enum of well-known output property names.

Fields:

  • BACKLIGHT :  Backlight
    type string
  • RANDR_EDID :  EDID
    type string
  • SIGNAL_FORMAT :  SignalFormat
    type string
  • SIGNAL_PROPERTIES :  SignalProperties
    type string
  • CONNECTOR_TYPE :  ConnectorType
    type string
  • CONNECTOR_NUMBER :  ConnectorNumber
    type string
  • COMPATIBILITY_LIST :  CompatibilityList
    type string
  • CLONE_LIST :  CloneList
    type string
  • BORDER :  Border
    type string
  • BORDER_DIMENSIONS :  BorderDimensions
    type string
  • GUID :  GUID
    type string
  • RANDR_TILE :  TILE
    type string
  • NON_DESKTOP :  non-desktop
    type string
XRRScreenConfiguration
This only functions as a marker. Values need to be retrieved through the XRRConfig* functions, such as XRRConfigCurrentRate.
XRRModeFlags
This table maps the bitfield to individual booleans.

Fields:

  • HSyncPositive
    type boolean
  • HSyncNegative
    type boolean
  • VSyncPositive
    type boolean
  • VSyncNegative
    type boolean
  • Interlace
    type boolean
  • DoubleScan
    type boolean
  • CSync
    type boolean
  • CSyncPositive
    type boolean
  • CSyncNegative
    type boolean
  • HSkewPresent
    type boolean
  • BCast
    type boolean
  • PixelMultiplex
    type boolean
  • DoubleClock
    type boolean
  • ClockDivideBy2
    type boolean
XRRMode
Contrary to the other types in this module, this is provided as an actual Lua table, rather than userdata.

Fields:

  • id
    type number
  • name
    type number
  • width
    type number
  • height
    type number
  • dotClock
    type number
  • hSyncStart
    type number
  • hSyncEnd
    type number
  • hTotal
    type number
  • hSkew
    type number
  • vSyncStart
    type number
  • vSyncEnd
    type number
  • vTotal
    type number
  • modeFlags
    type XRRModeFlags
XRRScreenResources

Fields:

  • timestamp
    type number
  • configTimestamp
    type number
  • crtcs
    type table
  • outputs
    type table
  • modes
    type table
XRROutputInfo

Fields:

  • name
    type string
  • mm_width
    type number
  • mm_height
    type number
  • connection
    type string
  • subpixel_order
    type string
  • modes :  List of IDs. These map to the mode list in XRRScreenResources.
    type table
  • crtcs :  List of XIDs
    type table
  • crtc
    type number
XRRPropertyInfo
If pending == true, changes to the property via XRRChangeOutputProperty will be queued until the next call to XRRSetCrtcConfig.

If range == true, values will contain exactly two entries, that denote the minimum and maximum values for the property. Otherwise values is a list of valid values.

If immutable == true, the property cannot be changed by the client.

Fields:

  • pending
    type bool
  • range
    type bool
  • immutable
    type bool
  • values
    type table
XRRCrtcInfo

Fields:

  • name
    type string
  • mm_width
    type number
  • mm_height
    type number
  • connection
    type string
  • subpixel_order
    type string
  • modes
    type table