Merge pull request #86 from svgor-code/translate/ru

Translation of documentation to Russian

conf.py

@@ -195,5 +195,6 @@
     ("fr", "🇫🇷", "Français", "French"),
     ("kr", "🇰🇷", "한국인", "Korean"),
     ("it", "🇮🇹", "Italiano", "Italian"),
+    ("ru", "🇷🇺", "Русский", "Russian"),
     ("zh", "🇨🇳", "中文", "Chinese"),
 ]

toc.md

@@ -11,6 +11,7 @@ Contents
 
 index
 fr/index
+ru/index
 zh/index
 
 contributing/index

translation/ru/index.md

@@ -0,0 +1,98 @@
+Изучаем WebGPU
+============
+
+*Для нативной графики в C++.*
+
+Эта документация проведёт вас через использование графического API [WebGPU](https://www.w3.org/TR/webgpu) для создания **нативных 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
+
+Используйте вкладку "**With webgpu.hpp**".
+```
+
+```{admonition} Нет, покажи мне **чистый C WebGPU API**!
+:class: foldable no
+
+Используйте вкладку "**Vanilla 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 Mesh Viewer с базовым управлением
+:class: foldable quickstart
+
+Рекомендую начать с конца главы [Контроль освещения](basic-3d-rendering/some-interaction/lighting-control.md).
+```
+
+````
+
+```{admonition} Я хочу, чтобы код **работал и в вебе**.
+:class: foldable warning
+
+Основная часть руководства не включает несколько дополнительных строк кода. Обратитесь к приложению [Сборка для веба](appendices/building-for-the-web.md), чтобы **адаптировать примеры** для запуска в вебе!
+```
+
+`````
+
+```{admonition}  🚧 Work in progress
+Этот гайд всё ещё **находится в разработке**, а **стандарт WebGPU продолжает эволюционировать**. Чтобы помочь читателю отслеживать его актуальность, мы используем следующие значки в заголовках глав:
+
+🟢 **Актуально!** *Использует последнюю версию [WebGPU-distribution](https://github.com/eliemichel/WebGPU-distribution).*  
+🟡 **Готово к чтению**, *но использует устаревшую версию WebGPU.*  
+🟠 **В процессе работы**: *читаемо, но не завершено.*  
+🔴 **TODO**: *поверхностно рассмотренная тема.*  
+
+**NB:** При использовании кода, сопровождающего главу, убедитесь, что используете **именно ту версию** `webgpu/`, которая предоставляется в ней, чтобы избежать несовместимостей.
+```
+
+
+Содержание
+--------
+
+```{toctree}
+:titlesonly:
+
+introduction
+getting-started/index
+basic-3d-rendering/index
+basic-compute/index
+advanced-techniques/index
+appendices/index
+```

translation/ru/introduction.md

@@ -0,0 +1,140 @@
+Введение
+============
+
+```{translation-warning} Outdated Translation, /introduction.md
+This is a **community translation** of [the original English page](%original%), which **has been updated** since it was translated and may thus no longer be in sync. You are welcome to [contribute](%contribute%)!
+```
+
+```{admonition} Incomplete Translation
+This is a **community translation** of [the original English page](/introduction.md), which is **not fully translated yet**. You are welcome to [contribute](https://github.com/eliemichel/LearnWebGPU/edit/main/translation/fr/introduction.md)!
+```
+
+Что такое графический API?
+-----------------------
+
+Персональный компьютер или смартфон обычно содержат два вычислительных блока: **CPU** (*Central Processing Unit*) и **GPU** (*Graphics Processing Unit*). При программировании приложения **основное внимание уделяется написанию инструкций для 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 — это *Render Hardware Interface*, построенный на различных API, предоставляемых драйвером/ОС в зависимости от вашей платформы. Эта разработка была выполнена веб-браузерами и теперь доступна нам через заголовок `webgpu.h`, который они предоставляют.
+```
+
+<!--
+    The different applications running on the computer are orchestrated in the CPU space, by the Operating System.
+
+    Some APIs are directly provided by the driver, some others are an extra programming layer (a .so or .dll shared library, or some C files that needs to be compiled with your application).
+-->
+
+Почему WebGPU?
+-----------
+
+> 🤔 Зачем мне использовать *Web API* для разработки *десктопного приложения*?
+
+Хороший вопрос, краткий ответ:
+
+ - Разумный уровень абстракции
+ - Хорошая производительность
+ - Кроссплатформенность
+ - Стандартизированность
+ - Готовность к будущему
+
+И на самом деле это *единственный* графический API, который обладает всеми этими свойствами!
+
+Да, API WebGPU был **первоначально разработан для веба**, как интерфейс между JavaScript и GPU. Это **не является недостатком**, поскольку на сегодняшний день требования к производительности веб-страниц аналогичны тем, что предъявляются к нативным приложениям. Подробнее о том, почему я считаю, что WebGPU — лучший графический API для изучения в 2025 году можно прочитать [в этой статье](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) и использовать шаблонный код, полученный из первой части, как стартовый набор? Вы всегда можете вернуться к деталям части "Начало работы" позже.
+
+Рендеринг далеко не единственное использование ГПУ в наше время; третья часть вводит [Базовые Вычисления](basic-compute/index.md), т.е. использование WebGPU в нерендеринговых задачах.
+
+Четвёртая часть [Продвинутые техники](advanced-techniques/index.md) состоит из фокуса на различных техниках компьютерной графики, которые можно читать более независимо друг от друга.
+
+### Literate Programming
+
+```{warning}
+Этот гайд находится на ранней стадии; доступны только первые несколько глав.
+```
+
+Этот гайд следует принципу **Literate Programming**: документация, которую вы читаете, аннотирована таким образом, чтобы можно было **автоматически объединить её блоки кода**  в полностью рабочий код. Это способ гарантировать, что руководство действительно содержит всё необходимое для **воспроизведения результатов**.
+
+В правой боковой панели глав, поддерживающих эту функцию, можно включить/выключить отображение этой информации:
+
+```{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: Используйте кнопку редактирования, которая находится вверху каждой страницы!
+:class: only-light
+```
+
+```{image} /images/edit-dark.png
+:alt: Используйте кнопку редактирования, которая находится вверху каждой страницы!
+:class: only-dark
+```
+
+В общем, вы можете обсуждать любые технические или организационные решения через [issues репозитория](https://github.com/eliemichel/LearnWebGPU/issues).  
+Любые конструктивные и/или доброжелательные отзывы приветствуются!
+
+### Work In Progress
+
+Этот гайд всё ещё в разработке, и сам API WebGPU также находится в процессе разработки. Я стараюсь как можно точнее отслеживать изменения, но пока API не станет стабильным, это неизбежно приведёт к небольшим несоответствиям.
+
+Всегда обращайте внимание на дату последнего изменения страницы и сопровождающего кода (используйте [git](https://github.com/eliemichel/LearnWebGPU)). Они могут быть не совсем синхронизированы; обычно я сначала обновляю код, а затем контент документации.
+
+<!--
+    Cross-platform is not optional. It never really was, but since the global pandemic of 2020 it is even more important: students follow the lecture from a wide variety of devices and a teacher cannot rely on them using all the same machine from the university's lab room.
+-->