SharedGL

SharedGL is an OpenGL 4.6 implementation that enables 3D acceleration for Windows and Linux guests within QEMU/KVM by streaming OpenGL commands over shared memory or sockets.

<details open> <summary>Click to hide: Preview</summary>

preview

</details> <details> <summary>Click to reveal: Table of contents</summary>

Getting started
Usage
Networking
Known issues
Troubleshooting
Showcase

</details>

Getting started

Dependencies

| Name | Version | | ---- | ------- | | CMake | 3.15+ | | libepoxy | Latest | | SDL2 | 2.24.0+ |

Building

git clone https://github.com/dmaivel/sharedgl.git
cd sharedgl
mkdir build
cd build
cmake ..
cmake --build . --target sglrenderer --config Release

If you also wish to build the client library libGL for Linux, libx11 is required. Build with --target sharedgl-core.

For detailed build instructions for Windows, visit the Windows section. The renderer/server is only supported on Linux hosts.

Build options

These CMake options are accessible by either:

Using ccmake on build folder
Configuring with -D...

| Option | Legal values | Default | Description | |-|-|-|-| | LINUX_LIB32 | ON/OFF | OFF | Enable if you wish to build the Linux client library (libGL) as 32-bit. This does not affect the server. |

Usage

The server must be started on the host before running any clients. Note that the server can only be ran on Linux.

usage: sglrenderer [-h] [-v] [-o] [-n] [-x] [-g MAJOR.MINOR] [-r WIDTHxHEIGHT] [-m SIZE] [-p PORT]
    
options:
    -h                 display help information
    -v                 display virtual machine arguments
    -o                 enables fps overlay on clients
    -n                 enable networking instead of shared memory
    -x                 remove shared memory file
    -g [MAJOR.MINOR]   report specific opengl version (default: 4.6)
    -r [WIDTHxHEIGHT]  set max resolution (default: 1920x1080)
    -m [SIZE]          max amount of megabytes program may allocate (default: 32mib)
    -p [PORT]          if networking is enabled, specify which port to use (default: 3000)

Your virtual machine must also be configured with a shared memory device (unless you are using the sockets version, in which case see networking). You can get the configurations from sglrenderer if you run it with -v. Sample configurations are provided below:

libvirt:

<!--> THIS IS A SAMPLE; ONLY USE THIS AS A GUIDE ON WHERE TO PLACE THE OUTPUT <-->
...
<devices>
    ...
    <shmem name="sharedgl_shared_memory">
        <model type="ivshmem-plain"/>
        <size unit="M">??</size>
    </shmem>
</devices>

qemu:

# THIS IS A SAMPLE; ONLY USE THIS AS A GUIDE ON WHERE TO PLACE THE OUTPUT
qemu-system-x86_64 -object memory-backend-file,size=??M,share,mem-path=/dev/shm/sharedgl_shared_memory,id=sharedgl_shared_memory

For installation of the client driver inside the virtual machine, refer to one of these:

Windows as the guest
Linux as the guest

Environment variables

Variables labeled with host get their values from the host/server when their override isn't set.

Windows (in a VM)

Two things must be done for the windows installation:

Install a compatible driver
Install the clients

Kernel driver

There are two possible drivers one may use:

VirtIO's IVSHMEM driver (no multiclient support)
1. Download and extract the upstream virtio win drivers, found here.
2. Navigate into ...\virtio-win-upstream\Win10\amd64\.
3. Right click on ivshmem.inf and press Install.

[!WARNING]
If you use the included driver, test signing must be on. Enable it by running the following command in an elevated command prompt: bcdedit.exe -set testsigning on and restart.

[!NOTE]
If you are looking for multiclient support but do not wish to install the patched driver, take a look into the networking feature which requires no drivers.

Included driver (multiclient support)
1. Use the release (>= 0.4.0) (Windows 10 only)
  1. Download the latest release for windows and extract the zip file.
  2. Navigate into the extracted folder.
  3. Right click on ksgldrv.inf and press Install.
2. Compile from source (use Visual Studio Developer Command Prompt)
  1. Ensure you have installed the WDK, which can be found here.
  2. ```
  :: git clone https://github.com/dmaivel/sharedgl.git
  :: cd sharedgl
  mkdir build
  cd build
  cmake -DCMAKE_GENERATOR_PLATFORM=x64 -DWINKERNEL=ON ..
  cmake --build . --target ksgldrv --config Release
  cd ..
  xcopy .\scripts\kcertify.bat .\build\Release\kcertify.bat
  xcopy .\scripts\ksgldrv.inf .\build\Release\ksgldrv.inf
  cd build\Release
  call kcertify.bat 10_X64
  
  :: requires admin privs, you may right click on the file and press install instead
  pnputil -i -a ksgldrv.inf
```
3. By default, this builds for Windows 10 x64 (10_X64). If you wish to compile for a different version or multiple versions, you must provide it through the command line like so: kcertify.bat 10_X64,10_NI_X64. A list of OS versions is provided on MSDN here.

Library / ICD

There are two ways to install the library on windows:

Use a release (>= 0.3.1)
1. Download the latest release for windows and extract the zip file.
2. Navigate into the extracted folder and run wininstall.bat and allow admin privledges.
3. The libraries should now be installed, meaning any application that uses OpenGL (32-bit and 64-bit) will use SharedGL.

Compile from source (use Visual Studio Developer Command Prompt)

:: git clone https://github.com/dmaivel/sharedgl.git
:: cd sharedgl
mkdir build
cd build
:: if you get errors regarding wdk, also use -DWINKERNEL=OFF
cmake -DCMAKE_GENERATOR_PLATFORM=x64 ..
cmake --build . --target sharedgl-core --config Release
cmake -DCMAKE_GENERATOR_PLATFORM=Win32 ..
cmake --build . --target sharedgl-core --config Release
cd ..
xcopy .\scripts\wininstall.bat .\build\Release\wininstall.bat
cd build\Release
call wininstall.bat

Linux

[!CAUTION] The following sections discuss using the client library, not the renderer/server. If your intention is to only accelerate Windows guests, you may disregard this section as all you need to do is run the renderer, no additional libraries required (other than the dependencies).

For your OpenGL application to communicate with the server, the client library must be specified in your library path. Upon exporting, any program you run in the terminal where you inputted this command will run with the SGL binary.

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/sharedgl/build
$ glxgears
$ ...

Some applications may require adding the library to the LD_PRELOAD environment variable aswell, which is done the same way as shown above.

Note that the Linux library does not need to be used in a virtual machine, allowing users to debug the library entirely on the host.

Some applications may require an explicit libGLX, so run ln -s libGL.so.1 libGLX.so.0 in build to make a symlink.

Linux in a VM

For virtual Linux clients, an additional kernel module needs to be compiled in the virtual machine, resulting in a binary sharedgl.ko which needs to be loaded. Loading/installing can be done by running the provided script (./kernel/linux/install.sh), following compilation. If the module doesn't load on boot, it is recommended that you add sharedgl to your modprobe config.

# within 'shared

Sharedgl

Install / Use

README