Using the Skia+GTK head

Important

The Skia+Gtk support is being retired as of Uno Platform 5.2. The package will continue to be available until further notice and the latest apps should be moving to the Skia Desktop support.

Uno supports running applications using Gtk+3 shell, using a Skia backend rendering. Gtk3+ is used to create a shell for the application to be used on various operating systems, such as Linux, Windows, and macOS.

Depending on the target platform, the UI rendering may be using OpenGL or software rendering.

Note that for Linux, the FrameBuffer rendering head is also available.

Get started with the Skia+GTK head

Follow the getting started guide for VS Code or Visual Studio 2022, make sure to use Uno Platform 5.1 templates to get it.

Additional setup

In order to run Skia+GTK heads, you will need to make sure to install the GTK3 runtime.

Tip

Once the GTK3 runtime is installed, you will need restart your IDE for the changes to take effect.

To install on CI using Azure Pipelines, use the following step:

steps:
  - powershell: |
        $source = "https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases/download/2020-07-15/gtk3-runtime-3.24.20-2020-07-15-ts-win64.exe"
        $destination = "gtk3-runtime.exe"
        Invoke-WebRequest $source -OutFile $destination
        Start-Process -FilePath "gtk3-runtime.exe" -Wait -PassThru -ArgumentList /S
        Write-Host "##vso[task.setvariable variable=PATH;]${env:PATH};C:\Program Files\GTK3-Runtime Win64\bin";

    displayName: Install GTK3 runtime

Install the required dependencies:

sudo apt update
sudo apt-get install mesa-utils libgl1-mesa-glx ttf-mscorefonts-installer dbus libfontconfig1 libxrandr2

Update system and packages
```
pacman -Syu
```

Install the necessary dependencies

sudo pacman -S dotnet-targeting-pack dotnet-sdk dotnet-host dotnet-runtime python ninja gn aspnet-runtime dbus libxrandr

You may also need to install the Microsoft fonts manually.

If you are using Windows Subsystem for Linux (WSL), you can find specific instructions in the following video:

In order to run Skia+GTK heads, you will need to make sure to install gtk+3 package using the following command line, using homebrew:

brew install gtk+3

Once done, you can create a new app with dotnet new using:

dotnet new unoapp --preset=blank -o MyApp

or by using the Visual Studio "project new" templates.

Changing the rendering target

It may be required, depending on the environment, to use software rendering.

To do so, immediately before the line host.Run() in you Program.cs file, add the following:

host.RenderSurfaceType = RenderSurfaceType.Software;

Hosting Native GTK Controls

Hosting native GTK controls is supported through ContentPresenter and ContentControl. For more information, see embedding native controls.

Linux considerations

When running under Linux, GTK can use OpenGL for the UI rendering but some restrictions can apply depending on the environment and available hardware.

When running under Wayland, to enable OpenGL acceleration, you may need to set the GDK_BACKEND environment variable to x11 before running your application.
When running under Wayland and running with OpenGL ES 3.3 or later (using glxinfo to confirm), you may need to set the GDK_GL environment variable to gles before running your application.

Troubleshooting OpenGL integration

Enabling debug logging messages for the GTK Host can help diagnose the render surface type selection.

In your App.xaml.cs file, change the minimum log level to:

builder.SetMinimumLevel(LogLevel.Debug);

Then change the logging level of the GTK Host to Information or Debug:

builder.AddFilter("Uno.UI.Runtime.Skia", LogLevel.Information);

You may also need to initialize the logging system earlier than what is found in Uno.UI's default templates by calling this in Main:

YourAppNamespace.App.ConfigureFilters(); // Enable tracing of the GTK host

Upgrading to a later version of SkiaSharp

By default, Uno comes with a set of SkiaSharp dependencies set by the Uno.UI.Runtime.Skia.Gtk package.

If you want to upgrade SkiaSharp to a later version, you'll need to specify all packages individually in your project as follows:

<ItemGroup>
   <PackagReference Include="SkiaSharp" Version="2.88.7" />
   <PackagReference Include="SkiaSharp.Harfbuzz" Version="2.88.7" />
   <PackagReference Include="SkiaSharp.NativeAssets.Linux" Version="2.88.7" />
   <PackageReference Update="SkiaSharp.NativeAssets.macOS" Version="2.88.7" />
</ItemGroup>

Remote debugging

VS Code can connect to a remote computer (using SSH) to develop and debug projects. Note that all the sources, build and debugging are done on the remote computer, where the Uno Platform extension is being executed.

To debug the application remotely, it's necessary to modify the launch.json file and add the DISPLAY variable in the env section:

{
  "configurations": [
    {
      "env": {
        "DOTNET_MODIFIABLE_ASSEMBLIES": "debug",
        "DISPLAY": ":0"
      }
    }
  ]
}

.NET Native AOT support

Building an Uno Platform Skia+GTK app with .NET (7+) Native AOT requires, GtkSharp 3.24.24.38 (or later), or Uno Platform 4.7 (or later).

To build an app with this feature enabled:

Add the following property in your .csproj:

<PropertyGroup>
   <PublishAot>true</PublishAot>
</PropertyGroup>

Upgrade your project to net7.0:

<TargetFramework>net7.0</TargetFramework>

Add the following items in your .csproj:

<ItemGroup>
   <TrimmerRootAssembly Include="MyApp.Skia.Gtk" />
   <TrimmerRootAssembly Include="GtkSharp" />
   <TrimmerRootAssembly Include="GdkSharp" />
</ItemGroup>

Build your app with:
```
dotnet publish -c Release
```
Note

Cross-compilation support is not supported as of .NET 7. To build a Native AOT app for Linux or Mac, you'll need to build on the corresponding host.

For more information, see the runtime documentation and the .NET Native AOT documentation.