Cleanup: move public doc-strings into headers for 'blenkernel'

- Added space below non doc-string comments to make it clear
  these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.

Ref T92709

1 files changed, 260 insertions, 7 deletions

diff --git a/source/blender/blenkernel/BKE_tracking.h b/source/blender/blenkernel/BKE_tracking.h
index 47145a7d6bd..9caf5d31765 100644
--- a/source/blender/blenkernel/BKE_tracking.h
+++ b/source/blender/blenkernel/BKE_tracking.h
@@ -46,20 +46,53 @@ struct rcti;
 
 /* **** Common functions **** */
 
+/**
+ * Free tracking structure, only frees structure contents
+ * (if structure is allocated in heap, it shall be handled outside).
+ *
+ * All the pointers inside structure becomes invalid after this call.
+ */
 void BKE_tracking_free(struct MovieTracking *tracking);
+/**
+ * Copy tracking structure content.
+ */
 void BKE_tracking_copy(struct MovieTracking *tracking_dst,
                        const struct MovieTracking *tracking_src,
                        const int flag);
 
+/**
+ * Initialize motion tracking settings to default values,
+ * used when new movie clip data-block is created.
+ */
 void BKE_tracking_settings_init(struct MovieTracking *tracking);
 
+/**
+ * Get list base of active object's tracks.
+ */
 struct ListBase *BKE_tracking_get_active_tracks(struct MovieTracking *tracking);
+/**
+ * Get list base of active object's plane tracks.
+ */
 struct ListBase *BKE_tracking_get_active_plane_tracks(struct MovieTracking *tracking);
+/**
+ * Get reconstruction data of active object.
+ */
 struct MovieTrackingReconstruction *BKE_tracking_get_active_reconstruction(
     struct MovieTracking *tracking);
 
-/* matrices for constraints and drawing */
+/* Matrices for constraints and drawing. */
+
+/**
+ * Get transformation matrix for a given object which is used
+ * for parenting motion tracker reconstruction to 3D world.
+ */
 void BKE_tracking_get_camera_object_matrix(struct Object *camera_object, float mat[4][4]);
+/**
+ * Get projection matrix for camera specified by given tracking object
+ * and frame number.
+ *
+ * \note frame number should be in clip space, not scene space.
+ */
 void BKE_tracking_get_projection_matrix(struct MovieTracking *tracking,
                                         struct MovieTrackingObject *object,
                                         int framenr,
@@ -68,16 +101,45 @@ void BKE_tracking_get_projection_matrix(struct MovieTracking *tracking,
                                         float mat[4][4]);
 
 /* **** Clipboard **** */
+/**
+ * Free clipboard by freeing memory used by all tracks in it.
+ */
 void BKE_tracking_clipboard_free(void);
+/**
+ * Copy selected tracks from specified object to the clipboard.
+ */
 void BKE_tracking_clipboard_copy_tracks(struct MovieTracking *tracking,
                                         struct MovieTrackingObject *object);
+/**
+ * Check whether there are any tracks in the clipboard.
+ */
 bool BKE_tracking_clipboard_has_tracks(void);
+/**
+ * Paste tracks from clipboard to specified object.
+ *
+ * Names of new tracks in object are guaranteed to be unique here.
+ */
 void BKE_tracking_clipboard_paste_tracks(struct MovieTracking *tracking,
                                          struct MovieTrackingObject *object);
 
 /* **** Track **** */
+
+/**
+ * Add new empty track to the given list of tracks.
+ *
+ * It is required that caller will append at least one marker to avoid degenerate tracks.
+ */
 struct MovieTrackingTrack *BKE_tracking_track_add_empty(struct MovieTracking *tracking,
                                                         struct ListBase *tracks_list);
+/**
+ * Add new track to a specified tracks base.
+ *
+ * Coordinates are expected to be in normalized 0..1 space,
+ * frame number is expected to be in clip space.
+ *
+ * Width and height are clip's dimension used to scale track's
+ * pattern and search regions.
+ */
 struct MovieTrackingTrack *BKE_tracking_track_add(struct MovieTracking *tracking,
                                                   struct ListBase *tracksbase,
                                                   float x,
@@ -85,14 +147,35 @@ struct MovieTrackingTrack *BKE_tracking_track_add(struct MovieTracking *tracking
                                                   int framenr,
                                                   int width,
                                                   int height);
+/**
+ * Duplicate the specified track, result will no belong to any list.
+ */
 struct MovieTrackingTrack *BKE_tracking_track_duplicate(struct MovieTrackingTrack *track);
+/**
+ * Ensure specified track has got unique name,
+ * if it's not name of specified track will be changed
+ * keeping names of all other tracks unchanged.
+ */
 void BKE_tracking_track_unique_name(struct ListBase *tracksbase, struct MovieTrackingTrack *track);
+/**
+ * Free specified track, only frees contents of a structure
+ * (if track is allocated in heap, it shall be handled outside).
+ *
+ * All the pointers inside track becomes invalid after this call.
+ */
 void BKE_tracking_track_free(struct MovieTrackingTrack *track);
 
+/**
+ * Get frame numbers of the very first and last markers.
+ * There is no check on whether the marker is enabled or not.
+ */
 void BKE_tracking_track_first_last_frame_get(const struct MovieTrackingTrack *track,
                                              int *r_first_frame,
                                              int *r_last_frame);
 
+/**
+ * Find the minimum starting frame and maximum ending frame within given set of tracks.
+ */
 void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ struct MovieTrackingTrack **tracks,
                                                  const int num_tracks,
                                                  int *r_first_frame,
@@ -101,17 +184,50 @@ void BKE_tracking_tracks_first_last_frame_minmax(/*const*/ struct MovieTrackingT
 int BKE_tracking_count_selected_tracks_in_list(const struct ListBase *tracks_list);
 int BKE_tracking_count_selected_tracks_in_active_object(/*const*/ struct MovieTracking *tracking);
 
-/* Get array of selected tracks from the current active object in the tracking structure.
- * If nothing is selected then the result is nullptr and `r_num_tracks` is set to 0. */
+/**
+ * Get array of selected tracks from the current active object in the tracking structure.
+ * If nothing is selected then the result is nullptr and `r_num_tracks` is set to 0.
+ */
 struct MovieTrackingTrack **BKE_tracking_selected_tracks_in_active_object(
     struct MovieTracking *tracking, int *r_num_tracks);
 
+/**
+ * Set flag for all specified track's areas.
+ *
+ * \param area: which part of marker should be selected. see TRACK_AREA_* constants.
+ * \param flag: flag to be set for areas.
+ */
 void BKE_tracking_track_flag_set(struct MovieTrackingTrack *track, int area, int flag);
+/**
+ * Clear flag from all specified track's areas.
+ *
+ * \param area: which part of marker should be selected. see TRACK_AREA_* constants.
+ * \param flag: flag to be cleared for areas.
+ */
 void BKE_tracking_track_flag_clear(struct MovieTrackingTrack *track, int area, int flag);
 
+/**
+ * Check whether track has got marker at specified frame.
+ *
+ * \note frame number should be in clip space, not scene space.
+ */
 bool BKE_tracking_track_has_marker_at_frame(struct MovieTrackingTrack *track, int framenr);
+/**
+ * Check whether track has got enabled marker at specified frame.
+ *
+ * \note frame number should be in clip space, not scene space.
+ */
 bool BKE_tracking_track_has_enabled_marker_at_frame(struct MovieTrackingTrack *track, int framenr);
 
+/**
+ * Clear track's path:
+ *
+ * - If action is #TRACK_CLEAR_REMAINED path from `ref_frame+1` up to end will be clear.
+ * - If action is #TRACK_CLEAR_UPTO path from the beginning up to `ref_frame-1` will be clear.
+ * - If action is #TRACK_CLEAR_ALL only marker at frame ref_frame will remain.
+ *
+ * \note frame number should be in clip space, not scene space.
+ */
 void BKE_tracking_track_path_clear(struct MovieTrackingTrack *track, int ref_frame, int action);
 
 void BKE_tracking_tracks_join(struct MovieTracking *tracking,
@@ -140,7 +256,11 @@ float BKE_tracking_track_get_weight_for_marker(struct MovieClip *clip,
                                                struct MovieTrackingTrack *track,
                                                struct MovieTrackingMarker *marker);
 
-/* selection */
+/* Selection */
+
+/**
+ * \param area: which part of marker should be selected. see TRACK_AREA_* constants.
+ */
 void BKE_tracking_track_select(struct ListBase *tracksbase,
                                struct MovieTrackingTrack *track,
                                int area,
@@ -155,19 +275,31 @@ void BKE_tracking_marker_delete(struct MovieTrackingTrack *track, int framenr);
 
 void BKE_tracking_marker_clamp(struct MovieTrackingMarker *marker, int event);
 
+/**
+ * Get marker closest to the given frame number.
+ *
+ * If there is maker with exact frame number it returned.
+ * Otherwise, marker with highest frame number but lower than the requested
+ * frame is returned if such marker exists. Otherwise, the marker with lowest
+ * frame number greater than the requested frame number is returned.
+ *
+ * This function has complexity of `O(log number_of_markers)`.
+ */
 struct MovieTrackingMarker *BKE_tracking_marker_get(struct MovieTrackingTrack *track, int framenr);
 struct MovieTrackingMarker *BKE_tracking_marker_get_exact(struct MovieTrackingTrack *track,
                                                           int framenr);
 struct MovieTrackingMarker *BKE_tracking_marker_ensure(struct MovieTrackingTrack *track,
                                                        int framenr);
 
-/* Get marker position, possibly interpolating gap between key-framed/tracked markers.
+/**
+ * Get marker position, possibly interpolating gap between key-framed/tracked markers.
  *
  * The result marker frame number is set to the requested frame number. Its flags are 0 if the
  * marker is interpolated, and is set to original marker flag if there were no interpolation
  * involved.
  *
- * Returns truth if the result is usable. */
+ * \returns truth if the result is usable.
+ */
 bool BKE_tracking_marker_get_interpolated(struct MovieTrackingTrack *track,
                                           const int framenr,
                                           struct MovieTrackingMarker *r_marker);
@@ -181,12 +313,21 @@ void BKE_tracking_marker_get_subframe_position(struct MovieTrackingTrack *track,
                                                float pos[2]);
 
 /* **** Plane Track **** */
+/**
+ * Creates new plane track out of selected point tracks.
+ */
 struct MovieTrackingPlaneTrack *BKE_tracking_plane_track_add(struct MovieTracking *tracking,
                                                              struct ListBase *plane_tracks_base,
                                                              struct ListBase *tracks,
                                                              int framenr);
 void BKE_tracking_plane_track_unique_name(struct ListBase *plane_tracks_base,
                                           struct MovieTrackingPlaneTrack *plane_track);
+/**
+ * Free specified plane track, only frees contents of a structure
+ * (if track is allocated in heap, it shall be handled outside).
+ *
+ * All the pointers inside track becomes invalid after this call.
+ */
 void BKE_tracking_plane_track_free(struct MovieTrackingPlaneTrack *plane_track);
 
 bool BKE_tracking_plane_track_has_marker_at_frame(struct MovieTrackingPlaneTrack *plane_track,
@@ -222,10 +363,21 @@ struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_insert(
     struct MovieTrackingPlaneTrack *plane_track, struct MovieTrackingPlaneMarker *plane_marker);
 void BKE_tracking_plane_marker_delete(struct MovieTrackingPlaneTrack *plane_track, int framenr);
 
+/**
+ * Get a plane marker at given frame,
+ * If there's no such marker, closest one from the left side will be returned.
+ */
 struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get(
     struct MovieTrackingPlaneTrack *plane_track, int framenr);
+/**
+ * Get a plane marker at exact given frame, if there's no marker at the frame,
+ * NULL will be returned.
+ */
 struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_get_exact(
     struct MovieTrackingPlaneTrack *plane_track, int framenr);
+/**
+ * Ensure there's a marker for the given frame.
+ */
 struct MovieTrackingPlaneMarker *BKE_tracking_plane_marker_ensure(
     struct MovieTrackingPlaneTrack *plane_track, int framenr);
 void BKE_tracking_plane_marker_get_subframe_corners(struct MovieTrackingPlaneTrack *plane_track,
@@ -255,6 +407,9 @@ struct MovieTrackingReconstruction *BKE_tracking_object_get_reconstruction(
     struct MovieTracking *tracking, struct MovieTrackingObject *object);
 
 /* **** Camera **** */
+/**
+ * Converts principal offset from center to offset of blender's camera.
+ */
 void BKE_tracking_camera_shift_get(
     struct MovieTracking *tracking, int winx, int winy, float *shiftx, float *shifty);
 void BKE_tracking_camera_to_blender(struct MovieTracking *tracking,
@@ -346,10 +501,21 @@ struct ImBuf *BKE_tracking_get_search_imbuf(struct ImBuf *ibuf,
                                             bool anchored,
                                             bool disable_channels);
 
+/**
+ * Zap channels from the imbuf that are disabled by the user. this can lead to
+ * better tracks sometimes. however, instead of simply zeroing the channels
+ * out, do a partial gray-scale conversion so the display is better.
+ */
 void BKE_tracking_disable_channels(
     struct ImBuf *ibuf, bool disable_red, bool disable_green, bool disable_blue, bool grayscale);
 
 /* **** 2D tracking **** */
+
+/**
+ * Refine marker's position using previously known keyframe.
+ * Direction of searching for a keyframe depends on backwards flag,
+ * which means if backwards is false, previous keyframe will be as reference.
+ */
 void BKE_tracking_refine_marker(struct MovieClip *clip,
                                 struct MovieTrackingTrack *track,
                                 struct MovieTrackingMarker *marker,
@@ -368,6 +534,9 @@ void BKE_autotrack_context_free(struct AutoTrackContext *context);
 
 /* **** Plane tracking **** */
 
+/**
+ * \note frame number should be in clip space, not scene space.
+ */
 void BKE_tracking_track_plane_from_existing_motion(struct MovieTrackingPlaneTrack *plane_track,
                                                    int start_frame);
 void BKE_tracking_retrack_plane_from_existing_motion_at_segment(
@@ -377,11 +546,20 @@ void BKE_tracking_homography_between_two_quads(/*const*/ float reference_corners
                                                float H[3][3]);
 
 /* **** Camera solving **** */
+
+/**
+ * Perform early check on whether everything is fine to start reconstruction.
+ */
 bool BKE_tracking_reconstruction_check(struct MovieTracking *tracking,
                                        struct MovieTrackingObject *object,
                                        char *error_msg,
                                        int error_size);
 
+/**
+ * Create context for camera/object motion reconstruction.
+ * Copies all data needed for reconstruction from movie clip datablock,
+ * so editing this clip is safe during reconstruction job is in progress.
+ */
 struct MovieReconstructContext *BKE_tracking_reconstruction_context_new(
     struct MovieClip *clip,
     struct MovieTrackingObject *object,
@@ -389,13 +567,29 @@ struct MovieReconstructContext *BKE_tracking_reconstruction_context_new(
     int keyframe2,
     int width,
     int height);
+/**
+ * Free memory used by a reconstruction process.
+ */
 void BKE_tracking_reconstruction_context_free(struct MovieReconstructContext *context);
+/**
+ * Solve camera/object motion and reconstruct 3D markers position
+ * from a prepared reconstruction context.
+ *
+ * stop is not actually used at this moment, so reconstruction
+ * job could not be stopped.
+ *
+ * do_update, progress and stat_message are set by reconstruction
+ * callback in libmv side and passing to an interface.
+ */
 void BKE_tracking_reconstruction_solve(struct MovieReconstructContext *context,
                                        short *stop,
                                        short *do_update,
                                        float *progress,
                                        char *stats_message,
                                        int message_size);
+/**
+ * Finish reconstruction process by copying reconstructed data to an actual movie clip data-block.
+ */
 bool BKE_tracking_reconstruction_finish(struct MovieReconstructContext *context,
                                         struct MovieTracking *tracking);
 
@@ -405,9 +599,16 @@ void BKE_tracking_reconstruction_report_error_message(struct MovieReconstructCon
 const char *BKE_tracking_reconstruction_error_message_get(
     const struct MovieReconstructContext *context);
 
+/**
+ * Apply scale on all reconstructed cameras and bundles, used by camera scale apply operator.
+ */
 void BKE_tracking_reconstruction_scale(struct MovieTracking *tracking, float scale[3]);
 
 /* **** Feature detection **** */
+
+/**
+ * Detect features using FAST detector.
+ */
 void BKE_tracking_detect_fast(struct MovieTracking *tracking,
                               struct ListBase *tracksbase,
                               struct ImBuf *ibuf,
@@ -418,6 +619,9 @@ void BKE_tracking_detect_fast(struct MovieTracking *tracking,
                               struct bGPDlayer *layer,
                               bool place_outside_layer);
 
+/**
+ * Detect features using Harris detector.
+ */
 void BKE_tracking_detect_harris(struct MovieTracking *tracking,
                                 struct ListBase *tracksbase,
                                 struct ImBuf *ibuf,
@@ -429,6 +633,24 @@ void BKE_tracking_detect_harris(struct MovieTracking *tracking,
                                 bool place_outside_layer);
 
 /* **** 2D stabilization **** */
+
+/**
+ * Get stabilization data (translation, scaling and angle) for a given frame.
+ * Returned data describes how to compensate the detected movement, but with any
+ * chosen scale factor already applied and any target frame position already compensated.
+ * In case stabilization fails or is disabled, neutral values are returned.
+ *
+ * \param framenr: is a frame number, relative to the clip (not relative to the scene timeline).
+ * \param width: is an effective width of the canvas (square pixels), used to scale the
+ * determined translation.
+ *
+ * Outputs:
+ * \param translation: of the lateral shift, absolute canvas coordinates (square pixels).
+ * \param scale: of the scaling to apply.
+ * \param angle: of the rotation angle, relative to the frame center.
+ *
+ * TODO(sergey): Use `r_` prefix for output parameters here.
+ */
 void BKE_tracking_stabilization_data_get(struct MovieClip *clip,
                                          int framenr,
                                          int width,
@@ -436,12 +658,30 @@ void BKE_tracking_stabilization_data_get(struct MovieClip *clip,
                                          float translation[2],
                                          float *scale,
                                          float *angle);
+/**
+ * Stabilize given image buffer using stabilization data for a specified frame number.
+ *
+ * \note frame number should be in clip space, not scene space.
+ *
+ * TODO(sergey): Use `r_` prefix for output parameters here.
+ */
 struct ImBuf *BKE_tracking_stabilize_frame(struct MovieClip *clip,
                                            int framenr,
                                            struct ImBuf *ibuf,
                                            float translation[2],
                                            float *scale,
                                            float *angle);
+/**
+ * Build a 4x4 transformation matrix based on the given 2D stabilization data.
+ * mat is a 4x4 matrix in homogeneous coordinates, adapted to the
+ *     final image buffer size and compensated for pixel aspect ratio,
+ *     ready for direct OpenGL drawing.
+ *
+ * TODO(sergey): The signature of this function should be changed. we actually
+ *               don't need the dimensions of the image buffer. Instead we
+ *               should consider to provide the pivot point of the rotation as a
+ *               further stabilization data parameter.
+ */
 void BKE_tracking_stabilization_data_to_mat4(int width,
                                              int height,
                                              float aspect,
@@ -450,17 +690,30 @@ void BKE_tracking_stabilization_data_to_mat4(int width,
                                              float angle,
                                              float mat[4][4]);
 
-/* Dopesheet */
+/* Dope-sheet */
+
+/**
+ * Tag dope-sheet for update, actual update will happen later when it'll be actually needed.
+ */
 void BKE_tracking_dopesheet_tag_update(struct MovieTracking *tracking);
+/**
+ * Do dope-sheet update, if update is not needed nothing will happen.
+ */
 void BKE_tracking_dopesheet_update(struct MovieTracking *tracking);
 
 /* **** Query/search **** */
 
+/**
+ * \note Returns NULL if the track comes from camera object,.
+ */
 struct MovieTrackingObject *BKE_tracking_find_object_for_track(
     const struct MovieTracking *tracking, const struct MovieTrackingTrack *track);
 struct ListBase *BKE_tracking_find_tracks_list_for_track(struct MovieTracking *tracking,
                                                          const struct MovieTrackingTrack *track);
 
+/**
+ * \note Returns NULL if the track comes from camera object,.
+ */
 struct MovieTrackingObject *BKE_tracking_find_object_for_plane_track(
     const struct MovieTracking *tracking, const struct MovieTrackingPlaneTrack *plane_track);
 struct ListBase *BKE_tracking_find_tracks_list_for_plane_track(