includes/Core/e_buffer.h - master - Zamar_Terrier/TigorEngine

includes/Core/e_buffer.h
191 строка11 KB
Zamar_Terrier
Доработка + нововведения
06 июл 2026, 16:26
06 июл 2026, 16:260d4ab95
/**
 * @file e_buffer.h
 * @brief Управление Vulkan буферами и операции с ними
 * @details Предоставляет функции для создания, обновления и управления Vulkan буферами,
 * включая вершинные буферы, индексные буферы, униформные буферы и буферы хранения.
 * Реализует командные пулы и буферы для операций с буферами, а также функции
 * копирования данных между буферами и изображениями.
 */

#ifndef E_BUFFER_H
#define E_BUFFER_H

#include "Variabels/engine_includes.h"

/** @brief Максимальное количество вершин */
#define MAX_VERTEX_COUNT UINT16_MAX

/** @brief Максимальное количество индексов */
#define MAX_INDEX_COUNT MAX_VERTEX_COUNT * 3

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * @brief Создаёт командный пул для операций с буферами
 * @details Инициализирует Vulkan командный пул, который будет использоваться
 * для выполнения команд, связанных с буферами (создание, обновление, копирование).
 * Командный пул необходим для выделения командных буферов.
 */
void BuffersCreateCommandPool();

/**
 * @brief Создаёт командный буфер для операций с буферами
 * @details Выделяет и инициализирует командный буфер из командного пула
 * для выполнения операций с буферами. Командный буфер используется для
 * записи команд создания и обновления буферов.
 */
void BuffersCreateCommand();

/**
 * @brief Уничтожает контейнер буфера и освобождает ресурсы
 * @details Освобождает все ресурсы, связанные с буфером, включая Vulkan буфер,
 * выделенную память и дескрипторы. Вызывается при удалении объекта.
 * 
 * @param container Указатель на контейнер буфера, который нужно уничтожить
 */
void BuffersDestroyContainer(BufferContainer *container);

/**
 * @brief Уничтожает объект по указателю
 * @details Универсальная функция для уничтожения объектов через указатель.
 * Используется как функция обратного вызова для освобождения ресурсов.
 * 
 * @param obj Указатель на объект, который нужно уничтожить
 */
void BuffersDestroyer(void *obj);

/**
 * @brief Создаёт вершинный буфер
 * @details Создаёт Vulkan буфер для хранения вершинных данных с указанными
 * параметрами конфигурации. Буфер создаётся в памяти, доступной для CPU
 * для последующего обновления данных.
 * 
 * @param vert Указатель на структуру параметров вершины, содержащую конфигурацию буфера
 * @return 0 в случае успеха, код ошибки в случае неудачи
 */
int BuffersCreateVertex(VertexParam *vert);

/**
 * @brief Обновляет вершинный буфер новыми данными
 * @details Копирует новые вершинные данные в уже существующий буфер.
 * Использует временный буфер и команды копирования для эффективного
 * обновления данных без пересоздания буфера.
 * 
 * @param vert Указатель на структуру параметров вершины, содержащую обновлённые данные
 * @return 0 в случае успеха, код ошибки в случае неудачи
 */
int BuffersUpdateVertex(VertexParam *vert);

/**
 * @brief Создаёт индексный буфер
 * @details Создаёт Vulkan буфер для хранения индексных данных с указанными
 * параметрами конфигурации. Индексный буфер используется для рендеринга
 * геометрии с переиспользованием вершин.
 * 
 * @param ind Указатель на структуру параметров индекса, содержащую конфигурацию буфера
 * @return 0 в случае успеха, код ошибки в случае неудачи
 */
int BuffersCreateIndex(IndexParam *ind);

/**
 * @brief Обновляет индексный буфер новыми данными
 * @details Копирует новые индексные данные в уже существующий буфер.
 * Использует временный буфер и команды копирования для эффективного
 * обновления данных без пересоздания буфера.
 * 
 * @param ind Указатель на структуру параметров индекса, содержащую обновлённые данные
 * @return 0 в случае успеха, код ошибки в случае неудачи
 */
int BuffersUpdateIndex(IndexParam *ind);

/**
 * @brief Пересоздаёт униформные буферы для шаблона рендеринга
 * @details Пересоздаёт все униформные буферы в указанном шаблоне рендеринга.
 * Используется при изменении конфигурации или восстановлении после
 * потери устройства Vulkan.
 * 
 * @param blueprints Указатель на структуру шаблона рендеринга, содержащую униформные буферы
 */
void BuffersRecreateUniform(BluePrints *blueprints);

/**
 * @brief Создаёт буфер хранения (storage buffer)
 * @details Создаёт Vulkan буфер типа storage buffer, который может быть
 * использован в шейдерах для чтения и записи данных. Буфер создаётся
 * в памяти, доступной для GPU.
 * 
 * @param uniform Указатель на структуру контейнера буфера для инициализации
 */
void BuffersCreateStorage(BufferContainer *uniform);

/**
 * @brief Создаёт униформный буфер
 * @details Создаёт Vulkan буфер типа uniform buffer, который используется
 * для передачи неизменяемых данных в шейдеры (матрицы, цвета, параметры
 * освещения и т.д.). Буфер создаётся в памяти, доступной для CPU.
 * 
 * @param uniform Указатель на структуру контейнера буфера для инициализации
 */
void BuffersCreateUniform(BufferContainer *uniform);

/**
 * @brief Находит подходящий тип памяти для выделения Vulkan буфера
 * @details Производит поиск типа памяти, который соответствует требованиям
 * к свойствам (device local, host visible и т.д.) и поддерживается Vulkan
 * реализацией. Используется при выделении памяти для буферов.
 * 
 * @param typeFilter Битовая маска типов памяти, поддерживаемых Vulkan
 * @param properties Требуемые свойства памяти (VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT,
 * VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT и т.д.)
 * @return Индекс найденного типа памяти, или 0xFFFFFFFF если подходящий тип не найден
 */
uint32_t findMemoryType(uint32_t typeFilter, uint32_t properties);

/**
 * @brief Создаёт Vulkan буфер с указанными параметрами
 * @details Создаёт Vulkan буфер заданного размера с указанным назначением
 * (вершинный, индексный, униформный и т.д.) и свойствами памяти. Инициализирует
 * структуру BufferObject всеми необходимыми ресурсами.
 * 
 * @param size Размер буфера в байтах
 * @param usage Битовая маска назначения буфера (VK_BUFFER_USAGE_VERTEX_BUFFER_BIT,
 * VK_BUFFER_USAGE_INDEX_BUFFER_BIT, VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT и т.д.)
 * @param properties Свойства памяти буфера (VK_MEMORY_PROPERTY_*_BIT)
 * @param buffer Указатель на структуру объекта буфера, которая будет инициализирована
 * @param type Тип создаваемого буфера (вершинный, индексный, униформный и т.д.)
 */
void BuffersCreate(uint64_t size, uint32_t usage, uint32_t properties, BufferObject *buffer, uint32_t type);

/**
 * @brief Копирует данные между двумя буферами
 * @details Выполняет копирование данных из исходного буфера в целевой буфер
 * с использованием Vulkan команд. Оба буфера должны быть созданы и готовы
 * к использованию.
 * 
 * @param srcBuffer Указатель на исходный объект буфера
 * @param dstBuffer Указатель на целевой объект буфера
 * @param size Количество байт для копирования
 */
void BuffersCopy(BufferObject *srcBuffer, BufferObject *dstBuffer, uint64_t size);

/**
 * @brief Копирует данные из Vulkan изображения в буфер
 * @details Выполняет копирование пиксельных данных из Vulkan изображения
 * в буфер для последующей обработки или сохранения. Использует команды
 * перехода состояния изображения и копирования.
 * 
 * @param image Vulkan объект изображения, из которого нужно скопировать данные
 * @param width Ширина изображения в пикселях
 * @param height Высота изображения в пикселях
 * @param dstBuffer Указатель на целевой объект буфера
 */
void BuffersFromImage(VkImage image, uint32_t width, uint32_t height, BufferObject *dstBuffer);

#ifdef __cplusplus
}
#endif

#endif // E_BUFFER_H