From 7a4d64e46ddafce75f504b2434b9da838dc67012 Mon Sep 17 00:00:00 2001 From: YaroslavRomanenko Date: Fri, 30 Jan 2026 15:50:54 +0200 Subject: [PATCH] feat: add ukrainian translation --- conf.py | 1 + translation/uk/index.md | 106 ++++++++++++++++++++++++++ translation/uk/introduction.md | 131 +++++++++++++++++++++++++++++++++ 3 files changed, 238 insertions(+) create mode 100644 translation/uk/index.md create mode 100644 translation/uk/introduction.md diff --git a/conf.py b/conf.py index 77bdce6..4912690 100644 --- a/conf.py +++ b/conf.py @@ -200,4 +200,5 @@ ("it", "🇮🇹", "Italiano", "Italian"), ("ru", "🇷🇺", "Русский", "Russian"), ("zh", "🇨🇳", "中文", "Chinese"), + ("uk", "🇺🇦", "Українська", "Ukrainian"), ] diff --git a/translation/uk/index.md b/translation/uk/index.md new file mode 100644 index 0000000..0b8ad6f --- /dev/null +++ b/translation/uk/index.md @@ -0,0 +1,106 @@ +Вчимо WebGPU +============ + +*Для нативної графіки на C++.* + +Ця документація допоможе вам освоїти [WebGPU](https://www.w3.org/TR/webgpu) графічний API, щоб створювати **нативні 3D додатки** на C++ з нуля, для Windows, Linux і macOS. + +`````{admonition} Швидкий Старт! (Натисни на Мене) +:class: foldable quickstart + +*Чи хочете ви зрозуміти кожну частинку GPU коду, який ви пишете?* + +````{admonition} Так, писати WebGPU код **з нуля**! +:class: foldable yes + +Чудово! Ви можете просто перейти до [вступу](introduction.md) і **прочитати всі розділи** послідовно. +```` + +````{admonition} Ні, я краще **пропущу початковий шаблонний код**. +:class: foldable no + +Це цілком логічно, ви можете завжди **повернутися до [початкових кроків](getting-started/index.md) пізніше**. + +Ви, ймовірно, захочете переглянути посилання _**Кінцевий код**_ на початку та в кінці **кожної сторінки**, наприклад: + +```{image} /images/intro/resulting-code-light.png +:class: only-light with-shadow +``` + +```{image} /images/intro/resulting-code-dark.png +:class: only-dark with-shadow +``` + +*Ви згодні використовувати тонку обгортку для зручнішого читання?* + +```{admonition} Так, я віддаю перевагу **C++** коду. +:class: foldable yes + +Зайдіть на "**З webgpu.hpp**" вкладку. +``` + +```{admonition} Ні, покажіть мені **сирий C WebGPU API**! +:class: foldable no + +Зайдіть на "**Ванільний webgpu.h**" вкладку. *Кінцевий код* для ванільного WebGPU є менш актуальним, але ця вкладка також перемикає **всі блоки коду** всередині посібника, і вони є **актуальними**. +``` + +Для того, щоб **зробити збірку цього базового коду**, зверніться до [Збірка](getting-started/project-setup.md#building) секції розділу про налаштування проєкту. Ви можете додати `-DWEBGPU_BACKEND=WGPU` (стандарт) або `-DWEBGPU_BACKEND=DAWN` до `cmake -B build` команди, щоб обрати як бекенд [`wgpu-native`](https://github.com/gfx-rs/wgpu-native) або [Dawn](https://dawn.googlesource.com/dawn/) відповідно. + +*Наскільки далеко ви хочете просунутися з базовим кодом?* + +```{admonition} Простий трикутник +:class: foldable quickstart + +Перегляньте розділ [Привіт трикутник](basic-3d-rendering/hello-triangle.md). +``` + +```{admonition} 3D-сітка з базовою взаємодією +:class: foldable quickstart + +Я рекомендую починати з кінця розділу [Управління освітленням](basic-3d-rendering/some-interaction/lighting-control.md). +``` + +```` + +```{admonition} Я хочу, щоб все так само **запускалося в Інтернеті**. +:class: foldable warning + +В основній частині посібника бракує декількох додаткових рядків, зверніться до [Збірка для Інтернету](appendices/building-for-the-web.md) додатку, щоб **адаптувати приклади** та, щоб вони запускались в Інтернеті! +``` + +````` + +```{admonition} 🚧 Робота в процесі +Цей посібник досі **в розробці**, і **стандарт WebGPU досі еволюціонує**. Щоб допомогти читачу зрозуміти, наскільки актуальна інформація, ми використовуємо ці знаки в заголовках до кожного розділу: + +🟢 **Актуальна!** *Використовує останню стабільну версію [WebGPU-distribution](https://github.com/eliemichel/WebGPU-distribution), а саме `v0.2.0`.* +🟡 **Готове до читання** *але використовує старішу версію WebGPU.* +🟠 **Робота в процесі**: *достатньо читабельно, але не закінчено.* +🔴 **Треба зробити**: *ми тільки торкнулися поверхні.* + +Для попереднього огляду **майбутньої версії** цього посібника, ви можете глянути в сховану секцію [Наступне](next/index.md), але це не означає, що вона стабільна. + +**Примітка:** При використанні супровідного коду з розділу, обов'язково використовуйте **саме ту версію** `webgpu/` яку вона надає, щоб уникнути розбіжностей. +``` + +Зміст +-------- + +```{toctree} +:titlesonly: + +introduction +getting-started/index +basic-3d-rendering/index +basic-compute/index +advanced-techniques/index +appendices/index +``` + +```{toctree} +:titlesonly: +:hidden: + +next/index +``` diff --git a/translation/uk/introduction.md b/translation/uk/introduction.md new file mode 100644 index 0000000..78c7df0 --- /dev/null +++ b/translation/uk/introduction.md @@ -0,0 +1,131 @@ +Вступ +============ + +Що таке графічний API? +----------------------- + +Персональний комп'ютер, або смартфон зазвичай складається з двох обчислювальних одиниць: **CPU** (*Центральний процесор*) і **GPU** (*Графічний процесор*). При програмуванні додатку **в першу чергу пишуться інструкції для CPU**. Для цього призначені більшість мов програмування. + +```{figure} /images/architecture-notes.png +:align: center +CPU та GPU - це два різних процесори. Ми програмуємо CPU так, щоб він наказував GPU, що робити, за допомогою графічного API і драйвера. +``` + +Якщо хтось хоче, щоб додаток виконував інструкції на GPU (наприклад, рендерив 3D-зображення), код CPU повинен **відправити інструкції до драйвера** GPU. Графічний API є програмним інтерфейсом, який використовується для того, щоб CPU код комунікував з GPU. + +Існує багато таких API, наприклад, ви могли чути про OpenGL, DirectX, Vulkan чи Metal. + +```{tip} +В теорії, будь-хто може створити свій власний графічний API. Кожен виробник GPU має власний низькорівневий протокол для взаємодії драйвера із залізом, на основі якого реалізовані більш поширені API (часто надаються разом із драйвером). +``` + +У цій документації ми вивчимо графічний API, який називається [WebGPU](https://www.w3.org/TR/webgpu/). Цей API був розроблений для забезпечення **єдиного доступу** до графічних процесорів, незалежно від виробника GPU та операційної системи, на якій працює програма. + +```{figure} /images/rhi.png +:align: center +:class: with-shadow +WebGPU - це *Інтерфейс Апаратного Забезпечення для Рендерингу*, який побудований на основі різних API, що надаються драйвером/ОС залежно від вашої платформи. Ця дублююча розробка виконується один раз веббраузерами і надається нам через хедер `webgpu.h`. +``` + + + +Чому WebGPU? +----------- + +> 🤔 Так, чому я повинен використовувати **веб-API**, щоб розробляти **настільні додатки**? + +Радий, що ви запитали. Коротка відповідь: + + - Прийнятний рівень абстрації + - Гарна продуктивність + - Кросплатформенність + - Стандартизованість + - Перспективність + +І це насправді **єдиний** графічний API, який використовує всі ці властивості! + +Так, WebGPU API був **розроблений в першу чергу для вебсайтів**, як інтерфейс між JavaScript та графічними процесорами. Це не є **недоліком**, оскільки на сьогодні вимоги до продуктивності вебсайтів насправді такі самі, як і для нативних додатків. Ви можете прочитати більше про те, [Чому я вважаю, що WebGPU це найкращий графічний API для вивчення в 2023 році](appendices/teaching-native-graphics-in-2023.md). + +```{note} +При розробці API для вебу є два важливих обмеження: **портативність** та **конфіденційність**. Ми отримуємо тут **переваги** від зусиль, докладених для забезпечення портативності, і, на щастя, обмеження API, пов'язані з міркувань конфіденційності, можна **відключити** при використанні WebGPU, як нативний API. +``` + +Чому тоді C++? +------------- + +Чи не повинні ми використовувати **JavaScript**, оскільки він є початковою ціллю WebGPU? Або **C**, бо це мова хедеру `webgpu.h`, який ми будемо використовувати? Або ж **Rust** так як це мова, на якій написаний один з бекендів WebGPU? Все це валідні мови, які можна використовувати з WebGPU, але, я обрав C++ бо: + + - C++ досі є основною мовою, яка використовується для високопродуктивних графічних додатків (відеоігри, рендер-рушії, інструменти для моделювання, тощо). + - Рівень абстрації та контроль над C++ загалом добре підходять для взаємодії з графічними API. + - Графічне програмування - це дуже гарна нагода, щоб дійсно навчитися C++. На початку я буду виходити з того, що ви маєте лише дуже поверхневі знання цієї мови. + +```{seealso} +Для еквівалента цієї документації мовою Rust я рекомендую вам ознайомитись з [Learn WGPU](https://sotrh.github.io/learn-wgpu) від Sotrh. +``` + +Як використовувати цю документацію? +------------------------------ + +### Читання + +Перші дві частини цієї документації були розроблені для того, щоб читати послідовно, як повну лекцію, але окремі сторінки також можна використовувати як довідники з конкретних тем. + +Розділ [Початок Роботи](getting-started/index.md) присвячений шаблонному коду який потрібен для ініціалізації WebGPU і управлінню вікном (використовуючи GLFW), і представляє ключові концепції та ідіоми API. У цьому розділі, ми маніпулюємо сирим C API, і закінчуємо представляючи C++ обгортку, яку ми можемо використовувати в іншій частині цієї документації. + +Можна **перейти безпосередньо до частини 2** [Базовий 3D Рендеринг](basic-3d-rendering/index.md) і використовувати шаблонний код, який є результатом з першої частини, як початковий набір. Ви можете завжди повернутися назад пізніше до деталей з розділу початок роботи. + +Рендеринг - це далеко не єдине що можна робити за допомогою GPU на сьогодні; частина 3 представляє [Базове Обчислення](basic-compute/index.md), тобто використання WebGPU без рендерингу. + +Четверта частина [Просунуті Техніки](advanced-techniques/index.md) складається з розділів присвячених різним технікам комп'ютерної графіки, які можна читати незалежно один від одного. + +### Грамотне Програмування + +```{warning} +Цей посібник в початковій фазі; це доступно тільки для перших декількох розділів. +``` + +Посібник слідує принципу **Грамотного програмування**: Документація, яку ви читаєте, має коментарі, завдяки яким можна **автоматично об'єднати її блоки коду** в повністю робочий файл. Це спосіб переконатися, що посібник дійсно містить все необхідне для **відтворення результатів**. + +У правій бічній панелі розділів, які підтримують цю функцію, ви можете ввімкнути/вимкнути відображення такої інформації: + +```{image} /images/literate-light.png +:align: center +:class: only-light +``` + +```{image} /images/literate-dark.png +:align: center +:class: only-dark +``` + +Все вимкнено за замовчуванню, щоб уникнути візуального шуму, але якщо ви не знаєте, куди саме помістити конкретний фрагмент коду, ви можете їх увімкнути. + +### Внесок + +Якщо ви виявили помилку, або більш серйозну проблему, не соромтеся виправити її, натиснувши кнопку редагування, яка знаходиться у верхній частині кожної сторінки! + +```{image} images/edit-light.png +:alt: Use the edit button present on top of each page! +:class: only-light +``` + +```{image} images/edit-dark.png +:alt: Use the edit button present on top of each page! +:class: only-dark +``` + +Взагалі, ви можете обговорити будь-які технічні або організаційні питання через репозиторій [Issues у репозиторії](https://github.com/eliemichel/LearnWebGPU/issues). Будь-які конструктивні та/або доброзичливі відгуки вітаються! + +### Робота в Процесі + +Цей посібник досі в розробці, і сам WebGPU API також. Я намагаюсь якомога ретельніше стежити за змінами, але доки API не стабілізується, це неминуче призводить до невеликих невідповідностей. + +Завжди слідкуйте за актуальністю останньої модифікації сторінки і супровідного коду (використовуй [git](https://github.com/eliemichel/LearnWebGPU)). Вони можуть бути не ідеально синхронізовані; зазвичай я спершу оновлюю код, а потім вміст посібника. + +