SharedGL is an OpenGL implementation that enables 3D acceleration for Windows and Linux guests within QEMU by streaming OpenGL commands over shared memory (and networks, for devices over LAN). For future plans, click here for the roadmap.
The following libraries are required for building the server (and client) on Linux:
The following script builds: sglrenderer
and libGL
for Linux:
git clone https://github.com/dmaivel/sharedgl.git
cd sharedgl
mkdir build
cd build
cmake ..
cmake --build . --config Release
If on Windows (Visual Studio required), you must specify that you only want to build the library, sharedglXX.dll
:
cmake --build . --target sharedgl-core --config Release
For detailed build instructions for Windows, visit the Windows section.
These CMake options are accessible by either:
ccmake
on build
folder-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. |
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)
Variables labeled with host
get their values from the host/server when their override isn't set.
Option | Legal values | Default | Description |
---|---|---|---|
SGL_WINED3D_DONT_VFLIP | Boolean | false | If running a DirectX application via WineD3D, ensure this variable is set to true in order for the application to render the framebuffer in the proper orientation. Only available for Windows clients. |
SGL_RUN_WITH_LOW_PRIORITY | Boolean | false | On single core setups, by setting the process priority to low / IDLE_PRIORITY_CLASS , applications will run smoother as the kernel driver is given more CPU time. Users should only set this to true if the VM has only a single VCPU. Only available for Windows clients. |
GL_VERSION_OVERRIDE | Digit.Digit | host |
Override the OpenGL version on the client side. Available for both Windows and Linux clients. |
GLX_VERSION_OVERRIDE | Digit.Digit | 1.4 | Override the GLX version on the client side. Only available for Linux clients. |
GLSL_VERSION_OVERRIDE | Digit.Digit | Override the GLSL version on the client side. Available for both Windows and Linux clients. | |
SGL_NET_OVER_SHARED | Ip:Port | If networking is enabled, this environment variable must exist on the guest. Available for both Windows and Linux clients. |
Two things must be done for the windows installation:
There are two possible drivers one may use:
...\virtio-win-upstream\Win10\amd64\
.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.
Included driver (multiclient support)
0.4.0
) (Windows 10 only)
ksgldrv.inf
and press Install
.Compile from source (use Visual Studio Developer Command Prompt)
WDK
, which can be found here.:: 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
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.There are two ways to install the library on windows:
0.3.1
)
wininstall.bat
and allow admin privledges.:: 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
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.
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 'sharedgl' directory
cd kernel/linux
make
[!WARNING]\ If you move the client library to the guest from the host instead of compiling it in the guest, you may encounter the
SIGILL
exception in the virtual machine as the build compiles with the native (host) architecture. To fix, either change your cpu model tohost-model
/host-passthrough
or comment out the-march=native
line in the cmake script (will most likely reduce performance).
Starting from 0.5.0
, SharedGL offers a networking feature that may be used in place of shared memory. No additional drivers are required for the network feature, meaning if you wish to have a driverless experience in your virtual machine, networking is the given alternative. If the networking feature is used exclusively, the kernel drivers do not need be compiled/installed. However, installation of the ICD for either Linux or Windows is still required.
-n
(and provide a port if the default is not available through -p PORT
)SGL_NET_OVER_SHARED=ADDRESS:PORT
exists in the guest (ADDRESS
being the host's IP address)If the network feature feels too slow, you may want to modify SGL_FIFO_UPLOAD_COMMAND_BLOCK_COUNT
in inc/network/packet.h
, which can be ranged from [1, 15360]:
/*
* 256: safe, keeps packet size under 1400 bytes
* 512: default
* 15360: largest, may result in fragmentation
*/
- #define SGL_FIFO_UPLOAD_COMMAND_BLOCK_COUNT 512
+ #define SGL_FIFO_UPLOAD_COMMAND_BLOCK_COUNT 15360
Note that changing this file will require rebuilding the client and server.
Before starting the virtual machine, you must pass a shared memory device and start the server before starting the virtual machine. This can be done within libvirt's XML editor or the command line. Before starting the virtual machine, start the server using -v
, which will start the server and print the necessary configurations:
$ ./sglrenderer -v [OTHER PARAMETERS]
[!IMPORTANT]\ Once these configurations are in place, running the server with
-v
is not required. If you make changes to the amount of memory to reserve using the-m
argument, you must reflect that change in the virtual machine configuration.
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
This list describes the amount of functions left from each standard to implement. This excludes EXT/ARB functions. This list may be inaccurate in terms of totals and also counts stubs as implementations.
freeglut
or glad
to no longer run (only tested on Linux clients).LD_PRELOAD
.IOT instruction
or No provider of glXXX found.
:
-g 2.0
)-m 256
)sudo ./sglrenderer -x
, start the server, start the VMerr: failed to open shared memory 'sharedgl_shared_memory'
sudo
sudo ./sglrenderer -x
, start the server, then start the VMglimpl_init: failed to find memory
to the terminal