Skip to content

Commit c77f2fa

Browse files
dmaiveldmaivel
committed
Improve README
1 parent fc70fbe commit c77f2fa

File tree

1 file changed

+50
-80
lines changed

1 file changed

+50
-80
lines changed

‎README.md‎

Lines changed: 50 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# SharedGL ![license](https://img.shields.io/badge/license-MIT-blue)
44

5-
SharedGL is an OpenGL implementation that enables 3D acceleration for Windows and Linux guests within QEMU/KVM by streaming OpenGL commands over shared memory *(and networks, for devices over LAN)*. For future plans, click [here](https://github.com/users/dmaivel/projects/2) for the roadmap.
5+
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.
66

77
<details>
88
<summary>Click to reveal: Table of contents</summary>
@@ -11,24 +11,27 @@ SharedGL is an OpenGL implementation that enables 3D acceleration for Windows an
1111
2. [Usage](#usage)
1212
- [Environment variables](#environment-variables)
1313
- [Windows in a VM](#windows-in-a-vm)
14-
- [Linux](#linux)
15-
- [Linux in a VM](#linux-in-a-vm)
14+
- [Linux (client debugging)](#linux)
15+
- [Linux in a VM](#linux-in-a-vm)
1616
3. [Networking](#networking)
17-
4. [Virtual machines](#virtual-machines)
18-
5. [Supported GL versions](#supported-gl-versions)
19-
6. [Limitations / Issues](#limitations--issues)
20-
7. [Troubleshooting](#troubleshooting)
21-
8. [Showcase](#showcase)
17+
4. [Known issues](#known-issues)
18+
5. [Troubleshooting](#troubleshooting)
19+
6. [Showcase](#showcase)
2220

2321
</details>
2422

2523
# Getting started
2624

27-
The following libraries are required for building the server on Linux:
28-
- libepoxy
29-
- SDL2
25+
## Dependencies
26+
27+
| Name | Version |
28+
| ---- | ------- |
29+
| [CMake](https://cmake.org/) | 3.5+ |
30+
| [libepoxy](https://github.com/anholt/libepoxy) | Latest |
31+
| [SDL2](https://www.libsdl.org/) | 2.24.0+ |
32+
33+
## Building
3034

31-
The following script builds `sglrenderer` for Linux:
3235
```bash
3336
git clone https://github.com/dmaivel/sharedgl.git
3437
cd sharedgl
@@ -38,7 +41,7 @@ cmake ..
3841
cmake --build . --target sglrenderer --config Release
3942
```
4043

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

4346
For detailed build instructions for Windows, visit the [Windows section](#windows-in-a-vm). The renderer/server is only supported on Linux hosts.
4447

@@ -70,6 +73,31 @@ options:
7073
-p [PORT] if networking is enabled, specify which port to use (default: 3000)
7174
```
7275
76+
Your virtual machine must also be configured with a shared memory device *(unless you are using the sockets version, in which case see [networking](#networking))*. You can get the configurations from `sglrenderer` if you run it with `-v`. Sample configurations are provided below:
77+
78+
**libvirt:**
79+
```xml
80+
<!--> THIS IS A SAMPLE; ONLY USE THIS AS A GUIDE ON WHERE TO PLACE THE OUTPUT <-->
81+
...
82+
<devices>
83+
...
84+
<shmem name="sharedgl_shared_memory">
85+
<model type="ivshmem-plain"/>
86+
<size unit="M">??</size>
87+
</shmem>
88+
</devices>
89+
```
90+
91+
**qemu:**
92+
```bash
93+
# THIS IS A SAMPLE; ONLY USE THIS AS A GUIDE ON WHERE TO PLACE THE OUTPUT
94+
qemu-system-x86_64 -object memory-backend-file,size=??M,share,mem-path=/dev/shm/sharedgl_shared_memory,id=sharedgl_shared_memory
95+
```
96+
97+
For installation of the client driver inside the virtual machine, refer to one of these:
98+
- [Windows as the guest](#windows-in-a-vm)
99+
- [Linux as the guest](#linux-in-a-vm)
100+
73101
### Environment variables
74102
75103
Variables labeled with `host` get their values from the host/server when their override isn't set.
@@ -85,8 +113,6 @@ Variables labeled with `host` get their values from the host/server when their o
85113
86114
## Windows (in a VM)
87115
88-
[Windows is only supported as a guest: Click here for virtual machine configuring, which is required for the guest to see SharedGL's shared memory](#virtual-machines)
89-
90116
Two things must be done for the windows installation:
91117
1. Install a compatible driver
92118
2. Install the clients
@@ -153,7 +179,7 @@ There are two ways to install the library on windows:
153179
154180
## Linux
155181
156-
> [!IMPORTANT]
182+
> [!CAUTION]
157183
> 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).
158184
159185
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.
@@ -170,9 +196,7 @@ Note that the Linux library does not need to be used in a virtual machine, allow
170196
171197
Some applications may require an explicit `libGLX`, so run `ln -s libGL.so.1 libGLX.so.0` in `build` to make a symlink.
172198
173-
### Linux in a VM
174-
175-
[Click here for virtual machine configuring, which is required for the guest to see SharedGL's shared memory](#virtual-machines)
199+
## Linux in a VM
176200
177201
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.
178202
@@ -187,6 +211,9 @@ make
187211
188212
# Networking
189213
214+
> [!NOTE]
215+
> Shared memory should be prefered over sockets if speed is a concern.
216+
190217
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.
191218
- Start the server using `-n` (and provide a port if the default is not available through `-p PORT`)
192219
- Ensure the client libraries are installed
@@ -205,66 +232,9 @@ If the network feature feels too slow, you may want to modify `SGL_FIFO_UPLOAD_C
205232
206233
Note that changing this file will require rebuilding the client and server.
207234
208-
# Virtual machines
209-
210-
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:
211-
212-
```bash
213-
$ ./sglrenderer -v [OTHER PARAMETERS]
214-
```
215-
216-
> [!IMPORTANT]\
217-
> 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.
218-
219-
**libvirt:**
220-
```xml
221-
<!--> THIS IS A SAMPLE; ONLY USE THIS AS A GUIDE ON WHERE TO PLACE THE OUTPUT <-->
222-
...
223-
<devices>
224-
...
225-
<shmem name="sharedgl_shared_memory">
226-
<model type="ivshmem-plain"/>
227-
<size unit="M">??</size>
228-
</shmem>
229-
</devices>
230-
```
231-
232-
**qemu:**
233-
```bash
234-
# THIS IS A SAMPLE; ONLY USE THIS AS A GUIDE ON WHERE TO PLACE THE OUTPUT
235-
qemu-system-x86_64 -object memory-backend-file,size=??M,share,mem-path=/dev/shm/sharedgl_shared_memory,id=sharedgl_shared_memory
236-
```
237-
238-
# Supported GL versions
239-
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.
240-
241-
- [x] OpenGL 1
242-
- [x] 1.0 (~306 total)
243-
- [x] 1.1 (~30 total)
244-
- [x] 1.2 (~4 total)
245-
- [x] 1.3 (~46 total)
246-
- [x] 1.4 (~47 total)
247-
- [x] 1.5 (~19 total)
248-
- [x] OpenGL 2
249-
- [x] 2.0 (~93 total)
250-
- [x] 2.1 (~6 total)
251-
- [x] OpenGL 3
252-
- [x] 3.0 (~84 total)
253-
- [x] 3.1 (~15 total)
254-
- [x] 3.2 (~19 total)
255-
- [x] 3.3 (~58 total)
256-
- [x] OpenGL 4
257-
- [x] 4.0 (~46 total)
258-
- [x] 4.1 (~89 total)
259-
- [x] 4.2 (~12 total)
260-
- [x] 4.3 (~44 total)
261-
- [x] 4.4 (~9 total)
262-
- [x] 4.5 (~122 total)
263-
- [x] 4.6 (~4 total)
264-
265-
# Limitations / Issues
266-
- New GLX FB configs may cause applications using `freeglut` or `glad` to no longer run (only tested on Linux clients).
267-
- Incomplete framebuffers when using network feature
235+
# Known issues
236+
- **Network:** Incomplete framebuffers when using network feature
237+
- **Linux clients:** New GLX FB configs may cause applications using `freeglut` or `glad` to no longer run (only tested on Linux clients).
268238
269239
# Troubleshooting
270240
@@ -327,4 +297,4 @@ https://github.com/dmaivel/sharedgl/assets/38770072/0d46bf46-5693-4842-a81f-2f18
327297
328298
https://github.com/dmaivel/sharedgl/assets/38770072/ded179b8-23dc-491d-ba34-4108e014f296
329299
330-
</details>
300+
</details>

0 commit comments

Comments
 (0)