From 560f2b9d9a9e8b65881cbd9be81f0add8f76e620 Mon Sep 17 00:00:00 2001 From: Luis Michaelis Date: Sun, 25 Feb 2024 16:36:09 +0100 Subject: [PATCH] docs(VCutsceneCamera): add documentation comments for `VCutsceneCamera` --- include/zenkit/vobs/Camera.hh | 130 ++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/include/zenkit/vobs/Camera.hh b/include/zenkit/vobs/Camera.hh index 3999e693..0a76a5fa 100644 --- a/include/zenkit/vobs/Camera.hh +++ b/include/zenkit/vobs/Camera.hh @@ -17,11 +17,23 @@ namespace zenkit { enum class CameraMotion : std::uint32_t { UNDEFINED = 0, + + /// \brief The movement method is calculated taking into account nearby frames. SMOOTH = 1, + + /// \brief Constant speed in the current frame. LINEAR = 2, + + /// \brief Step by step. Movement is jerky. STEP = 3, + + /// \brief The camera movement slows down in the current frame. SLOW = 4, + + /// \brief The camera movement accelerates in the current frame. FAST = 5, + + /// \brief Not implemented. CUSTOM = 6, // Deprecated entries. @@ -36,6 +48,7 @@ namespace zenkit { enum class CameraCoordinateReference : std::uint32_t { /// \brief Positions are relative to the global world coordinate system. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#targettrjfor WORLD = 0, /// \brief Positions are relative to the position of the camera object in the previous frame. @@ -43,6 +56,8 @@ namespace zenkit { /// Essentially, when the camera travels along the keyframes each subsequent keyframe's position is relative /// to the position of the previous keyframe. The position of the first keyframe is relative to the initial /// position of the camera. + /// + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#targettrjfor OBJECT = 1, // Deprecated entries. @@ -51,9 +66,21 @@ namespace zenkit { }; enum class CameraLerpType : std::uint32_t { + /// \brief Unset. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#spllerpmode UNDEFINED = 0, + + /// \brief The camera's orientation is specified by the slope of the target path spline. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#spllerpmode PATH = 1, + + /// \brief The camera's orientation is similar to PATH with the only difference being that the camera's XZ + /// plane is always parallel to the world's XZ plane. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#spllerpmode PATH_IGNORE_ROLL = 2, + + /// \brief The camera's orientation is based on the keyframes. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#spllerpmode PATH_ROTATION_SAMPLES = 3, // Deprecated entries. @@ -65,18 +92,23 @@ namespace zenkit { enum class CameraLoop : std::uint32_t { /// \brief The camera animation stops after the last frame is reached. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#loopmode NONE = 0, /// \brief The camera animation starts from the beginning after the last frame is reached. /// /// The ModKit states, that this is only useful if the animation is to be interrupted by scripts /// or triggers. + /// + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#loopmode RESTART = 1, /// \brief The camera animation re-plays the keyframes in reverse order after reaching the last frame. /// /// This causes the camera to infinitely move back and forth along the keyframes. The ModKit states, that /// like CameraLoop::RESTART, this is only useful if the animation will be interrupted by scripts or triggers. + /// + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#loopmode PINGPONG = 2, // Deprecated entries. @@ -86,21 +118,60 @@ namespace zenkit { }; /// \brief A VOb which describes the trajectory of a camera during a cutscene. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/ struct VCameraTrajectoryFrame : VirtualObject { ZK_OBJECT(ObjectType::zCCamTrj_KeyFrame); + /// \brief Unclear. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#time float time; + + /// \brief The camera rotation angle of the frame along the Z axis. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#anglerolldeg float roll_angle; + + /// \brief Focal zoom of the camera's field of view (FOV) of the frame. Use reasonable values to avoid dizzying effects. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#camfovscale float fov_scale; + + /// \brief The type of camera movement for the frame. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#motiontype CameraMotion motion_type; + + /// \brief The type of focus change for the frame. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#motiontypefov CameraMotion motion_type_fov; + + /// \brief The type of rotation for the frame. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#motiontyperoll CameraMotion motion_type_roll; + + /// \brief Unclear. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#motiontypetimescale CameraMotion motion_type_time_scale; + + /// \brief Defines the bend of the camera motion curve at the specified key. Larger values result in a sharper bend. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#tension float tension; + + /// \brief Determines the slope of a line in one direction. The direction of the slope is determined by the sign, and the steepness by the value. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#bias float cam_bias; + + /// \brief Determines the amount of curve discontinuity at this animation key. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#continuity float continuity; + + /// \brief Unknown. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#timescale float time_scale; + + /// \brief An auxiliary flag indicating the time of the key frame, which cannot be changed automatically. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#timeisfixed bool time_fixed; + + /// \brief Unknown. + /// \see https://zk.gothickit.dev/engine/objects/zCCamTrj_KeyFrame/#originalpose glm::mat4 original_pose; ZKREM("use ::load()") @@ -118,40 +189,99 @@ namespace zenkit { }; /// \brief A VOb which defined the movement of the camera during a cutscene. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/ struct VCutsceneCamera : VirtualObject { ZK_OBJECT(ObjectType::zCCSCamera); /// \brief The reference coordinate system of camera trajectory keyframes. /// \note FOR stands for "frame of reference". + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#camtrjfor CameraCoordinateReference trajectory_for; /// \brief The reference coordinate system of camera target keyframes. /// \note FOR stands for "frame of reference". + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#targettrjfor CameraCoordinateReference target_trajectory_for; /// \brief The repetition mode of the camera animation. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#loopmode CameraLoop loop_mode; + + /// \brief Adjust camera orientation while moving. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#spllerpmode CameraLerpType lerp_mode; + + /// \brief Determines whether the orientation to reference VOB objects should be taken into account when + /// passing through key frames. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#ignoreforvobrotcam bool ignore_for_vob_rotation; + + /// \brief Determines the need to take into account the orientation of target key frames to reference VOB objects. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#ignoreforvobrottarget bool ignore_for_vob_rotation_target; + + /// \brief Indicates the need for dynamic adaptation to the environment. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#adapttosurroundings bool adapt; + + /// \brief Gives a smooth transition of camera position from the first keyframe to the last, if possible. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#easetofirstkey bool ease_first; + + /// \brief Gives a smooth transition of camera position from the last keyframe to the first, if possible. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#easefromlastkey bool ease_last; + + /// \brief The duration of the camera animation in seconds. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#totaltime float total_duration; + + /// \brief The name of the VOB object which the camera will automatically focus. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#autocamfocusvobname std::string auto_focus_vob; + + /// \brief Indicates whether the player will be able to move when moving the camera animation. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#autocamplayermovable bool auto_player_movable; + + /// \brief Emit an `OnUntrigger` event after reaching the last animation frame. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#autocamuntriggeronlastkey bool auto_untrigger_last; + + /// \brief Unclear. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#autocamuntriggeronlastkeydelay float auto_untrigger_last_delay; + + /// \brief The number of position key frames for the camera animation. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#numpos std::int32_t position_count; + + /// \brief The number of target key frames for the camera animation. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#numtargets std::int32_t target_count; + /// \brief The list of all position keyframes. std::vector> trajectory_frames; + + /// \brief The list of all target keyframes. std::vector> target_frames; // Save-game only variables + + /// \brief Unknown. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#paused bool paused {false}; + + /// \brief Unknown. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#started bool started {false}; + + /// \brief Unknown. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#gototimemode bool goto_time_mode {false}; + + /// \brief Unknown. + /// \see https://zk.gothickit.dev/engine/objects/zCCSCamera/#cstime float cs_time {0}; ZKREM("use ::load()") ZKAPI static void parse(VCutsceneCamera& obj, ReadArchive& r, GameVersion version);