/**
 * @file Camera.h
 * @brief 相机句柄与视图/投影参数接口定义。
 * @details
 * camera 提供对渲染相机实例的统一访问，覆盖：
 * - 透视/正交两类投影参数设置；
 * - 视图矩阵、投影矩阵及其逆矩阵查询；
 * - 近远裁剪面、宽高与绑定实体 ID 读取。
 */
#pragma once
#include "CommonHeader.h"

namespace XEngine::graphics {


/**
 * @brief 相机强类型标识符。
 */
DEFINE_TYPED_ID(camera_id);

/**
 * @brief 渲染相机句柄对象。
 */
class camera
{
public:
	/**
	 * @brief 投影模式枚举。
	 */
	enum type :u32
	{
		perspective,
		orthographic,
	};

	constexpr explicit camera(camera_id id) : _id{ id } {}
	constexpr camera() = default;
	constexpr camera_id get_id() const { return _id; }
	constexpr bool is_valid() const { return id::is_valid(_id); }

	/**
	 * @brief 设置相机上方向。
	 */
	void up(math::v3 up) const;
	/**
	 * @brief 设置透视投影视场角。
	 */
	void field_of_view(f32 fov)	const;
	/**
	 * @brief 设置视口宽高比。
	 */
	void aspect_ratio(f32 aspect_ratio) const;
	/**
	 * @brief 设置正交视口宽度。
	 */
	void view_width(f32 width) const;
	/**
	 * @brief 设置正交视口高度。
	 */
	void view_height(f32 height) const;
	/**
	 * @brief 设置近远裁剪面。
	 */
	void range(f32 near_z, f32 far_z) const;

	/**
	 * @brief 获取视图矩阵。
	 */
	math::m4x4 view() const;
	/**
	 * @brief 获取投影矩阵。
	 */
	math::m4x4 projection() const;
	/**
	 * @brief 获取投影矩阵逆矩阵。
	 */
	math::m4x4 inverse_projection() const;
	/**
	 * @brief 获取视图投影矩阵。
	 */
	math::m4x4 view_projection() const;
	/**
	 * @brief 获取视图投影逆矩阵。
	 */
	math::m4x4 inverse_view_projection() const;
	/**
	 * @brief 获取上方向向量。
	 */
	math::v3 up() const;

	/**
	 * @brief 获取近裁剪面。
	 */
	f32 near_z() const;
	/**
	 * @brief 获取远裁剪面。
	 */
	f32 far_z() const;
	/**
	 * @brief 获取视场角。
	 */
	f32 field_of_view() const;
	/**
	 * @brief 获取宽高比。
	 */
	f32 aspect_ratio() const;
	/**
	 * @brief 获取视口宽度。
	 */
	f32 view_width() const;
	/**
	 * @brief 获取视口高度。
	 */
	f32 view_height() const;
	/**
	 * @brief 获取投影类型。
	 */
	type projection_type() const;
	/**
	 * @brief 获取绑定实体 ID。
	 */
	id::id_type entity_id() const;
private:
	camera_id _id{ id::invalid_id };
};


}
