[vlc-devel] [PATCH 2/2] libvlc: provide sane interfaces for video crop

[Rémi Denis-Courmont]

This provides one setter for each crop mode, matching the internal video
output functionality.
---
 include/vlc/libvlc_media_player.h | 77 +++++++++++++++++++++++++++++--
 lib/libvlc.sym                    |  4 +-
 lib/video.c                       | 53 ++++++++++++++++-----
 3 files changed, 117 insertions(+), 17 deletions(-)

diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h
index 7445e985b3..c1b0e3db4c 100644
--- a/include/vlc/libvlc_media_player.h
+++ b/include/vlc/libvlc_media_player.h
@@ -1649,13 +1649,82 @@ void libvlc_chapter_descriptions_release( libvlc_chapter_description_t **p_chapt
                                           unsigned i_count );
 
 /**
- * Set new crop filter geometry.
+ * Set/unset the video crop ratio.
  *
- * \param p_mi the media player
- * \param psz_geometry new crop filter geometry (NULL to unset)
+ * This function forces a crop ratio on any and all video tracks rendered by
+ * the media player. If the display aspect ratio of a video does not match the
+ * crop ratio, either the top and bottom, or the left and right of the video
+ * will be cut out to fit the crop ratio.
+ *
+ * For instance, a ratio of 1:1 will force the video to a square shape.
+ *
+ * To disable video crop, set a crop ratio with zero as denominator.
+ *
+ * A call to this function overrides any previous call to any of
+ * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
+ * libvlc_video_set_crop_window().
+ *
+ * \see libvlc_video_set_aspect_ratio()
+ *
+ * \param mp the media player
+ * \param num crop ratio numerator (ignored if denominator is 0)
+ * \param den crop ratio denominator (or 0 to unset the crop ratio)
+ *
+ * \version LibVLC 4.0.0 and later
+ */
+LIBVLC_API
+void libvlc_video_set_crop_ratio(libvlc_media_player_t *mp,
+                                 unsigned num, unsigned den);
+
+/**
+ * Set the video crop window.
+ *
+ * This function selects a sub-rectangle of video to show. Any pixels outside
+ * the rectangle will not be shown.
+ *
+ * To unset the video crop window, use libvlc_video_set_crop_ratio() or
+ * libvlc_video_set_crop_border().
+ *
+ * A call to this function overrides any previous call to any of
+ * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
+ * libvlc_video_set_crop_window().
+ *
+ * \param mp the media player
+ * \param x abscissa (i.e. leftmost sample column offset) of the crop window
+ * \param y ordinate (i.e. topmost sample row offset) of the crop window
+ * \param width sample width of the crop window (cannot be zero)
+ * \param height sample height of the crop window (cannot be zero)
+ *
+ * \version LibVLC 4.0.0 and later
+ */
+LIBVLC_API
+void libvlc_video_set_crop_window(libvlc_media_player_t *mp,
+                                  unsigned x, unsigned y,
+                                  unsigned width, unsigned height);
+
+/**
+ * Set the video crop borders.
+ *
+ * This function selects the size of video edges to be cropped out.
+ *
+ * To unset the video crop borders, set all borders to zero.
+ *
+ * A call to this function overrides any previous call to any of
+ * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
+ * libvlc_video_set_crop_window().
+ *
+ * \param mp the media player
+ * \param left number of sample columns to crop on the left
+ * \param right number of sample columns to crop on the right
+ * \param top number of sample rows to crop on the top
+ * \param bottom number of sample rows to corp on the bottom
+ *
+ * \version LibVLC 4.0.0 and later
  */
 LIBVLC_API
-void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry );
+void libvlc_video_set_crop_border(libvlc_media_player_t *mp,
+                                  unsigned left, unsigned right,
+                                  unsigned top, unsigned bottom);
 
 /**
  * Get current teletext page requested or 0 if it's disabled.
diff --git a/lib/libvlc.sym b/lib/libvlc.sym
index 9c109b8272..438cd54485 100644
--- a/lib/libvlc.sym
+++ b/lib/libvlc.sym
@@ -236,7 +236,9 @@ libvlc_video_set_adjust_float
 libvlc_video_set_adjust_int
 libvlc_video_set_aspect_ratio
 libvlc_video_set_callbacks
-libvlc_video_set_crop_geometry
+libvlc_video_set_crop_ratio
+libvlc_video_set_crop_window
+libvlc_video_set_crop_border
 libvlc_video_set_deinterlace
 libvlc_video_set_format
 libvlc_video_set_format_callbacks
diff --git a/lib/video.c b/lib/video.c
index e62f2a7ae2..d671e7b4fe 100644
--- a/lib/video.c
+++ b/lib/video.c
@@ -363,25 +363,54 @@ int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi,
     return 0;
 }
 
-void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi,
-                                     const char *psz_geometry )
+static void libvlc_video_set_crop(libvlc_media_player_t *mp,
+                                  const char *geometry)
 {
-    if (psz_geometry == NULL)
-        psz_geometry = "";
-
-    var_SetString (p_mi, "crop", psz_geometry);
+    var_SetString(mp, "crop", geometry);
 
     size_t n;
-    vout_thread_t **pp_vouts = GetVouts (p_mi, &n);
+    vout_thread_t **vouts = GetVouts(mp, &n);
 
     for (size_t i = 0; i < n; i++)
     {
-        vout_thread_t *p_vout = pp_vouts[i];
-
-        var_SetString (p_vout, "crop", psz_geometry);
-        vout_Release(p_vout);
+        var_SetString(vouts[i], "crop", geometry);
+        vout_Release(vouts[i]);
     }
-    free (pp_vouts);
+    free(vouts);
+}
+
+void libvlc_video_set_crop_ratio(libvlc_media_player_t *mp,
+                                 unsigned num, unsigned den)
+{
+    char geometry[2 * (sizeof (unsigned) + 1)];
+
+    if (den == 0)
+        geometry[0] = '\0';
+    else
+        sprintf(geometry, "%u:%u", num, den);
+
+    libvlc_video_set_crop(mp, geometry);
+}
+
+void libvlc_video_set_crop_window(libvlc_media_player_t *mp,
+                                  unsigned x, unsigned y,
+                                  unsigned width, unsigned height)
+{
+    char geometry[4 * (sizeof (unsigned) + 1)];
+
+    assert(width != 0 && height != 0);
+    sprintf(geometry, "%ux%u+%u+%u", x, y, width, height);
+    libvlc_video_set_crop(mp, geometry);
+}
+
+void libvlc_video_set_crop_border(libvlc_media_player_t *mp,
+                                  unsigned left, unsigned right,
+                                  unsigned top, unsigned bottom)
+{
+    char geometry[4 * (sizeof (unsigned) + 1)];
+
+    sprintf(geometry, "%u+%u+%u+%u", left, top, right, bottom);
+    libvlc_video_set_crop(mp, geometry);
 }
 
 int libvlc_video_get_teletext( libvlc_media_player_t *p_mi )
-- 
2.20.1