1. Clone the Project Repository 1. Клонирование репозитория проекта

You can clone or download the complete ready-to-run 3D demo project directly from GitHub: github.com/ivan-enzhaev/textured-y-bot-cgltf-cglm-sdl3-image-webp-webgpu-qt6-desktop Вы можете клонировать или скачать готовый к запуску 3D демонстрационный проект с GitHub: github.com/ivan-enzhaev/textured-y-bot-cgltf-cglm-sdl3-image-webp-webgpu-qt6-desktop

git clone https://github.com/ivan-enzhaev/textured-y-bot-cgltf-cglm-sdl3-image-webp-webgpu-qt6-desktop.git

2. Project Directory Structure 2. Структура каталогов проекта

The repository contains the following files: Репозиторий содержит следующие файлы:

textured-y-bot-cgltf-cglm-sdl3-image-webp-webgpu-qt6-desktop/
├── assets/
│   └── models/
│       └── y-bot/
│           ├── y-bot.glb
│           └── y-bot.webp
├── src/
│   ├── main.cpp
│   ├── mainwindow.h
│   ├── mainwindow.cpp
│   ├── texture_utils.h
│   ├── webgpu_context.h
│   └── webgpu_context.cpp
└── CMakeLists.txt

• assets/models/y-bot/y-bot.glb: The binary glTF 2.0 3D model parsed at runtime using the lightweight, single-header cgltf library to extract vertex positions, texture coordinates, and index buffers.Бинарная 3D-модель формата glTF 2.0, загружаемая во время выполнения с помощью легковесной single-header библиотеки cgltf для извлечения позиций вершин, текстурных координат и буферов индексов.
• assets/models/y-bot/y-bot.webp: The WebP diffuse texture loaded at runtime via SDL3_image and uploaded to a 2D WebGPU texture with a filtering sampler.Диффузная текстура формата WebP, загружаемая во время выполнения через SDL3_image и загружаемая в 2D-текстуру WebGPU с фильтрующим сэмплером.
• src/webgpu_context.h / src/webgpu_context.cpp: Initializes the WebGPU instance, adapter, device, and queue via wgpu-native, creates a native WGPUSurface directly from Qt's QWindow (HWND on Windows, Wayland wl_surface or X11 Window on Ubuntu), and handles surface reconfiguration on resize.Инициализирует экземпляр, адаптер, устройство и очередь WebGPU через wgpu-native, создаёт нативную поверхность WGPUSurface напрямую из QWindow (HWND на Windows, Wayland wl_surface или X11 Window на Ubuntu) и обрабатывает перенастройку поверхности при изменении размера окна.
• src/texture_utils.h: Provides helper functions using SDL3_image to decode WebP/PNG images into RGBA8 surfaces and create WebGPU WGPUTexture, WGPUTextureView, and WGPUSampler resources.Содержит вспомогательные функции на базе SDL3_image для декодирования изображений WebP/PNG в формат RGBA8 и создания ресурсов WebGPU: WGPUTexture, WGPUTextureView и WGPUSampler.
• src/mainwindow.h / src/mainwindow.cpp: Subclasses QWindow, initializes the WebGPU context and WGPURenderPipeline with WGSL shaders and a Depth24Plus depth attachment, parses the GLB mesh using cgltf into GPU vertex/index buffers, calculates Model, View, and Perspective matrices using cglm, rotates the model around the Y-axis at 90°/s via QTimer and QElapsedTimer, and writes the combined MVP matrix to the uniform buffer u.mvp.Наследует QWindow, инициализирует контекст WebGPU и конвейер рендеринга WGPURenderPipeline с WGSL-шейдерами и буфером глубины Depth24Plus, парсит меш GLB с помощью cgltf в вершинные и индексный буферы GPU, вычисляет матрицы модели, вида и перспективы с помощью cglm, вращает модель вокруг оси Y со скоростью 90°/с через QTimer и QElapsedTimer и записывает итоговую MVP-матрицу в uniform-буфер u.mvp.
• src/main.cpp: Initializes SDL3 for file/image loading, imports QWaylandIntegrationPlugin on Linux, and starts the QGuiApplication event loop.Инициализирует SDL3 для загрузки файлов и изображений, импортирует плагин QWaylandIntegrationPlugin на Linux и запускает цикл событий QGuiApplication.
• CMakeLists.txt: Configures include directories for cgltf (C:/libs/cgltf-1.15 on Windows or $ENV{HOME}/libs/cgltf-1.15 on Linux), cglm (C:/libs/cglm-0.9.6/include), and wgpu-native (C:/libs/wgpu-native-29.0.1.1-mingw or $ENV{HOME}/libs/wgpu-native-29.0.1.1-ubuntu), and sets up static linking for Qt 6, wgpu-native, SDL3, SDL3_image, and libwebp.Настраивает каталоги включения для cgltf (C:/libs/cgltf-1.15 на Windows или $ENV{HOME}/libs/cgltf-1.15 на Linux), cglm (C:/libs/cglm-0.9.6/include) и wgpu-native (C:/libs/wgpu-native-29.0.1.1-mingw или $ENV{HOME}/libs/wgpu-native-29.0.1.1-ubuntu), а также задаёт статическую компоновку с Qt 6, wgpu-native, SDL3, SDL3_image и libwebp.

3. Project Configuration & Testing in Qt Creator (Windows) 3. Конфигурация проекта и запуск в Qt Creator (Windows)

How to Open and Run in Qt Creator: Как открыть и запустить проект в Qt Creator:

1. In Qt Creator, click File > Open File or Project... (or press Ctrl+O). В Qt Creator нажмите File > Open File or Project... (или нажмите Ctrl+O).
2. Navigate to the cloned repository folder and select the CMakeLists.txt file. Перейдите в папку склонированного репозитория и выберите файл CMakeLists.txt.
3. In the Configure Project screen, select your kit Qt 6.12.0 Static (MinGW 16.2).
   Important: Only Debug is checked by default. Make sure to also check the Release checkbox so that Qt Creator configures the optimized release build! Then click Configure Project. На экране Configure Project выберите ваш Kit Qt 6.12.0 Static (MinGW 16.2).
   Важно: По умолчанию галочка стоит только на Debug. Обязательно поставьте галочку напротив Release, чтобы Qt Creator сконфигурировал оптимизированную Release-сборку! После этого нажмите Configure Project.
4. Switch the active build configuration to Release (click the monitor icon in the bottom-left corner of Qt Creator or press Ctrl+T). Переключите активную конфигурацию сборки на Release (нажмите на значок монитора в левом нижнем углу окна Qt Creator или нажмите Ctrl+T).
5. Press Ctrl+R to build and launch! The resulting single executable in the release build folder will run smoothly without needing any external DLLs. Нажмите Ctrl+R для сборки и запуска! Итоговый одиночный .exe файл в папке release-сборки запустится плавно без необходимости наличия каких-либо внешних DLL.

4. Build and Run on Ubuntu & Ubuntu WSL (Terminal) 4. Сборка и запуск на Ubuntu и Ubuntu WSL (Терминал)

On Ubuntu or Ubuntu WSL, configure and compile the project using CMake and Ninja from the terminal: В Ubuntu или Ubuntu WSL сконфигурируйте и скомпилируйте проект с помощью CMake и Ninja через терминал:

wsl -d Ubuntu

mkdir dist && cd dist

# Configure pointing to your static Qt
cmake -DCMAKE_PREFIX_PATH=$HOME/libs/qt-6.12.0-static-gcc \
      -DCMAKE_BUILD_TYPE=Release \
      -GNinja ..

# Build
ninja

# Run! Window appears seamlessly on Windows desktop via WSLg
./app

5. Expected Output 5. Ожидаемый результат

When launched, the desktop application displays a 500x500 window showing the textured 3D Y-Bot character model rotating smoothly around the Y-axis at exactly 90 degrees per second via WebGPU. The Depth24Plus depth texture ensures rear geometry is properly occluded, and perspective projection creates realistic spatial depth with no lighting applied. При запуске откроется нативное десктопное окно (500x500), отображающее текстурированную 3D-модель персонажа Y-Bot, плавно вращающуюся вокруг оси Y со скоростью ровно 90 градусов в секунду с помощью WebGPU. Текстура глубины Depth24Plus корректно отсекает скрытую геометрию, а перспективная проекция создаёт реалистичный объём без использования освещения.