Selecting a backend in CMake

TGUI is not a standalone library, it depends on libraries such as SFML, SDL or GLFW, which you will likely need to use in your own code as well. The choice of the backend should thus be based on which libraries you want to use in your own program.

When building the library with CMake, the TGUI_BACKEND property has to be set to the wanted backend. It is also possible to build the library with multiple backends (or with none if you want to provide one yourself) by setting TGUI_BACKEND to “Custom” and setting the boolean TGUI_HAS_BACKEND_XXX values.

The following backends exist and can be given as value to TGUI_BACKEND:

Backend Platforms Dependencies
SFML_GRAPHICS
sfml-graphics (>= 2.5)
SFML_OPENGL3
sfml-window (>= 2.5) + FreeType (>= 2.6) + OpenGL (>= 3.3)
SDL_RENDERER
SDL2 (>= 2.0.18) + SDL2_ttf (>= 2.0.14)
SDL_TTF_OPENGL3
SDL2 (>= 2.0.6) + SDL2_ttf (>= 2.0.14) + OpenGL (>= 3.3)
SDL_TTF_GLES2
SDL2 (>= 2.0.6) + SDL2_ttf (>= 2.0.14) + OpenGL ES (>= 2.0)
SDL_OPENGL3
SDL2 (>= 2.0.6) + FreeType (>= 2.6) + OpenGL (>= 3.3)
SDL_GLES2
SDL2 (>= 2.0.6) + FreeType (>= 2.6) + OpenGL ES (>= 2.0)
GLFW_OPENGL3
GLFW (>= 3.2) + FreeType (>= 2.6) + OpenGL (>= 3.3)
GLFW_GLES2
GLFW (>= 3.2) + FreeType (>= 2.6) + OpenGL ES (>= 2.0)

Platform remarks:

Dependencies

Once the backend is chosen, CMake will try to find the dependencies. On some platforms (e.g. Linux), CMake will be able to automatically find them if they are installed, but on other platforms (e.g. Windows) you will have to manually tell CMake where to find the dependencies.

Below you find some information about which properties you need to set when CMake can’t find the dependencies automatically.

SFML

To find SFML, the SFML_DIR variable needs to be set to the directory that contains the SFMLConfig.cmake file (just the path without the filename). If you built SFML yourself without installing it then this will be your SFML build directory, otherwise the file can be found in the lib/cmake/SFML subfolder of your installed or downloaded SFML directory.

Note that the the file you need is called exactly “SFMLConfig.cmake”, the “SFMLConfig.cmake.in” file is not the correct one.

Usually you will use static SFML libraries when linking TGUI statically, but if for some reason you want to link to SFML dynamically while TGUI_SHARED_LIBS=FALSE then you can set SFML_STATIC_LIBRARIES to FALSE.

Both SFML 2 and 3 are supported. As SFML 3 is still in development, there might however be moments where TGUI temporarily fails to build with SFML 3 after an API breaking change was just made in SFML.

SDL

TGUI will first attempt to find an SDL2Config.cmake file. If CMake can’t find it and you have such file (usually in a lib/cmake/SDL2 subfolder) then you can set the SDL2_DIR property to the path containing this file.

If you downloaded the Development Libraries from the SDL download page then you won’t have the SDL2Config.cmake file. In this case you can set the SDL2_PATH property to the root of the downloaded SDL directory.

Note that you should not confuse SDL2_DIR and SDL2_PATH. The first one is a directory that contains SDL2Config.cmake, the latter is a directory that contains include and lib subdirectories (or just an SDL2.framework file on macOS). Only one of the two has to be provided.

SDL_ttf

If SDL_ttf isn’t automatically found then set the SDL2_TTF_PATH variable to the root folder of the Development Libraries that you downloaded from the SDL_ttf download page.

The value of SDL2_TTF_PATH should be a directory that either contains include and lib subdirectories, or a directory containing SDL2_ttf.framework (for macOS).

GLFW

TGUI will first attempt to find a glfw3Config.cmake file. If CMake can’t find it and you have such file (usually in a lib/cmake/glfw3 subfolder) then you can set the glfw3_DIR property to the path containing this file.

Alternatively, you can manually specify the values for GLFW_INCLUDE_DIR and GLFW_LIBRARY. Note that GLFW_INCLUDE_DIR has to be the path that contains the GLFW subdirectory, not the path that contains glfw3.h file (which has to be located inside the GLFW subdirectory).

FreeType

CMake provides 3 properties that have to be set in order to find FreeType:

If you downloaded the Windows libraries from github.com/ubawurinna/freetype-windows-binaries then you can set FREETYPE_WINDOWS_BINARIES_PATH to the root directory to automatically select the correct include and library files. Otherwise you can ignore this property and set the 3 properties listed above.

Warning: due to a bug in FreeType, version 2.11.0 can NOT be used on Windows. Both newer and older versions will work.