win32-displayconfig
Advanced tools
Simplified Node bindings to the Win32 Display Device Reference API.
This module has currently only received testing on Windows 10 version 2004. Additional testing on other versions of Windows 10 and Windows 8.1 would be appreciated.
We are not planning on supporting Windows 7 or Windows 8, as they are generally unsupported by Microsoft. However, patches to support Windows 7 or Windows 8 are welcome.
This module requires N-API Version 4, bounding the minimum supported Node versions to 8.16.0 (without any support for Node 9), Node 10.16.0, and Node 11.8.0. We are only actively testing on Node 10.21 and above. We'll note incompatibilities and accept patches for Node 8 if the need arises.
The queryDisplayConfig function returns data somewhat similar to the outputs of the
QueryDisplayConfig function
via the pathArray and modeInfoArray properties, and naming and manufacturer info via its
nameArray properties.
From scripts/dumpquery.js:
const w32disp = require("win32-displayconfig");
const util = require("util");
w32disp.queryDisplayConfig().then((config) => {
// The outputs of `pathArray` and `modeArray` refer to
// both parsed values and raw buffer values. The raw buffers
// are the exact structs returned by the Win32 API, and are
// used to save and restore display positioning configuration.
const pathArray = config.pathArray.map((pa) => pa.value);
const modeArray = config.modeArray.map((ma) => ma.value);
console.log(
util.inspect(
// However, the `nameArray` only refers to parsed values.
{ pathArray, modeArray, nameArray: config.nameArray },
{ depth: 10 }
)
);
});
Which outputs:
{ pathArray:
[ { flags: 1,
sourceInfo:
{ adapterId: { LowPart: 945385802, HighPart: 0 },
id: 0,
statusFlags: 1,
modeInfoIdx: 1 },
targetInfo:
{ adapterId: { LowPart: 945385802, HighPart: 0 },
id: 114948,
statusFlags: 1,
outputTechnology: 'dvi',
rotation: 0,
scaling: 'identity',
refreshRate: { Numerator: 60000, Denominator: 1000 },
scanLineOrdering: 'progressive',
targetAvailable: 1,
modeInfoIdx: 0 } },
...
],
modeArray:
[ { infoType: 'target',
id: 114948,
adapterId: { LowPart: 945385802, HighPart: 0 },
targetMode:
{ targetVideoSignalInfo:
{ pixelRate: { lowPart: 148500000, highPart: 0 },
hSyncFreq: { Numerator: 148500000, Denominator: 2200 },
vSyncFreq: { Numerator: 60000, Denominator: 1000 },
activeSize: { cx: 1920, cy: 1080 },
totalSize: { cx: 2200, cy: 1125 },
videoStandard: 255,
scanlineOrdering: 'progressive' } } },
...
],
nameArray:
[ { adapterId: { LowPart: 945385802, HighPart: 0 },
id: 114948,
deviceFlags: 5,
outputTechnology: 'dvi',
edidManufactureId: 29188,
edidProductCodeId: 147,
connectorInstance: 2,
monitorFriendlyDeviceName: 'Acer X233H',
monitorDevicePath:
'\\\\?\\DISPLAY#ACR0093#5&326e05e0&0&UID114948#{e6f07b5f-ee97-4a90-b076-33f57bf4eaa7}' },
...
] }
This is generally lower-level output than you want. Consider using extractDisplayConfig instead.
The extractDisplayConfig function reshapes the output of queryDisplayConfig to be more useful
to application programmers. Information from the pathArray, modeInfoArray, and nameArray properties
of the output of queryDisplayConfig are all joined according to their IDs.
From scripts/dumpextract.js:
const w32disp = require("win32-displayconfig");
const util = require("util");
w32disp.extractDisplayConfig().then((output) => {
console.log(util.inspect(output, { depth: 10 }));
});
Which outputs:
[ { displayName: 'Acer X233H',
devicePath:
'\\\\?\\DISPLAY#ACR0093#5&326e05e0&0&UID114948#{e6f07b5f-ee97-4a90-b076-33f57bf4eaa7}',
sourceConfigId: { adapterId: { LowPart: 945385802, HighPart: 0 }, id: 1 },
targetConfigId:
{ adapterId: { LowPart: 945385802, HighPart: 0 }, id: 114948 },
inUse: false,
outputTechnology: 'dvi',
rotation: 0,
scaling: 'preferred',
sourceMode:
{ width: 1920,
height: 1080,
pixelFormat: 32,
position: { x: 0, y: 0 } },
pathBuffer:
<Buffer ... >,
sourceModeBuffer:
<Buffer ... >,
targetVideoSignalInfo:
{ pixelRate: { lowPart: 148500000, highPart: 0 },
hSyncFreq: { Numerator: 148500000, Denominator: 2200 },
vSyncFreq: { Numerator: 60000, Denominator: 1000 },
activeSize: { cx: 1920, cy: 1080 },
totalSize: { cx: 2200, cy: 1125 },
videoStandard: 255,
scanlineOrdering: 'progressive' },
targetModeBuffer:
<Buffer ... > },
...
]
Note that the low-level buffers are still present, but sourceMode, targetVideoSignalInfo, devicePath,
and displayName have all been combined from multiple sources. Also note the inUse boolean, which is
derived from comparing against low-level flags in the Display Device Reference API.
You will likely see multiple outputs for a single display device in this output, with only one of them
having inUse: true. The inUse: false entries correspond to alternative output modes available on the device.
The display geometry can change at any time during the execution of your program, but sometimes you
depend on knowledge of this geometry for the correct behavior. You can observe changes as they
occur using the addDisplayChangeListener function:
const w32disp = require("win32-displayconfig");
const listener1 = (err, conf) => {
if (err !== null) {
// Report error
console.error(err);
} else {
// conf is the same as the output of extractDisplayConfig
// ...
}
};
w32disp.addDisplayChangeListener(listener1);
// Or equivalently
const listener2 = w32disp.addDisplayChangeListener((err, conf) => {
if (err !== null) {
console.error(err);
} else {
// ...
}
});
Adding these change listeners keeps the event loop active, even when all other
activities have been stopped, so for situations where graceful shutdown is required,
remove all of the listeners using the removeDisplayChangeListener function:
w32disp.removeDisplayChangeListener(listener1);
w32disp.removeDisplayChangeListener(listener2);
// No more display config activities are present on the event loop,
// so Node can now exit cleanly.
Some operations need to only occur as quickly as the vertical refresh rate for smooth performance. For example, many Windows positioning APIs cannot perform well if they are invoked any faster than the frame rate of the GPU.
This module provides a VerticalRefreshRateContext class to determine the
refresh rate of the displays servicing a given display point. Note that not
all displays will necessarily have the same refresh rate, and many displays
can be servicing the same display point. When multiple displays are servicing
the same display point, the result is the minimum vertical refresh rate.
const { VerticalRefreshRateContext } = require("win32-displayconfig");
const ctx = new VerticalRefreshRateContext();
async function refreshRateForPoint(x, y) {
// Here, x is the vertical offset and y is the horizontal offset.
// These offsets are relative to the upper left hand corner of the
// primary display, so they are allowed and expected to become negative.
//
// The result is either a number indicating the vertical refresh rate in Hz,
// or undefined if the given point is not present in the display bounds of
// the current display configuration.
return await ctx.findVerticalRefreshRateForDisplayPoint(x, y);
}
// ...
// This context reacts to underlying display changes, as a trade-off between
// performance and accuracy. It does so using the `addDisplayChangeListener`
// capabilities, so it needs to be disposed of properly to clear the event
// loop for graceful shutdown.
//
// Call this when you are finished with the context. A good place to do so
// is in the code that handles gracefully exiting your program.
ctx.close();
See scripts/watchmouse.js for a working example, polling
for the refresh rate based on the mouse cursor position.
This module can save and restore display device layouts (although it cannot directly modify them yet; patches welcome!). You can use this to implement a display configuration profile system.
Saving a profile is achieved with the displayConfigForRestoration function:
const w32disp = require("win32-displayconfig");
async function saveDisplayConfig() {
const conf = await w32disp.displayConfigForRestoration();
// The type of conf is JSON-safe: you can store this on the disk,
// transmit it over a network, etc.
return JSON.stringify(conf);
}
And restoring a profile is achieved with the restoreDisplayConfig function:
const w32disp = require("win32-displayconfig");
async function restoreDisplayConfig(serialized, persistent) {
// If "persistent", then this display configuration will be saved in Windows
// as the default display configuration. This means that restoring to defaults
// or rebooting will result in this exact configuration.
persistent = !!persistent;
const conf = JSON.parse(serialized);
// If portions of the configuration refer to displays that are not actually
// present, we make a best effort to enable all of the displays that are both
// present and enabled in this configuration, and disable all other displays.
//
// Otherwise, the display configuration is set exactly.
await w32disp.restoreDisplayConfig(conf);
}
This module is available under the terms of the MIT license. See the COPYRIGHT file
for more information.
FAQs
Inspect and reconfigure displays in Windows
We found that win32-displayconfig demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Malicious PyPI package ‘set-utils’ steals Ethereum private keys by exfiltrating them through blockchain transactions via the Polygon RPC.
Research
Security News
Malicious Go packages are impersonating popular libraries to install hidden loader malware on Linux and macOS, targeting developers with obfuscated payloads.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.