Client usage

looking-glass-client [--help] [-f] [-F] [-s] [-S] [options...]

Command line options

A full list of command line options is available with the --help or -h options.

Example: looking-glass-client --help

Common options are listed below:

Short option	Description
`-f shmFile`	use `shmFile` for IVSHMEM shared memory
`-F`	automatically enter full screen
`-s`	disable spice
`-S`	disable host screensaver

Options may be provided in short form when available, or long form. Boolean options may be specified without a parameter to toggle their state.

Examples:

looking-glass-client -F (short)
looking-glass-client win:fullScreen (long)
looking-glass-client -f /dev/shm/my-lg-shmem (short with parameter)
looking-glass-client app:shmFile=/dev/shm/my-lg-shmem (long with parameter)

Default key bindings

By default, Looking Glass uses the ScrLk 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
`ScrLk`	Toggle capture mode
`ScrLk` + `Q`	Quit
`ScrLk` + `E`	Toggle audio recording
`ScrLk` + `R`	Rotate the output clockwise by 90° increments
`ScrLk` + `T`	Show frame timing information
`ScrLk` + `I`	Spice keyboard & mouse enable toggle
`ScrLk` + `O`	Toggle overlay
`ScrLk` + `D`	FPS display toggle
`ScrLk` + `F`	Full screen toggle
`ScrLk` + `V`	Video stream toggle
`ScrLk` + `N`	Toggle night vision mode
`ScrLk` + `F1`	Send `Ctrl` + `Alt` + `F1` to the guest
`ScrLk` + `F2`	Send `Ctrl` + `Alt` + `F2` to the guest
`ScrLk` + `F3`	Send `Ctrl` + `Alt` + `F3` to the guest
`ScrLk` + `F4`	Send `Ctrl` + `Alt` + `F4` to the guest
`ScrLk` + `F5`	Send `Ctrl` + `Alt` + `F5` to the guest
`ScrLk` + `F6`	Send `Ctrl` + `Alt` + `F6` to the guest
`ScrLk` + `F7`	Send `Ctrl` + `Alt` + `F7` to the guest
`ScrLk` + `F8`	Send `Ctrl` + `Alt` + `F8` to the guest
`ScrLk` + `F9`	Send `Ctrl` + `Alt` + `F9` to the guest
`ScrLk` + `F10`	Send `Ctrl` + `Alt` + `F10` to the guest
`ScrLk` + `F11`	Send `Ctrl` + `Alt` + `F11` to the guest
`ScrLk` + `F12`	Send `Ctrl` + `Alt` + `F12` to the guest
`ScrLk` + `M`	Send mute to the guest
`ScrLk` + `↑`	Send volume up to the guest
`ScrLk` + `↓`	Send volume down to the guest
`ScrLk` + `Insert`	Increase mouse sensitivity in capture mode
`ScrLk` + `Del`	Decrease mouse sensitivity in capture mode
`ScrLk` + `LWin`	Send `LWin` to the guest
`ScrLk` + `RWin`	Send `RWin` to the guest

You can also find this list at any time by holding down ScrLk.

Configuration files

By default, Looking Glass will load config files from the following locations:

/etc/looking-glass-client.ini
~/.looking-glass-client.ini
$XDG_CONFIG_HOME/looking-glass/client.ini (usually ~/.config/looking-glass/client.ini)

All config files are loaded in order. Duplicate entries override earlier ones. This means you can set a system-wide configuration in /etc/looking-glass-client.ini, and override specific options for just your user in ~/.looking-glass-client.ini, which is overlayed on top of the system-wide configuration.

When first launched, the Looking-Glass client will create the folder $XDG_CONFIG_HOME/looking-glass/ if it does not yet exist.

The format of config files is the commonly known INI format, for example:

[win]
fullScreen=yes

[egl]
nvGain=1

; this is a comment

Command line arguments will override any options loaded from config files.

Overlay mode

The Overlay Mode lets you configure various runtime options for Looking Glass. These include:

EGL filters
Performance metrics options
Debug frame damage display

(see Configuration widget)

You can also reposition and resize enabled widgets, like the FPS/UPS display, and performance metrics.

Enter and exit Overlay Mode with ScrLk + O. ESC can also be used to exit. (see Default key bindings)

Modifications done to widgets in overlay mode are stored in $XDG_CONFIG_HOME/looking-glass/imgui.ini. Please do not manually edit this file while Looking Glass is running, as your changes may be discarded.

Configuration widget

The configuration widget is accessible through the overlay mode. The widget has multiple tabs that allow setting a variety of modes and parameters for Looking Glass at runtime.

Settings tab

Performance Metrics: A toggle for the performance metrics widget. Multiple graphs are available, and they will stack vertically.
EGL: Modify EGL settings, such as the algorithm used for scaling, and night vision mode.

Changes in the settings tab are not persistent, and will be reset back to their default values when the client is restarted.

EGL filters tab

The EGL filters tab contains options for toggling, configuring, and ordering post-processing filters. Each filter can be expanded to open its settings. Filters can also be re-ordered by dragging them up or down. Filters are applied from top to bottom. Keep this in mind when ordering them – for example, applying CAS before FSR might have different results than the reverse. Users are encouraged to experiment with the order and parameters to achieve optimal results. The currently available filters include:

Downscaler: Filter for downscaling the host resolution. Can be used to undo poor upscaling on the VM to better utilize AMD FSR (see below). The filter has a pixel-size setting that is used to set the effective downscaling ratio, and a configurable interpolation algorithm.
AMD FidelityFX Super Resolution (FSR): Spatial upscaling filter that works on low resolution frames from the guest VM and intelligently upscales to a higher resolution. The filter sharpness is tunable, and displays the equivalent AMD quality mode based on the resolution difference.
AMD FidelityFX Contrast Adaptive Sharpening (CAS): Filter that increases visual quality by applying a sharpening algorithm to the video. CAS can sometimes restore detail lost in a typical upscaling application. Has adjustable sharpness setting.

The filter settings and order can be saved to presets so that it can be restored at a later time. As filter settings are usually application specific, multiple presets can be defined for each case scenario. To save a preset, click on “Save preset as…” and enter a preset name. Presets are loaded by selecting them in the Preset name pull down. Presets are persistent and are stored on disk at $XDG_CONFIG_HOME/looking-glass/presets.

Warning

Please refrain from modifying any files under the presets folder. Those files are meant to be modified only by the Looking-Glass client.

Note

Although presets are persistent, the client will not remember which preset was used last session, so a preset needs to be recalled once the client starts.

All command line options

Long

Short

Value

Description

app:configFile

-C

NULL

A file to read additional configuration from

app:renderer

-g

EGL

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 supported (see README.md in the module dir)

app:shmFile

-f

/dev/kvmfr0

The path to the shared memory file, or the name of the kvmfr device to use, e.g. 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:intUpscale

no

Allow only integer upscaling

win:shrinkOnUpscale

no

Limit the window dimensions when dontUpscale is enabled

win:borderless

-d

no

Borderless mode

win:fullScreen

-F

no

Launch in fullscreen borderless mode

win:maximize

-T

no

Launch window maximized

win:minimizeOnFocusLoss

no

Minimize window on focus loss

win:fpsMin

-K

-1

Frame rate minimum (0 = disable - not recommended, -1 = auto detect)

win:ignoreQuit

-Q

no

Ignore requests to quit (i.e. Alt+F4)

win:noScreensaver

-S

yes

Prevent the screensaver from starting

win:autoScreensaver

no

Prevent the screensaver from starting when guest requests it

win:alerts

-q

yes

Show on screen alert messages

win:quickSplash

no

Skip fading out the splash screen when a connection is established

win:overlayDimsDesktop

no

Dim the desktop when in interactive overlay mode

win:rotate

0

Rotate the displayed image (0, 90, 180, 270)

win:uiFont

DejaVu Sans Mono

The font to use when rendering on-screen UI

win:uiSize

14

The font size to use when rendering on-screen UI

win:jitRender

no

Enable just-in-time rendering

win:requestActivation

yes

Request activation when attention is needed

win:showFPS

-k

no

Enable the FPS & UPS display

Long

Short

Value

Description

input:captureOnFocus

no

Enable capture mode when the window becomes focused

input:grabKeyboard

-G

yes

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/menu key to use (use “help” to see 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

yes

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

input:helpMenuDelay

200

Show help menu after holding down the escape key for this many milliseconds

Long

Short

Value

Description

spice:enable

-s

yes

Enable the built in SPICE client for input and/or clipboard support

spice:host

-c

/opt/PVM/vms/Windows/windows.sock

The SPICE server host or UNIX socket

spice:port

-p

0

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 synchronize the clipboard contents with the guest

spice:clipboardToVM

yes

Allow the clipboard to be synchronized TO the VM

spice:clipboardToLocal

yes

Allow the clipboard to be synchronized FROM the VM

spice:audio

yes

Enable SPICE audio support

spice:scaleCursor

-j

yes

Scale cursor input position to screen size when up/down scaled

spice:captureOnStart

no

Capture mouse and keyboard on start

spice:alwaysShowCursor

no

Always show host cursor

spice:showCursorDot

yes

Use a “dot” cursor when the window does not have focus

spice:largeCursorDot

yes

Use a larger version of the “dot” cursor

Long

Short

Value

Description

audio:periodSize

256

Requested audio device period size in samples

audio:bufferLatency

12

Additional buffer latency in milliseconds

audio:micDefault

allow

Default action when an application opens the microphone (prompt, allow, deny)

audio:micShowIndicator

yes

Display microphone usage indicator

audio:syncVolume

yes

Synchronize the volume level with the guest

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)

egl:scale

0

Set the scale algorithm (0 = auto, 1 = nearest, 2 = linear)

egl:debug

no

Enable debug output

egl:noBufferAge

no

Disable partial rendering based on buffer age

egl:noSwapDamage

no

Disable swapping with damage

egl:scalePointer

yes

Keep the pointer size 1:1 when downscaling

egl:mapHDRtoSDR

yes

Map HDR content to the SDR color space

egl:peakLuminance

250

The peak luminance level in nits for HDR to SDR mapping

egl:maxCLL

10000

Maximum content light level in nits for HDR to SDR mapping

egl:preset

NULL

The initial filter preset to load

Long

Short

Value

Description

opengl:mipmap

yes

Enable mipmapping

opengl:vsync

no

Enable vsync

opengl:preventBuffer

yes

Prevent the driver from buffering frames

opengl:amdPinnedMem

yes

Use GL_AMD_pinned_memory if it is available

Long

Short

Value

Description

wayland:warpSupport

yes

Enable cursor warping

wayland:fractionScale

yes

Enable fractional scale

Long

Short

Value

Description

i3:globalFullScreen

yes

Use i3’s global full screen feature (spans all monitors)

Long

Short

Value

Description

pipewire:outDevice

Looking Glass

The default playback device to use

pipewire:recDevice

PureNoise Mic

The default record device to use

Host usage

By default the host application will simply work however there are some configurable options available. While the host application will accept command line arguments, it is more convenient to create a looking-glass-host.ini config file for persistent configuration changes.

This file must be placed in the same directory as the Looking Glass host, by default C:\Program Files\Looking Glass (host)\.

Capture interface

Note

Currently we only provide support for the Windows host application, Linux options are not currently documented.

Currently under windows there are three capture interfaces available for use, by default the most compatible and commonly supported interface is selected however this can be changed via the ini file with the following configuration:

[app]
capture=<INTERFACE>

Where <INTERFACE> is one of d12, dxgi or nvfbc

DXGI Desktop Duplication Caveat

Due to the design of Microsoft’s DXGI API and the decision made to roll hardware cursor updates into the capture stream this interface can suffer from microstutters when the mouse is being moved/updated. This issue only affects guest applications that make use of the hardware cursor instead of compositing the cursor directly, as such titles that do not use a mouse (most FPV games) are not affected.

Most people will not even notice this, but it needs to be said for those that do so that we do not get flooded with support requests for something we can not fix.

DirectX 12 DXGI Desktop Duplication

This interface (D12) is the default and most performant capture interface for Windows 10 and later having been introduced with the Beta 7 release of Looking Glass. Impressively this new capture engine is faster then NvFBC, and has fewer overheads. This is because this interface can capture and download the captured frames directly from the GPU into the shared memory interface.

D12 Configuration Options

adapter - The name of the specific adapter you wish to capture
output - The name of the specific output you wish to capture
trackDamage - Default enabled, this saves bandwidth by only updating and transferring the regions of the capture that have changed since the last frame.
debug - Enables DirectX 12 debugging and validation, only enable this if you’re having problems and have been told to do so by our support team. Note that you must have the DirectX SDK installed for this to work.
downsample - See Downsampling
HDR16to10 - Converts HDR16/8bpp content to HDR10/4bpp to save bandwidth. Note that this incurs additional overheads in the guest and may decrease performance. Default enabled, but only active if HDR is enabled in Windows.
allowRGB24 - Losslessly packs 32-bit RGBA8 content into 24-bit RGB by omitting the unused alpha channel. This saves bandwidth but requires additional processing so may not yield a performance increase. Might be helpful if you’re already bandwidth constrained. Default disabled.

DirectX 11 DXGI Desktop Duplication

This interface (DXGI) is the most compatible capture interface for Windows, unfortunately though it does suffer from several drawbacks over other options. If the DirectX 12 (D12) capture interface fails to initialize Looking Glass will automatically fall back to using this capture interface instead.

Due to the design of Microsoft’s DXGI API and the decision made to roll hardware cursor updates into the capture stream this interface can suffer from microstutters when the mouse is being moved/updated. This issue only affects guest applications that make use of the hardware cursor instead of compositing the cursor directly, as such titles that do not use a mouse (most FPV games) are not affected.

The other drawback of this API is the overall system overhead as it requires copying the captured frames into a staging buffer before it is copied into the shared memory area.

DXGI Configuration Options

adapter - The name of the specific adapter you wish to capture
output - The name of the specific output you wish to capture
maxTextures - The maximum number of frames to buffer before skipping frames. Default is 4 however realistically the this limit should never be reached unless the Looking Glass client application is not keeping up.
useAcquireLock - Enable locking around AcquireNextFrame. This is an experimental feature and should be left enabled if you’re not sure. Default is enabled.
dwmFlush - Use DwmFlush to sync the capture to the windows presentation interval. This is experimental and may degrade performance. Default is disabled.
disableDamage - Default is false. This disables damage tracking which normally would save bandwidth by only updating and transferring the regions of the capture that have changed since the last frame.
debug - Enables DirectX 11 debugging, only enable this if you’re having problems and have been told to do so by our support team. Note that you must have the DirectX SDK installed for this to work.
allowRGB24 - Losslessly packs 32-bit RGBA8 content into 24-bit RGB by omitting the unused alpha channel. This saves bandwidth but requires additional processing so may not yield a performance increase. Might be helpful if you’re already bandwidth constrained. Default enabled.
downsample - See Downsampling

NVIDIA Frame Buffer Capture

Due to the NVIDIA SDK License agreement this GPU feature is only available on professional/workstation GPUs such as the Quadro series. It is known however that all NVIDIA GPUs are capable of this as both GeForce Experience and Steam are able to make use of it.

If you are able to make use/enable this this feature it offers lower overall system load and lower latency capture, and does not suffer from the mouse motion stutter issues that DXGI suffers from.

Note

As of Looking Glass Beta 7, the D12 capture interface is faster then NvFBC while also reducing the memory bandwidth requirements. We recommend migrating to D12 if at all possible.

To enable its usage use the following configuration in the looking-glass-host.ini file:

[app]
capture=nvfbc

If this feature is unavailable to you the host application will fail to start and the host log will contain an error stating that the feature is not available.

NvFBC Configuration Options

decoupleCursor - This option prevents the cursor from being composited before capture onto the captured frame, and instead sends cursor updates to the client independent of frame updates. Default is true.
diffRes - The resolution of the differential map, see the NvFBC capture SDK documentation for more information. Default is 128.
adapterIndex - If you have multiple adapters, you can select which to use with this option. Default is to select the first valid device.
dwmFlush - Use DwmFlush to sync the capture to the windows presentation interval. This is experimental and may degrade performance. Default is disabled.
noHDR - Force NvFBC to capture HDR content as SDR. Default is enabled.
downsample - See Downsampling

This capture interface also looks for and reads the value of the system environment variable NVFBC_PRIV_DATA if it has been set, documentation on its usage however is unavailable (Google is your friend).

Selecting an IVSHMEM device

For those attaching multiple IVSHMEM devices to their Virtual Machines, you must configure the Looking Glass host to use the correct device. By default the first device is selected.

The os:shmDevice option configures which device is used. These are ordered by PCI slot and count up from 0 (default), with 0 being the first IVSHMEM device in the lowest slot.

[os]
; Select the second IVSHMEM device
shmDevice=1

Note

os:shmDevice ignores the actual PCI slot number, instead selecting the Nth slot occupied by an IVSHMEM device. For example: with only two IVSHMEM devices in slots 0x03 and 0x05, the device in slot 0x03 will be referred to by 0 (first shm device), and the device in 0x05 by 1 (second shm device).

PCI slot numbers are visible in Device Manager:

Double-click any “IVSHMEM device” in Device Manager (devmgmt.msc)
Find the slot number in the “Location:” field. (e.g. PCI slot 5)

You can also find a listing of IVSHMEM devices in the looking-glass-host.txt log file, with slot numbers shown next to “device” (asterisk indicates currently selected device):

[I]     19989544      …      IVSHMEM 0  on bus 0x6, device 0x3, function 0x0
[I]     19990438      …      IVSHMEM 1* on bus 0x6, device 0x5, function 0x0

Downsampling

The host application is able to downsample the captured frame before transfer to the client application, this provides an opportunity to save some bandwidth on memory constrained systems. It also makes it possible to run the guest at a substantially higher resolution then your actual monitor for a super scaling type effect, without having to incur the bandwidth penalty that would normally occur when doing this.

The configuration for this is fairly straightforward and is defined as set of rules to determine when to perform this downsampling. The format is as follows:

(>|>=)(WIDTH)x(HEIGHT):(TARGET WIDTH)x(TARGET HEIGHT)

Examples:

; Downsample exactly 3840x2160 to 1920x1080
downsample=3840x2160:1920x1080

; Downsample anything greater then 1920x1080 to 1920x1080
downsample=>1920x1080:1920x1080

; Downsample 3840x2160 to 1920x1080, or 3840x2400 to 1920x1200
downsample=3840x2160:1920x1080,3840x2400:1920x1200