Graphics configuration and fine-tuning
This article provides guidance for the Linux VDA graphics configuration and fine-tuning.
For more information, see System requirements and the Installation overview section.
Configuration
Thinwire is the display remoting technology used in the Linux VDA. The technology allows graphics generated on one machine to be transmitted, typically across a network, to another machine for display.
The Use video codec for compression graphics policy sets the default graphics mode and provides the following options for different use cases:
- Use when preferred. This setting is the default. No additional configuration is required. It ensures that Thinwire is selected for all Citrix connections, and optimized for scalability, bandwidth, and superior image quality for typical desktop workloads.
- For the entire screen. Delivers Thinwire with full-screen H.264 or H.265 to optimize for improved user experience and bandwidth, especially in cases with heavy use of 3D graphics.
- For actively changing regions. The adaptive display technology in Thinwire identifies moving images (video, 3D in motion). It uses H.264 only in the part of the screen where the image is moving. The selective use of the H.264 video codec enables HDX Thinwire to detect and encode parts of the screen that are frequently updated using the H.264 video codec, for example, video content. Still image compression (JPEG, RLE) and bitmap caching continue to be used for the rest of the screen, including text and photographic imagery. Users get the benefit of lower bandwidth consumption and better quality for video content combined with lossless text or high quality imagery elsewhere. To enable this feature, change the policy setting Use video codec for compression to Use when preferred (default) or For actively changing regions. For more information, see Graphics policy settings. To enable H.264 hardware encoding for this feature, see Selective use of the H.264 hardware codec for actively changing regions.
Some other policy settings, including the following visual display policy settings can be used to fine-tune the performance of display remoting:
Parallel processing
Thinwire can improve the numbers of Frames Per Second (FPS) by parallelizing certain tasks, with the overhead of slightly higher overall CPU consumption. This feature is disabled by default. To enable the feature, run the following command on your VDA:
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKLM\System\CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "ParallelProcessing" -d "0x00000001" --force
<!--NeedCopy-->
Selective use of the H.264 hardware codec for actively changing regions
Starting with version 2204, the Linux VDA supports selective use of the H.264 hardware codec for actively changing regions. This feature offloads CPU video compression consumption to hardware and improves image quality and the number of frames per second (FPS). To enable the feature, do the following:
-
Enable the Use hardware encoding for video codec policy.
-
Enable the Use video codec for compression policy and select For actively changing regions.
Use H.264 for Build to Lossless in Thinwire
By default, the Build to Lossless preference of the Visual quality policy setting is now H.264 instead of JPEG for moving images.
H.264 encoding offers superior image quality. The Use video codec for compression policy controls that preference, with the default being Use when preferred. To force Build to Lossless to use JPEG, set the Use video codec for compression policy to Do not use video codec. If your client does not support Selective H.264, Build to Lossless falls back to JPEG regardless of the policy settings.
The following clients support Selective H.264:
- Citrix Receiver for Windows 4.9 through 4.12
- Citrix Receiver for Linux 13.5 through 13.10
- Citrix Workspace app 1808 for Windows and later
- Citrix Workspace app 1808 for Linux and later
For more information about the Visual quality and Use video codec for compression policy settings, see Visual display policy settings and Graphics policy settings.
Support for H.265 video codec
Starting with the 7.18 release, the Linux VDA supports the H.265 video codec for hardware acceleration of remote graphics and videos. You can use this feature on Citrix Receiver for Windows 4.10 through 4.12 and on Citrix Workspace app 1808 for Windows and later. To benefit from this feature, enable it on both the Linux VDA and on your client. If the GPU of your client doesn’t support H.265 decoding using the DXVA interface, the H.265 Decoding for graphics policy setting is ignored and the session falls back to using the H.264 video codec. For more information, see H.265 video encoding.
To enable H.265 hardware encoding on the VDA:
- Enable the Use hardware encoding for video codec policy.
- Enable the Optimize for 3D graphics workload policy
- Ensure that the Use video codec for compression policy is default or set to For the entire screen.
- Ensure that the Visual quality policy is NOT set to Build to Lossless or Always Lossless.
To enable H.265 hardware encoding on your client, see H.265 video encoding.
Support for YUV444 software encoding
The Linux VDA supports YUV444 software encoding. The YUV encoding scheme assigns both brightness and color values to each pixel. In YUV, ‘Y
’ represents the brightness or ‘luma
’ value, and ‘UV
’ represents the color or ‘chroma’ values. You can use this feature on Citrix Receiver for Windows 4.10 through 4.12 and on Citrix Workspace app 1808 for Windows and later.
Each unique Y, U, and V value comprises 8 bits, or one byte, of data. The YUV444 data format transmits 24 bits per pixel. The YUV422 data format shares U and V values between two pixels, which results in an average transmission rate of 16 bits per pixel. The following table shows an intuitive comparison between YUV444 and YUV420.
YUV444 | YUV420 |
---|---|
![]() |
![]() |
To enable YUV444 software encoding on the VDA:
- Enable the Allow visually lossless compression policy.
- Ensure that the Use video codec for compression policy is set to For the entire screen.
- Ensure that the Visual quality policy is set to Always Lossless or Build to Lossless.
Adjust average bit rates based on bandwidth estimates
Citrix enhances HDX 3D Pro hardware encoding by adjusting average bit rates based on bandwidth estimates.
When HDX 3D Pro hardware encoding is in use, the VDA can intermittently estimate the bandwidth of the network and adjust the bit rates of encoded frames accordingly. This new feature provides a mechanism to balance between sharpness and fluency.
This feature is enabled by default. To disable it, run the following command:
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "DisableReconfigureEncoder" -d "0x00000001" --force
<!--NeedCopy-->
In addition to using this feature, you can also run the following commands to adjust between sharpness and fluency. The AverageBitRatePercent and MaxBitRatePercent parameters set the percentage of bandwidth usage. The higher values you set, the sharper graphics and lower fluency you get. The recommended setting range is 50–100.
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "AverageBitRatePercent" -d "90" --force
sudo /opt/Citrix/VDA/bin/ctxreg create -k "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Citrix\Thinwire" -t "REG_DWORD" -v "MaxBitRatePercent" -d "100" --force
<!--NeedCopy-->
In the average bit rate adjustment, when your screen holds still, the most recent frame stays in a low-quality state because no new frames are sent. Sharpening support can address this issue by reconfiguring and immediately sending the most recent frame at the highest quality.
For a full list of the policies supported by the Linux VDA Thinwire, see Policy support list.
For information on the configuration of multi-monitor support on the Linux VDA, see CTX220128.
Graphics quality slider
We have included a graphics quality slider in the graphics status indicator tool that runs in your virtual Linux sessions. The slider helps to find the right balance between image quality and interactivity.
To use the slider, complete the following steps:
-
Enable the Graphic status indicator policy in Citrix Studio.
-
Open the Terminal and run the
ctxslider
command. The slider UI appears.Note:
If you have set the Visual Quality policy to Always Lossless or Build to Lossless, the slider UI is not showing.
The following choices are now available:
- To change the image quality, move the slider. The slider supports a range of 0–9.
- To use system-defined settings, select Let the system decide.
- To switch to lossless mode, select Pixel perfect.
Troubleshooting
Check which graphics mode is in use
Run the following command to check which graphics mode is in use (0 means TW+. 1 means full-screen video codec):
sudo /opt/Citrix/VDA/bin/ctxreg dump | grep GraphicsMode
<!--NeedCopy-->
The result resembles:
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "GraphicsMode" -d "0x00000000" --force
Check whether H.264 is in use
Run the following command to check whether H.264 is in use (0 means not in use. 1 means in use):
sudo /opt/Citrix/VDA/bin/ctxreg dump | grep H264
<!--NeedCopy-->
The result resembles:
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "H264" -d "0x00000000" --force
Check whether H.265 is in use
Run the following command to check whether full-screen H.265 is in use (0 means not in use. 1 means in use):
sudo /opt/Citrix/VDA/bin/ctxreg dump | grep H265
<!--NeedCopy-->
The result resembles:
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "H265" -d "0x00000000" --force
Check which YUV encoding scheme is in use
Run the following command to check which YUV encoding scheme is in use (0 means YUV420. 1 means YUV422. 2 means YUV444):
Note: The value of YUVFormat is meaningful only when a video codec is in use.
sudo /opt/Citrix/VDA/bin/ctxreg dump | grep YUVFormat
<!--NeedCopy-->
The result resembles:
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "YUVFormat" -d "0x00000000" --force
Check whether YUV444 software encoding is in use
Run the following command to check whether YUV444 software encoding is in use:
sudo /opt/Citrix/VDA/bin/ctxreg dump | grep Graphics
<!--NeedCopy-->
When YUV444 is in use, the result resembles:
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "GraphicsMode" -d "0x00000001" --force
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "H264" -d "0x00000001" --force
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "HardwareEncoding" -d "0x00000000" --force
create -k "HKLM\Software\Citrix\Ica\Session\4\Graphics" -t "REG_DWORD" -v "YUVFormat" -d "0x00000002" --force
Check whether hardware encoding is in use for 3D Pro
Run the following command (0 means not in use. 1 means in use):
sudo /opt/Citrix/VDA/bin/ctxreg dump | grep HardwareEncoding
<!--NeedCopy-->
The results resemble:
create -k "HKLM\Software\Citrix\Ica\Session\1\Graphics" -t "REG_DWORD" -v "HardwareEncoding" -d "0x00000001" --force
Another way is to use the nvidia-smi command. The outputs resemble the following if hardware encoding is in use:
Tue Apr 12 10:42:03 2016
+------------------------------------------------------+
| NVIDIA-SMI 361.28 Driver Version: 361.28 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
|===============================+======================+======================|
| 0 GRID K1 Off | 0000:00:05.0 Off | N/A |
| N/A 42C P0 14W / 31W | 207MiB / 4095MiB | 8% Default |
+-------------------------------+----------------------+----------------------+
+-----------------------------------------------------------------------------+
| Processes: GPU Memory |
| GPU PID Type Process name Usage |
|=============================================================================|
| 0 2164 C+G /usr/local/bin/ctxgfx 106MiB |
| 0 2187 G Xorg 85MiB |
+-----------------------------------------------------------------------------+
<!--NeedCopy-->
Verify that the NVIDIA GRID graphics driver is installed correctly
To verify that the NVIDIA GRID graphics driver is installed correctly, run nvidia-smi. The results resemble:
+------------------------------------------------------+
| NVIDIA-SMI 352.70 Driver Version: 352.70 |
|-------------------------------+----------------------+----------------------+
| GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
|===============================+======================+======================|
| 0 Tesla M60 Off | 0000:00:05.0 Off | Off |
| N/A 20C P0 37W / 150W | 19MiB / 8191MiB | 0% Default |
+-------------------------------+----------------------+----------------------+
+-----------------------------------------------------------------------------+
| Processes: GPU Memory |
| GPU PID Type Process name Usage |
|=============================================================================|
| No running processes found |
+-----------------------------------------------------------------------------+
<!--NeedCopy-->
Set the correct configuration for the card:
etc/X11/ctx-nvidia.sh
HDX 3D Pro multi-monitor redraw issues
If you are seeing redraw issues on screens other than the primary monitor, check that the NVIDIA GRID license is available.
Check Xorg error logs
The log file of Xorg is named similar to Xorg.{DISPLAY}.log in the /var/log/ folder.
Known issues and limitations
For vGPU, the Citrix Hypervisor local console shows the ICA desktop session screen
Workaround: Disable the VM’s local VGA console by running the following commands:
For Citrix Hypervisor 8.1 and later:
[root@xenserver ~]# xe vgpu-param-set uuid=vgpu-uuid extra_args=disable_vnc=1
<!--NeedCopy-->
For Citrix Hypervisor earlier than 8.1:
xe vm-param-set uuid=<vm-uuid> platform:vgpu_extra_args="disable_vnc=1"
<!--NeedCopy-->
NVIDIA K2 graphics cards do not support YUV444 hardware encoding in pass-through mode
With Build to Lossless enabled through the policy setting, a black or gray screen appears when users are launching an app/desktop session with an NVIDIA K2 graphics card. The issue occurs because NVIDIA K2 graphics cards do not support YUV444 hardware encoding in pass-through mode. For more information, see Video Encode and Decode GPU Support Matrix.
Gnome 3 desktop popups slow when logging on
It is a limitation of Gnome 3 desktop session startup.
Some OpenGL/WebGL applications do not render well upon resizing the Citrix Workspace app window
Resizing the window of Citrix Workspace app changes the screen resolution. The NVIDIA proprietary driver changes some internal states and might require applications to respond accordingly. For example, the WebGL library element lightgl.js might spawn an error saying that ‘Rendering to this texture is not supported (incomplete frame buffer)
’.