mirror/OpenSpace
1
0
Fork 0
mirror of https://github.com/OpenSpace/OpenSpace.git synced 2026-04-27 22:40:41 -05:00
Code Issues Packages Projects Releases Wiki Activity

Doxygen style overhaul (#2954)

Browse Source 
Reformatting the existing Doxygen comments to be unified
This commit is contained in:
Alexander Bock
2023-11-20 23:39:17 +01:00
committed by GitHub
parent 4ee078502b
commit 7db7c40841
163 changed files with 2266 additions and 2035 deletions
Download Patch File Download Diff File Expand all files Collapse all files
include/openspace/navigation/keyframenavigator.h
+8 -7
View File
@@ -60,13 +60,14 @@ public:
};
/**
* Update camera position using the next camera pose keyframe from the timeline.
* Returns true if camera was set to a pose from the next keyframe.
* Returns false if no keyframes are available after the current time.
* \param camera A reference to the camera object to have its pose updated.
* \param ignoreFutureKeyframes true if only past keyframes are to be used.
* \returns true only if a new future keyframe is available to set camera pose.
*/
* Update camera position using the next camera pose keyframe from the timeline.
* Returns true if camera was set to a pose from the next keyframe. Returns false if
* no keyframes are available after the current time.
*
* \param camera A reference to the camera object to have its pose updated
* \param ignoreFutureKeyframes `true` if only past keyframes are to be used
* \return true only if a new future keyframe is available to set camera pose
*/
bool updateCamera(Camera& camera, bool ignoreFutureKeyframes);
static bool updateCamera(Camera* camera, const CameraPose prevPose,
const CameraPose nextPose, double t, bool ignoreFutureKeyframes);
include/openspace/navigation/navigationhandler.h
+5 -5
View File
@@ -151,7 +151,7 @@ public:
* Set camera state from a provided navigation state next frame. The actual position
* will computed from the scene in the same frame as it is set.
*
* \param state the navigation state to compute a camera positon from
* \param state The navigation state to compute a camera positon from
*/
void setNavigationStateNextFrame(const NavigationState& state);
@@ -161,14 +161,14 @@ public:
* node info. The actual position will computed from the scene in the same frame as
* it is set.
*
* \param spec the node specification from which to compute the resulting camera pose
* \param spec The node specification from which to compute the resulting camera pose
*/
void setCameraFromNodeSpecNextFrame(NodeCameraStateSpec spec);
/**
* \return The Lua library that contains all Lua functions available to affect the
* interaction
*/
* \return The Lua library that contains all Lua functions available to affect the
* interaction
*/
static scripting::LuaLibrary luaLibrary();
private:
include/openspace/navigation/orbitalnavigator.h
+40 -38
View File
@@ -43,9 +43,9 @@
#include <optional>
namespace openspace {
class SceneGraphNode;
class Camera;
struct CameraPose;
class SceneGraphNode;
struct SurfacePositionHandle;
} // namespace
@@ -87,10 +87,10 @@ public:
void updateCameraScalingFromAnchor(double deltaTime);
void resetVelocities();
/*
/**
* This function should be called on every camera interaction: for example when
* navigating using an input device, changing the focus node or starting a path or
* a session recording playback
* navigating using an input device, changing the focus node or starting a path or a
* session recording playback
*/
void updateOnCameraInteraction();
@@ -143,16 +143,15 @@ public:
glm::quat anchorNodeToCameraRotation() const;
/**
* Compute a camera position that pushed the camera position to
* a valid position over the anchor node, accounting for the
* minimal allowed distance
* Compute a camera position that pushed the camera position to a valid position over
* the anchor node, accounting for the minimal allowed distance
*/
glm::dvec3 pushToSurfaceOfAnchor(const glm::dvec3& cameraPosition) const;
/**
* \return the Lua library that contains all Lua functions available to affect the
* OrbitalNavigator
*/
* \return The Lua library that contains all Lua functions available to affect the
* OrbitalNavigator
*/
static scripting::LuaLibrary luaLibrary();
private:
@@ -184,12 +183,11 @@ private:
Friction _friction;
// Anchor: Node to follow and orbit
/// Anchor: Node to follow and orbit
properties::StringProperty _anchor;
// Aim: Node to look at (when camera direction is reset),
// Empty string means same as anchor.
// If these are the same node we call it the `focus` node
/// Aim: Node to look at (when camera direction is reset), empty string means same as
/// anchor. If these are the same node we call it the `focus` node
properties::StringProperty _aim;
// Reset camera direction to the anchor node.
@@ -283,6 +281,7 @@ private:
* Decomposes the camera's rotation in to a global and a local rotation defined by
* CameraRotationDecomposition. The global rotation defines the rotation so that the
* camera points towards the reference position.
*
* The local rotation defines the differential from the global to the current total
* rotation so that `cameraRotation = globalRotation * localRotation`.
*/
@@ -290,40 +289,42 @@ private:
glm::dvec3 reference);
/**
* Composes a pair of global and local rotations into a quaternion that can be used
* as the world rotation for a camera.
* Composes a pair of global and local rotations into a quaternion that can be used as
* the world rotation for a camera.
*/
glm::dquat composeCameraRotation(const CameraRotationDecomposition& composition);
/*
* Moves and rotates the camera around the anchor node in order to maintain the
* screen space position of the aim node. Also interpolates to the aim node, when
* retargeting the aim.
/**
* Moves and rotates the camera around the anchor node in order to maintain the screen
* space position of the aim node. Also interpolates to the aim node, when retargeting
* the aim.
*/
CameraPose followAim(CameraPose pose, glm::dvec3 cameraToAnchor,
Displacement anchorToAim);
/*
* Perform a camera roll on the local camera rotation
* \returns a local camera rotation modified with a roll.
/**
* Perform a camera roll on the local camera rotation.
*
* \return A local camera rotation modified with a roll
*/
glm::dquat roll(double deltaTime, const glm::dquat& localCameraRotation) const;
/**
* Performs rotation around the cameras x and y axes.
* \returns a local camera rotation modified with two degrees of freedom.
*
* \return A local camera rotation modified with two degrees of freedom
*/
glm::dquat rotateLocally(double deltaTime,
const glm::dquat& localCameraRotation) const;
/**
* Interpolates the camera rotation based on active interpolators.
* \returns a new rotation quaternion
*
* \return A new rotation quaternion
*/
glm::dquat interpolateLocalRotation(double deltaTime,
const glm::dquat& localCameraRotation);
Displacement interpolateRetargetAim(double deltaTime, CameraPose pose,
glm::dvec3 cameraToAnchor, Displacement anchorToAim);
@@ -332,7 +333,7 @@ private:
/**
* Modify the camera position and global rotation to rotate around the up vector
* of the current anchor based on x-wise input
* of the current anchor based on x-wise input.
*
* The up-vector to rotate around is determined by the "_upToUseForRotation" property
*/
@@ -344,18 +345,18 @@ private:
* result in an orbital rotation around the object. This function does not affect the
* rotation but only the position.
*
* \return a position vector adjusted in the horizontal direction.
* \return A position vector adjusted in the horizontal direction.
*/
glm::dvec3 translateHorizontally(double deltaTime, double speedScale,
const glm::dvec3& cameraPosition, const glm::dvec3& objectPosition,
const glm::dquat& globalCameraRotation,
const SurfacePositionHandle& positionHandle) const;
/*
/**
* Adds rotation to the camera position so that it follows the rotation of the anchor
* node defined by the differential anchorNodeRotationDiff.
* node defined by the differential \p anchorNodeRotationDiff.
*
* \return a position updated with the rotation defined by anchorNodeRotationDiff
* \return A position updated with the rotation defined by \p anchorNodeRotationDiff
*/
glm::dvec3 followAnchorNodeRotation(const glm::dvec3& cameraPosition,
const glm::dvec3& objectPosition, const glm::dquat& anchorNodeRotationDiff) const;
@@ -363,7 +364,7 @@ private:
/**
* Updates the global rotation so that it points towards the anchor node.
*
* \return a global rotation quaternion defining a rotation towards the anchor node
* \return A global rotation quaternion defining a rotation towards the anchor node
*/
glm::dquat rotateGlobally(const glm::dquat& globalCameraRotation,
const glm::dquat& aimNodeRotationDiff,
@@ -371,7 +372,8 @@ private:
/**
* Translates the camera position towards or away from the anchor node.
* \returns a position vector adjusted in the vertical direction.
*
* \return A position vector adjusted in the vertical direction.
*/
glm::dvec3 translateVertically(double deltaTime, const glm::dvec3& cameraPosition,
const glm::dvec3& objectPosition,
@@ -380,7 +382,7 @@ private:
/**
* Rotates the camera around the out vector of the surface.
*
* \return a quaternion adjusted to rotate around the out vector of the surface
* \return A quaternion adjusted to rotate around the out vector of the surface
*/
glm::dquat rotateHorizontally(double deltaTime,
const glm::dquat& globalCameraRotation,
@@ -389,7 +391,7 @@ private:
/**
* Push the camera out to the surface of the object.
*
* \return a position vector adjusted to be at least _minimumAllowedDistance meters
* \return A position vector adjusted to be at least _minimumAllowedDistance meters
* above the actual surface of the object
*/
glm::dvec3 pushToSurface(const glm::dvec3& cameraPosition,
@@ -417,7 +419,7 @@ private:
void resetIdleBehavior();
/**
* Apply the currently selected idle behavior to the position and rotations
* Apply the currently selected idle behavior to the position and rotations.
*/
void applyIdleBehavior(double deltaTime, glm::dvec3& position,
glm::dquat& localRotation, glm::dquat& globalRotation);
@@ -441,8 +443,8 @@ private:
* vector coincides with the axis, and should be used with care.
*
* Used for:
* IdleBehavior::Behavior::OrbitAtConstantLat (axis = north = z-axis) and
* IdleBehavior::Behavior::OrbitAroundUp (axis = up = y-axis)
* - IdleBehavior::Behavior::OrbitAtConstantLat (axis = north = z-axis) and
* - IdleBehavior::Behavior::OrbitAroundUp (axis = up = y-axis)
*
* \param axis The axis to arbit around, given in model coordinates of the anchor
* \param angle The rotation angle to use for the motion
include/openspace/navigation/path.h
+42 -42
View File
@@ -44,12 +44,12 @@ public:
AvoidCollision = 0,
ZoomOutOverview,
Linear,
AvoidCollisionWithLookAt // @TODO (2021-08-13, emmbr) This type right now leads
// to rapid rotations, but is useful in specific
// scenarios, e.g. close to surfaces. Later we want to
// remove it, and create a curve type that looks nicely
// at the targets when moving, avoids collisions and
// doesn't introduce sudden large changes in rotation
// @TODO (2021-08-13, emmbr) This type right now leads to rapid rotations, but is
// useful in specific scenarios, e.g. close to surfaces. Later we want to remove
// it, and create a curve type that looks nicely at the targets when moving,
// avoids collisions and doesn't introduce sudden large changes in rotation
AvoidCollisionWithLookAt
};
Path(Waypoint start, Waypoint end, Type type,
@@ -59,55 +59,55 @@ public:
Waypoint endPoint() const;
/**
* Return the total length of the the curve for the path, in meters
* Return the total length of the the curve for the path, in meters.
*/
double pathLength() const;
/**
* Return a vector of positions corresponding to the control points of the path's
* spline curve
* spline curve.
*/
std::vector<glm::dvec3> controlPoints() const;
/**
* Take a step along the current path, corresponding to the delta time step \p dt, and
* return the resulting camera pose. The \p speedScale is a factor that will be
* multiplied with the traversal speed
* multiplied with the traversal speed.
*/
CameraPose traversePath(double dt, float speedScale = 1.f);
/**
* Function that can be used to permaturely quit a path, for example when skipping
* to the end
* to the end.
*/
void quitPath();
/**
* Return the identifer of the node that is the current appropriate anchor node, of
* the start and end waypoint's reference node. Dtermined based on how far along the
* path we have traveled
* path we have traveled.
*/
std::string currentAnchor() const;
/**
* Return wether the path has reached its end point or not
* Return wether the path has reached its end point or not.
*/
bool hasReachedEnd() const;
/**
* Compute the interpolated camera pose at a certain distance along a *linear*
* path. Note that the linear path is a special case, to avoid risks of precision
* problems for long paths
* problems for long paths.
*/
CameraPose linearInterpolatedPose(double distance, double displacement);
/**
* Compute the interpolated camera pose at a certain distance along the path
* Compute the interpolated camera pose at a certain distance along the path.
*/
CameraPose interpolatedPose(double distance) const;
/**
* Reset variables used to play back path
* Reset variables used to play back path.
*/
void resetPlaybackVariables();
@@ -116,49 +116,49 @@ public:
private:
/**
* Interpolate between the paths start and end rotation using the approach that
* corresponds to the path's curve type. The interpolation parameter \p t is the
* same as for the position interpolation, i.e. the relative traveled distance
* along the path, in [0, 1]
* corresponds to the path's curve type. The interpolation parameter \p t is the same
* as for the position interpolation, i.e. the relative traveled distance along the
* path, in [0, 1].
*
* \param t The interpolation parameter, given as the relative traveled distance
along the path, in [0, 1]
* \param t The interpolation parameter, given as the relative traveled distance along
* the path, in [0, 1]
*/
glm::dquat interpolateRotation(double t) const;
/**
* Compute the interpolated rotation quaternion using an eased SLERP approach
* Compute the interpolated rotation quaternion using an eased SLERP approach.
*
* \param t The interpolation variable for the rotatation interpolation.
* Should be the relative traveled distance, in [0, 1]
* \param t The interpolation variable for the rotatation interpolation. Should be the
* relative traveled distance, in [0, 1]
*/
glm::dquat easedSlerpRotation(double t) const;
/**
* Compute the interpolated rotation quaternion using a method that is customized
* for linear paths. The camera will first interpoalte to look at the targetted
* node, and keep doing so for most of the path. At the end, when within a certain
* distance from the target, the rotation is interpolated so that the camera ends up
* in the target pose at the end of the path.
* Compute the interpolated rotation quaternion using a method that is customized for
* linear paths. The camera will first interpoalte to look at the targetted node, and
* keep doing so for most of the path. At the end, when within a certain distance from
* the target, the rotation is interpolated so that the camera ends up in the target
* pose at the end of the path.
*
* \param t The interpolation variable for the rotatation interpolation.
* Should be the relative traveled distance, in [0, 1]
* \param t The interpolation variable for the rotatation interpolation. Should be the
* relative traveled distance, in [0, 1]
*/
glm::dquat linearPathRotation(double t) const;
/**
* Compute the interpolated rotation quaternion using an approach that first
* interpolates to look at the start node, and then the end node, before
* interpolating to the end rotation
* interpolates to look at the start node, and then the end node, before interpolating
* to the end rotation.
*
* \param t The interpolation variable for the rotatation interpolation.
* Should be the relative traveled distance, in [0, 1]
* \param t The interpolation variable for the rotatation interpolation. Should be the
* relative traveled distance, in [0, 1]
*/
glm::dquat lookAtTargetsRotation(double t) const;
/**
* Evaluate the current traversal speed along the path, based on the currently
* traveled distance. The final speed will be scaled to match the desired duration
* for the path (which might have been specified by the user)
* traveled distance. The final speed will be scaled to match the desired duration for
* the path (which might have been specified by the user).
*
* \param traveledDistance The current distance traveled along the path, in meters
*/
@@ -180,13 +180,13 @@ private:
};
/**
* Create a path based on an instruction given as a dictionary. (See top of cpp file
* for documentation on keys and values for the dictionary.)
* If /p forceType is specified, that type will primarily be used as the type for the
* created path. Secondly, the type will be read from the dictionary, and lastly it will
* use the default from PathNavigator.
* Create a path based on an instruction given as a dictionary (see top of cpp file
* for documentation on keys and values for the dictionary). If \p forceType is specified,
* that type will primarily be used as the type for the created path. Secondly, the type
* will be read from the dictionary, and lastly it will use the default from
* PathNavigator.
*
* \return the created path
* \return The created path
*/
Path createPathFromDictionary(const ghoul::Dictionary& dictionary,
std::optional<Path::Type> forceType = std::nullopt);
include/openspace/navigation/pathcurve.h
+9 -10
View File
@@ -46,7 +46,7 @@ public:
virtual ~PathCurve() = 0;
/**
* Return the length of the curve, in meters
* Return the length of the curve, in meters.
*/
double length() const;
@@ -56,7 +56,7 @@ public:
* the full length of the path.
*
* Can be overridden by subclasses that want more control over the position
* interpolation
* interpolation.
*/
virtual glm::dvec3 positionAt(double relativeDistance) const;
@@ -66,27 +66,26 @@ public:
* position. Note that u does not correspond to the relatively traveled distance.
*
* Can be overridden by subclasses that want more control over the position
* interpolation
* interpolation.
*/
virtual glm::dvec3 interpolate(double u) const;
/**
* Return the positions defining the control points for the spline interpolation
* Return the positions defining the control points for the spline interpolation.
*/
std::vector<glm::dvec3> points() const;
protected:
/**
* Precompute information related to the spline parameters that are
* needed for arc length reparameterization. Must be called after
* control point creation.
* Precompute information related to the spline parameters that are needed for arc
* length reparameterization. Must be called after control point creation.
*/
void initializeParameterData();
/**
* Compute curve parameter u that matches the input arc length s.
* Input s is a length value in meters, in the range [0, _totalLength].
* The returned curve parameter u is in range [0, 1].
* Compute curve parameter u that matches the input arc length s. Input s is a length
* value in meters, in the range [0, _totalLength]. The returned curve parameter u is
* in range [0, 1].
*/
double curveParameter(double s) const;
include/openspace/navigation/pathnavigator.h
+10 -9
View File
@@ -81,24 +81,25 @@ public:
const std::vector<SceneGraphNode*>& relevantNodes();
/**
* Find a node close to the given node. Closeness is determined by a factor times
* the bounding sphere of the object
* \return pointer to the SGN if one was found, nullptr otherwise
*/
* Find a node close to the given node. Closeness is determined by a factor times
* the bounding sphere of the object.
*
* \return Pointer to the SGN if one was found, nullptr otherwise
*/
static SceneGraphNode* findNodeNearTarget(const SceneGraphNode* node);
/**
* \return The Lua library that contains all Lua functions available to affect the
* path navigation
*/
* \return The Lua library that contains all Lua functions available to affect the
* path navigation
*/
static scripting::LuaLibrary luaLibrary();
private:
void handlePathEnd();
/**
* Populate list of nodes that are relevant for collision checks, etc
*/
* Populate list of nodes that are relevant for collision checks, etc.
*/
void findRelevantNodes();
void removeRollRotation(CameraPose& pose, double deltaTime);
include/openspace/navigation/waypoint.h
+7 -7
View File
@@ -59,7 +59,7 @@ private:
/**
* Compute a waypoint from the current camera position.
*
* \return the computed WayPoint
* \return The computed WayPoint
*/
Waypoint waypointFromCamera();
@@ -76,14 +76,14 @@ struct NodeCameraStateSpec {
* where the camera will be facing the given node. If there is a 'Sun' node in the scene,
* it will possibly be used to compute a position on the lit side of the object.
*
* \param spec details about the node and state to create the waypoint from. Minimal
* information is the identifier of the node, but a position or height
* above the bounding sphere may also be given.
* \param startPoint an optional previous waypoint. If not specified, the current camera
* \param spec Details about the node and state to create the waypoint from. Minimal
* information is the identifier of the node, but a position or height above
* the bounding sphere may also be given.
* \param startPoint An optional previous waypoint. If not specified, the current camera
* position will be used.
* \param useLinear if true, the new waypoint will be computed along a straight line
* \param useLinear If `true`, the new waypoint will be computed along a straight line
* from the start waypoint to the scene graph node or position.
* \return the computed WayPoint
* \return The computed WayPoint
*/
Waypoint computeWaypointFromNodeInfo(const NodeCameraStateSpec& spec,
std::optional<Waypoint> startPoint = std::nullopt, bool useLinear = false);