From 583e68f1de4e489138ad815c99170b827c1c5dab Mon Sep 17 00:00:00 2001 From: dmaivel Date: Sun, 16 Jun 2024 19:38:03 -0400 Subject: [PATCH] Improve clarity in code and README * move Windows section up in README * add GLIMPL_USES_SHARED_MEMORY for checking if net_ctx is NULL * clarify values in packet.h --- README.md | 73 ++++++++++++++++++++++++++------------------ inc/network/packet.h | 4 +-- src/client/glimpl.c | 8 +++-- 3 files changed, 50 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 19f6623..4acbb8d 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ SharedGL is an OpenGL implementation that enables 3D acceleration for Windows an 2. [Usage](#usage) - [Environment variables](#environment-variables) - [Shared memory or network](#shared-memory-or-network) + - [Windows in a VM](#windows-in-a-vm) - [Linux](#linux) - [Linux in a VM](#linux-in-a-vm) - - [Windows in a VM](#windows-in-a-vm) 3. [Networking](#networking) 4. [Virtual machines](#virtual-machines) 5. [Supported GL versions](#supported-gl-versions) @@ -79,35 +79,7 @@ options: ### Network -Starting from version `0.5.0`, network capabilities are offered. If you wish to accelerate graphics over another machine or do not wish to install any kernel drivers, use the network feature. - -## Linux -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. - -```bash -$ 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. - -### Linux in a VM - -[Click here for virtual machine configuring, which is required for the guest to see SharedGL's shared memory](#virtual-machines) - -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. - -```bash -# 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 to `host-model`/`host-passthrough` or comment out the `-march=native` line in the cmake script (will most likely reduce performance). +Starting from version `0.5.0`, network capabilities are offered. If you wish to accelerate graphics over another machine or do not wish to install any kernel drivers, use the network feature. See [networking](#networking) for more information. ## Windows (in a VM) @@ -177,6 +149,34 @@ There are two ways to install the library on windows: call wininstall.bat ``` +## Linux +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. + +```bash +$ 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. + +### Linux in a VM + +[Click here for virtual machine configuring, which is required for the guest to see SharedGL's shared memory](#virtual-machines) + +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. + +```bash +# 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 to `host-model`/`host-passthrough` or comment out the `-march=native` line in the cmake script (will most likely reduce performance). + # Networking 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. @@ -184,6 +184,19 @@ Starting from `0.5.0`, SharedGL offers a networking feature that may be used in - Ensure the client libraries are installed - Ensure that the environment variable `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]: +```diff +/* + * 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 this change will require rebuilding the client and server. + # Virtual machines > [!NOTE]\ diff --git a/inc/network/packet.h b/inc/network/packet.h index 7376046..6f3f39e 100644 --- a/inc/network/packet.h +++ b/inc/network/packet.h @@ -7,8 +7,8 @@ /* * 256: safe, keeps packet size under 1400 bytes - * 512: medium - * 15360: largest, not to be used over networks due to fragmentation + * 512: default + * 15360: largest, may result in fragmentation */ #define SGL_FIFO_UPLOAD_COMMAND_BLOCK_COUNT 512 #define SGL_FIFO_UPLOAD_COMMAND_BLOCK_SIZE (SGL_FIFO_UPLOAD_COMMAND_BLOCK_COUNT * sizeof(uint32_t)) diff --git a/src/client/glimpl.c b/src/client/glimpl.c index 7666ac0..ea8809c 100644 --- a/src/client/glimpl.c +++ b/src/client/glimpl.c @@ -18,6 +18,8 @@ #include #endif +#define GLIMPL_USES_SHARED_MEMORY (net_ctx == NULL) + #define GLIMPL_MAX_OBJECTS 256 #define GLIMPL_MAX_TEXTURES 8 @@ -256,7 +258,7 @@ void glimpl_submit() */ pb_push(0); - if (net_ctx == NULL) { + if (GLIMPL_USES_SHARED_MEMORY) { /* * lock */ @@ -365,7 +367,7 @@ void glimpl_report(int width, int height) void glimpl_swap_buffers(int width, int height, int vflip, int format) { - if (net_ctx == NULL) { + if (GLIMPL_USES_SHARED_MEMORY) { pb_push(SGL_CMD_REQUEST_FRAMEBUFFER); pb_push(width); pb_push(height); @@ -481,7 +483,7 @@ void glimpl_init() glimpl_major = gl_version_override ? gl_version_override[0] - '0' : pb_read(SGL_OFFSET_REGISTER_GLMAJ); glimpl_minor = gl_version_override ? gl_version_override[2] - '0' : pb_read(SGL_OFFSET_REGISTER_GLMIN); - if (network == NULL) { + if (GLIMPL_USES_SHARED_MEMORY) { lockg = pb_ptr(SGL_OFFSET_REGISTER_LOCK); /*