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

includes/Core/e_transform.h
296 строк16 KB
Zamar_Terrier
Доработка + нововведения
06 июл 2026, 16:26
06 июл 2026, 16:260d4ab95
/**
 * @file e_transform.h
 * @brief Модуль управления трансформациями объектов
 *
 * @details Реализует функции для работы с трансформациями 2D и 3D объектов:
 * - Инициализация структур трансформаций
 * - Управление позицией, масштабом и поворотом объектов
 * - Обновление трансформаций в графе сцены
 * - Работа со смещениями изображений для 2D объектов
 *
 * Модуль предоставляет полный набор инструментов для манипуляции
 * положением и ориентацией объектов в 2D и 3D пространстве.
 */

#ifndef E_TRANSFORM_H
#define E_TRANSFORM_H

#include "Variabels/engine_includes.h"
#include "Objects/gameObject2D.h"
#include "Objects/gameObject3D.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Инициализирует структуру 2D трансформации
 *
 * @param[out] transform Указатель на структуру Transform2D для инициализации
 *
 * @details Функция устанавливает начальные значения для 2D трансформации:
 * позиция (0, 0), масштаб (1, 1), угол поворота 0 и смещение изображения (0, 0).
 * Используется при создании нового 2D объекта для подготовки его к работе.
 */
void Transform2DInit(Transform2D* transform);

/**
 * @brief Инициализирует структуру 3D трансформации
 *
 * @param[out] transform Указатель на структуру Transform3D для инициализации
 *
 * @details Функция устанавливает начальные значения для 3D трансформации:
 * позиция (0, 0, 0), масштаб (1, 1, 1), углы поворота (0, 0, 0).
 * Используется при создании нового 3D объекта для подготовки его к работе.
 */
void Transform3DInit(Transform3D* transform);

/**
 * @brief Устанавливает позицию 2D объекта
 *
 * @param[in,out] go Указатель на 2D объект (GameObject2D)
 * @param[in] x Координата X позиции в мировом пространстве
 * @param[in] y Координата Y позиции в мировом пространстве
 *
 * @details Функция устанавливает абсолютную позицию 2D объекта в мировом
 * пространстве. Обновляет внутреннюю структуру трансформации и помечает
 * объект как требующий обновления в графе сцены.
 */
void Transform2DSetPosition(GameObject2D* go, float x, float y);

/**
 * @brief Возвращает позицию 2D объекта
 *
 * @param[in] go Указатель на 2D объект (GameObject2D)
 * @return vec2 Вектор позиции объекта с координатами (x, y)
 *
 * @details Функция возвращает текущую позицию 2D объекта в мировом
 * пространстве как вектор с двумя компонентами. Используется для
 * получения координат объекта для расчетов и отображения.
 */
vec2 Transform2DGetPosition(GameObject2D* go);

/**
 * @brief Обновляет позицию 2D объекта в графе сцены
 *
 * @param[in,out] go Указатель на 2D объект (GameObject2D)
 *
 * @details Функция обновляет позицию 2D объекта в графе сцены после
 * изменения параметров трансформации. Пересчитывает матрицу трансформации
 * и обновляет параметры для последующего рендеринга. Вызывается автоматически
 * при изменении позиции, масштаба или поворота.
 */
void Transform2DReposition(GameObject2D* go);

/**
 * @brief Устанавливает смещение изображения 2D объекта
 *
 * @param[in,out] go Указатель на 2D объект (GameObject2D)
 * @param[in] x Смещение по оси X в пикселях
 * @param[in] y Смещение по оси Y в пикселях
 *
 * @details Функция устанавливает смещение изображения относительно
 * базовой позиции объекта. Используется для корректировки позиции
 * спрайта внутри объекта, например, для выравнивания или анимации.
 */
void Transform2DSetImageOffset(GameObject2D* go, float x, float y);

/**
 * @brief Возвращает смещение изображения 2D объекта
 *
 * @param[in] go Указатель на 2D объект (GameObject2D)
 * @return vec2 Вектор смещения изображения с компонентами (x, y)
 *
 * @details Функция возвращает текущее смещение изображения 2D объекта
 * относительно его базовой позиции. Используется для получения параметров
 * смещения для расчетов и отображения.
 */
vec2 Transform2DGetImageOffset(GameObject2D* go);

/**
 * @brief Устанавливает масштаб 2D объекта
 *
 * @param[in,out] go Указатель на 2D объект (GameObject2D)
 * @param[in] x Масштаб по оси X (1.0 - исходный размер)
 * @param[in] y Масштаб по оси Y (1.0 - исходный размер)
 *
 * @details Функция устанавливает масштаб 2D объекта относительно
 * исходного размера изображения. Значения больше 1.0 увеличивают объект,
 * значения меньше 1.0 уменьшают его. Обновляет матрицу трансформации
 * и помечает объект как требующий обновления.
 */
void Transform2DSetScale(GameObject2D* go, float x, float y);

/**
 * @brief Возвращает масштаб 2D объекта
 *
 * @param[in] go Указатель на 2D объект (GameObject2D)
 * @return vec2 Вектор масштаба с компонентами (x, y)
 *
 * @details Функция возвращает текущий масштаб 2D объекта как вектор
 * с двумя компонентами, представляющими масштаб по осям X и Y.
 * Используется для получения параметров масштаба для расчетов.
 */
vec2 Transform2DGetScale(GameObject2D* go);

/**
 * @brief Обновляет масштаб 2D объекта в графе сцены
 *
 * @param[in,out] go Указатель на 2D объект (GameObject2D)
 *
 * @details Функция обновляет масштаб 2D объекта в графе сцены после
 * изменения параметров трансформации. Пересчитывает матрицу трансформации
 * и обновляет параметры для последующего рендеринга. Обычно вызывается
 * автоматически при изменении масштаба.
 */
void Transform2DRescale(GameObject2D* go);

/**
 * @brief Устанавливает угол поворота 2D объекта
 *
 * @param[in,out] go Указатель на 2D объект (GameObject2D)
 * @param[in] angle Угол поворота в градусах по часовой стрелке
 *
 * @details Функция устанавливает угол поворота 2D объекта вокруг его
 * центра. Положительные значения поворачивают объект по часовой стрелке.
 * Обновляет матрицу трансформации и помечает объект как требующий обновления.
 */
void Transform2DSetRotation(GameObject2D* go, float angle);

/**
 * @brief Возвращает угол поворота 2D объекта
 *
 * @param[in] go Указатель на 2D объект (GameObject2D)
 * @return float Угол поворота в градусах (по часовой стрелке)
 *
 * @details Функция возвращает текущий угол поворота 2D объекта в градусах.
 * Положительные значения соответствуют повороту по часовой стрелке.
 * Используется для получения параметров поворота для расчетов.
 */
float Transform2DGetRotation(GameObject2D* go);

/**
 * @brief Устанавливает позицию в структуре 3D трансформации
 *
 * @param[in,out] transform Указатель на структуру Transform3D
 * @param[in] x Координата X позиции в мировом пространстве
 * @param[in] y Координата Y позиции в мировом пространстве
 * @param[in] z Координата Z позиции в мировом пространстве
 *
 * @details Функция устанавливает абсолютную позицию в структуре 3D
 * трансформации. Используется для низкоуровневой работы с трансформацией
 * независимо от объектов. Обновляет матрицу трансформации.
 */
void Transform3DSetPositionT(Transform3D* transform, float x, float y, float z);

/**
 * @brief Устанавливает позицию 3D объекта
 *
 * @param[in,out] go Указатель на 3D объект (GameObject3D)
 * @param[in] x Координата X позиции в мировом пространстве
 * @param[in] y Координата Y позиции в мировом пространстве
 * @param[in] z Координата Z позиции в мировом пространстве
 *
 * @details Функция устанавливает абсолютную позицию 3D объекта в мировом
 * пространстве. Обновляет внутреннюю структуру трансформации и помечает
 * объект как требующий обновления в графе сцены.
 */
void Transform3DSetPosition(GameObject3D* go, float x, float y, float z);

/**
 * @brief Возвращает позицию 3D объекта
 *
 * @param[in] go Указатель на 3D объект (GameObject3D)
 * @return vec3 Вектор позиции объекта с координатами (x, y, z)
 *
 * @details Функция возвращает текущую позицию 3D объекта в мировом
 * пространстве как вектор с тремя компонентами. Используется для
 * получения координат объекта для расчетов и отображения.
 */
vec3 Transform3DGetPosition(GameObject3D* go);

/**
 * @brief Устанавливает масштаб в структуре 3D трансформации
 *
 * @param[in,out] transform Указатель на структуру Transform3D
 * @param[in] x Масштаб по оси X (1.0 - исходный размер)
 * @param[in] y Масштаб по оси Y (1.0 - исходный размер)
 * @param[in] z Масштаб по оси Z (1.0 - исходный размер)
 *
 * @details Функция устанавливает масштаб в структуре 3D трансформации.
 * Значения больше 1.0 увеличивают объект, значения меньше 1.0 уменьшают его.
 * Обновляет матрицу трансформации.
 */
void Transform3DSetScaleT(Transform3D* transform, float x, float y, float z);

/**
 * @brief Устанавливает масштаб 3D объекта
 *
 * @param[in,out] go Указатель на 3D объект (GameObject3D)
 * @param[in] x Масштаб по оси X (1.0 - исходный размер)
 * @param[in] y Масштаб по оси Y (1.0 - исходный размер)
 * @param[in] z Масштаб по оси Z (1.0 - исходный размер)
 *
 * @details Функция устанавливает масштаб 3D объекта относительно
 * исходного размера. Значения больше 1.0 увеличивают объект,
 * значения меньше 1.0 уменьшают его. Обновляет матрицу трансформации.
 */
void Transform3DSetScale(GameObject3D* go, float x, float y, float z);

/**
 * @brief Возвращает масштаб 3D объекта
 *
 * @param[in] go Указатель на 3D объект (GameObject3D)
 * @return vec3 Вектор масштаба с компонентами (x, y, z)
 *
 * @details Функция возвращает текущий масштаб 3D объекта как вектор
 * с тремя компонентами, представляющими масштаб по осям X, Y и Z.
 * Используется для получения параметров масштаба для расчетов.
 */
vec3 Transform3DGetScale(GameObject3D* go);

/**
 * @brief Устанавливает вращение в структуре 3D трансформации
 *
 * @param[in,out] transform Указатель на структуру Transform3D
 * @param[in] x Угол поворота вокруг оси X в градусах
 * @param[in] y Угол поворота вокруг оси Y в градусах
 * @param[in] z Угол поворота вокруг оси Z в градусах
 *
 * @details Функция устанавливает углы поворота в структуре 3D трансформации
 * вокруг каждой из осей координат. Используется для низкоуровневой работы
 * с трансформацией. Обновляет матрицу трансформации.
 */
void Transform3DSetRotationT(Transform3D* transform, float x, float y, float z);

/**
 * @brief Устанавливает вращение 3D объекта
 *
 * @param[in,out] go Указатель на 3D объект (GameObject3D)
 * @param[in] x Угол поворота вокруг оси X в градусах
 * @param[in] y Угол поворота вокруг оси Y в градусах
 * @param[in] z Угол поворота вокруг оси Z в градусах
 *
 * @details Функция устанавливает углы поворота 3D объекта вокруг каждой
 * из осей координат. Повороты применяются последовательно вокруг каждой
 * оси. Обновляет матрицу трансформации объекта.
 */
void Transform3DSetRotation(GameObject3D* go, float x, float y, float z);

/**
 * @brief Возвращает вращение 3D объекта
 *
 * @param[in] go Указатель на 3D объект (GameObject3D)
 * @return vec3 Вектор углов поворота с компонентами (x, y, z) в градусах
 *
 * @details Функция возвращает текущие углы поворота 3D объекта вокруг
 * каждой из осей координат в градусах. Используется для получения
 * параметров вращения для расчетов и отображения.
 */
vec3 Transform3DGetRotation(GameObject3D* go);

#ifdef __cplusplus
}
#endif

#endif // E_TRANSFORM_H