Compress/update comments ubl_motion

…to fit more code on the screen and correct outdated commentary contrasting ABL.

Marlin/ubl_motion.cpp

@@ -70,12 +70,10 @@
         debug_current_and_destination(PSTR("Start of ubl.line_to_destination_cartesian()"));
       }
 
-      if (cell_start_xi == cell_dest_xi && cell_start_yi == cell_dest_yi) { // if the whole move is within the same cell,
+      // A move within the same cell needs no splitting
-                                                                            // we don't need to break up the move
+      if (cell_start_xi == cell_dest_xi && cell_start_yi == cell_dest_yi) {
-        /**
+
-         * If we are moving off the print bed, we are going to allow the move at this level.
+        // For a move off the bed, use a constant Z raise
-         * But we detect it and isolate it. For now, we just pass along the request.
-         */
         if (!WITHIN(cell_dest_xi, 0, GRID_MAX_POINTS_X - 1) || !WITHIN(cell_dest_yi, 0, GRID_MAX_POINTS_Y - 1)) {
 
           // Note: There is no Z Correction in this case. We are off the grid and don't know what
@@ -98,15 +96,7 @@
 
         FINAL_MOVE:
 
-        /**
+        // The distance is always MESH_X_DIST so multiply by the constant reciprocal.
-         * Optimize some floating point operations here. We could call float get_z_correction(float x0, float y0) to
-         * generate the correction for us. But we can lighten the load on the CPU by doing a modified version of the function.
-         * We are going to only calculate the amount we are from the first mesh line towards the second mesh line once.
-         * We will use this fraction in both of the original two Z Height calculations for the bi-linear interpolation. And,
-         * instead of doing a generic divide of the distance, we know the distance is MESH_X_DIST so we can use the preprocessor
-         * to create a 1-over number for us. That will allow us to do a floating point multiply instead of a floating point divide.
-         */
-
         const float xratio = (end[X_AXIS] - mesh_index_to_xpos(cell_dest_xi)) * (1.0 / (MESH_X_DIST));
 
         float z1 = z_values[cell_dest_xi    ][cell_dest_yi    ] + xratio *
@@ -116,22 +106,13 @@
 
         if (cell_dest_xi >= GRID_MAX_POINTS_X - 1) z1 = z2 = 0.0;
 
-        // we are done with the fractional X distance into the cell. Now with the two Z-Heights we have calculated, we
+        // X cell-fraction done. Interpolate the two Z offsets with the Y fraction for the final Z offset.
-        // are going to apply the Y-Distance into the cell to interpolate the final Z correction.
+        const float yratio = (end[Y_AXIS] - mesh_index_to_ypos(cell_dest_yi)) * (1.0 / (MESH_Y_DIST)),
+                    z0 = cell_dest_yi < GRID_MAX_POINTS_Y - 1 ? (z1 + (z2 - z1) * yratio) * planner.fade_scaling_factor_for_z(end[Z_AXIS]) : 0.0;
 
-        const float yratio = (end[Y_AXIS] - mesh_index_to_ypos(cell_dest_yi)) * (1.0 / (MESH_Y_DIST));
+        // Undefined parts of the Mesh in z_values[][] are NAN.
-        float z0 = cell_dest_yi < GRID_MAX_POINTS_Y - 1 ? (z1 + (z2 - z1) * yratio) * planner.fade_scaling_factor_for_z(end[Z_AXIS]) : 0.0;
+        // Replace NAN corrections with 0.0 to prevent NAN propagation.
-
+        planner.buffer_segment(end[X_AXIS], end[Y_AXIS], end[Z_AXIS] + (isnan(z0) ? 0.0 : z0), end[E_AXIS], feed_rate, extruder);
-        /**
-         * If part of the Mesh is undefined, it will show up as NAN
-         * in z_values[][] and propagate through the
-         * calculations. If our correction is NAN, we throw it out
-         * because part of the Mesh is undefined and we don't have the
-         * information we need to complete the height correction.
-         */
-        if (isnan(z0)) z0 = 0.0;
-
-        planner.buffer_segment(end[X_AXIS], end[Y_AXIS], end[Z_AXIS] + z0, end[E_AXIS], feed_rate, extruder);
 
         if (g26_debug_flag)
           debug_current_and_destination(PSTR("FINAL_MOVE in ubl.line_to_destination_cartesian()"));
@@ -141,11 +122,8 @@
       }
 
       /**
-       * If we get here, we are processing a move that crosses at least one Mesh Line. We will check
+       * Past this point the move is known to cross one or more mesh lines. Check for the most common
-       * for the simple case of just crossing X or just crossing Y Mesh Lines after we get all the details
+       * case - crossing only one X or Y line - after details are worked out to reduce computation.
-       * of the move figured out. We can process the easy case of just crossing an X or Y Mesh Line with less
-       * computation and in fact most lines are of this nature. We will check for that in the following
-       * blocks of code:
        */
 
       const float dx = end[X_AXIS] - start[X_AXIS],
@@ -161,12 +139,11 @@
                 dyi = cell_start_yi == cell_dest_yi ? 0 : down_flag ? -1 : 1;
 
       /**
-       * Compute the scaling factor for the extruder for each partial move.
+       * Compute the extruder scaling factor for each partial move, checking for
-       * We need to watch out for zero length moves because it will cause us to
+       * zero-length moves that would result in an infinite scaling factor.
-       * have an infinate scaling factor. We are stuck doing a floating point
+       * A float divide is required for this, but then it just multiplies.
-       * divide to get our scaling factor, but after that, we just multiply by this
+       * Also select a scaling factor based on the larger of the X and Y
-       * number. We also pick our scaling factor based on whether the X or Y
+       * components. The larger of the two is used to preserve precision.
-       * component is larger. We use the biggest of the two to preserve precision.
        */
 
       const bool use_x_dist = adx > ady;
@@ -186,43 +163,37 @@
 
       const bool inf_normalized_flag = (isinf(e_normalized_dist) != 0),
                  inf_m_flag = (isinf(m) != 0);
+
       /**
-       * This block handles vertical lines. These are lines that stay within the same
+       * Handle vertical lines that stay within one column.
-       * X Cell column. They do not need to be perfectly vertical. They just can
+       * These need not be perfectly vertical.
-       * not cross into another X Cell column.
        */
-      if (dxi == 0) {       // Check for a vertical line
+      if (dxi == 0) {             // Vertical line?
-        current_yi += down_flag;  // Line is heading down, we just want to go to the bottom
+        current_yi += down_flag;  // Line going down? Just go to the bottom.
         while (current_yi != cell_dest_yi + down_flag) {
           current_yi += dyi;
           const float next_mesh_line_y = mesh_index_to_ypos(current_yi);
 
           /**
-           * if the slope of the line is infinite, we won't do the calculations
+           * Skip the calculations for an infinite slope.
-           * else, we know the next X is the same so we can recover and continue!
+           * For others the next X is the same so this can continue.
-           * Calculate X at the next Y mesh line
+           * Calculate X at the next Y mesh line.
            */
           const float rx = inf_m_flag ? start[X_AXIS] : (next_mesh_line_y - c) / m;
 
           float z0 = z_correction_for_x_on_horizontal_mesh_line(rx, current_xi, current_yi)
                      * planner.fade_scaling_factor_for_z(end[Z_AXIS]);
 
-          /**
+          // Undefined parts of the Mesh in z_values[][] are NAN.
-           * If part of the Mesh is undefined, it will show up as NAN
+          // Replace NAN corrections with 0.0 to prevent NAN propagation.
-           * in z_values[][] and propagate through the
-           * calculations. If our correction is NAN, we throw it out
-           * because part of the Mesh is undefined and we don't have the
-           * information we need to complete the height correction.
-           */
           if (isnan(z0)) z0 = 0.0;
 
           const float ry = mesh_index_to_ypos(current_yi);
 
           /**
-           * Without this check, it is possible for the algorithm to generate a zero length move in the case
+           * Without this check, it's possible to generate a zero length move, as in the case where
-           * where the line is heading down and it is starting right on a Mesh Line boundary. For how often that
+           * the line is heading down, starting exactly on a mesh line boundary. Since this is rare
-           * happens, it might be best to remove the check and always 'schedule' the move because
+           * it might be fine to remove this check and let planner.buffer_segment() filter it out.
-           * the planner.buffer_segment() routine will filter it if that happens.
            */
           if (ry != start[Y_AXIS]) {
             if (!inf_normalized_flag) {
@@ -242,9 +213,7 @@
         if (g26_debug_flag)
           debug_current_and_destination(PSTR("vertical move done in ubl.line_to_destination_cartesian()"));
 
-        //
+        // At the final destination? Usually not, but when on a Y Mesh Line it's completed.
-        // Check if we are at the final destination. Usually, we won't be, but if it is on a Y Mesh Line, we are done.
-        //
         if (current_position[X_AXIS] != end[X_AXIS] || current_position[Y_AXIS] != end[Y_AXIS])
           goto FINAL_MOVE;
 
@@ -253,16 +222,11 @@
       }
 
       /**
-       *
+       * Handle horizontal lines that stay within one row.
-       * This block handles horizontal lines. These are lines that stay within the same
+       * These need not be perfectly horizontal.
-       * Y Cell row. They do not need to be perfectly horizontal. They just can
-       * not cross into another Y Cell row.
-       *
        */
-
+      if (dyi == 0) {             // Horizontal line?
-      if (dyi == 0) {             // Check for a horizontal line
+        current_xi += left_flag;  // Heading left? Just go to the left edge of the cell for the first move.
-        current_xi += left_flag;  // Line is heading left, we just want to go to the left
-                                  // edge of this cell for the first move.
         while (current_xi != cell_dest_xi + left_flag) {
           current_xi += dxi;
           const float next_mesh_line_x = mesh_index_to_xpos(current_xi),
@@ -271,22 +235,16 @@
           float z0 = z_correction_for_y_on_vertical_mesh_line(ry, current_xi, current_yi)
                      * planner.fade_scaling_factor_for_z(end[Z_AXIS]);
 
-          /**
+          // Undefined parts of the Mesh in z_values[][] are NAN.
-           * If part of the Mesh is undefined, it will show up as NAN
+          // Replace NAN corrections with 0.0 to prevent NAN propagation.
-           * in z_values[][] and propagate through the
-           * calculations. If our correction is NAN, we throw it out
-           * because part of the Mesh is undefined and we don't have the
-           * information we need to complete the height correction.
-           */
           if (isnan(z0)) z0 = 0.0;
 
           const float rx = mesh_index_to_xpos(current_xi);
 
           /**
-           * Without this check, it is possible for the algorithm to generate a zero length move in the case
+           * Without this check, it's possible to generate a zero length move, as in the case where
-           * where the line is heading left and it is starting right on a Mesh Line boundary. For how often
+           * the line is heading left, starting exactly on a mesh line boundary. Since this is rare
-           * that happens, it might be best to remove the check and always 'schedule' the move because
+           * it might be fine to remove this check and let planner.buffer_segment() filter it out.
-           * the planner.buffer_segment() routine will filter it if that happens.
            */
           if (rx != start[X_AXIS]) {
             if (!inf_normalized_flag) {
@@ -315,7 +273,7 @@
 
       /**
        *
-       * This block handles the generic case of a line crossing both X and Y Mesh lines.
+       * Handle the generic case of a line crossing both X and Y Mesh lines.
        *
        */
 
@@ -328,7 +286,7 @@
       current_xi += left_flag;
       current_yi += down_flag;
 
-      while (xi_cnt > 0 || yi_cnt > 0) {
+      while (xi_cnt || yi_cnt) {
 
         const float next_mesh_line_x = mesh_index_to_xpos(current_xi + dxi),
                     next_mesh_line_y = mesh_index_to_ypos(current_yi + dyi),
@@ -343,13 +301,8 @@
           float z0 = z_correction_for_x_on_horizontal_mesh_line(rx, current_xi - left_flag, current_yi + dyi)
                      * planner.fade_scaling_factor_for_z(end[Z_AXIS]);
 
-          /**
+          // Undefined parts of the Mesh in z_values[][] are NAN.
-           * If part of the Mesh is undefined, it will show up as NAN
+          // Replace NAN corrections with 0.0 to prevent NAN propagation.
-           * in z_values[][] and propagate through the
-           * calculations. If our correction is NAN, we throw it out
-           * because part of the Mesh is undefined and we don't have the
-           * information we need to complete the height correction.
-           */
           if (isnan(z0)) z0 = 0.0;
 
           if (!inf_normalized_flag) {
@@ -370,13 +323,8 @@
           float z0 = z_correction_for_y_on_vertical_mesh_line(ry, current_xi + dxi, current_yi - down_flag)
                      * planner.fade_scaling_factor_for_z(end[Z_AXIS]);
 
-          /**
+          // Undefined parts of the Mesh in z_values[][] are NAN.
-           * If part of the Mesh is undefined, it will show up as NAN
+          // Replace NAN corrections with 0.0 to prevent NAN propagation.
-           * in z_values[][] and propagate through the
-           * calculations. If our correction is NAN, we throw it out
-           * because part of the Mesh is undefined and we don't have the
-           * information we need to complete the height correction.
-           */
           if (isnan(z0)) z0 = 0.0;
 
           if (!inf_normalized_flag) {
@@ -394,7 +342,7 @@
           xi_cnt--;
         }
 
-        if (xi_cnt < 0 || yi_cnt < 0) break; // we've gone too far, so exit the loop and move on to FINAL_MOVE
+        //if (xi_cnt < 0 || yi_cnt < 0) break; // Too far! Exit the loop and go to FINAL_MOVE
       }
 
       if (g26_debug_flag)