cybershadow / hax11

Hackbrary to Hook and Augment X11 protocol calls

hax11

Hackbrary to Hook and Augment X11 protocol calls.

Allows customizing the behavior of and fix common annoyances of X11 applications:

• exclusively grabbing the mouse or keyboard
• forcibly pausing the game when the window loses focus
• forcibly changing the screen resolution
• not restricting the mouse cursor to its window/monitor

Additionally, attempts to fix game and full-screen application issues on Linux, such as:

• starting on the wrong monitor
• spanning too many monitors
• spanning one half of a tiled (MST) monitor (such as some 4K/5K/8K monitors)
• refusing to allow selecting a desired resolution

See the configuration section for more details.

Building

Build the library:

$ make

The Makefile assumes you have a 64-bit system. You will need gcc-multilib to build the 32-bit version.

Usage

To try this library, build this library as above, then in the same directory, run the following in a shell:

$ export LD_PRELOAD=`pwd`/\$LIB/hax11.so

Then, from the same shell session, start the desired game or application.

To temporarily disable hax11, unset LD_PRELOAD before running a program, e.g.:

$ LD_PRELOAD= xrandr

Configuration

By default, this library will not do anything.

For every application using the affected API, it will create an empty configuration file under $HOME/.config/hax11/profiles/. Each file corresponds to one program, and will be named after the program executable's absolute path, but with forward slashes / substituted with backslashes \.

Additionally, a default configuration file (in the same directory as above) will be loaded before the program's.

The syntax is one Name=Value pair per line.

Supported configuration options:

Name	Values	Description
Enable	0/1	Boolean - Intercept the X11 connection (required for any other settings to have any effect)
JoinMST	0/1	Boolean - For monitors which present each half as one MST panel, join them and present them as one monitor to the application
MaskOtherMonitors	0/1	Boolean - Whether to hide the presence of other monitors from the application
ResizeWindows	0/1	Boolean - Whether to forcibly change the size of windows whose width is equal to DesktopW
ResizeAll	0/1	Boolean - Resize (stretch) all windows, not just those matching the size of one MST panel
MoveWindows	0/1	Boolean - Whether to forcibly move windows created at (0,0) to the primary monitor
Fork	0/1	Boolean - Move processing to a separate forked process.
FilterFocus	0/1	Boolean - Filter out FocusOut events, making games think they always have focus.
NoMouseGrab	0/1	Boolean - Filter out GrabPointer requests, preventing games from exclusively grabbing the mouse pointer.
NoKeyboardGrab	0/1	Boolean - Filter out GrabKeyboard requests, preventing games from exclusively grabbing the keyboard, and thus disabling global hotkeys.
ConfineMouse	0/1	Boolean - Confine the mouse to the program's window while it is focused. Focus must then be changed with the keyboard.
NoPrimarySelection	0/1	Boolean - Disable getting (pasting) or setting (copying) the PRIMARY X selection (usually done by middle clicks).
NoResolutionChange	0/1	Boolean - Disable setting screen resolution.
NoMinSize	0/1	Boolean - Disable minimum window size restriction.
NoMaxSize	0/1	Boolean - Disable maximum window size restriction.
NoWindowStackMove	0/1	Boolean - Disable moving windows through the window stack. Prevents moving windows to the top or bottom.
NoWMRaise	0/1	Boolean - Filter out _NET_ACTIVE_WINDOW requests, prevents asking the window manager to raise windows to the top.
FakeScreenW/H	Integer	Fake the reported resolution of all X11 screens to the application on X11 handshake. Active when non zero
FakeScreenDimW/H	Integer	Fake the reported dimensions in millimeters of all X11 screens to the application on X11 handshake. Active when non zero
MainX/Y	Integer	The X11 coordinates of your primary monitor (or left-top-most monitor to be used for games)
MainW/H	Integer	The resolution of your primary monitor (or total resolution of monitors to be used for games)
DesktopW/H	Integer	The resolution of your desktop (all monitors combined)
Debug	Integer	Log level - Non-zero enables debugging output to stderr and /tmp/hax11.log
LogTimestamp	0/1	Boolean - Enable timestamp logging
MSTnX/Y/W/H	Integer	Coordinates and sizes of additional MST monitors (n can be 2, 3 or 4).
MapK/Binteger	Key	Map keys or buttons - see below

Beware that your window manager and shell use the same APIs, thus having other options enabled for such programs may make other monitors unusable.

A sensible configuration is to have JoinMST=1 and the Main* / Desktop* settings in the default profile, and per-game settings in their executables' profiles.

Example

Here is an example configuration for a two-monitor system. On the left is a 1920x1200 monitor; on the right, a 4K monitor which presents itself as two 1920x2160 panels. The goal is to have games running full-screen on the 4K monitor.

In ~/.config/hax11/profiles/default:

JoinMST=1

# Top-left coordinate of your main (4K) screen
MainX=1920
MainY=0

# Width and height of the 4K screen
MainW=3840
MainH=2160

Then, in ~/.config/hax11/profiles/path\to\game\binary:

Enable=1

# If this is insufficient, you can also try:
# ResizeWindows=1
# MoveWindows=1
# ResizeAll=1
# Check the status section for example configurations for some games.

Key / button mapping

You can map a key or mouse button to one or more keys / mouse buttons using configuration lines in the form Map ( K | B ) integer = ( K | B ) integer. The integer is the key or button code, and can be found using e.g. the xev utility. Defining the same key or button on the left side of = allows mapping it to multiple keys / buttons. The original key / button event is suppressed. To include it, map the key / button to itself.

Example - reverse the Left and Right arrow keys:

MapK113=K114
MapK114=K113

Example - making the left mouse button click also generate an F4 key press (in addition to sending itself):

MapB1=B1
MapB1=K70

Installation

You can install this library system-wide, so that it is loaded into all applications on start-up.

Warning! This project may or may not be compatible with your system. Installing this library system-wide may put your system into an unusable state. Before installation, make sure you're capable of uninstalling this library if X, your desktop environment, etc. refuses to start.

This will install the libraries under /usr/local/lib{32,64}, and a script under /etc/profile.d:

$ make install

Log out and back in (or reboot) to apply the hack to all applications.

Status

The following table represents the results of testing this library on the author's machine, consisting of a 1920x1200 monitor at (0,0), and a 4K monitor in MST mode (thus presenting itself as two 1920x2160 panels) at (1920,0). The 4K monitor is the primary one.

The desired result (and solution listed to achieve said result) is to launch the game in full-screen on the 4K monitor, at 4K resolution if the game supports it.

Game	Status
10,000,000	Works (MoveWindows + ResizeWindows)
140	Works (Unity - MoveWindows)
3089	Java. Resolution selector is completely broken, throws NullPointerException
Adventures of Shuggy	Works (not needed)
And Yet It Moves	Works (MoveWindows + ResizeWindows, then set <Resolution>...</Resolution> in ~/.Broken Rules/And Yet It Moves/common/commonConfig.xml)
Anodyne	Adobe Air version doesn't start (exits with code 5); standalone (.swf) version can't get past the calibration screen
Antichamber	Works (not needed)
Aquaria (Steam)	Works (ResizeWindows, then set resx and resy in ~/.Aquaria/preferences/usersettings.xml)
Aquaria (tarball)	Works (as above)
Avadon: The Black Fortress	Works (MoveWindows + ResizeWindows)
Bad Hotel	Works (ResizeWindows + ResizeAll)
The Binding of Isaac: Rebirth	Works (not needed)
BIT.TRIP RUNNER	Does not actually have a Linux port on Steam
Blueberry Garden	Works (ResizeWindows)
Bridge Constructor Playground	Works (Unity - MoveWindows)
Card City Nights	Works (Unity - MoveWindows)
Crimsonland	Works (ResizeWindows, then change the resolution)
Darwinia	Works (MoveWindows + ResizeWindows, change the resolution to fix AR)
DEFCON	Works (MoveWindows + ResizeWindows, then change the resolution)
Dota 2	Works (ResizeWindows + "Use my monitor's current resolution")
Dungeons of Dredmor	Works (MoveWindows + ResizeWindows, set resolution in the launcher)
Dust: An Elysian Tail	Works (ResizeWindows, then change the resolution)
Dynamite Jack	Works (MoveWindows + ResizeWindows, then change the resolution)
Escape Goat	Works (ResizeWindows + ResizeAll)
Eversion	Works (not needed)
Faerie Solitaire [Beta]	Works (ResizeWindows)
Garry's Mod	Works (Source - ResizeWindows, then change the resolution)
Gigantic Army	Works (not needed)
Gone Home	Doesn't start at all on my machine
Guacamelee! Gold Edition	Works (ResizeWindows, then change the resolution)
Half-Life 2: Deathmatch	Works (Source - ResizeWindows, then change the resolution)
Heavy Bullets	Works (not needed)
Hexcells	Works (Unity - MoveWindows)
HyperRogue	Works (MoveWindows + ResizeWindows, then set the resolution on the first line of ~/.hyperrogue.ini)
Intrusion 2	Works (not needed)
Jazzpunk	Works (MoveWindows)
Lugaru HD	Works (ResizeWindows, then set the resolution in ~/.lugaru/Data/config.txt)
Lume	Works (ResizeWindows, then Ctrl+F to exit full screen, drag to correct monitor, Ctrl+F to enter full screen)
The Magic Circle	Works (MoveWindows)
Multiwinia	Crashes after the splash screen on my machine
Osmos	Works (not needed)
Outlast	Works (ResizeWindows, then change the resolution)
Papers, Please	Works (not needed)
Perfection.	TODO - Queries resolution via proprietary NVIDIA protocol extension
Psychonauts	Works (MoveWindows + ResizeWindows, then set the resolution on the first line of $XDG_DATA_HOME/Psychonauts/DisplaySettings.ini)
Quest of Dungeons	Works (ResizeWindows)
Risk of Rain	Works (not needed)
Satazius	Works (not needed)
Shatter	Works (ResizeWindows)
Sigils of Elohim	Doesn't seem to have a full-screen mode. Works otherwise
Snuggle Truck	Works (Unity - MoveWindows)
Soul Axiom	Works (Unity - MoveWindows)
Starbound	Works (MoveWindows + ResizeWindows)
Sunless Sea	Works (MoveWindows + ResizeWindows + ResizeAll, then set the resolution to 1920x1080)
Super Hexagon	Works (MoveWindows + ResizeWindows)
Superfrog HD	TODO - Wrong scaling
Teleglitch: DME	Works (not needed)
Terraria	Works (not needed)
Teslagrad	Works (Unity - MoveWindows)
They Bleed Pixels	Works (ResizeWindows)
Tiki Man	Works (Unity - MoveWindows)
TIS-100	Works (MoveWindows)
Uplink	Works (MoveWindows + ResizeWindows + ResizeAll)
Voxatron	Works (ResizeWindows), though the KDE panel remains on top for some reason.
VVVVVV	Works (not needed)
World of Goo	Works (MoveWindows + ResizeWindows, then copy .../World of Goo/properties/config.txt to ~/.WorldOfGoo/config.txt and set screen_width/screen_height)

hax11's Issues

Can this be used to fake displays?

Im having a huge pain dealing with games that require a display. They simply fail to start and crash in most cases with errors ranging from failed xrandr ccrtinfos (no crts) to unable to initialize opengl contexts. When the opengl context is obviously fully functional and there, glxgears works, glxinfo is very prudent.

i am not sure if this library goes deep enough as to fix all these issues. I looked at making fakerandr work, but I am concerned it wont address all these errors. Note that as soon as a hook up a real display and xrandr -q shows a CRT or DFP or HDMI, etc the game works and runs fine. As soon as xrandr -q just shows a screen[n] of size 1920x1080 for example without any CRT/DFP, games that query the monitor at startup crash, other games coded differently work.

The reason why I want the game running on the virtual screen/display is so I can VNC to the screen. Which will support full glx if done this way. The only problem is the apps themselves start refusing to start when theres no real outputs.

Can't install hax11

I'm new to linux, but i heard hax11 fixes some mouse problems with War Thunder.
Firstly, i used git clone. Then it said i need some x,org libs to make, so i installed everything hax11 asked for (i found analogues for Fedora).
Now there's no home/.config/hax11 directory and when i try to launch a game it says
ERROR: ld.so: object '/home/shinyzero/hax11/$LIB/hax11.so' from LD_PRELOAD cannot be preloaded (cannot open shared object file): ignored.
Also i tried to reboot but it didn't help

Dual MST screen setup

First of all, thanks a lot for sharing this awesome hack. I'm currently experimenting with a dual screen MST setup (two 5k monitors). I just enabled the hack by default like this:

JoinMST=1
MainX=0
MainY=0
MainW=5120
MainH=2880
DesktopW=10240
DesktopH=2880
Enable=1

The problem is that it only works correctly on the "Main" display (the left one). Windows are maximized as expected, across the entire display. The other display remains split vertically. :-( Details about my setup:

• ArchLinux
• 4.10.4 kernels, both custom and stock (both exhibit the same behavior)
• xorg-xrandr 1.5.0-1
• libx11 1.6.5-1
• nvidia 378.13-3
• hardware
  • 05:00.0 VGA compatible controller: NVIDIA Corporation GP104GL [Quadro P5000] (rev a1)
  • 2x HP Z27q (on 2 DisplayPorts each, showing 5120x2880@60Hz in their monitor menus)

Additionally, although I've set the configuration above for my user account, for root and also for the sddm user, many things remain unaffected:

• SDDM: login greeter on the left halves of both monitors; a weird white area covers (almost) the entire right halves
• KDE plasmashell: split into two halves on both monitors, even on the one where windows are maximized correctly

The sddm and plasmashell problems are quite minor, but getting windows maximized correctly on both monitors whould be awesome. If you need further details, please just let me know what to tweak or what Debug= loglevel to use.

Add support for (something like) JoinTILE

The current version of hax11 supports JoinMST, which makes it possible to present a screen that presents itself as two or more xrandr screens using MST, as one.

Another way this is done is with the TILE property. A good example of this is the Dell UP3218k 8K monitor, which is attached using two DisplayPort 1.4 cables. This screen presents itself as two 3840x4320 screens, a left and a right, with TILE information, that lets modern drivers (Nvidia, AMDGPU) set up the display "as one". However, Xrandr, will still see two connectors. Example xrandr --query output:

Screen 0: minimum 8 x 8, current 11520 x 4320, maximum 32767 x 32767
HDMI-0 connected primary 3840x2160+0+0 (normal left inverted right x axis y axis) 344mm x 193mm
   3840x2160     60.00*+  59.94    50.00    29.97    25.00    23.98  
   2560x1440     59.95  
   1920x1080     60.00    59.94    50.00    29.97    25.00    23.98  
   1680x1050     59.95  
   1600x1200     60.00  
   1440x900      59.89  
   1400x1050     59.98  
   1280x1024     75.02    60.02  
   1280x960      60.00  
   1280x720      60.00    59.94    50.00  
   1024x768      75.03    70.07    60.00  
   800x600       75.00    72.19    60.32    56.25  
   720x576       50.00  
   720x480       59.94  
   640x480       75.00    72.81    59.94    59.93  
DP-0 disconnected (normal left inverted right x axis y axis)
DP-1 disconnected (normal left inverted right x axis y axis)
DP-2 connected 3840x4320+3840+0 (normal left inverted right x axis y axis) 700mm x 390mm
   3840x2160     60.00 +  29.98  
   7680x4320     29.93    24.00  
   3840x4320     60.00*   48.00  
   2560x1440     59.95  
   2048x1080     59.99    23.90  
   1920x1200     59.88  
   1920x1080     60.00    59.94    50.00    23.98  
   1680x1050     59.95  
   1600x1200     60.00  
   1280x1024     75.02    60.02  
   1280x800      59.81  
   1280x720      59.94    50.00  
   1024x768      75.03    60.00  
   800x600       75.00    60.32  
   720x576       50.00  
   720x480       59.94  
   640x480       75.00    59.94    59.93  
DP-3 disconnected (normal left inverted right x axis y axis)
DP-4 connected 3840x4320+7680+0 (normal left inverted right x axis y axis) 700mm x 390mm
   3840x2160     60.00 +  29.98  
   7680x4320     29.93    24.00  
   3840x4320     60.00*   48.00  
   2560x1440     59.95  
   2048x1080     59.99    23.90  
   1920x1200     59.88  
   1920x1080     60.00    59.94    50.00    23.98  
   1680x1050     59.95  
   1600x1200     60.00  
   1280x1024     75.02    60.02  
   1280x800      59.81  
   1280x720      59.94    50.00  
   1024x768      75.03    60.00  
   800x600       75.00    60.32  
   720x576       50.00  
   720x480       59.94  
   640x480       75.00    59.94    59.93  
DP-5 disconnected (normal left inverted right x axis y axis)

In the Above, DP-2 and DP-4 are the connectors attached to the TILE'd display. Example xrandr --listactivemonitors output:

Monitors: 2
 0: +*HDMI-0 3840/344x2160/193+0+0  HDMI-0
 1: DELL UP3218K-495 7680/700x4320/390+3840+0  DP-2 DP-4

It would be great if a new feature, maybe called JoinTILE or a more generic Join could also handle these kind of monitors that instead of MST use TILE.

firefox freezes on middle mouse (3) button click

1. Select text, click right mouse button and copy;
2. Select any other text click mouse 3 button - freeze.

root@deb12:~/Desktop# export LD_PRELOAD=/usr/local/lib64/hax11.so
root@deb12:~/Desktop# firefox

deb 12 and xfce4 running, ps as was mentioned in #6 even $LIB is suddenly empty, so had to hardcore the path.

Bezel correction?

Any chance to support some kind of bezel correction?

its/libc-header-start.h: No such file or directory

I cannot seem to build the library... Here is the complete error:

/usr/include/stdio.h:27:10: fatal error: bits/libc-header-start.h: No such file or directory
   27 | #include <bits/libc-header-start.h>

Specifications:
X86_64 Architecture
Ubuntu 20.04 OS

Command to download:

git clone https://github.com/CyberShadow/hax11

kdeconnectd segfaults

Not that it matters since it is easy to disable hax11 for it, but it might be interesting to investigate why it crashes.

Application: kdeconnectd (kdeconnectd), signal: Segmentation fault
Using host libthread_db library "/usr/lib/libthread_db.so.1".
[Current thread is 1 (Thread 0x7f922cc63c80 (LWP 1261))]
...
Thread 1 (Thread 0x7f922cc63c80 (LWP 1261)):
[KCrash Handler]
#6  0x00007f9230100440 in xcb_get_property_value_length () from /usr/lib/libxcb.so.1
#7  0x00007f922c7d3f43 in QXcbNativeInterface::atspiBus() () from /usr/lib/libQt5XcbQpa.so.5
#8  0x00007f922c7d4bb9 in QXcbNativeInterface::nativeResourceForIntegration(QByteArray const&) () from /usr/lib/libQt5XcbQpa.so.5
#9  0x00007f922c86940a in ?? () from /usr/lib/libQt5XcbQpa.so.5
#10 0x00007f922c869c36 in ?? () from /usr/lib/libQt5XcbQpa.so.5
#11 0x00007f922c85d489 in ?? () from /usr/lib/libQt5XcbQpa.so.5
#12 0x00007f922c7b5d10 in QXcbIntegration::accessibility() const () from /usr/lib/libQt5XcbQpa.so.5
#13 0x00007f92329a2437 in QAccessible::setRootObject(QObject*) () from /usr/lib/libQt5Gui.so.5
#14 0x00007f92329caca4 in QGuiApplication::exec() () from /usr/lib/libQt5Gui.so.5
#15 0x000055bd0281112f in ?? ()
#16 0x00007f9232059223 in __libc_start_main () from /usr/lib/libc.so.6
#17 0x000055bd0281119e in _start ()
[Inferior 1 (process 1261) detached]

How to enable hax11 for all apps by default

Hi!

To try this library, build this library as above, then in the same directory, run the following in a shell:

$ export LD_PRELOAD=`pwd`/\$LIB/hax11.so

Then, from the same shell session, start the desired game or application.

How to preload hax11.so for ALL apps automatically?
I tried to add

export LD_PRELOAD=/path/to/hax11.so

to ~/.xsessionrc, ~/.bashrc, ~/profile and even to /etc/environment but nothing works: library is used only when I start GUI app from terminal emulator.

ConfineMouse causes 0ad to crash

I'm trying to use hax11 to confine the mouse in a windowed instance of 0ad running on Debian/unstable. However as soon as I start 0ad I get the following output and just an empty window where I'd expect 0ad to show up (however at least the mouse is already confined in that empty window):

$ LD_PRELOAD=`pwd`/\$LIB/hax11.so pyrogenesis 
TIMER| InitVfs: 1.06341 ms
Writing the mainlog at /home/user/.config/0ad/logs/mainlog.html
TIMER| CONFIG_Init: 1.86034 ms
Sound: AlcInit success, using OpenAL Soft
TIMER| shutdown ConfigDB: 0.338 us
TIMER| resource modules: 3.45899 ms
TIMER TOTALS (9 clients)
-----------------------------------------------------
  tc_pool_alloc: 0 c (0x)
  tc_png_decode: 0 c (0x)
  tc_dds_transform: 0 c (0x)
  tc_transform: 0 c (0x)
  tc_plain_transform: 0 c (0x)
  tc_ShaderGLSLLink: 0 c (0x)
  tc_ShaderGLSLCompile: 0 c (0x)
  tc_ShaderValidation: 0 c (0x)
  xml_validation: 0 c (0x)
-----------------------------------------------------
TIMER| shutdown misc: 1.07213 ms
TIMER| InitVfs: 200.807 ms
Writing the mainlog at /home/user/.config/0ad/logs/mainlog.html
TIMER| CONFIG_Init: 3.26789 ms
Sound: AlcInit success, using OpenAL Soft
hax11: Found X connection!
hax11: Intercepting X connection!
hax11: Server connection setup reply: 1
hax11: Exiting work thread.
hax11: Found X connection!
hax11: Intercepting X connection!
hax11: Server connection setup reply: 1
hax11: Found X connection!
hax11: Intercepting X connection!
hax11: Server connection setup reply: 1
hax11: Exiting work thread.
XIO:  fatal IO error 11 (Resource temporarily unavailable) on X server ":0"
      after 229 requests (229 known processed) with 19 events remaining.
hax11: Acquiring mouse grab
^C

My hax11 config for 0ad is:

Enable=1
ConfineMouse=1
Debug=1

Wiithout preloading hax11, 0ad works fine.