video_displaymodes(3)

okay so bestie, this is the video_displaymodes glow-up from the Arcan Lua API — manual page video_displaymodes(3) — and it’s giving “tiny function, huge display energy.” 💖 The vibe: retrieve (or set) platform-specific output display options. No cap.

🌸 NAME 🌸

video_displaymodes — retrieve (or set) platform-specific output display options. 💅

✨ SYNOPSIS ✨

modelist or nil or bool
video_displaymodes( int:id )
video_displaymodes( int:id, int:modeid )
video_displaymodes( int:id, int:modeid, tbl:modeopts )
video_displaymodes( int:id, int:width, int:height )

🦋 DESCRIPTION 🦋

Some video platforms let the user dynamically change how output is being mapped. This is necessary for multiple- display support and for changing video configuration and behavior when a user hotplugs a display. 🫶

There are four ways to use this function. Bestie, let’s break them down:

• no arguments at all — the underlying video platform gets asked to do a rescan of devices and connectors. This can stall graphics for noticable (100ms+) periods of time on some systems, but it’s necessary where we don’t have working hotplug support. It’s also an asynchronous process, and any results will be propagated as _display_state events. ⏳
• display index — returns a table of possible modes.
• display index + a modeid obtained from a previous table from video_displaymodes — attempts to switch the display to that mode, and returns success or not as a boolean.
• display index + width + height on a display that supports dynamic (caller-defined) modes — tries to force that specific dynamic mode, and returns success or not as a boolean.

The mode switch can be further hinted by providing a modeopts table. The valid keys for this table are:

• *modeopts:number:vrr* — sets the refresh rate target (Hz), or a <= 0 value for letting the platform dynamically decide.
• *modeopts:int:quality* — sets the mode scanout quality. This overrides the behaviour for WORLDID and directly composited output only. If another rendertarget has been set as the direct output through map_video_display, then the properties of the rendertarget store takes precendent. The permitted quality options are the same as for alloc_surface: ALLOC_QUALITY_LOW (typically RGB 565), ALLOC_QUALITY_NORMAL ( RGB 888), ALLOC_QUALITY_HIGH (R10G10B10, "deep"), ALLOC_QUALITY_FLOAT 16 ( HDR - FP 16) or ALLOC_QUALITY_FLOAT 32 ( HDR - FP 32).

🧚 NOTES 🧚

1. possible modelist table members are: cardid, displayid, phy_width_mm, phy_height_mm, subpixel_layout, dynamic, primary, modeid, width, height, refresh, depth

💀 EXAMPLE 💀

the page’s example, in all its iconic glory:

       function video_displaymodes0()
             local list = video_displaymodes(0);
             if (#list == 0) then
                   return shutdown("video platform did not expose any modes.");
             end
             for i,v in ipairs(list) do
                   print(string.format("(%d) display(%d:%d)" ..
                         "dimensions(%d * %d) @ %d Hz, depth: %d0,
                         v.modeid, v.cardid, v.displayid, v.width,
                         v.height, v.refresh, v.depth)
                   );
             end
             print("swiching modes0);
             video_displaymodes(0, list[math.random(#list)].modeid);
             print("modes switched0);
       end

🙈 MISUSE 🙈

and here’s the misuse section, because the page said so:

       function video_displaymodes0()
             video_displaymodes("not acceptable");
       end

👀 SEE ALSO: 👀

vidsys — that’s the ref, bestie. Go look. 👑

---

later, bestie! this was video_displaymodes(3) from the vidsys source/version, dated October 2026 — mwah 💅✨