v4l2object: rename crop function to reflect its usage

The gst_v4l2_object_set_crop() is used for removing buffer
alignment padding. Give it a name that better reflects
that usage.  This helps to distinguish from cropping of the
input image (e.g. cropping at the image sensor on a captre
device), which can be  unrelated to the memory buffer padding,
especially if scaling is involved.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/2392>

subprojects/gst-plugins-good/sys/v4l2/gstv4l2object.c

@@ -4291,29 +4291,40 @@ unsupported_format:
   }
 }
 
+/**
+ * gst_v4l2_object_set_crop:
+ * @obj: the object
+ * @crop_rect: the region to crop
+ *
+ * Crop the video data to the regions specified in the @crop_rect.
+ *
+ * For capture devices, this crop the image sensor / video stream provided by
+ * the V4L2 device.
+ * For output devices, this crops the memory buffer that GStreamer passed to
+ * the V4L2 device.
+ *
+ * The crop_rect may be modified by the V4L2 device to a region that
+ * fulfills H/W requirements.
+ *
+ * Returns: %TRUE on success, %FALSE on failure.
+ */
 gboolean
-gst_v4l2_object_set_crop (GstV4l2Object * obj)
+gst_v4l2_object_set_crop (GstV4l2Object * obj, struct v4l2_rect * crop_rect)
 {
   struct v4l2_selection sel = { 0 };
   struct v4l2_crop crop = { 0 };
 
+  GST_V4L2_CHECK_OPEN (obj);
+  GST_V4L2_CHECK_NOT_ACTIVE (obj);
+
   sel.type = obj->type;
   sel.target = V4L2_SEL_TGT_CROP;
   sel.flags = 0;
-  sel.r.left = obj->align.padding_left;
-  sel.r.top = obj->align.padding_top;
-  sel.r.width = obj->info.width;
-  sel.r.height = GST_VIDEO_INFO_FIELD_HEIGHT (&obj->info);
+  sel.r = *crop_rect;
 
   crop.type = obj->type;
   crop.c = sel.r;
 
-  if (obj->align.padding_left + obj->align.padding_top +
-      obj->align.padding_right + obj->align.padding_bottom == 0) {
-    GST_DEBUG_OBJECT (obj->dbg_obj, "no cropping needed");
-    return TRUE;
-  }
-
   GST_DEBUG_OBJECT (obj->dbg_obj,
       "Desired cropping left %u, top %u, size %ux%u", crop.c.left, crop.c.top,
       crop.c.width, crop.c.height);
@@ -4346,6 +4357,40 @@ gst_v4l2_object_set_crop (GstV4l2Object * obj)
   return TRUE;
 }
 
+/**
+ * gst_v4l2_object_setup_padding:
+ * @obj: v4l2 object
+ *
+ * Crop away the padding around the video data as specified
+ * in GstVideoAlignement data stored in @obj.
+ *
+ * For capture devices, this crop the image sensor / video stream provided by
+ * the V4L2 device.
+ * For output devices, this crops the memory buffer that GStreamer passed to
+ * the V4L2 device.
+ *
+ * Returns: %TRUE on success, %FALSE on failure.
+ */
+gboolean
+gst_v4l2_object_setup_padding (GstV4l2Object * obj)
+{
+  GstVideoAlignment *align = &obj->align;
+  struct v4l2_rect crop;
+
+  if (align->padding_left + align->padding_top
+      + align->padding_right + align->padding_bottom == 0) {
+    GST_DEBUG_OBJECT (obj->dbg_obj, "no cropping needed");
+    return TRUE;
+  }
+
+  crop.left = align->padding_left;
+  crop.top = align->padding_top;
+  crop.width = obj->info.width;
+  crop.height = GST_VIDEO_INFO_FIELD_HEIGHT (&obj->info);
+
+  return gst_v4l2_object_set_crop (obj, &crop);
+}
+
 gboolean
 gst_v4l2_object_caps_equal (GstV4l2Object * v4l2object, GstCaps * caps)
 {
@@ -4712,7 +4757,7 @@ gst_v4l2_object_match_buffer_layout (GstV4l2Object * obj, guint n_planes,
     /* Crop because of vertical padding */
     GST_DEBUG_OBJECT (obj->dbg_obj, "crop because of bottom padding of %d",
         obj->align.padding_bottom);
-    gst_v4l2_object_set_crop (obj);
+    gst_v4l2_object_setup_padding (obj);
   }
 
   return TRUE;

subprojects/gst-plugins-good/sys/v4l2/gstv4l2object.h

@@ -307,7 +307,7 @@ GstCaps *    gst_v4l2_object_get_caps    (GstV4l2Object * v4l2object, GstCaps *
 
 gboolean     gst_v4l2_object_acquire_format (GstV4l2Object * v4l2object, GstVideoInfo * info);
 
-gboolean     gst_v4l2_object_set_crop    (GstV4l2Object * obj);
+gboolean     gst_v4l2_object_setup_padding (GstV4l2Object * obj);
 
 gboolean     gst_v4l2_object_decide_allocation (GstV4l2Object * v4l2object, GstQuery * query);
 
@@ -315,6 +315,9 @@ gboolean     gst_v4l2_object_propose_allocation (GstV4l2Object * obj, GstQuery *
 
 GstStructure * gst_v4l2_object_v4l2fourcc_to_structure (guint32 fourcc);
 
+/* crop / compose */
+gboolean     gst_v4l2_object_set_crop (GstV4l2Object * obj, struct v4l2_rect *result);
+
 /* TODO Move to proper namespace */
 /* open/close the device */
 gboolean     gst_v4l2_open           (GstV4l2Object * v4l2object, GstV4l2Error * error);

subprojects/gst-plugins-good/sys/v4l2/gstv4l2transform.c

@@ -225,10 +225,10 @@ gst_v4l2_transform_set_caps (GstBaseTransform * trans, GstCaps * incaps,
   gst_caps_replace (&self->outcaps, outcaps);
 
   /* FIXME implement fallback if crop not supported */
-  if (!gst_v4l2_object_set_crop (self->v4l2output))
+  if (!gst_v4l2_object_setup_padding (self->v4l2output))
     goto failed;
 
-  if (!gst_v4l2_object_set_crop (self->v4l2capture))
+  if (!gst_v4l2_object_setup_padding (self->v4l2capture))
     goto failed;
 
   return TRUE;