Файли шрифтів

Шрифти використовуються для рендерингу тексту в компонентах (components) Label і текстових вузлах GUI. Defold підтримує кілька форматів файлів шрифтів:

• TrueType
• OpenType
• BMFont

Як попередня, так і повна системи компонування тексту підтримують контури TrueType і контури OpenType CFF1/CFF2, зокрема генерування під час виконання з ресурсів .ttf і .otf.

Про оформлення окремих фрагментів тексту й роботу з посиланнями та вбудованими спрайтами читайте в посібнику з розмітки форматованого тексту.

Для шрифтів TrueType і OpenType властивість Mode визначає спосіб рендерингу гліфів:

• Bitmap використовує растрові зображення гліфів.
• SDF (знакове поле відстаней) зберігає в текстурі відстані до країв гліфів, що дає змогу гнучкіше масштабувати шрифт, ніж Bitmap.
• Vector відображає основну форму гліфів із даних кривих, зберігаючи чіткість під час масштабування. Ефекти обведення й тіні й далі використовують растрові дані.

Нові ресурси шрифтів використовують режим Vector і генерування гліфів Dynamic. Наявні ресурси шрифтів зберігають режим Bitmap або SDF. Джерела BMFont завжди використовують надане растрове зображення.

Режим Vector потребує підтримки текстур RGBA16F і R32UI та не підтримується в OpenGL ES 2 або WebGL 1. Для непідтримуваних графічних адаптерів використовуйте шрифти Bitmap або SDF і відповідні матеріали; автоматичного переходу з Vector на SDF немає. Налаштування див. у розділі Векторні шрифти.

Шрифти з попереднім генеруванням або генеруванням під час виконання

Властивість Glyph Generation визначає, коли генеруються дані гліфів кожного шрифту:

• Static генерує вибрані гліфи під час збирання (заздалегідь). Characters і All Chars визначають, які гліфи включати. Вихідний файл .ttf або .otf не додається до пакета для генерування під час виконання.
• Dynamic додає до пакета вихідний файл .ttf або .otf і генерує гліфи за потреби під час виконання. Prewarm Text готує гліфи під час завантаження шрифту. Інші гліфи можна згенерувати пізніше за потреби.

Шрифти SDF і Vector підтримують обидва варіанти. Шрифти Bitmap і джерела BMFont використовують генерування Static. Кожен ресурс шрифту налаштовується незалежно, тож у проєкті можна поєднувати Static і Dynamic.

Динамічне генерування може зменшити розмір пакета й використання пам’яті під час виконання, особливо для шрифтів із великими наборами символів. Воно потребує повної системи компонування тексту в рушії; див. Увімкнення генерування шрифтів під час виконання.

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

Шрифти з генеруванням під час виконання також мають перевагу повної підтримки компонування тексту, наприклад справа наліво. Наразі ми використовуємо бібліотеки HarfBuzz, SheenBidi, libunibreak і SkriBidi.

Див. Увімкнення генерування шрифтів під час виконання

Для попереднього перегляду шрифтів і тексту сцени редактор використовує засіб рендерингу шрифтів рушія. Формування гліфів і компонування справа наліво потребують генерування шрифтів під час виконання і параметра Use full text layout system у маніфесті застосунку. Для шрифтів, згенерованих заздалегідь, попередній перегляд враховує їхні налаштування Characters і All Chars.

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

Формат файлів .fontc також відомий як колекція шрифтів (font collection). У режимі попереднього генерування з нею пов’язано лише один шрифт. Якщо ви використовуєте генерування шрифтів під час виконання, з колекцією шрифтів можна пов’язати кілька файлів шрифтів (.ttf або .otf).

Це дає змогу використовувати колекцію шрифтів для рендерингу кількох текстів різними мовами й водночас зберігати низьке споживання пам’яті. Наприклад, можна завантажити колекцію з японським шрифтом, пов’язати цей шрифт із поточним основним шрифтом, а потім вивантажити колекцію японського шрифту.

Створення шрифту

Щоб створити шрифт для використання в Defold, створіть новий файл Font: виберіть у меню File ▸ New..., а потім Font. Також можна клацнути правою кнопкою миші в потрібному місці браузера Assets і вибрати New... ▸ Font.

Дайте новому файлу шрифту назву й натисніть Ok. Новий файл шрифту відкриється в редакторі.

Перетягніть шрифт, який хочете використовувати, у браузер Assets і розмістіть його в потрібному місці.

Укажіть файл шрифту у властивості Font. Для джерела .ttf або .otf виберіть Mode і Glyph Generation, а потім налаштуйте решту властивостей за потреби. Для генерування Dynamic також виконайте налаштування шрифтів під час виконання.

Для шрифтів Vector змінюйте розмір відображеного тексту через Font Size компонента Label або текстового вузла GUI. Outline/Shadow Bitmap Size керує роздільною здатністю растрових зображень ефектів незалежно від розміру відображеного тексту.

Для шрифтів Bitmap і SDF задайте Size у ресурсі шрифту, щоб вибрати розмір згенерованих гліфів. Розміри BMFont беруться з вихідного файлу .fnt. Щоб змінити розмір відображення цих шрифтів, масштабуйте компонент Label або текстовий вузол GUI.

Властивості

Font

Файл TTF, OTF або .fnt, який використовується для генерування даних шрифту.

Material

Матеріал для рендерингу цього шрифту. Він має відповідати режиму шрифту; див. Матеріали шрифтів.

Mode

Техніка рендерингу для джерела .ttf або .otf: Bitmap, SDF або Vector. Замінює колишню властивість Output Format. Для джерел BMFont властивість не показується.

Glyph Generation

Static генерує дані гліфів під час збирання. Dynamic генерує їх під час виконання й потребує повної системи компонування тексту. Властивість доступна для шрифтів SDF і Vector. У режимі Bitmap вона має незмінне значення Static, а для джерел BMFont не показується.

Render Mode

Розміщення шарів для згенерованих шрифтів Bitmap. Ця властивість показується лише в режимі Bitmap для джерел .ttf і .otf. Для SDF, Vector і BMFont Defold вибирає розміщення шарів автоматично.

• Single Layer створює один чотирикутник для кожного символу.
• Multi Layer створює окремі чотирикутники для форми гліфа, обведення й тіні. Шари відображаються від заднього до переднього, щоб символ не затуляв раніше відображені символи, коли обведення ширше за відстань між гліфами. Це також вмикає зміщення тіні з властивостей Shadow X/Y.

Size

Розмір гліфа в пікселях для генерування даних шрифту Bitmap або SDF. Для джерел BMFont розмір читається з файлу .fnt і тут не редагується.

Outline/Shadow Bitmap Size

У режимі Vector замінює Size. Керує роздільною здатністю растрових зображень увімкнених ефектів обведення й тіні для генерування Static і Dynamic. Властивість вимкнено, якщо обидва ефекти вимкнені, оскільки основна форма гліфів використовує дані кривих. Зміна Font Size компонента Label або текстового вузла GUI не змінює цю спільну роздільну здатність.

Antialias

Чи згладжувати гліфи під час генерування даних шрифту Bitmap. Вимкніть для піксельно точного рендерингу. Властивість показується лише в режимі Bitmap для джерел .ttf і .otf.

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

Ступінь розмиття згенерованої тіні. Задайте 0 для чіткої тіні.

Shadow X/Y

Горизонтальне й вертикальне зміщення згенерованої тіні в пікселях. Для згенерованих шрифтів Bitmap використовуйте режим Multi Layer, щоб застосувати ці зміщення. Для SDF і Vector Defold автоматично вибирає відповідні шари.

Characters

Для генерування Static — символи, які потрібно включити до зібраного шрифту. За замовчуванням поле містить друковані символи ASCII (коди символів 32-126). Додавайте або видаляйте символи, щоб керувати доступними під час виконання гліфами.

Prewarm Text

Для генерування Dynamic замінює Characters. Текст використовується для генерування гліфів і попереднього заповнення кешу під час завантаження шрифту. Він не обмежує символи, які можна згенерувати пізніше. Текст також можна попередньо підготувати зі скрипту через font.prewarm_text().

All Chars

Для генерування Static — включити всі гліфи, доступні у джерелі, замість обмеження поля Characters. Для шрифтів Dynamic ця властивість прихована.

Cache Width/Height

Обмежує розмір растрового кешу гліфів, який використовують шрифти Bitmap і SDF, а також ефекти обведення й тіні Vector. Під час рендерингу тексту рушій шукає гліф у растровому кеші. Якщо його там немає, він додається до кешу перед рендерингом. Якщо растровий кеш замалий для всіх гліфів, які потрібно відобразити, повідомляється помилка (ERROR:RENDER: Out of available cache cells! Consider increasing cache_width or cache_height for the font.).

Якщо задано 0, розмір кешу визначається автоматично й може зростати щонайбільше до 2048x4096.

Матеріали шрифтів

Використовуйте матеріал, що відповідає режиму шрифту. Текстові вузли GUI використовують Material ресурсу шрифту. Компоненти Label мають окрему властивість Material, яка також має відповідати шрифту:

Зміна Mode у редакторі шрифту перемикає відповідні вбудовані матеріали Bitmap, SDF і Vector, якщо один із них уже призначено шрифту. Власні матеріали не замінюються автоматично. Також перевірте властивість Material усіх компонентів Label, що використовують цей шрифт.

Векторні шрифти

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

1. Створіть ресурс .font, наприклад /fonts/ui.font, і виберіть джерело TrueType або OpenType у властивості Font. Для звичайного тексту можна використати вбудований /builtins/fonts/vera_mo_bd.ttf.
2. Установіть Mode у Vector, Glyph Generation у Dynamic, а Material у /builtins/fonts/font-vector.material. Це типові значення для нових ресурсів шрифтів.
3. Увімкніть Use full text layout system у маніфесті застосунку, призначеному проєкту. Налаштуйте власний рушій за розділом Увімкнення генерування шрифтів під час виконання.
4. Увімкніть Shader ▸ Exclude GLES 2.0 у game.project.
5. Призначте шрифт компоненту Label або додайте його до Fonts сцени GUI й виберіть у текстовому вузлі. Для Label також задайте Material компонента як /builtins/fonts/label-vector.material. Установіть бажаний розмір відображення у Font Size компонента або вузла.

Основна форма векторних гліфів використовує текстури кривих, але ввімкнені обведення й тіні й далі генерують растрові дані SDF і займають пам’ять текстури кешу гліфів. Outline/Shadow Bitmap Size задає роздільну здатність цих зображень незалежно від Font Size компонента Label або текстового вузла GUI. Якщо ефекти не потрібні, задайте Outline Alpha і Shadow Alpha значення 0, щоб не генерувати їхні растрові дані.

Кольорові емодзі

Векторні шрифти можуть відображати кольорові емодзі COLRv1, зокрема кольори палітри та лінійні й радіальні градієнти. Режими Bitmap і SDF не відображають кольори COLRv1. Виконайте наведене вище налаштування Dynamic Vector, а потім додайте шрифт емодзі COLRv1 як резервний до колекції шрифтів. Звичайний текст і далі використовуватиме початковий шрифт.

Наприклад, скопіюйте шрифт Noto Color Emoji у форматі COLRv1 до проєкту як /fonts/NotoColorEmoji-Regular.ttf. Виберіть версію COLRv1: інші шрифти емодзі можуть використовувати інший формат кольору, навіть якщо назва файлу закінчується на .ttf.

Додайте /fonts/NotoColorEmoji-Regular.ttf до Project ▸ Custom Resources у game.project. Якщо інших власних ресурсів немає, налаштування має такий вигляд:

[project]
custom_resources = /fonts/NotoColorEmoji-Regular.ttf

Шлях до шрифту в коді Lua не призводить до додавання файлу шрифту до пакета. Custom Resources робить цей вихідний шрифт доступним для font.add_font(), яка завантажує його через систему ресурсів. Під час завантаження з пакета передавайте рядковий шлях до вихідного шрифту.

Додавайте резервний шрифт один раз для кожного спільного ресурсу шрифту. Зміна впливає на всі компоненти Label і текстові вузли GUI, які використовують цей шрифт, а повторне додавання того самого резервного шрифту спричиняє помилку. Якщо ви використовуєте приклад Label і приклад GUI з тим самим .font, узгодьте ініціалізацію так, щоб резервний шрифт додавався один раз до попередньої підготовки або відображення тексту в будь-якому прикладі. Приклади попередньо готують увесь текст після додавання резервного шрифту й показують його після успішного зворотного виклику.

Шрифти на основі поля відстаней

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

Виберіть SDF у Mode і Static або Dynamic у Glyph Generation. Використовуйте /builtins/fonts/font-df.material для шрифту та /builtins/fonts/label-df.material для компонентів Label або власні матеріали, що обробляють дані поля відстаней.

Растрові шрифти BMFont

Окрім згенерованих растрових зображень, Defold підтримує попередньо растеризовані шрифти у форматі «BMFont». Такі шрифти складаються з PNG-зображення з усіма гліфами. Крім того, файл .fnt містить інформацію про розташування кожного гліфа на зображенні, а також про його розмір і кернінг. (Зауважте, що Defold не підтримує XML-версію формату .fnt, яку використовують Phaser і деякі інші інструменти)

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

Додайте згенеровані файли .fnt і .png до проєкту Defold. Ці файли мають бути в одній папці. Створіть новий файл шрифту й укажіть файл .fnt у властивості Font. Defold використовує надане растрове зображення й читає його розмір із файлу .fnt. Для джерел BMFont Mode і Glyph Generation не показуються.

Задайте Material шрифту як /builtins/fonts/font-fnt.material. Для компонентів Label використовуйте /builtins/fonts/label-fnt.material.

Артефакти й рекомендовані підходи

Загалом растрові шрифти найкраще підходять для рендерингу без масштабування. Вони виводяться на екран швидше, ніж шрифти на основі поля відстаней.

Шрифти на основі поля відстаней дуже добре зберігають якість під час збільшення. Растрові шрифти є лише піксельними зображеннями, тому зі збільшенням шрифту збільшуються й пікселі, що призводить до появи артефактів у вигляді блоків. Нижче наведено приклад шрифту розміром 48 пікселів, збільшеного в 4 рази.

Під час зменшення GPU може якісно й ефективно зменшувати та згладжувати растрові текстури. Растровий шрифт краще зберігає колір, ніж шрифт на основі поля відстаней. Нижче наведено збільшений фрагмент того самого зразка шрифту розміром 48 пікселів, зменшеного до 1/5 розміру:

Шрифти на основі поля відстаней потрібно растеризувати в цільовому розмірі, достатньому для зберігання інформації про відстані, яка передає криві гліфів шрифту. Нижче показано той самий шрифт, але розміром 18 пікселів і збільшений у 10 разів. Видно, що цей розмір замалий для кодування форм цієї гарнітури:

Якщо вам не потрібна підтримка тіні або обведення, установіть відповідні значення альфа-каналу в нуль. Інакше дані тіні й обведення все одно генеруватимуться та займатимуть зайву пам’ять. У режимі Vector вимкнення обох ефектів запобігає генеруванню їхніх растрових даних; основна форма гліфів і далі використовує дані кривих.

Кеш шрифту

Ресурси шрифтів Bitmap і SDF під час виконання використовують текстуру кешу гліфів і дані шрифту. Векторні шрифти зберігають основну форму гліфів як дані кривих, а для ввімкнених ефектів обведення й тіні використовують растровий кеш. Описане нижче компонування текстури стосується шрифтів Bitmap і SDF.

• Дані шрифту складаються зі списку записів гліфів, кожен із яких містить базову інформацію про кернінг і растрові дані відповідного гліфа.
• Усередині рушія текстура називається «текстура кешу гліфів» і використовується під час рендерингу тексту певним шрифтом.

Під час виконання, коли потрібно відобразити текст, рушій спочатку перебирає гліфи, які мають бути відображені, щоб перевірити їхню наявність у кеші текстури. Для кожного гліфа, якого немає в текстурі кешу гліфів, запускається завантаження в текстуру растрових даних, що зберігаються в даних шрифту.

Кожен гліф розміщується в кеші відповідно до базової лінії шрифту. Це дає змогу обчислювати в шейдері локальні текстурні координати гліфа всередині відповідної комірки кешу. Отже, ви можете динамічно створювати певні текстові ефекти, як-от градієнти чи накладання текстур. Рушій передає шейдеру параметри кешу через спеціальну константу шейдера 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);

Докладніше про uniform-змінні шейдерів див. у посібнику із шейдерів.

Увімкнення генерування шрифтів під час виконання

Генерування під час виконання налаштовується окремо для кожного ресурсу шрифту:

1. Відкрийте ресурс .font і виберіть джерело TrueType (.ttf) або OpenType (.otf).
2. Установіть Mode у SDF або Vector, а Glyph Generation у Dynamic.
3. Виберіть відповідні матеріали шрифту й Label.
4. Додайте маніфест застосунку, призначте його в Native Extensions ▸ App Manifest у game.project й увімкніть Use full text layout system. Це збере власний рушій із підтримкою генерування шрифтів під час виконання й повного компонування тексту.
5. Задайте в Prewarm Text текст, який відображатиметься невдовзі після завантаження шрифту. Для тексту, потрібного пізніше, використовуйте font.prewarm_text() і чекайте її зворотного виклику перед відображенням.

Нові ресурси шрифтів уже використовують режим Vector і генерування Dynamic, але все одно потребують наведеного вище налаштування маніфеста застосунку.

Робота зі шрифтами зі скриптів

Попереднє заповнення кешу гліфів

Шрифти Dynamic під час завантаження генерують гліфи, потрібні для Prewarm Text. Поле інтерпретується як текст для компонування, тож кеш готується для гліфів, необхідних цьому тексту. All Chars недоступне для шрифтів Dynamic.

Для шрифту Dynamic також можна викликати font.prewarm_text(font_collection, text, callback). Зворотний виклик повідомляє, коли всі відсутні гліфи додано до кешу й текст можна безпечно відобразити. Цю функцію не можна використовувати зі шрифтами Static.

Додавання шрифтів до колекції шрифтів і їх видалення

Для шрифтів Dynamic можна додавати вихідні шрифти (.ttf або .otf) до колекції шрифтів або видаляти їх із неї. Це корисно, коли великий шрифт розділено на кілька файлів для різних наборів символів (наприклад, CJK)

function init(self)
    -- Get the target font collection.
    self.font_collection = go.get("#label", "font")

    -- Get the first font assigned to the selected language collection.
    local language_collection = go.get("localization_japanese#label", "font")
    local font_info = font.get_info(language_collection)
    self.language_ttf_hash = font_info.fonts[1].path_hash

    -- Associate it with the target collection and increase its reference count.
    font.add_font(self.font_collection, self.language_ttf_hash)
end

function final(self)
    -- Remove the association and release the font reference.
    font.remove_font(self.font_collection, self.language_ttf_hash)
end

Попередня підготовка гліфів

Щоб правильно показати текст шрифтом із генеруванням під час виконання, потрібно підготувати гліфи. Функція font.prewarm_text() робить це за вас. Це асинхронна операція. Після її завершення та отримання зворотного виклику можна переходити до показу будь-якого повідомлення, що містить ці гліфи.

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