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:
|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_OPENGL3||SDL2 (>= 2.0.6) + FreeType (>= 2.6) + OpenGL (>= 3.3)|
|SDL_GLES2||SDL2 (>= 2.0.6) + FreeType (>= 2.6) + OpenGL ES (>= 2.0)|
|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)|
|GLFW_OPENGL3||GLFW (>= 3.2) + FreeType (>= 2.6) + OpenGL (>= 3.3)|
|GLFW_GLES2||GLFW (>= 3.2) + FreeType (>= 2.6) + OpenGL ES (>= 2.0)|
Raspberry Pi: Should be supported by backends that support Linux, but GLES backends are recommended over OpenGL backends.
BSD: Should be supported by backends that support Linux, if the dependencies also support BSD.
macOS: TGUI is known to work, but guides may be incomplete due to lack of experience with macOS.
iOS: Building TGUI was tested, but running a program that uses it (either in simulator or on real device) has not been tested!
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.
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.
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
lib subdirectories (or just an
SDL2.framework file on macOS). Only one of the two has to be provided.
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
lib subdirectories, or a directory containing
SDL2_ttf.framework (for macOS).
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).
CMake provides 3 properties that have to be set in order to find FreeType:
FREETYPE_INCLUDE_DIR_ft2build: The directory that contains the ft2build.h header file
FREETYPE_INCLUDE_DIR_freetype2: The directory that contains the freetype header files and the config subdirectory
FREETYPE_LIBRARIES: The freetype library file to link against
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.