DOCSEARCHbyAlgolia
Submit Docs

SDL_ttf 3.0 Documentation

repository·main·Indexed 20 days ago

https://github.com/libsdl-org/sdl_ttf

SDL_ttf 3.0 is a library that allows SDL applications to render text using TrueType fonts by wrapping the FreeType and Harfbuzz libraries. This documentation provides integration guides for CMake, Android Studio, Emscripten, Visual Studio, and Xcode, as well as migration details from version 2.0, including changes to error handling, UTF-8 standardization, and API renames.

Tokens
5K
Snippets
14
Records
21
Agent score
73%

What's inside SDL_ttf

  1. Overview of SDL_ttf 3.0

    main
    SDL_ttf 3.0 is a library that provides a wrapper around FreeType and Harfbuzz, enabling developers to render TrueType fonts within SDL applications. It facilitates text rendering by leveraging these specialized font and shaping engines.

  2. Migrate text encoding and rendering to UTF-8

    main

    SDL_ttf 3.0 has standardized on UTF-8.

    • Encoding: Functions that previously offered multiple variants (Latin-1, UTF-8, and UCS2) now exclusively accept UTF-8 text.
    • Substrings: Rendering functions now include an optional length parameter, allowing you to render specific substrings of a larger text buffer.
    • Color Transparency: For background colors, an alpha value of 0 is now treated as transparent.

  3. Understand the SDL versioning policy

    main

    SDL uses an "odd/even" versioning policy to distinguish between stable production releases and development prereleases. This helps developers decide which version to target based on their stability requirements.

    Stable Releases

    A version is considered stable and suitable for production if both the minor version (second part) and the patch version (third part) are divisible by 2 (e.g., 3.2.6, 3.4.0).

    • Patch releases (e.g., 3.2.x): Indicate bugfixes. They are backwards-compatible (code built against 3.2.0 works with 3.2.8), but not necessarily forwards-compatible.
    • Minor releases (e.g., 3.4.x): Indicate significant changes or new functionality. They are backwards-compatible (code built against 3.2.x works with 3.4.x), but not necessarily forwards-compatible.

    Development Prereleases

    A version is a development prerelease if the minor version or patch version is not divisible by 2 (e.g., 3.2.9, 3.3.x).

    • Usage Warning: Prereleases are not suitable for stable software distributions and should be used with caution.
    • Compatibility: Prereleases are backwards-compatible with older stable branches (e.g., 3.2.x code works with 3.3.x), but they are not guaranteed to be backwards-compatible with each other (APIs may change between 3.3.0 and 3.3.1).
    • Recommendation: Only use a prerelease if you can promptly upgrade to the subsequent stable release (e.g., upgrading from 3.3.x to 3.4.0).

  4. Build SDL_ttf projects for Emscripten

    main

    Once your CMakeLists.txt is configured, use emcmake and emmake to perform the build process. This ensures the Emscripten toolchain is correctly applied to the CMake generation and the subsequent make process.

    1. Generate the build files using emcmake cmake.
    2. Compile the project using emmake make.
    3. Serve the resulting build directory using a webserver to view the generated .html output in a browser.
    emcmake cmake -S . -B build
cd build
emmake make

  5. Build and use SDL_ttf with CMake

    main

    SDL_ttf supports various development environments. For CMake-based workflows, you can build the library and then include the generated headers and library files in your own project.

    To build the included example programs alongside the library, enable the samples option during the CMake configuration step using -DSDLTTF_SAMPLES=ON.

    cmake -DSDLTTF_SAMPLES=ON ..

  6. Set up SDL_ttf with Visual Studio using subprojects

    main

    The recommended way to use SDL_ttf in Visual Studio is to include both SDL and SDL_ttf as subprojects within your solution.

    Prerequisites

    Ensure you have downloaded the external dependencies by running the following command in the external directory:

    ./Get-GitModules.ps1

    Project Configuration Steps

    1. Create Project: Create a new Visual Studio project using the C++ Empty Project template and add your source file (e.g., hello.c) to the Source Files.
    2. Add SDL Subproject: Right-click the solution, select Add > Existing Project, and navigate to the SDL VisualC/SDL directory to add SDL.vcxproj.
    3. Add SDL_ttf Subproject: Right-click the solution, select Add > Existing Project, and navigate to the SDL_ttf VisualC directory to add SDL_ttf.vcxproj.
    4. Configure SDL_ttf References: Select the SDL_ttf project, go to Project > Add Reference, and select SDL3.
    5. Configure SDL_ttf Include Paths:
      • Select the SDL_ttf project.
      • Go to Project > Properties.
      • Set the Configuration and Platform filters to All Configurations and All Platforms.
      • Navigate to VC++ Directories > Include Directories and update the default SDL path to point to your SDL include directories.
    6. Configure Main Project References: Select your main project, go to Project > Add Reference, and select both SDL3 and SDL3_ttf.
    7. Configure Main Project Include Paths:
      • Select your main project.
      • Go to Project > Properties.
      • Set the Configuration and Platform filters to All Configurations and All Platforms.
      • Navigate to VC++ Directories > Include Directories and add both the SDL and SDL_ttf include directories.
    8. Build: Build and run your project.

  7. Use SDL_ttf as a CMake subproject with vendored libraries

    main

    The simplest way to integrate SDL_ttf into your project is to include both SDL and SDL_ttf as subprojects using add_subdirectory. This approach requires setting SDLTTF_VENDORED to ON and ensuring the source code for both SDL and SDL_ttf is available in your project's vendored/ directory.

    To ensure that dynamic libraries are placed in the same directory as your executable for easy running, set CMAKE_RUNTIME_OUTPUT_DIRECTORY and CMAKE_LIBRARY_OUTPUT_DIRECTORY to use the configuration-specific build directory.

    cmake_minimum_required(VERSION 3.16)
project(hello)

# Set output directories so dynamic libraries are in the build folder
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")

# Enable vendored mode
set(SDLTTF_VENDORED ON)

# Add SDL and SDL_ttf as subdirectories
add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL)
add_subdirectory(vendored/SDL_ttf EXCLUDE_FROM_ALL)

# Define your executable
add_executable(hello WIN32 hello.c)

# Link against the SDL_ttf and SDL3 targets
target_link_libraries(hello PRIVATE SDL3_ttf::SDL3_ttf SDL3::SDL3)

  10. Build and use SDL_ttf in Visual Studio, Xcode, or Android Studio

    main

    SDL_ttf provides specific setup instructions and project files for several IDEs:

    • Visual Studio (Windows): Use the separate projects located in the VisualC directory.
    • Xcode (Apple platforms): Use the separate projects located in the Xcode directory.
    • Android Studio: Follow the specific guide for Android development.
    • Emscripten: Use the guide for web-based builds.

  11. Use the SDL_ttf Android Studio sample project

    main

    For a complete, working example of integrating SDL_ttf into an Android project using Android Studio, refer to the sample repository provided by Ravbug. This sample demonstrates the necessary setup and integration steps for Android environments.

    https://github.com/Ravbug/sdl3-sample

  12. Build and run an SDL_ttf project with CMake

    main

    After configuring your CMakeLists.txt as described in the subproject guide, follow these steps to build and run your application:

    1. Download dependencies: Run the provided scripts to fetch the required source code:

      • Linux/macOS: ./external/download.sh
      • Windows: ./external/Get-GitModules.ps1

    2. Configure and Build:

      cmake -S . -B build
cmake --build build

    3. Run the executable:

      • Windows: The executable is located in the Debug subdirectory of your build folder:
        cd build/Debug
./hello
      • Other platforms: The executable is located directly in the build folder:
        cd build
./hello
    # Configure
cmake -S . -B build

# Build
cmake --build build

# Run (Linux/macOS example)
cd build
./hello