gst-libs/gst/video/video-overlay-composition.c

   1 /* GStreamer Video Overlay Composition
   2  * Copyright (C) 2011 Intel Corporation
   3  * Copyright (C) 2011 Collabora Ltd.
   4  * Copyright (C) 2011 Tim-Philipp Müller <tim centricular net>
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /**
  23  * SECTION:gstvideooverlaycomposition
  24  * @short_description: Video Buffer Overlay Compositions (Subtitles, Logos)
  25  *
  26  * <refsect2>
  27  * <para>
  28  * Functions to create and handle overlay compositions on video buffers.
  29  * </para>
  30  * <para>
  31  * An overlay composition describes one or more overlay rectangles to be
  32  * blended on top of a video buffer.
  33  * </para>
  34  * <para>
  35  * This API serves two main purposes:
  36  * <itemizedlist>
  37  * <listitem>
  38  * it can be used to attach overlay information (subtitles or logos)
  39  * to non-raw video buffers such as GL/VAAPI/VDPAU surfaces. The actual
  40  * blending of the overlay can then be done by e.g. the video sink that
  41  * processes these non-raw buffers.
  42  * </listitem>
  43  * <listitem>
  44  * it can also be used to blend overlay rectangles on top of raw video
  45  * buffers, thus consolidating blending functionality for raw video in
  46  * one place.
  47  * </listitem>
  48  * Together, this allows existing overlay elements to easily handle raw
  49  * and non-raw video as input in without major changes (once the overlays
  50  * have been put into a #GstOverlayComposition object anyway) - for raw
  51  * video the overlay can just use the blending function to blend the data
  52  * on top of the video, and for surface buffers it can just attach them to
  53  * the buffer and let the sink render the overlays.
  54  * </itemizedlist>
  55  * </para>
  56  * </refsect2>
  57  *
  58  * Since: 0.10.36
  59  */
  60
  61 /* TODO:
  62  *  - provide accessors for seq_num and other fields (as needed)
  63  *  - allow overlay to set/get original pango markup string on/from rectangle
  64  */
  65
  66 #ifdef HAVE_CONFIG_H
  67 #include "config.h"
  68 #endif
  69
  70 #include "video-overlay-composition.h"
  71 #include "video-blend.h"
  72
  73 struct _GstVideoOverlayComposition
  74 {
  75   GstMiniObject parent;
  76
  77   guint num_rectangles;
  78   GstVideoOverlayRectangle **rectangles;
  79
  80   /* lowest rectangle sequence number still used by the upstream
  81    * overlay element. This way a renderer maintaining some kind of
  82    * rectangles <-> surface cache can know when to free cached
  83    * surfaces/rectangles. */
  84   guint min_seq_num_used;
  85
  86   /* sequence number for the composition (same series as rectangles) */
  87   guint seq_num;
  88 };
  89
  90 struct _GstVideoOverlayCompositionClass
  91 {
  92   GstMiniObjectClass parent_class;
  93 };
  94
  95 struct _GstVideoOverlayRectangle
  96 {
  97   GstMiniObject parent;
  98
  99   /* Position on video frame and dimension of output rectangle in
 100    * output frame terms (already adjusted for the PAR of the output
 101    * frame). x/y can be negative (overlay will be clipped then) */
 102   gint x, y;
 103   guint render_width, render_height;
 104
 105   /* Dimensions of overlay pixels */
 106   guint width, height, stride;
 107
 108   /* The format of the data in pixels */
 109   GstVideoFormat format;
 110
 111   /* Refcounted blob of memory, no caps or timestamps */
 112   GstBuffer *pixels;
 113
 114   /* FIXME: how to express source like text or pango markup?
 115    *        (just add source type enum + source buffer with data)
 116    *
 117    * FOR 0.10: always send pixel blobs, but attach source data in
 118    * addition (reason: if downstream changes, we can't renegotiate
 119    * that properly, if we just do a query of supported formats from
 120    * the start). Sink will just ignore pixels and use pango markup
 121    * from source data if it supports that.
 122    *
 123    * FOR 0.11: overlay should query formats (pango markup, pixels)
 124    * supported by downstream and then only send that. We can
 125    * renegotiate via the reconfigure event.
 126    */
 127
 128   /* sequence number: useful for backends/renderers/sinks that want
 129    * to maintain a cache of rectangles <-> surfaces. The value of
 130    * the min_seq_num_used in the composition tells the renderer which
 131    * rectangles have expired. */
 132   guint seq_num;
 133
 134   /* FIXME: we may also need a (private) way to cache converted/scaled
 135    * pixel blobs */
 136 #if !GLIB_CHECK_VERSION (2, 31, 0)
 137   GStaticMutex lock;
 138 #else
 139   GMutex lock;
 140 #endif
 141
 142   GList *scaled_rectangles;
 143 };
 144
 145 struct _GstVideoOverlayRectangleClass
 146 {
 147   GstMiniObjectClass parent_class;
 148 };
 149
 150 #if !GLIB_CHECK_VERSION (2, 31, 0)
 151 #define GST_RECTANGLE_LOCK(rect)   g_static_mutex_lock(&rect->lock)
 152 #define GST_RECTANGLE_UNLOCK(rect) g_static_mutex_unlock(&rect->lock)
 153 #else
 154 #define GST_RECTANGLE_LOCK(rect)   g_mutex_lock(&rect->lock)
 155 #define GST_RECTANGLE_UNLOCK(rect) g_mutex_unlock(&rect->lock)
 156 #endif
 157
 158 static void gst_video_overlay_composition_class_init (GstMiniObjectClass * k);
 159 static void gst_video_overlay_composition_finalize (GstMiniObject * comp);
 160 static void gst_video_overlay_rectangle_class_init (GstMiniObjectClass * klass);
 161 static void gst_video_overlay_rectangle_finalize (GstMiniObject * rect);
 162
 163 /* --------------------------- utility functions --------------------------- */
 164
 165 #ifndef GST_DISABLE_GST_DEBUG
 166
 167 #define GST_CAT_DEFAULT ensure_debug_category()
 168
 169 static GstDebugCategory *
 170 ensure_debug_category (void)
 171 {
 172   static gsize cat_gonce = 0;
 173
 174   if (g_once_init_enter (&cat_gonce)) {
 175     gsize cat_done;
 176
 177     cat_done = (gsize) _gst_debug_category_new ("video-composition", 0,
 178         "video overlay composition");
 179
 180     g_once_init_leave (&cat_gonce, cat_done);
 181   }
 182
 183   return (GstDebugCategory *) cat_gonce;
 184 }
 185
 186 #else
 187
 188 #define ensure_debug_category() /* NOOP */
 189
 190 #endif /* GST_DISABLE_GST_DEBUG */
 191
 192 static guint
 193 gst_video_overlay_get_seqnum (void)
 194 {
 195   static gint seqnum;           /* 0 */
 196
 197 #if GLIB_CHECK_VERSION(2,29,5)
 198   return (guint) g_atomic_int_add (&seqnum, 1);
 199 #else
 200   return (guint) g_atomic_int_exchange_and_add (&seqnum, 1);
 201 #endif
 202 }
 203
 204 #define GST_OVERLAY_COMPOSITION_QUARK gst_overlay_composition_quark_get()
 205 static GQuark
 206 gst_overlay_composition_quark_get (void)
 207 {
 208   static gsize quark_gonce = 0;
 209
 210   if (g_once_init_enter (&quark_gonce)) {
 211     gsize quark;
 212
 213     quark = (gsize) g_quark_from_static_string ("GstVideoOverlayComposition");
 214
 215     g_once_init_leave (&quark_gonce, quark);
 216   }
 217
 218   return (GQuark) quark_gonce;
 219 }
 220
 221 #define COMPOSITION_QUARK composition_quark_get()
 222 static GQuark
 223 composition_quark_get (void)
 224 {
 225   static gsize quark_gonce = 0;
 226
 227   if (g_once_init_enter (&quark_gonce)) {
 228     gsize quark;
 229
 230     quark = (gsize) g_quark_from_static_string ("composition");
 231
 232     g_once_init_leave (&quark_gonce, quark);
 233   }
 234
 235   return (GQuark) quark_gonce;
 236 }
 237
 238 /**
 239  * gst_video_buffer_set_overlay_composition:
 240  * @buf: a #GstBuffer
 241  * @comp: (allow-none): a #GstVideoOverlayComposition, or NULL to clear a
 242  *     previously-set composition
 243  *
 244  * Sets an overlay composition on a buffer. The buffer will obtain its own
 245  * reference to the composition, meaning this function does not take ownership
 246  * of @comp.
 247  *
 248  * Since: 0.10.36
 249  */
 250 void
 251 gst_video_buffer_set_overlay_composition (GstBuffer * buf,
 252     GstVideoOverlayComposition * comp)
 253 {
 254   gst_buffer_set_qdata (buf, GST_OVERLAY_COMPOSITION_QUARK,
 255       gst_structure_id_new (GST_OVERLAY_COMPOSITION_QUARK,
 256           COMPOSITION_QUARK, GST_TYPE_VIDEO_OVERLAY_COMPOSITION, comp, NULL));
 257 }
 258
 259 /**
 260  * gst_video_buffer_get_overlay_composition:
 261  * @buf: a #GstBuffer
 262  *
 263  * Get the overlay composition that has previously been attached to a buffer
 264  * with gst_video_buffer_get_overlay_composition(), usually by another element
 265  * upstream.
 266  *
 267  * Returns: (transfer none): the #GstVideoOverlayComposition attached to
 268  *    this buffer, or NULL. Does not return a reference to the composition,
 269  *    caller must obtain her own ref via gst_video_overlay_composition_ref()
 270  *    if needed.
 271  *
 272  * Since: 0.10.36
 273  */
 274 GstVideoOverlayComposition *
 275 gst_video_buffer_get_overlay_composition (GstBuffer * buf)
 276 {
 277   const GstStructure *s;
 278   const GValue *val;
 279
 280   s = gst_buffer_get_qdata (buf, GST_OVERLAY_COMPOSITION_QUARK);
 281   if (s == NULL)
 282     return NULL;
 283
 284   val = gst_structure_id_get_value (s, COMPOSITION_QUARK);
 285   if (val == NULL)
 286     return NULL;
 287
 288   return GST_VIDEO_OVERLAY_COMPOSITION (gst_value_get_mini_object (val));
 289 }
 290
 291 /* ------------------------------ composition ------------------------------ */
 292
 293 #define RECTANGLE_ARRAY_STEP 4  /* premature optimization */
 294
 295 GType
 296 gst_video_overlay_composition_get_type (void)
 297 {
 298   static volatile gsize type_id = 0;
 299
 300   if (g_once_init_enter (&type_id)) {
 301     GType new_type_id = g_type_register_static_simple (GST_TYPE_MINI_OBJECT,
 302         g_intern_static_string ("GstVideoOverlayComposition"),
 303         sizeof (GstVideoOverlayCompositionClass),
 304         (GClassInitFunc) gst_video_overlay_composition_class_init,
 305         sizeof (GstVideoOverlayComposition),
 306         NULL,
 307         (GTypeFlags) 0);
 308
 309     g_once_init_leave (&type_id, new_type_id);
 310   }
 311
 312   return type_id;
 313 }
 314
 315 static void
 316 gst_video_overlay_composition_finalize (GstMiniObject * mini_obj)
 317 {
 318   GstVideoOverlayComposition *comp = (GstVideoOverlayComposition *) mini_obj;
 319   guint num;
 320
 321   num = comp->num_rectangles;
 322
 323   while (num > 0) {
 324     gst_video_overlay_rectangle_unref (comp->rectangles[num - 1]);
 325     --num;
 326   }
 327
 328   g_free (comp->rectangles);
 329   comp->rectangles = NULL;
 330   comp->num_rectangles = 0;
 331
 332   /* not chaining up to GstMiniObject's finalize for now, we know it's empty */
 333 }
 334
 335 static void
 336 gst_video_overlay_composition_class_init (GstMiniObjectClass * klass)
 337 {
 338   klass->finalize = gst_video_overlay_composition_finalize;
 339   klass->copy = (GstMiniObjectCopyFunction) gst_video_overlay_composition_copy;
 340 }
 341
 342 /**
 343  * gst_video_overlay_composition_new:
 344  * @rectangle: (transfer none): a #GstVideoOverlayRectangle to add to the
 345  *     composition
 346  *
 347  * Creates a new video overlay composition object to hold one or more
 348  * overlay rectangles.
 349  *
 350  * Returns: (transfer full): a new #GstVideoOverlayComposition. Unref with
 351  *     gst_video_overlay_composition_unref() when no longer needed.
 352  *
 353  * Since: 0.10.36
 354  */
 355 GstVideoOverlayComposition *
 356 gst_video_overlay_composition_new (GstVideoOverlayRectangle * rectangle)
 357 {
 358   GstVideoOverlayComposition *comp;
 359
 360
 361   /* FIXME: should we allow empty compositions? Could also be expressed as
 362    * buffer without a composition on it. Maybe there are cases where doing
 363    * an empty new + _add() in a loop is easier? */
 364   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
 365
 366   comp = (GstVideoOverlayComposition *)
 367       gst_mini_object_new (GST_TYPE_VIDEO_OVERLAY_COMPOSITION);
 368
 369   comp->rectangles = g_new0 (GstVideoOverlayRectangle *, RECTANGLE_ARRAY_STEP);
 370   comp->rectangles[0] = gst_video_overlay_rectangle_ref (rectangle);
 371   comp->num_rectangles = 1;
 372
 373   comp->seq_num = gst_video_overlay_get_seqnum ();
 374
 375   /* since the rectangle was created earlier, its seqnum is smaller than ours */
 376   comp->min_seq_num_used = rectangle->seq_num;
 377
 378   GST_LOG ("new composition %p: seq_num %u with rectangle %p", comp,
 379       comp->seq_num, rectangle);
 380
 381   return comp;
 382 }
 383
 384 /**
 385  * gst_video_overlay_composition_add_rectangle:
 386  * @comp: a #GstVideoOverlayComposition
 387  * @rectangle: (transfer none): a #GstVideoOverlayRectangle to add to the
 388  *     composition
 389  *
 390  * Adds an overlay rectangle to an existing overlay composition object. This
 391  * must be done right after creating the overlay composition.
 392  *
 393  * Since: 0.10.36
 394  */
 395 void
 396 gst_video_overlay_composition_add_rectangle (GstVideoOverlayComposition * comp,
 397     GstVideoOverlayRectangle * rectangle)
 398 {
 399   g_return_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp));
 400   g_return_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle));
 401   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (comp) == 1);
 402
 403   if (comp->num_rectangles % RECTANGLE_ARRAY_STEP == 0) {
 404     comp->rectangles =
 405         g_renew (GstVideoOverlayRectangle *, comp->rectangles,
 406         comp->num_rectangles + RECTANGLE_ARRAY_STEP);
 407   }
 408
 409   comp->rectangles[comp->num_rectangles] =
 410       gst_video_overlay_rectangle_ref (rectangle);
 411   comp->num_rectangles += 1;
 412
 413   comp->min_seq_num_used = MIN (comp->min_seq_num_used, rectangle->seq_num);
 414
 415   GST_LOG ("composition %p: added rectangle %p", comp, rectangle);
 416 }
 417
 418 /**
 419  * gst_video_overlay_composition_n_rectangles:
 420  * @comp: a #GstVideoOverlayComposition
 421  *
 422  * Returns the number of #GstVideoOverlayRectangle<!-- -->s contained in @comp.
 423  *
 424  * Returns: the number of rectangles
 425  *
 426  * Since: 0.10.36
 427  */
 428 guint
 429 gst_video_overlay_composition_n_rectangles (GstVideoOverlayComposition * comp)
 430 {
 431   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), 0);
 432
 433   return comp->num_rectangles;
 434 }
 435
 436 /**
 437  * gst_video_overlay_composition_get_rectangle:
 438  * @comp: a #GstVideoOverlayComposition
 439  * @n: number of the rectangle to get
 440  *
 441  * Returns the @n-th #GstVideoOverlayRectangle contained in @comp.
 442  *
 443  * Returns: (transfer none): the @n-th rectangle, or NULL if @n is out of
 444  *     bounds. Will not return a new reference, the caller will need to
 445  *     obtain her own reference using gst_video_overlay_rectangle_ref()
 446  *     if needed.
 447  *
 448  * Since: 0.10.36
 449  */
 450 GstVideoOverlayRectangle *
 451 gst_video_overlay_composition_get_rectangle (GstVideoOverlayComposition * comp,
 452     guint n)
 453 {
 454   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), NULL);
 455
 456   if (n >= comp->num_rectangles)
 457     return NULL;
 458
 459   return comp->rectangles[n];
 460 }
 461
 462 static gboolean
 463 gst_video_overlay_rectangle_needs_scaling (GstVideoOverlayRectangle * r)
 464 {
 465   return (r->width != r->render_width || r->height != r->render_height);
 466 }
 467
 468 /**
 469  * gst_video_overlay_composition_blend:
 470  * @comp: a #GstVideoOverlayComposition
 471  * @video_buf: a #GstBuffer containing raw video data in a supported format
 472  *
 473  * Blends the overlay rectangles in @comp on top of the raw video data
 474  * contained in @video_buf. The data in @video_buf must be writable. If
 475  * needed, use gst_buffer_make_writable() before calling this function to
 476  * ensure a buffer is writable. @video_buf must also have valid raw video
 477  * caps set on it.
 478  *
 479  * Since: 0.10.36
 480  */
 481 gboolean
 482 gst_video_overlay_composition_blend (GstVideoOverlayComposition * comp,
 483     GstBuffer * video_buf)
 484 {
 485   GstBlendVideoFormatInfo video_info, rectangle_info;
 486   GstVideoFormat fmt;
 487   gboolean ret = TRUE;
 488   guint n, num;
 489   int w, h;
 490
 491   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), FALSE);
 492   g_return_val_if_fail (GST_IS_BUFFER (video_buf), FALSE);
 493   g_return_val_if_fail (gst_buffer_is_writable (video_buf), FALSE);
 494   g_return_val_if_fail (GST_BUFFER_CAPS (video_buf) != NULL, FALSE);
 495
 496   if (!gst_video_format_parse_caps (GST_BUFFER_CAPS (video_buf), &fmt, &w, &h)) {
 497     gchar *str = gst_caps_to_string (GST_BUFFER_CAPS (video_buf));
 498     g_warning ("%s: could not parse video buffer caps '%s'", GST_FUNCTION, str);
 499     g_free (str);
 500     return FALSE;
 501   }
 502
 503   video_blend_format_info_init (&video_info, GST_BUFFER_DATA (video_buf),
 504       h, w, fmt);
 505
 506   num = comp->num_rectangles;
 507   GST_LOG ("Blending composition %p with %u rectangles onto video buffer %p "
 508       "(%ux%u, format %u)", comp, num, video_buf, w, h, fmt);
 509
 510   for (n = 0; n < num; ++n) {
 511     GstVideoOverlayRectangle *rect;
 512     gboolean needs_scaling;
 513
 514     rect = comp->rectangles[n];
 515
 516     GST_LOG (" rectangle %u %p: %ux%u, format %u", n, rect, rect->height,
 517         rect->width, rect->format);
 518
 519     video_blend_format_info_init (&rectangle_info,
 520         GST_BUFFER_DATA (rect->pixels), rect->height, rect->width,
 521         rect->format);
 522
 523     needs_scaling = gst_video_overlay_rectangle_needs_scaling (rect);
 524     if (needs_scaling) {
 525       video_blend_scale_linear_RGBA (&rectangle_info, rect->render_height,
 526           rect->render_width);
 527     }
 528
 529     ret = video_blend (&video_info, &rectangle_info, rect->x, rect->y);
 530     if (!ret) {
 531       GST_WARNING ("Could not blend overlay rectangle onto video buffer");
 532     }
 533
 534     /* FIXME: should cache scaled pixels in the rectangle struct */
 535     if (needs_scaling)
 536       g_free (rectangle_info.pixels);
 537   }
 538
 539   return ret;
 540 }
 541
 542 /**
 543  * gst_video_overlay_composition_copy:
 544  * @comp: (transfer none): a #GstVideoOverlayComposition to copy
 545  *
 546  * Makes a copy of @comp and all contained rectangles, so that it is possible
 547  * to modify the composition and contained rectangles (e.g. add additional
 548  * rectangles or change the render co-ordinates or render dimension). The
 549  * actual overlay pixel data buffers contained in the rectangles are not
 550  * copied.
 551  *
 552  * Returns: (transfer full): a new #GstVideoOverlayComposition equivalent
 553  *     to @comp.
 554  *
 555  * Since: 0.10.36
 556  */
 557 GstVideoOverlayComposition *
 558 gst_video_overlay_composition_copy (GstVideoOverlayComposition * comp)
 559 {
 560   GstVideoOverlayComposition *copy;
 561   GstVideoOverlayRectangle *rect;
 562   guint n;
 563
 564   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), NULL);
 565
 566   if (G_LIKELY (comp->num_rectangles == 0))
 567     return gst_video_overlay_composition_new (NULL);
 568
 569   rect = gst_video_overlay_rectangle_copy (comp->rectangles[0]);
 570   copy = gst_video_overlay_composition_new (rect);
 571   gst_video_overlay_rectangle_unref (rect);
 572
 573   for (n = 1; n < comp->num_rectangles; ++n) {
 574     rect = gst_video_overlay_rectangle_copy (comp->rectangles[n]);
 575     gst_video_overlay_composition_add_rectangle (copy, rect);
 576     gst_video_overlay_rectangle_unref (rect);
 577   }
 578
 579   return copy;
 580 }
 581
 582 /**
 583  * gst_video_overlay_composition_make_writable:
 584  * @comp: (transfer full): a #GstVideoOverlayComposition to copy
 585  *
 586  * Takes ownership of @comp and returns a version of @comp that is writable
 587  * (i.e. can be modified). Will either return @comp right away, or create a
 588  * new writable copy of @comp and unref @comp itself. All the contained
 589  * rectangles will also be copied, but the actual overlay pixel data buffers
 590  * contained in the rectangles are not copied.
 591  *
 592  * Returns: (transfer full): a writable #GstVideoOverlayComposition
 593  *     equivalent to @comp.
 594  *
 595  * Since: 0.10.36
 596  */
 597 GstVideoOverlayComposition *
 598 gst_video_overlay_composition_make_writable (GstVideoOverlayComposition * comp)
 599 {
 600   GstVideoOverlayComposition *writable_comp;
 601
 602   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), NULL);
 603
 604   if (GST_MINI_OBJECT_REFCOUNT_VALUE (comp) == 1) {
 605     guint n;
 606
 607     for (n = 0; n < comp->num_rectangles; ++n) {
 608       if (GST_MINI_OBJECT_REFCOUNT_VALUE (comp->rectangles[n]) != 1)
 609         goto copy;
 610     }
 611     return comp;
 612   }
 613
 614 copy:
 615
 616   writable_comp = gst_video_overlay_composition_copy (comp);
 617   gst_video_overlay_composition_unref (comp);
 618
 619   return writable_comp;
 620 }
 621
 622 /**
 623  * gst_video_overlay_composition_get_seqnum:
 624  * @comp: a #GstVideoOverlayComposition
 625  *
 626  * Returns the sequence number of this composition. Sequence numbers are
 627  * monotonically increasing and unique for overlay compositions and rectangles
 628  * (meaning there will never be a rectangle with the same sequence number as
 629  * a composition).
 630  *
 631  * Returns: the sequence number of @comp
 632  *
 633  * Since: 0.10.36
 634  */
 635 guint
 636 gst_video_overlay_composition_get_seqnum (GstVideoOverlayComposition * comp)
 637 {
 638   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), 0);
 639
 640   return comp->seq_num;
 641 }
 642
 643 /* ------------------------------ rectangles ------------------------------ -*/
 644
 645 static void gst_video_overlay_rectangle_instance_init (GstMiniObject * miniobj);
 646
 647 GType
 648 gst_video_overlay_rectangle_get_type (void)
 649 {
 650   static volatile gsize type_id = 0;
 651
 652   if (g_once_init_enter (&type_id)) {
 653     GType new_type_id = g_type_register_static_simple (GST_TYPE_MINI_OBJECT,
 654         g_intern_static_string ("GstVideoOverlayRectangle"),
 655         sizeof (GstVideoOverlayRectangleClass),
 656         (GClassInitFunc) gst_video_overlay_rectangle_class_init,
 657         sizeof (GstVideoOverlayRectangle),
 658         (GInstanceInitFunc) gst_video_overlay_rectangle_instance_init,
 659         (GTypeFlags) 0);
 660
 661     g_once_init_leave (&type_id, new_type_id);
 662   }
 663
 664   return type_id;
 665 }
 666
 667 static void
 668 gst_video_overlay_rectangle_finalize (GstMiniObject * mini_obj)
 669 {
 670   GstVideoOverlayRectangle *rect = (GstVideoOverlayRectangle *) mini_obj;
 671
 672   gst_buffer_replace (&rect->pixels, NULL);
 673
 674   while (rect->scaled_rectangles != NULL) {
 675     GstVideoOverlayRectangle *scaled_rect = rect->scaled_rectangles->data;
 676
 677     gst_video_overlay_rectangle_unref (scaled_rect);
 678
 679     rect->scaled_rectangles =
 680         g_list_delete_link (rect->scaled_rectangles, rect->scaled_rectangles);
 681   }
 682 #if !GLIB_CHECK_VERSION (2, 31, 0)
 683   g_static_mutex_free (&rect->lock);
 684 #else
 685   g_mutex_clear (&rect->lock);
 686 #endif
 687   /* not chaining up to GstMiniObject's finalize for now, we know it's empty */
 688 }
 689
 690 static void
 691 gst_video_overlay_rectangle_class_init (GstMiniObjectClass * klass)
 692 {
 693   klass->finalize = gst_video_overlay_rectangle_finalize;
 694   klass->copy = (GstMiniObjectCopyFunction) gst_video_overlay_rectangle_copy;
 695 }
 696
 697 static void
 698 gst_video_overlay_rectangle_instance_init (GstMiniObject * mini_obj)
 699 {
 700   GstVideoOverlayRectangle *rect = (GstVideoOverlayRectangle *) mini_obj;
 701
 702 #if !GLIB_CHECK_VERSION (2, 31, 0)
 703   g_static_mutex_init (&rect->lock);
 704 #else
 705   g_mutex_init (&rect->lock);
 706 #endif
 707 }
 708
 709 /**
 710  * gst_video_overlay_rectangle_new_argb:
 711  * @pixels: (transfer none): a #GstBuffer pointing to the pixel memory
 712  * @width: the width of the rectangle in @pixels
 713  * @height: the height of the rectangle in @pixels
 714  * @stride: the stride of the rectangle in @pixels in bytes (&gt;= 4*width)
 715  * @x: the X co-ordinate on the video where the top-left corner of this
 716  *     overlay rectangle should be rendered to
 717  * @y: the Y co-ordinate on the video where the top-left corner of this
 718  *     overlay rectangle should be rendered to
 719  * @render_width: the render width of this rectangle on the video
 720  * @render_height: the render height of this rectangle on the video
 721  * @flags: flags (currently unused)
 722  *
 723  * Creates a new video overlay rectangle with ARGB pixel data. The layout
 724  * of the components in memory is B-G-R-A on little-endian platforms
 725  * (corresponding to #GST_VIDEO_FORMAT_BGRA) and A-R-G-B on big-endian
 726  * platforms (corresponding to #GST_VIDEO_FORMAT_ARGB). In other words,
 727  * pixels are treated as 32-bit words and the lowest 8 bits then contain
 728  * the blue component value and the highest 8 bits contain the alpha
 729  * component value. The RGB values are non-premultiplied. This is the
 730  * format that is used by most hardware, and also many rendering libraries
 731  * such as Cairo, for example.
 732  *
 733  * Returns: (transfer full): a new #GstVideoOverlayRectangle. Unref with
 734  *     gst_video_overlay_rectangle_unref() when no longer needed.
 735  *
 736  * Since: 0.10.36
 737  */
 738 GstVideoOverlayRectangle *
 739 gst_video_overlay_rectangle_new_argb (GstBuffer * pixels,
 740     guint width, guint height, guint stride, gint render_x, gint render_y,
 741     guint render_width, guint render_height, GstVideoOverlayFormatFlags flags)
 742 {
 743   GstVideoOverlayRectangle *rect;
 744
 745   g_return_val_if_fail (GST_IS_BUFFER (pixels), NULL);
 746   /* technically ((height-1)*stride)+width might be okay too */
 747   g_return_val_if_fail (GST_BUFFER_SIZE (pixels) >= height * stride, NULL);
 748   g_return_val_if_fail (stride >= (4 * width), NULL);
 749   g_return_val_if_fail (height > 0 && width > 0, NULL);
 750   g_return_val_if_fail (render_height > 0 && render_width > 0, NULL);
 751   g_return_val_if_fail (flags == 0, NULL);
 752
 753   rect = (GstVideoOverlayRectangle *)
 754       gst_mini_object_new (GST_TYPE_VIDEO_OVERLAY_RECTANGLE);
 755
 756 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 757   rect->format = GST_VIDEO_FORMAT_BGRA;
 758 #else
 759   rect->format = GST_VIDEO_FORMAT_ARGB;
 760 #endif
 761   rect->pixels = gst_buffer_ref (pixels);
 762
 763   rect->width = width;
 764   rect->height = height;
 765   rect->stride = stride;
 766
 767   rect->x = render_x;
 768   rect->y = render_y;
 769   rect->render_width = render_width;
 770   rect->render_height = render_height;
 771
 772   rect->seq_num = gst_video_overlay_get_seqnum ();
 773
 774   GST_LOG ("new rectangle %p: %ux%u => %ux%u @ %u,%u, seq_num %u, format %u, "
 775       "pixels %p", rect, width, height, render_width, render_height, render_x,
 776       render_y, rect->seq_num, rect->format, pixels);
 777
 778   return rect;
 779 }
 780
 781 /**
 782  * gst_video_overlay_rectangle_get_render_rectangle:
 783  * @rectangle: a #GstVideoOverlayRectangle
 784  * @render_x: (out) (allow-none): address where to store the X render offset
 785  * @render_y: (out) (allow-none): address where to store the Y render offset
 786  * @render_width: (out) (allow-none): address where to store the render width
 787  * @render_height: (out) (allow-none): address where to store the render height
 788  *
 789  * Retrieves the render position and render dimension of the overlay
 790  * rectangle on the video.
 791  *
 792  * Returns: TRUE if valid render dimensions were retrieved.
 793  *
 794  * Since: 0.10.36
 795  */
 796 gboolean
 797 gst_video_overlay_rectangle_get_render_rectangle (GstVideoOverlayRectangle *
 798     rectangle, gint * render_x, gint * render_y, guint * render_width,
 799     guint * render_height)
 800 {
 801   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), FALSE);
 802
 803   if (render_x)
 804     *render_x = rectangle->x;
 805   if (render_y)
 806     *render_y = rectangle->y;
 807   if (render_width)
 808     *render_width = rectangle->render_width;
 809   if (render_height)
 810     *render_height = rectangle->render_height;
 811
 812   return TRUE;
 813 }
 814
 815 /**
 816  * gst_video_overlay_rectangle_set_render_rectangle:
 817  * @rectangle: a #GstVideoOverlayRectangle
 818  * @render_x: render X position of rectangle on video
 819  * @render_y: render Y position of rectangle on video
 820  * @render_width: render width of rectangle
 821  * @render_height: render height of rectangle
 822  *
 823  * Sets the render position and dimensions of the rectangle on the video.
 824  * This function is mainly for elements that modify the size of the video
 825  * in some way (e.g. through scaling or cropping) and need to adjust the
 826  * details of any overlays to match the operation that changed the size.
 827  *
 828  * @rectangle must be writable, meaning its refcount must be 1. You can
 829  * make the rectangles inside a #GstVideoOverlayComposition writable using
 830  * gst_video_overlay_composition_make_writable() or
 831  * gst_video_overlay_composition_copy().
 832  *
 833  * Since: 0.10.36
 834  */
 835 void
 836 gst_video_overlay_rectangle_set_render_rectangle (GstVideoOverlayRectangle *
 837     rectangle, gint render_x, gint render_y, guint render_width,
 838     guint render_height)
 839 {
 840   g_return_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle));
 841   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (rectangle) == 1);
 842
 843   rectangle->x = render_x;
 844   rectangle->y = render_y;
 845   rectangle->render_width = render_width;
 846   rectangle->render_height = render_height;
 847 }
 848
 849 /**
 850  * gst_video_overlay_rectangle_get_pixels_argb:
 851  * @rectangle: a #GstVideoOverlayRectangle
 852  * @stride: (out) (allow-none): address of guint variable where to store the
 853  *    row stride of the ARGB pixel data in the buffer
 854  * @flags: flags (unused)
 855  *
 856  * Returns: (transfer none): a #GstBuffer holding the ARGB pixel data with
 857  *    row stride @stride and width and height of the render dimensions as per
 858  *    gst_video_overlay_rectangle_get_render_rectangle(). This function does
 859  *    not return a reference, the caller should obtain a reference of her own
 860  *    with gst_buffer_ref() if needed.
 861  *
 862  * Since: 0.10.36
 863  */
 864 GstBuffer *
 865 gst_video_overlay_rectangle_get_pixels_argb (GstVideoOverlayRectangle *
 866     rectangle, guint * stride, GstVideoOverlayFormatFlags flags)
 867 {
 868   GstVideoOverlayRectangle *scaled_rect = NULL;
 869   GstBlendVideoFormatInfo info;
 870   GstBuffer *buf;
 871   GList *l;
 872
 873   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
 874   g_return_val_if_fail (flags == 0, NULL);
 875   g_return_val_if_fail (stride != NULL, NULL);
 876
 877   /* This assumes we don't need to adjust the format */
 878   if (rectangle->render_width == rectangle->width &&
 879       rectangle->render_height == rectangle->height) {
 880     *stride = rectangle->stride;
 881     return rectangle->pixels;
 882   }
 883
 884   /* see if we've got one cached already */
 885   GST_RECTANGLE_LOCK (rectangle);
 886   for (l = rectangle->scaled_rectangles; l != NULL; l = l->next) {
 887     GstVideoOverlayRectangle *r = l->data;
 888
 889     if (r->width == rectangle->render_width &&
 890         r->height == rectangle->render_height) {
 891       /* we'll keep these rectangles around until finalize, so it's ok not
 892        * to take our own ref here */
 893       scaled_rect = r;
 894       break;
 895     }
 896   }
 897   GST_RECTANGLE_UNLOCK (rectangle);
 898
 899   if (scaled_rect != NULL)
 900     goto done;
 901
 902   /* not cached yet, do the scaling and put the result into our cache */
 903   video_blend_format_info_init (&info, GST_BUFFER_DATA (rectangle->pixels),
 904       rectangle->height, rectangle->width, rectangle->format);
 905
 906   video_blend_scale_linear_RGBA (&info, rectangle->render_height,
 907       rectangle->render_width);
 908
 909   buf = gst_buffer_new ();
 910   GST_BUFFER_DATA (buf) = info.pixels;
 911   GST_BUFFER_MALLOCDATA (buf) = info.pixels;
 912   GST_BUFFER_SIZE (buf) = info.size;
 913
 914   scaled_rect = gst_video_overlay_rectangle_new_argb (buf,
 915       rectangle->render_width, rectangle->render_height, info.stride[0],
 916       0, 0, rectangle->render_width, rectangle->render_height, 0);
 917
 918   gst_buffer_unref (buf);
 919
 920   GST_RECTANGLE_LOCK (rectangle);
 921   rectangle->scaled_rectangles =
 922       g_list_prepend (rectangle->scaled_rectangles, scaled_rect);
 923   GST_RECTANGLE_UNLOCK (rectangle);
 924
 925 done:
 926
 927   *stride = scaled_rect->stride;
 928   return scaled_rect->pixels;
 929 }
 930
 931 /**
 932  * gst_video_overlay_rectangle_get_pixels_unscaled_argb:
 933  * @rectangle: a #GstVideoOverlayRectangle
 934  * @width: (out): address where to store the width of the unscaled
 935  *    rectangle in pixels
 936  * @width: (out): address where to store the height of the unscaled
 937  *    rectangle in pixels
 938  * @stride: (out): address of guint variable where to store the row
 939  *    stride of the ARGB pixel data in the buffer
 940  * @flags: flags for future use (unused)
 941  *
 942  * Retrieves the pixel data as it is. This is useful if the caller can
 943  * do the scaling itself when handling the overlaying. The rectangle will
 944  * need to be scaled to the render dimensions, which can be retrieved using
 945  * gst_video_overlay_rectangle_get_render_rectangle().
 946  *
 947  * Returns: (transfer none): a #GstBuffer holding the ARGB pixel data with
 948  *    row stride @stride. This function does not return a reference, the caller
 949  *    should obtain a reference of her own with gst_buffer_ref() if needed.
 950  *
 951  * Since: 0.10.36
 952  */
 953 GstBuffer *
 954 gst_video_overlay_rectangle_get_pixels_unscaled_argb (GstVideoOverlayRectangle *
 955     rectangle, guint * width, guint * height, guint * stride,
 956     GstVideoOverlayFormatFlags flags)
 957 {
 958   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
 959   g_return_val_if_fail (width != NULL, NULL);
 960   g_return_val_if_fail (height != NULL, NULL);
 961   g_return_val_if_fail (stride != NULL, NULL);
 962   g_return_val_if_fail (flags == 0, NULL);
 963
 964   *width = rectangle->width;
 965   *height = rectangle->height;
 966   *stride = rectangle->stride;
 967
 968   return rectangle->pixels;
 969 }
 970
 971 /**
 972  * gst_video_overlay_rectangle_copy:
 973  * @rectangle: (transfer none): a #GstVideoOverlayRectangle to copy
 974  *
 975  * Makes a copy of @rectangle, so that it is possible to modify it
 976  * (e.g. to change the render co-ordinates or render dimension). The
 977  * actual overlay pixel data buffers contained in the rectangle are not
 978  * copied.
 979  *
 980  * Returns: (transfer full): a new #GstVideoOverlayRectangle equivalent
 981  *     to @rectangle.
 982  *
 983  * Since: 0.10.36
 984  */
 985 GstVideoOverlayRectangle *
 986 gst_video_overlay_rectangle_copy (GstVideoOverlayRectangle * rectangle)
 987 {
 988   GstVideoOverlayRectangle *copy;
 989
 990   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
 991
 992   copy = gst_video_overlay_rectangle_new_argb (rectangle->pixels,
 993       rectangle->width, rectangle->height, rectangle->stride,
 994       rectangle->x, rectangle->y,
 995       rectangle->render_width, rectangle->render_height, 0);
 996
 997   return copy;
 998 }
 999
1000 /**
1001  * gst_video_overlay_rectangle_get_seqnum:
1002  * @rectangle: a #GstVideoOverlayRectangle
1003  *
1004  * Returns the sequence number of this rectangle. Sequence numbers are
1005  * monotonically increasing and unique for overlay compositions and rectangles
1006  * (meaning there will never be a rectangle with the same sequence number as
1007  * a composition).
1008  *
1009  * Returns: the sequence number of @rectangle
1010  *
1011  * Since: 0.10.36
1012  */
1013 guint
1014 gst_video_overlay_rectangle_get_seqnum (GstVideoOverlayRectangle * rectangle)
1015 {
1016   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), 0);
1017
1018   return rectangle->seq_num;
1019 }