namespace Engine.Core;

/// <summary>
/// Represents a 3D camera in the engine.
/// </summary>
public interface ICamera3D : IBehaviour3D
{
    /// <summary>
    /// Event triggered when the near plane of the <see cref="ICamera3D"/> changes.
    /// </summary>
    Event<ICamera3D, NearPlaneChangedArguments> OnNearPlaneChanged { get; }

    /// <summary>
    /// Event triggered when the far plane of the <see cref="ICamera3D"/> changes.
    /// </summary>
    Event<ICamera3D, FarPlaneChangedArguments> OnFarPlaneChanged { get; }

    /// <summary>
    /// Event triggered when the field of view of the <see cref="ICamera3D"/> changes.
    /// </summary>
    Event<ICamera3D, FieldOfViewChangedArguments> OnFieldOfViewChanged { get; }

    /// <summary>
    /// Near plane distance of the camera.
    /// </summary>
    float NearPlane { get; set; }

    /// <summary>
    /// Far plane distance of the camera.
    /// </summary>
    float FarPlane { get; set; }

    /// <summary>
    /// Field of View (FOV) value of the camera in degrees.
    /// </summary>
    float FieldOfView { get; set; }

    /// <summary>
    /// Converts a position from screen coordinates to a <see cref="Ray3D"/>.
    /// </summary>
    /// <param name="screenPosition">The position in screen coordinates.</param>
    /// <returns>The <see cref="Ray3D"/> originating from the camera to the screen position in world coordinates.</returns>
    Ray3D ScreenToWorldRay(Vector2D screenPosition);

    /// <summary>
    /// Converts a position from world coordinates to screen coordinates.
    /// </summary>
    /// <param name="worldPosition">The position in world coordinates.</param>
    /// <returns>The position in screen coordinates.</returns>
    Vector2D WorldToScreenPosition(Vector3D worldPosition);

    readonly record struct NearPlaneChangedArguments(float PreviousNearPlane);
    readonly record struct FarPlaneChangedArguments(float PreviousFarPlane);
    readonly record struct FieldOfViewChangedArguments(float PreviousFieldOfView);
}