includes/TigorEngine.h - master - Zamar_Terrier/TigorEngine

includes/TigorEngine.h
353 строки16 KB
Zamar_Terrier
Офигенное обновление движка
31 июл 2026, 21:03
31 июл 2026, 21:031682686
/**
 * @file TigorEngine.h
 * @brief Основной заголовочный файл игрового движка TigorEngine
 * 
 * @details Этот файл содержит основные типы данных, функции и макросы для работы
 * с игровым движком TigorEngine. Он предоставляет интерфейс для инициализации
 * движка, управления окном, обработки ввода и отрисовки графики.
 * 
 * Основные возможности:
 * - Инициализация и настройка движка
 * - Управление окном и рендерингом
 * - Обработка ввода (клавиатура, мышь)
 * - Работа с ресурсами и шейдерами
 * - Система объектов и компонентов
 */

#ifndef TigorEngine_H
#define TigorEngine_H

#include <stdint.h>
#include <Objects/gameObject.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Тип функции отрисовки
 * 
 * Функция этого типа используется для пользовательской отрисовки графических объектов.
 * Вызывается движком каждый кадр для отрисовки сцены.
 */
typedef void (*DrawFunc_T)();

/**
 * @brief Тип функции пересоздания ресурсов
 * 
 * Функция этого типа вызывается при изменении размера окна или необходимости
 * пересоздания графических ресурсов (например, после изменения параметров Vulkan).
 */
typedef void (*RecreateFunc_T)();

/**
 * @brief Тип функции обновления с учетом времени
 * 
 * Функция этого типа используется для обновления состояния объектов с учетом
 * времени, прошедшего с последнего кадра. Позволяет создавать плавную
 * анимацию, независимую от частоты кадров.
 * 
 * @param deltaTime Время, прошедшее с последнего кадра в секундах
 */
typedef void (*UpdateFunc_T)(float deltaTime);

/**
 * @brief Блокирует глобальный мьютекс движка
 * 
 * Блокирует глобальный мьютекс движка для обеспечения потокобезопасного
 * доступа к общим ресурсам. Должен использоваться при многопоточной работе.
 * 
 * @return 0 при успешной блокировке, код ошибки в противном случае
 */
int TEngineLockGlobal();

/**
 * @brief Разблокирует глобальный мьютекс движка
 * 
 * Разблокирует глобальный мьютекс движка после завершения операций с
 * общими ресурсами. Должен вызываться после TEngineLockGlobal().
 * 
 * @return 0 при успешной разблокировке, код ошибки в противном случае
 */
int TEngineUnLockGlobal();

/**
 * @brief Пытается заблокировать глобальный мьютекс движка без ожидания
 * 
 * Пытается заблокировать глобальный мьютекс движка немедленно без ожидания.
 * Возвращает управление немедленно, независимо от того, был ли мьютекс заблокирован.
 * 
 * @return 0 при успешной блокировке, APR_STATUS_IS_EBUSY если мьютекс занят другим потоком
 */
int TEngineTryLockGlobal();

/**
 * @brief Инициализирует игровой движок
 * 
 * Инициализирует все компоненты игрового движка, включая Vulkan, оконную систему,
 * системы рендеринга и обработки ввода. Должен вызываться перед любыми другими
 * функциями движка.
 * 
 * @param width Ширина окна в пикселях
 * @param height Высота окна в пикселях
 * @param name Имя приложения, отображаемое в заголовке окна
 */
void TEngineInitSystem(int width, int height, const char* name);

/**
 * @brief Устанавливает путь к текущему шрифту
 * 
 * Устанавливает путь к файлу шрифта, котор��й будет использоваться для
 * отрисовки текста в интерфейсе.
 * 
 * @param font_path Путь к файлу шрифта (например, "assets/fonts/arial.ttf")
 */
void TEngineSetFont(char *font_path);

/**
 * @brief Устанавливает объекты рендеринга для отрисовки
 * 
 * Устанавливает массив объектов рендеринга, которые будут отрисовываться
 * каждый кадр. Эти объекты могут быть 2D или 3D объектами.
 * 
 * @param obj Указатель на массив объектов RenderTexture
 * @param count Количество объектов в массиве
 */
void TEngineSetRender(void *obj, uint32_t count);

/**
 * @brief Устанавливает функцию, вызываемую при изменении размера окна
 * 
 * Устанавливает пользовательскую функцию, которая будет вызываться при
 * изменении размера окна. Эта функция может пересоздавать ресурсы,
 * адаптировать камеру и выполнять другие действия, необходимые для
 * корректной работы при новом размере окна.
 * 
 * @param recreate Указатель на функцию пересоздания ресурсов
 */
void TEngineSetRecreateFunc(EngineRecreateFunc recreate);

/**
 * @brief Вызывает отрисовку объектов на всех указанных рендерах
 * 
 * Осуществляет отрисовку всех объектов, установленных через TEngineSetRender(),
 * на всех активных рендерах (основной экран, offscreen рендеры и т.д.).
 */
void TEngineRender();

/**
 * @brief Вызывает отрисовку элементов GUI
 * 
 * Осуществляет отрисовку всех элементов графического интерфейса (GUI),
 * установленных через соответствующие функции GUI-модуля.
 */
void TEngineRenderGUI();

/**
 * @brief Устанавливает функцию обновления данных
 * 
 * Устанавливает пользовательскую функцию, которая будет вызываться
 * каждый кадр для обновления игровой логики, анимаций и других данных.
 * 
 * @param update Указатель на функцию обновления
 */
void TEngineSetUpdater(EngineUpdateFunc update);

/**
 * @brief Устанавливает функцию отрисовки объектов
 * 
 * Устанавливает пользовательскую функцию, которая будет вызываться
 * для отрисовки пользовательских объектов после отрисовки основных
 * объектов рендеринга.
 * 
 * @param draw Указатель на функцию отрисовки
 */
void TEngineSetDrawer(EngineDrawFunc draw);

/**
 * @brief Запускает основной цикл рендеринга
 * 
 * Запускает основной цикл обработки событий, отрисовки и обновления.
 * Эта функция блокирует выполнение до тех пор, пока окно не будет закрыто.
 */
void TEngineStartRender();

/**
 * @brief Устанавливает обратный вызов для событий клавиш клавиатуры
 * 
 * Устанавливает функцию обратного вызова, которая будет вызываться
 * при нажатии или отпускании клавиш клавиатуры.
 * 
 * @param callback Указатель на функцию обратного вызова void callback(int key, int action)
 */
void TEngineSetKeyCallback(void *callback);

/**
 * @brief Устанавливает обратный вызов для ввода текста с клавиатуры
 * 
 * Устанавливает функцию обратного вызова, которая будет вызываться
 * при вводе текстовых символов (включая локализованные символы).
 * 
 * @param callback Указатель на функцию обратного вызова void callback(unsigned int codepoint)
 */
void TEngineSetCharCallback(void *callback);

/**
 * @brief Устанавливает обратный вызов для событий кнопок мыши
 * 
 * Устанавливает функцию обратного вызова, которая будет вызываться
 * при нажатии или отпускании кнопок мыши.
 * 
 * @param callback Указатель на функцию обратного вызова void callback(int button, int action)
 */
void TEngineSetMouseKeyCallback(void *callback);

/**
 * @brief Устанавливает обратный вызов для изменения позиции курсора мыши
 * 
 * Устанавливает функцию обратного вызова, которая будет вызываться
 * при движении курсора мыши по окну.
 * 
 * @param callback Указатель на функцию обратного вызова void callback(double x, double y)
 */
void TEngineSetCursorPoscallback(void * callback);

/**
 * @brief Получает размеры окна
 * 
 * Возвращает текущие размеры окна приложения.
 * 
 * @param width Указатель для возврата ширины окна
 * @param height Указатель для возврата высоты окна
 */
void TEngineGetWindowSize(int *width, int *height);

/**
 * @brief Фиксирует курсор в центре экрана
 * 
 * Фиксирует курсор мыши в центре окна, что полезно для управления
 * камерой в 3D приложениях (FPS/TPS камеры).
 */
void TEngineFixedCursorCenter();

/**
 * @brief Получает текущую позицию курсора мыши
 * 
 * Возвращает текущую позицию курсора мыши в координатах окна.
 * 
 * @param xpos Указатель для возврата координаты X
 * @param ypos Указатель для возврата координаты Y
 */
void TEngineGetCursorPos(double *xpos, double *ypos);

/**
 * @brief Устанавливает позицию курсора мыши
 * 
 * Устанавливает позицию курсора мыши в указанные координаты.
 * 
 * @param xpos Координата X курсора
 * @param ypos Координата Y курсора
 */
void TEngineSetCursorPos(float xpos, float ypos);

/**
 * @brief Устанавливает видимость курсора
 * 
 * Устанавливает состояние видимости и активности курсора мыши.
 * 
 * @param state Состояние курсора:
 *              0 - отключен и не видим
 *              1 - не видим и активен (используется для камеры)
 *              2 - видим и активен (обычный режим)
 */
void TEngineHideCursor(char state);

/**
 * @brief Проверяет нажатие кнопки мыши
 * 
 * Возвращает текущее состояние указанной кнопки мыши.
 * 
 * @param Key Идентификатор кнопки мыши (например, TIGOR_KEY_MOUSE_LEFT)
 * @return 1 если кнопка нажата, 0 если отпущена
 */
int TEngineGetMousePress(int Key);

/**
 * @brief Проверяет нажатие кнопки клавиатуры
 * 
 * Возвращает текущее состояние указанной клавиши клавиатуры.
 * 
 * @param Key Идентификатор клавиши клавиатуры (например, TIGOR_KEY_W)
 * @return 1 если клавиша нажата, 0 если отпущена
 */
int TEngineGetKeyPress(int Key);

/**
 * @brief Проверяет, является ли текущий рендер основным
 * 
 * Проверяет, является ли текущий рендеринг основным (на экран),
 * или это offscreen рендеринг (в текстуру и т.д.).
 * 
 * @return 1 если основной рендер, 0 если offscreen
 */
int TEngineIsMainRender();

/**
 * @brief Проверяет, закрыто ли окно
 * 
 * Проверяет флаг закрытия окна. Возвращает true, если пользователь
 * закрыл окно (нажал кнопку закрытия).
 * 
 * @return 1 если окно закрыто, 0 если открыто
 */
int TEngineWindowIsClosed();

/**
 * @brief Получает текущее время с момента запуска программы
 * 
 * Возвращает время в секундах, прошедшее с момента вызова TEngineInitSystem().
 * Используется для расчета deltaTime и анимаций.
 * 
 * @return Время в секундах как значение типа double
 */
double TEngineGetTime();

/**
 * @brief Получает строку из буфера обмена окна
 * 
 * Возвращает текущее содержимое системного буфера обмена (clipboard).
 * 
 * @return Указатель на строку в буфере обмена (внутренний буфер, не освобождать)
 */
const char *TEngineGetClipBoardString();

/**
 * @brief Устанавливает строку в буфер обмена окна
 * 
 * Копирует указанную строку в системный буфер обмена.
 * 
 * @param string Строка для установки в буфер обмена
 */
void TEngineSetClipBoardString(const char *string);

/**
 * @brief Очищает ресурсы движка перед закрытием
 * 
 * Освобождает все ресурсы, выделенные движком, включая Vulkan-ресурсы,
 * текстуры, шейдеры, окна и т.д. Должен вызываться перед завершением программы.
 */
void TEngineCleanUp();

/**
 * @brief Ожидает завершения работы устройства Vulkan
 * 
 * Блокирует выполнение до тех пор, пока все операции на устройстве Vulkan
 * не будут завершены. Используется для безопасного освобождения ресурсов.
 */
void TEngineDeviceWaitIdle();

#ifdef __cplusplus
}
#endif

#endif // TigorEngine_H