mirrors/looking-glass
2
0
Fork 0
mirror of https://github.com/gnif/LookingGlass.git synced 2024-12-23 14:21:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
looking-glass/client/README.md

200 lines
14 KiB
Markdown
Raw Normal View History

[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
# Looking Glass Client
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
This is the Looking Glass client application that is designed to work in tandem with the Looking Glass Host application
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
---
## Building the Application
### Build Dependencies
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
* binutils-dev
* cmake
* fonts-freefont-ttf
* libsdl2-dev
* libsdl2-ttf-dev
* libspice-protocol-dev
* libfontconfig1-dev
* libx11-dev
* nettle-dev
[client] doc: update README.md with new libraries and backend config
2021-01-20 04:33:56 +00:00
* libxss-dev
* libxi-dev
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
#### Debian (and maybe Ubuntu)
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[client] doc: update README.md with new libraries and backend config
2021-01-20 04:33:56 +00:00
apt-get install binutils-dev cmake fonts-freefont-ttf libsdl2-dev libsdl2-ttf-dev libspice-protocol-dev libfontconfig1-dev libx11-dev nettle-dev libxss-dev libxi-dev
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
### Building
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
mkdir build
cd build
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
cmake ../
make
[doc] fixed another formatting snafu
2019-05-23 10:20:18 +00:00
Should this all go well you should be left with the file `looking-glass-client`
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
[client] doc: update README.md with new libraries and backend config
2021-01-20 04:33:56 +00:00
### Removing Wayland or X11 support
Wayland and/or X11 support can be disabled with the compile options
[client] readme: remove mention of SDL SDL is default to off and its usage should not be encouraged, so -DENABLE_SDL=ON is not mentioned as an option in the README.
2021-02-25 23:10:48 +00:00
`ENABLE_WAYLAND=NO` and `ENABLE_X11=NO`. It is an error to disable both backends.
[client] doc: update README.md with new libraries and backend config
2021-01-20 04:33:56 +00:00
cmake ../ -DENABLE_WAYLAND=OFF
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
---
## Usage Tips
### Key Bindings
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
By default Looking Glass uses the `Scroll Lock` key as the escape key for commands as well as the input capture mode toggle, this can be changed using the `-m` switch if you desire a different key.
Below are a list of current key bindings:
| Command | Description |
|-|-|
[client] main: new feature to increase/decrease mouse sensitivity
2019-05-23 19:29:38 +00:00
| <kbd>ScrLk</kbd> | Toggle cursor screen capture |
| <kbd>ScrLk</kbd>+<kbd>F</kbd> | Full Screen toggle |
[client] add new keybind to toggle the video stream (ScrLck+V)
2020-10-14 08:32:21 +00:00
| <kbd>ScrLk</kbd>+<kbd>V</kbd> | Video stream toggle |
[client] main: new feature to increase/decrease mouse sensitivity
2019-05-23 19:29:38 +00:00
| <kbd>ScrLk</kbd>+<kbd>I</kbd> | Spice keyboard & mouse enable toggle |
| <kbd>ScrLk</kbd>+<kbd>N</kbd> | Toggle night vision mode (EGL renderer only!) |
[client] doc: added `win:rotate` and keybind to README.md
2021-01-20 04:36:14 +00:00
| <kbd>ScrLk</kbd>+<kbd>R</kbd> | Rotate the output clockwise by 90 degree increments |
[client] add quit keybind
2020-04-22 16:31:30 +00:00
| <kbd>ScrLk</kbd>+<kbd>Q</kbd> | Quit |
[client] fix typo
2019-05-23 19:31:16 +00:00
| <kbd>ScrLk</kbd>+<kbd>Insert</kbd> | Increase mouse sensitivity (in capture mode only) |
| <kbd>ScrLk</kbd>+<kbd>Del</kbd> | Decrease mouse sensitivity (in capture mode only) |
[client] README.md cosmetics
2019-05-31 06:45:55 +00:00
| <kbd>ScrLk</kbd>+<kbd>F1</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F1</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F2</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F2</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F3</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F3</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F4</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F4</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F5</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F5</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F6</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F6</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F7</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F7</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F8</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F8</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F9</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F9</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F10</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F10</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F11</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F11</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>F12</kbd> | Send <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>F12</kbd> to the guest |
[client] doc: updated the readme with the latest options and bindings
2021-01-04 07:45:54 +00:00
| <kbd>ScrLk</kbd>+<kbd>LWin</kbd> | Send <kbd>LWin</kbd> to the guest |
| <kbd>ScrLk</kbd>+<kbd>RWin</kbd> | Send <kbd>RWin</kbd> to the guest |
[client] README.md cosmetics
2019-05-31 06:45:55 +00:00
[client] updated documentation for new keybinds
2019-05-31 06:44:08 +00:00
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
### Setting options via command line arguments
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
The syntax is simple: `module:name=value`, for example:
[client] Fix typo in example of README.md
2019-05-24 16:09:14 +00:00
./looking-glass-client win:fullScreen=yes egl:nvGain=1
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
### Setting options via configuration files
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
By default the application will look for and load the config files in the following locations
* /etc/looking-glass-client.ini
* ~/.looking-glass-client.ini
The format of this file is the commonly known INI format, for example:
[win]
fullScreen=yes
[egl]
nvGain=1
Command line arguments will override any options loaded from the config files.
[doc] fix formatting a bit
2019-05-23 10:19:37 +00:00
### Supported options
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
```
[client] doc: updated the readme with the latest options and bindings
2021-01-04 07:45:54 +00:00
|--------------------------------------------------------------------------------------------------------------------------------------------------|
| Long | Short | Value | Description |
|--------------------------------------------------------------------------------------------------------------------------------------------------|
| app:configFile | -C | NULL | A file to read additional configuration from |
| app:renderer | -g | auto | Specify the renderer to use |
| app:license | -l | no | Show the license for this application and then terminate |
| app:cursorPollInterval | | 1000 | How often to check for a cursor update in microseconds |
| app:framePollInterval | | 1000 | How often to check for a frame update in microseconds |
| app:allowDMA | | yes | Allow direct DMA transfers if possible (VM-VM only for now) |
| app:shmFile | -f | /dev/shm/looking-glass | The path to the shared memory file, or the name of the kvmfr device to use, ie: kvmfr0 |
|--------------------------------------------------------------------------------------------------------------------------------------------------|
|---------------------------------------------------------------------------------------------------------------------------------|
| Long | Short | Value | Description |
|---------------------------------------------------------------------------------------------------------------------------------|
| win:title | | Looking Glass (client) | The window title |
| win:position | | center | Initial window position at startup |
| win:size | | 1024x768 | Initial window size at startup |
| win:autoResize | -a | no | Auto resize the window to the guest |
| win:allowResize | -n | yes | Allow the window to be manually resized |
| win:keepAspect | -r | yes | Maintain the correct aspect ratio |
| win:forceAspect | | yes | Force the window to maintain the aspect ratio |
| win:dontUpscale | | no | Never try to upscale the window |
| win:borderless | -d | no | Borderless mode |
| win:fullScreen | -F | no | Launch in fullscreen borderless mode |
| win:maximize | -T | no | Launch window maximized |
| win:minimizeOnFocusLoss | | yes | Minimize window on focus loss |
| win:fpsMin | -K | -1 | Frame rate minimum (0 = disable - not recommended, -1 = auto detect) |
| win:showFPS | -k | no | Enable the FPS & UPS display |
| win:ignoreQuit | -Q | no | Ignore requests to quit (ie: Alt+F4) |
| win:noScreensaver | -S | no | Prevent the screensaver from starting |
| win:alerts | -q | yes | Show on screen alert messages |
| win:quickSplash | | no | Skip fading out the splash screen when a connection is established |
[client] doc: added `win:rotate` and keybind to README.md
2021-01-20 04:36:14 +00:00
| win:rotate | | 0 | Rotate the displayed image (0, 90, 180, 270) |
[client] doc: updated the readme with the latest options and bindings
2021-01-04 07:45:54 +00:00
|---------------------------------------------------------------------------------------------------------------------------------|
[client] input: add releaseKeysOnFocusLoss option This makes dealing with window manager shortcuts that overlap with guest keys more pleasant, while retaining the previous functionality for users who prefer it. For instance, previously, using Alt+Tab (or $mod as Alt in i3/sway movement commands) would result in the guest retaining Alt as pressed. When the guest regained focus, it would continue thinking Alt is pressed, leading to accidentally triggering obscure shortcuts. One had to remember to press Alt again to "unstick" things, which was suboptimal.
2021-02-13 07:19:01 +00:00
|-----------------------------------------------------------------------------------------------------------------------------------------------|
| Long | Short | Value | Description |
|-----------------------------------------------------------------------------------------------------------------------------------------------|
| input:grabKeyboard | -G | no | Grab the keyboard in capture mode |
| input:grabKeyboardOnFocus | | no | Grab the keyboard when focused |
| input:releaseKeysOnFocusLoss | | yes | On focus loss, send key up events to guest for all held keys |
| input:escapeKey | -m | 70 = KEY_SCROLLLOCK | Specify the escape key, see <linux/input-event-codes.h> for valid values |
| input:ignoreWindowsKeys | | no | Do not pass events for the windows keys to the guest |
| input:hideCursor | -M | yes | Hide the local mouse cursor |
| input:mouseSens | | 0 | Initial mouse sensitivity when in capture mode (-9 to 9) |
| input:mouseSmoothing | | yes | Apply simple mouse smoothing when rawMouse is not in use (helps reduce aliasing) |
| input:rawMouse | | no | Use RAW mouse input when in capture mode (good for gaming) |
| input:mouseRedraw | | yes | Mouse movements trigger redraws (ignores FPS minimum) |
| input:autoCapture | | no | Try to keep the mouse captured when needed |
| input:captureOnly | | no | Only enable input via SPICE if in capture mode |
|-----------------------------------------------------------------------------------------------------------------------------------------------|
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[doc] client: document defaults instead of my preconfigured values
2019-05-23 10:26:37 +00:00
|------------------------------------------------------------------------------------------------------------------|
| Long | Short | Value | Description |
|------------------------------------------------------------------------------------------------------------------|
| spice:enable | -s | yes | Enable the built in SPICE client for input and/or clipboard support |
| spice:host | -c | 127.0.0.1 | The SPICE server host or UNIX socket |
| spice:port | -p | 5900 | The SPICE server port (0 = unix socket) |
| spice:input | | yes | Use SPICE to send keyboard and mouse input events to the guest |
| spice:clipboard | | yes | Use SPICE to syncronize the clipboard contents with the guest |
| spice:clipboardToVM | | yes | Allow the clipboard to be syncronized TO the VM |
| spice:clipboardToLocal | | yes | Allow the clipboard to be syncronized FROM the VM |
| spice:scaleCursor | -j | yes | Scale cursor input position to screen size when up/down scaled |
update client/README.md: spice:captureOnStart from #278
2020-08-18 22:14:27 +00:00
| spice:captureOnStart | | no | Capture mouse and keyboard on start |
[client] add option to always show cursor
2020-11-15 13:41:22 +00:00
| spice:alwaysShowCursor | | no | Always show host cursor |
[doc] client: document defaults instead of my preconfigured values
2019-05-23 10:26:37 +00:00
|------------------------------------------------------------------------------------------------------------------|
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
[client] doc: updated the readme with the latest options and bindings
2021-01-04 07:45:54 +00:00
|--------------------------------------------------------------------------------------------------------------|
| Long | Short | Value | Description |
|--------------------------------------------------------------------------------------------------------------|
| egl:vsync | | no | Enable vsync |
| egl:doubleBuffer | | no | Enable double buffering |
| egl:multisample | | yes | Enable Multisampling |
| egl:nvGainMax | | 1 | The maximum night vision gain |
| egl:nvGain | | 0 | The initial night vision gain at startup |
| egl:cbMode | | 0 | Color Blind Mode (0 = Off, 1 = Protanope, 2 = Deuteranope, 3 = Tritanope) |
|--------------------------------------------------------------------------------------------------------------|
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
|------------------------------------------------------------------------------------|
| Long | Short | Value | Description |
|------------------------------------------------------------------------------------|
| opengl:mipmap | | yes | Enable mipmapping |
[client] set default opengl:vsync=off This makes it consistent with the EGL renderer.
2021-01-04 03:19:46 +00:00
| opengl:vsync | | no | Enable vsync |
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
| opengl:preventBuffer | | yes | Prevent the driver from buffering frames |
| opengl:amdPinnedMem | | yes | Use GL_AMD_pinned_memory if it is available |
|------------------------------------------------------------------------------------|
[client] wayland: add option to enable cursor warp This is enabled on default. Specify wayland:warpSupport=no to disable it, which may be useful on certain compositors that do not warp when the pointer is confined.
2021-02-16 01:54:02 +00:00
|-------------------------------------------------------------|
| Long | Short | Value | Description |
|-------------------------------------------------------------|
| wayland:warpSupport | | yes | Enable cursor warping |
|-------------------------------------------------------------|
[doc] Updated project documentation in leu of Beta 1 release
2019-05-23 10:13:41 +00:00
```
Reference in a new issue Copy permalink