Ресурс Font

Шрифты используются для визуализации текста в компонентах Label и GUI-нодах Text. Defold поддерживает несколько форматов файлов шрифтов:

• TrueType
• OpenType
• BMFont

Шрифты, добавленные в проект, автоматически конвертируются в текстуру, которую Defold может визуализировать. Доступны два метода визуализации шрифтов, каждый из которых имеет свои преимущества и недостатки:

• Bitmap
• Distance field

Офлайн- и runtime-шрифты

По умолчанию преобразование в растровые изображения глифов происходит во время сборки (offline). Недостаток этого подхода в том, что каждый шрифт должен растрировать все возможные глифы на этапе сборки, что может приводить к очень большим текстурам, потребляющим память и увеличивающим размер бандла.

При использовании runtime-шрифтов .ttf-файлы включаются в бандл как есть, а растеризация выполняется по требованию во время выполнения. Это уменьшает как потребление памяти во время выполнения, так и размер бандла.

Поддержка раскладки текста (например, справа налево)

Runtime-шрифты также дают преимущество в виде полной поддержки раскладки текста, например письма справа налево. Сейчас для этого используются библиотеки HarfBuzz, SheenBidi, libunibreak и SkriBidi.

См. раздел Включение runtime-шрифтов

Коллекция шрифтов

Формат файла .fontc также называется коллекцией шрифтов. В офлайн-режиме с ним связан только один шрифт. При использовании runtime-шрифтов с коллекцией шрифтов можно связать более одного файла шрифта (.ttf).

Это позволяет использовать одну коллекцию шрифтов при рендеринге нескольких текстов на разных языках, при этом сохраняя низкое потребление памяти. Например, можно загрузить коллекцию с японским шрифтом, затем связать этот шрифт с текущим основным шрифтом и после этого выгрузить японскую коллекцию шрифтов.

Создание шрифта

Чтобы создать шрифт для использования в Defold, создайте новый файл Font, выбрав в меню File ▸ New..., затем Font. Можно также кликнуть ПКМ в нужном расположении в браузере ассетов и выбрать New... ▸ Font.

Присвойте новому файлу шрифта имя и кликните Ok. Новый файл шрифта откроется в редакторе.

Перетащите необходимый шрифт в браузер Assets в подходящее для него расположение.

В свойстве Font укажите файл шрифта и, при необходимости, настройте остальные свойства.

Свойства

Font

Файл TTF, OTF или .fnt, используемый для генерирования данных о шрифте.

Material

Материал, используемый при рендеринге этого шрифта. Обязательно измените этот параметр в соответствии с выбранным типом шрифта — Distance Field или Bitmap (подробнее см. ниже).

Output Format

Тип генерируемых данных о шрифте.

• TYPE_BITMAP — конвертирует импортированный файл OTF или TTF в текстуру, представляющую собой изображение шрифта, растровые данные которой используются для визуализации текстовых нод. Цветовые каналы используются для кодирования формы граней, контура и отбрасываемой тени. Для файлов .fnt исходная растровая текстура используется как есть.
• TYPE_DISTANCE_FIELD — импортированный шрифт конвертируется в текстуру, данные о пикселях которой представляют не экранные пиксели, а расстояния до границы шрифта. Подробности см. ниже.

Render Mode

Режим рендеринга глифов.

• MODE_SINGLE_LAYER — создает по одному четырехугольнику для каждого символа.
• MODE_MULTI_LAYER — создает отдельные четырехугольные формы для глифа, контура и теней соответственно. Слои отображаются в обратном порядке (back-to-front), что исключает вероятность загораживания одного символа другим, ранее отображенным, в случае когда контур шире, чем расстояние между глифами. Этот режим рендеринга также обеспечивает правильное смещение теней, задаваемое свойствами Shadow X/Y в ресурсе шрифта.

Size

Целевой размер глифов в пикселях.

Antialias

Сглаживание шрифта при запекании в целевое растровое изображение. Установите значение 0, если хотите получить чисто пиксельный (pixel perfect) рендеринг шрифта.

Alpha

Прозрачность глифа. 0.0–1.0, где 0.0 означает прозрачность, а 1.0 — непрозрачность.

Outline Alpha

Прозрачность сгенерированного контура. 0.0–1.0.

Outline Width

Ширина сгенерированного контура в пикселях. Установите значение 0 чтобы убрать контур.

Shadow Alpha

Прозрачность сгенерированной тени. 0.0–1.0.

Shadow Blur

Для растровых шрифтов эта настройка указывает на то, сколько раз небольшое зерно размытия будет применено к каждому глифу шрифта. Для шрифтов типа Distance Field эта настройка эквивалентна фактической ширине размытия в пикселях.

Shadow X/Y

Горизонтальное и вертикальное смещение сгенерированной тени в пикселях. Этот параметр влияет на тень глифа, только если свойство Render Mode установлено в значение MODE_MULTI_LAYER.

Characters

Какие символы включать в шрифт. По умолчанию это поле содержит печатные ASCII символы (коды символов 32–126). Вы можете добавить или удалить символы из этого поля, чтобы включить больше или меньше символов в шрифт.

Для runtime-шрифтов этот текст используется для предварительного прогрева кэша нужными глифами. Это происходит во время загрузки. См. font.prewarm_text().

All Chars

Если отметить это свойство, все глифы, имеющиеся в исходном файле, будут включены в вывод.

Cache Width/Height

Ограничивает размер кэша растра глифов. Когда движок рендерит текст, он ищет глиф в кэше растра. Если его там нет, он будет добавлен в кэш перед рендерингом. Если кэш растра слишком мал, чтобы вместить все глифы, которые движок пытается отрендерить, возникает ошибка (ERROR:RENDER: Out of available cache cells! Consider increasing cache_width or cache_height for the font.).

При значении 0 размер кэша устанавливается автоматически.

Шрифты Distance Field

Шрифты Distance Field (карта расстояний) вместо растровых данных хранят расстояние до границы глифа в текстуре. Когда движок рендерит шрифт, требуется специальный шейдер, чтобы интерпретировать данные о расстоянии и использовать их для отрисовки глифа. Шрифты Distance Field более ресурсоемки, чем растровые, но обеспечивают большую гибкость в выборе размера.

Обязательно измените свойство Material шрифта на builtins/fonts/font-df.material (или любой другой материал, который может обрабатывать данные карты расстояния) при создании шрифта, иначе при выводе шрифта на экран будет использоваться неподходящий шейдер.

Растровые шрифты BMFont

В дополнение к генерируемым растровым картам Defold поддерживает предварительно запеченные растровые шрифты формата “BMFont”. Эти шрифты представляют собой PNG-изображение в виде страницы с глифами. Кроме того, файл .fnt содержит информацию о том, где на странице находится каждый глиф, а также информацию о размере и кернинге. (Следует учесть, что Defold не поддерживает XML-версию формата .fnt, который используется в Phaser и в некоторых других инструментах).

Эти типы шрифтов не обеспечивают повышения производительности по сравнению с растровыми шрифтами, генерируемыми из файлов TrueType или OpenType, но могут включать произвольную графику, расцветку и тени непосредственно в изображении.

Добавьте сгенерированные файлы .fnt и .png в проект Defold. Эти файлы должны находиться в одной папке. Создайте новый файл шрифта и задайте свойству Font файл типа .fnt. Убедитесь, что Output Format установлен в значение TYPE_BITMAP. Defold не будет генерировать растровое изображение, а будет использовать то, которое содержится в PNG.

Чтобы шрифт отображался корректно, не забудьте установить его свойство Material в builtins/fonts/font-fnt.material.

Артефакты и рекомендации

Как правило, растровые шрифты лучше всего подходят для рендеринга без масштабирования. Они быстрее выводятся на экран, чем шрифты с картой расстояний.

Шрифты Distance Field очень хорошо реагируют на масштабирование. С другой стороны, растровые шрифты, будучи просто пиксельными изображениями, будут увеличиваться в размере, поэтому пиксели будут расти при масштабировании шрифта, что приведет к появлению блочных артефактов, то есть угловатости. Ниже приведен образец шрифта размером 48 пикселей, увеличенный в 4 раза.

При уменьшении масштаба растровые текстуры могут качественно и эффективно масштабироваться и сглаживаться средствами GPU. Растровый шрифт лучше сохраняет свой цвет, чем шрифт с картой расстояний. Вот масштаб того же образца шрифта размером 48 пикселей, уменьшенный до 1/5 размера:

Шрифты Distance Field должны быть отрендерены до целевого размера, достаточно большого для хранения информации о расстояниях и возможности описать кривые глифов шрифта. Это тот же шрифт, что и выше, но размером 18 пикселей и увеличенный в 10 раз. Разумеется, этого слишком мало для кодирования форм этого шрифта:

Если поддержка теней и контуров не требуется, установите соответствующие им значения альфа в 0. В противном случае данные о тенях и контурах все равно будут генерироваться, что приведет к излишнему потреблению памяти. Если вы не хотите использовать поддержку теней или контуров, установите соответствующие значения альфа в ноль. В противном случае данные о тенях и контурах всё равно будут генерироваться, занимая лишнюю память.

Кэш шрифта

Ресурс шрифта в Defold приводит к появлению двух вещей во время выполнения: текстуры и данных шрифта.

• Данные о шрифте состоят из списка вхождений глифов, каждое из которых содержит некоторую базовую информацию о кернинге и растровые данные для этого глифа.
• Текстура — это внутреннее название “кэша текстуры глифа”, используемого при рендеринге текста для определенного шрифта.

Во время выполнения, при рендеринге текста, движок сначала обходит глифы подлежащие рендерингу, чтобы проверить, какие глифы доступны в кэше текстур. Для каждого глифа, отсутствующего в кэше текстур глифов, будет произведена загрузка текстуры из растровых данных, хранящихся в данных шрифта.

Каждый глиф размещается внутри кэша в соответствии с базовой линией шрифта, что позволяет шейдеру вычислять локальные текстурные координаты глифа в соответствующей ячейке кэша. Это означает, что вы можете добиться определенных текстовых эффектов, таких как градиенты или наложение текстуры, динамически. Движок передает показатели кэша шейдеру через специальную шейдерную константу texture_size_recip, которая содержит следующую информацию как векторные компоненты:

• texture_size_recip.x — обратная ширина кэша
• texture_size_recip.y — обратная высота кэша
• texture_size_recip.z — отношение ширины ячейки кэша к ширине кэша
• texture_size_recip.w — отношение высоты ячейки кэша к высоте кэша

Например, чтобы сгенерировать градиент в фрагментном шейдере, достаточно написать:

float horizontal_gradient = fract(var_texcoord0.y / texture_size_recip.w);

Подробнее об унифицированных шейдерных переменных см. В руководстве по шейдерам.

Включение runtime-шрифтов

Возможно использовать генерацию шрифтов типа SDF (Distance Field) во время выполнения при использовании шрифтов TrueType (.ttf).
Этот подход позволяет значительно уменьшить размер загрузки и потребление памяти во время выполнения в игре на Defold.
Небольшой недостаток заключается в асинхронном характере генерации каждого глифа.

• Включите эту возможность, установив параметр font.runtime_generation в game.project.

• Добавьте App Manifest и включите опцию Use full text layout system. Это соберёт пользовательский движок с включённой поддержкой этой функции.

Скриптование шрифтов

Предварительный прогрев кэша глифов

Чтобы упростить использование шрифтов, генерируемых во время выполнения, поддерживается предварительная генерация кэша глифов.
Это означает, что шрифт сгенерирует глифы, указанные в поле Characters ресурса шрифта.

Если задано поле Characters в файле .fontc, этот текст используется для определения того, какие глифы нужно обновить в кэше глифов.

Также можно вручную обновить кэш глифов, вызвав font.prewarm_text(font_collection, text, callback). Этот метод принимает callback, чтобы сообщить вам, когда все недостающие глифы будут добавлены в кэш и текст можно будет безопасно показывать на экране.

Добавление и удаление шрифтов из коллекции шрифтов

Для runtime-шрифтов можно добавлять и удалять шрифты (.ttf) из коллекции шрифтов.
Это полезно, если большой шрифт был разбит на несколько файлов для разных наборов символов (например, CJK).

-- получить основной шрифт
local font_collection = go.get("#label", "font")
font.add_font(font_collection, self.language_ttf_hash)

-- получить шрифт выбранного языка
local font_collection_language = go.get("localization_japanese#label", "font")
local font_info = font.get_info(font_collection_language)
self.language_ttf_hash = font_info.fonts[1].path_hash -- получить первый шрифт (тот, что задан в редакторе)
font.add_font(self.font_collection, self.language_ttf_hash) -- увеличивает счётчик ссылок на шрифт

-- удалить ссылку на шрифт
font.remove_font(self.font_collection, self.language_ttf_hash)

Предварительный прогрев глифов

Чтобы корректно показать текст с runtime-шрифтом, соответствующие глифы должны быть разрешены. font.prewarm_text() делает это за вас. Это асинхронная операция, и после её завершения и получения callback можно безопасно показывать любой текст, содержащий эти глифы.

font.prewarm_text(self.font_collection, info.text, function (self, request_id, result, err)
    if result then
      print("PREWARMING OK!")
      label.set_text(self.label, info.text)
    else
      print("Error prewarming text:", err)
    end
  end)