LogicalViewport.hpp

Go to the documentation of this file.

#pragma once
 
#include <optional>
 
namespace monopoly::logicalviewport
{
    // The legacy 2D/UI contract remains 4:3. The historical 3D viewport is
    // independently 800x450 (16:9) and can therefore use the full modern
    // presentation surface without stretching the UI.
    inline constexpr double LogicalWidth = 800.0;
    inline constexpr double LogicalHeight = 600.0;
    inline constexpr double World3DWidth = 800.0;
    inline constexpr double World3DHeight = 450.0;
 
    struct Transform
    {
        double scale = 0.0;
        double offsetX = 0.0;
        double offsetY = 0.0;
        double pixelWidth = 0.0;
        double pixelHeight = 0.0;
 
        [[nodiscard]] bool valid() const noexcept;
    };
 
    struct LogicalPoint
    {
        double x = 0.0;
        double y = 0.0;
    };
 
    struct LogicalRect
    {
        double x = 0.0;
        double y = 0.0;
        double width = 0.0;
        double height = 0.0;
    };
 
    struct PixelRect
    {
        double x = 0.0;
        double y = 0.0;
        double width = 0.0;
        double height = 0.0;
    };
 
    // Fits the original 800x600 coordinate system inside a pixel extent while
    // preserving its aspect ratio. Any unused area forms centered letterbox
    // or pillarbox bars. A non-positive extent produces an invalid transform.
    [[nodiscard]] Transform makeTransform(
        int targetWidth,
        int targetHeight
    ) noexcept;
 
    // Fits the historical 16:9 3D canvas independently of the 4:3 UI.
    [[nodiscard]] Transform makeWorld3DTransform(
        int targetWidth,
        int targetHeight
    ) noexcept;
 
    // The content area is half-open: its top and left edges are included,
    // while its right and bottom edges belong to the surrounding bars/outside
    // area. This matches the coordinate range produced by pixel-based input.
    [[nodiscard]] std::optional<LogicalPoint> windowToLogical(
        const Transform& transform,
        double windowX,
        double windowY
    ) noexcept;
 
    // The bottom retail UI strip overlays the expanded 16:9 board surface.
    // Its input stays in the 800x600 canvas, ahead of 3D input remapping.
    [[nodiscard]] std::optional<LogicalPoint> windowToUIOverlay(
        const Transform& uiTransform, double windowX, double windowY) noexcept;
 
    // UI outside the authored 3D viewport overlays its expanded pixel area.
    // A modal owns the entire UI canvas, including any area over the board.
    [[nodiscard]] std::optional<LogicalPoint> windowToUIOverlay(
        const Transform& uiTransform, double windowX, double windowY,
        const LogicalRect& worldViewport, bool modal = false) noexcept;
 
    // Converts a logical rectangle without clipping or integer rounding. The
    // caller can apply the rounding policy required by its rendering backend.
    [[nodiscard]] PixelRect logicalToPixelRect(
        const Transform& transform,
        const LogicalRect& logicalRect
    ) noexcept;
}