viewport.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

//=============================================================================
//
// Definition for the game viewports and cameras.
//
//=============================================================================

#ifndef AGS_ENGINE_GAME_VIEWPORT_H
#define AGS_ENGINE_GAME_VIEWPORT_H

#include "common/std/memory.h"
#include "common/std/vector.h"
#include "ags/shared/util/geometry.h"
#include "ags/shared/util/scaling.h"

namespace AGS3 {

class Camera;
class Viewport;

typedef std::shared_ptr<Camera> PCamera;
typedef std::shared_ptr<Viewport> PViewport;
typedef std::weak_ptr<Camera> CameraRef;
typedef std::weak_ptr<Viewport> ViewportRef;

// TODO: move to utility header
// From https://stackoverflow.com/questions/45507041/how-to-check-if-weak-ptr-is-empty-non-assigned
// Tests that weak_ptr is empty (was not initialized with valid reference)
template <typename T>
bool is_uninitialized(std::weak_ptr<T> const &weak) {
    using wt = std::weak_ptr<T>;
    return !weak.owner_before(wt{}) &&!wt{} .owner_before(weak);
}


// Camera defines a "looking eye" inside the room, its position and size.
// It does not render anywhere on its own, instead it is linked to a viewport
// and latter draws what that camera sees.
// One camera may be linked to multiple viewports.
// Camera does not move on its own, this is performed by separate behavior
// algorithm. But it provides "lock" property that tells if its position is
// currently owned by user script.
class Camera {
public:
    // Gets camera ID (serves as an index)
    inline int GetID() const {
        return _id;
    }
    // Sets new camera ID
    void SetID(int id);
    // Returns Room camera position and size inside the room (in room coordinates)
    const Rect &GetRect() const;
    // Sets explicit room camera's orthographic size
    void SetSize(const Size sz);
    // Puts room camera to the new location in the room
    void SetAt(int x, int y);
    // Tells if camera is currently locked at custom position
    bool IsLocked() const;
    // Locks room camera at its current position
    void Lock();
    // Similar to SetAt, but also locks camera preventing it from following player character
    void LockAt(int x, int y);
    // Releases camera lock, letting it follow player character
    void Release();

    // Link this camera to a new viewport; this does not unlink any linked ones
    void LinkToViewport(ViewportRef viewport);
    // Unlinks this camera from a given viewport; does nothing if link did not exist
    void UnlinkFromViewport(int id);
    // Get the array of linked viewport references
    const std::vector<ViewportRef> &GetLinkedViewports() const;

    // Tell if this camera has changed recently
    inline bool HasChangedPosition() const {
        return _hasChangedPosition;
    }
    inline bool HasChangedSize() const {
        return _hasChangedSize;
    }
    // Clears the changed flags
    void ClearChangedFlags() {
        _hasChangedPosition = false;
        _hasChangedSize = false;
    }

private:
    int _id = -1;
    // Actual position and orthographic size
    Rect _position;
    // Locked or following player automatically
    bool _locked = false;
    // Linked viewport refs, used to notify viewports of camera changes
    std::vector<ViewportRef> _viewportRefs;
    // Flags that tell whether this camera's position on screen has changed recently
    bool _hasChangedPosition = false;
    bool _hasChangedSize = false;
};


// A result of coordinate conversion between screen and the room,
// tells which viewport was used to pass the "touch" through.
typedef std::pair<Point, int> VpPoint;


// Viewport class defines a rectangular area on game screen where the contents
// of a Camera are rendered.
// Viewport may have one linked camera at a time.
class Viewport {
public:
    // Gets viewport ID (serves as an index)
    inline int GetID() const {
        return _id;
    }
    // Sets new viewport ID
    void SetID(int id);
    // Returns viewport's position on screen
    inline const Rect &GetRect() const {
        return _position;
    }
    // Returns viewport's room-to-screen transformation
    inline const AGS::Shared::PlaneScaling &GetTransform() const {
        return _transform;
    }
    // Set viewport's rectangle on screen
    void SetRect(const Rect &rc);
    // Sets viewport size
    void SetSize(const Size sz);
    // Sets viewport's position on screen
    void SetAt(int x, int y);

    // Tells whether viewport content is rendered on screen
    bool IsVisible() const {
        return _visible;
    }
    // Changes viewport visibility
    void SetVisible(bool on);
    // Gets the order viewport is displayed on screen
    int GetZOrder() const {
        return _zorder;
    }
    // Sets the viewport's z-order on screen
    void SetZOrder(int zorder);

    // Calculates room-to-viewport coordinate conversion.
    void AdjustTransformation();
    // Returns linked camera
    PCamera GetCamera() const;
    // Links new camera to this viewport, overriding existing link;
    // pass nullptr to leave viewport without a camera link
    void LinkCamera(PCamera cam);

    // TODO: provide a Transform object here that does these conversions instead
    // Converts room coordinates to the game screen coordinates through this viewport;
    // if clipping is on, the function will fail for room coordinates outside of camera
    VpPoint RoomToScreen(int roomx, int roomy, bool clip = false) const;
    // Converts game screen coordinates to the room coordinates through this viewport;
    // if clipping is on, the function will fail for screen coordinates outside of viewport;
    // convert_cam_to_data parameter converts camera "game" coordinates to "data" units (legacy mode)
    VpPoint ScreenToRoom(int scrx, int scry, bool clip = false, bool convert_cam_to_data = false) const;

    // Following functions tell if this viewport has changed recently
    inline bool HasChangedPosition() const {
        return _hasChangedPosition;
    }
    inline bool HasChangedSize() const {
        return _hasChangedSize;
    }
    inline bool HasChangedVisible() const {
        return _hasChangedVisible;
    }
    inline void SetChangedVisible() {
        _hasChangedVisible = true;
    }
    // Clears the changed flags
    inline void ClearChangedFlags() {
        _hasChangedPosition = false;
        _hasChangedSize = false;
        _hasChangedVisible = false;
    }

private:
    // Parameterized implementation of screen-to-room coordinate conversion
    VpPoint ScreenToRoomImpl(int scrx, int scry, bool clip, bool convert_cam_to_data);

    int _id = -1;
    // Position of the viewport on screen
    Rect _position;
    // TODO: Camera reference (when supporting multiple cameras)
    // Coordinate transform between camera and viewport
    // TODO: need to add rotate conversion to let script API support that;
    // (maybe use full 3D matrix for that)
    AGS::Shared::PlaneScaling _transform;
    // Linked camera reference
    CameraRef _camera;
    bool _visible = true;
    int _zorder = 0;
    // Flags that tell whether this viewport's position on screen has changed recently
    bool _hasChangedPosition = false;
    bool _hasChangedOffscreen = false;
    bool _hasChangedSize = false;
    bool _hasChangedVisible = false;
};

} // namespace AGS3

#endif // AGS_ENGINE_AC_VIEWPORT_H