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 #include <string.h>
  73
  74 struct _GstVideoOverlayComposition
  75 {
  76   GstMiniObject parent;
  77
  78   guint num_rectangles;
  79   GstVideoOverlayRectangle **rectangles;
  80
  81   /* lowest rectangle sequence number still used by the upstream
  82    * overlay element. This way a renderer maintaining some kind of
  83    * rectangles <-> surface cache can know when to free cached
  84    * surfaces/rectangles. */
  85   guint min_seq_num_used;
  86
  87   /* sequence number for the composition (same series as rectangles) */
  88   guint seq_num;
  89 };
  90
  91 struct _GstVideoOverlayCompositionClass
  92 {
  93   GstMiniObjectClass parent_class;
  94 };
  95
  96 struct _GstVideoOverlayRectangle
  97 {
  98   GstMiniObject parent;
  99
 100   /* Position on video frame and dimension of output rectangle in
 101    * output frame terms (already adjusted for the PAR of the output
 102    * frame). x/y can be negative (overlay will be clipped then) */
 103   gint x, y;
 104   guint render_width, render_height;
 105
 106   /* Dimensions of overlay pixels */
 107   guint width, height, stride;
 108
 109   /* The format of the data in pixels */
 110   GstVideoFormat format;
 111
 112   /* The flags associated to this rectangle */
 113   GstVideoOverlayFormatFlags flags;
 114
 115   /* Refcounted blob of memory, no caps or timestamps */
 116   GstBuffer *pixels;
 117
 118   /* FIXME: how to express source like text or pango markup?
 119    *        (just add source type enum + source buffer with data)
 120    *
 121    * FOR 0.10: always send pixel blobs, but attach source data in
 122    * addition (reason: if downstream changes, we can't renegotiate
 123    * that properly, if we just do a query of supported formats from
 124    * the start). Sink will just ignore pixels and use pango markup
 125    * from source data if it supports that.
 126    *
 127    * FOR 0.11: overlay should query formats (pango markup, pixels)
 128    * supported by downstream and then only send that. We can
 129    * renegotiate via the reconfigure event.
 130    */
 131
 132   /* sequence number: useful for backends/renderers/sinks that want
 133    * to maintain a cache of rectangles <-> surfaces. The value of
 134    * the min_seq_num_used in the composition tells the renderer which
 135    * rectangles have expired. */
 136   guint seq_num;
 137
 138   /* global alpha: global alpha value of the rectangle. Each each per-pixel
 139    * alpha value of image-data will be multiplied with the global alpha value
 140    * during blending.
 141    * Can be used for efficient fading in/out of overlay rectangles.
 142    * GstElements that render OverlayCompositions and don't support global alpha
 143    * should simply ignore it.*/
 144   gfloat global_alpha;
 145
 146   /* track alpha-values already applied: */
 147   gfloat applied_global_alpha;
 148   /* store initial per-pixel alpha values: */
 149   guint8 *initial_alpha;
 150
 151   /* FIXME: we may also need a (private) way to cache converted/scaled
 152    * pixel blobs */
 153   GMutex lock;
 154
 155   GList *scaled_rectangles;
 156 };
 157
 158 struct _GstVideoOverlayRectangleClass
 159 {
 160   GstMiniObjectClass parent_class;
 161 };
 162
 163 #define GST_RECTANGLE_LOCK(rect)   g_mutex_lock(&rect->lock)
 164 #define GST_RECTANGLE_UNLOCK(rect) g_mutex_unlock(&rect->lock)
 165
 166 static void gst_video_overlay_composition_class_init (GstMiniObjectClass * k);
 167 static void gst_video_overlay_composition_finalize (GstMiniObject * comp);
 168 static void gst_video_overlay_rectangle_class_init (GstMiniObjectClass * klass);
 169 static void gst_video_overlay_rectangle_finalize (GstMiniObject * rect);
 170
 171 /* --------------------------- utility functions --------------------------- */
 172
 173 #ifndef GST_DISABLE_GST_DEBUG
 174
 175 #define GST_CAT_DEFAULT ensure_debug_category()
 176
 177 static GstDebugCategory *
 178 ensure_debug_category (void)
 179 {
 180   static gsize cat_gonce = 0;
 181
 182   if (g_once_init_enter (&cat_gonce)) {
 183     gsize cat_done;
 184
 185     cat_done = (gsize) _gst_debug_category_new ("video-composition", 0,
 186         "video overlay composition");
 187
 188     g_once_init_leave (&cat_gonce, cat_done);
 189   }
 190
 191   return (GstDebugCategory *) cat_gonce;
 192 }
 193
 194 #else
 195
 196 #define ensure_debug_category() /* NOOP */
 197
 198 #endif /* GST_DISABLE_GST_DEBUG */
 199
 200 static guint
 201 gst_video_overlay_get_seqnum (void)
 202 {
 203   static gint seqnum;           /* 0 */
 204
 205   return (guint) g_atomic_int_add (&seqnum, 1);
 206 }
 207
 208 #define GST_OVERLAY_COMPOSITION_QUARK gst_overlay_composition_quark_get()
 209 static GQuark
 210 gst_overlay_composition_quark_get (void)
 211 {
 212   static gsize quark_gonce = 0;
 213
 214   if (g_once_init_enter (&quark_gonce)) {
 215     gsize quark;
 216
 217     quark = (gsize) g_quark_from_static_string ("GstVideoOverlayComposition");
 218
 219     g_once_init_leave (&quark_gonce, quark);
 220   }
 221
 222   return (GQuark) quark_gonce;
 223 }
 224
 225 #define COMPOSITION_QUARK composition_quark_get()
 226 static GQuark
 227 composition_quark_get (void)
 228 {
 229   static gsize quark_gonce = 0;
 230
 231   if (g_once_init_enter (&quark_gonce)) {
 232     gsize quark;
 233
 234     quark = (gsize) g_quark_from_static_string ("composition");
 235
 236     g_once_init_leave (&quark_gonce, quark);
 237   }
 238
 239   return (GQuark) quark_gonce;
 240 }
 241
 242 /**
 243  * gst_video_buffer_set_overlay_composition:
 244  * @buf: a #GstBuffer
 245  * @comp: (allow-none): a #GstVideoOverlayComposition, or NULL to clear a
 246  *     previously-set composition
 247  *
 248  * Sets an overlay composition on a buffer. The buffer will obtain its own
 249  * reference to the composition, meaning this function does not take ownership
 250  * of @comp.
 251  *
 252  * Since: 0.10.36
 253  */
 254 void
 255 gst_video_buffer_set_overlay_composition (GstBuffer * buf,
 256     GstVideoOverlayComposition * comp)
 257 {
 258   gst_buffer_set_qdata (buf, GST_OVERLAY_COMPOSITION_QUARK,
 259       gst_structure_id_new (GST_OVERLAY_COMPOSITION_QUARK,
 260           COMPOSITION_QUARK, GST_TYPE_VIDEO_OVERLAY_COMPOSITION, comp, NULL));
 261 }
 262
 263 /**
 264  * gst_video_buffer_get_overlay_composition:
 265  * @buf: a #GstBuffer
 266  *
 267  * Get the overlay composition that has previously been attached to a buffer
 268  * with gst_video_buffer_get_overlay_composition(), usually by another element
 269  * upstream.
 270  *
 271  * Returns: (transfer none): the #GstVideoOverlayComposition attached to
 272  *    this buffer, or NULL. Does not return a reference to the composition,
 273  *    caller must obtain her own ref via gst_video_overlay_composition_ref()
 274  *    if needed.
 275  *
 276  * Since: 0.10.36
 277  */
 278 GstVideoOverlayComposition *
 279 gst_video_buffer_get_overlay_composition (GstBuffer * buf)
 280 {
 281   const GstStructure *s;
 282   const GValue *val;
 283
 284   s = gst_buffer_get_qdata (buf, GST_OVERLAY_COMPOSITION_QUARK);
 285   if (s == NULL)
 286     return NULL;
 287
 288   val = gst_structure_id_get_value (s, COMPOSITION_QUARK);
 289   if (val == NULL)
 290     return NULL;
 291
 292   return GST_VIDEO_OVERLAY_COMPOSITION (gst_value_get_mini_object (val));
 293 }
 294
 295 /* ------------------------------ composition ------------------------------ */
 296
 297 #define RECTANGLE_ARRAY_STEP 4  /* premature optimization */
 298
 299 GType
 300 gst_video_overlay_composition_get_type (void)
 301 {
 302   static volatile gsize type_id = 0;
 303
 304   if (g_once_init_enter (&type_id)) {
 305     GType new_type_id = g_type_register_static_simple (GST_TYPE_MINI_OBJECT,
 306         g_intern_static_string ("GstVideoOverlayComposition"),
 307         sizeof (GstVideoOverlayCompositionClass),
 308         (GClassInitFunc) gst_video_overlay_composition_class_init,
 309         sizeof (GstVideoOverlayComposition),
 310         NULL,
 311         (GTypeFlags) 0);
 312
 313     g_once_init_leave (&type_id, new_type_id);
 314   }
 315
 316   return type_id;
 317 }
 318
 319 static void
 320 gst_video_overlay_composition_finalize (GstMiniObject * mini_obj)
 321 {
 322   GstVideoOverlayComposition *comp = (GstVideoOverlayComposition *) mini_obj;
 323   guint num;
 324
 325   num = comp->num_rectangles;
 326
 327   while (num > 0) {
 328     gst_video_overlay_rectangle_unref (comp->rectangles[num - 1]);
 329     --num;
 330   }
 331
 332   g_free (comp->rectangles);
 333   comp->rectangles = NULL;
 334   comp->num_rectangles = 0;
 335
 336   /* not chaining up to GstMiniObject's finalize for now, we know it's empty */
 337 }
 338
 339 static void
 340 gst_video_overlay_composition_class_init (GstMiniObjectClass * klass)
 341 {
 342   klass->finalize = gst_video_overlay_composition_finalize;
 343   klass->copy = (GstMiniObjectCopyFunction) gst_video_overlay_composition_copy;
 344 }
 345
 346 /**
 347  * gst_video_overlay_composition_new:
 348  * @rectangle: (transfer none): a #GstVideoOverlayRectangle to add to the
 349  *     composition
 350  *
 351  * Creates a new video overlay composition object to hold one or more
 352  * overlay rectangles.
 353  *
 354  * Returns: (transfer full): a new #GstVideoOverlayComposition. Unref with
 355  *     gst_video_overlay_composition_unref() when no longer needed.
 356  *
 357  * Since: 0.10.36
 358  */
 359 GstVideoOverlayComposition *
 360 gst_video_overlay_composition_new (GstVideoOverlayRectangle * rectangle)
 361 {
 362   GstVideoOverlayComposition *comp;
 363
 364
 365   /* FIXME: should we allow empty compositions? Could also be expressed as
 366    * buffer without a composition on it. Maybe there are cases where doing
 367    * an empty new + _add() in a loop is easier? */
 368   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
 369
 370   comp = (GstVideoOverlayComposition *)
 371       gst_mini_object_new (GST_TYPE_VIDEO_OVERLAY_COMPOSITION);
 372
 373   comp->rectangles = g_new0 (GstVideoOverlayRectangle *, RECTANGLE_ARRAY_STEP);
 374   comp->rectangles[0] = gst_video_overlay_rectangle_ref (rectangle);
 375   comp->num_rectangles = 1;
 376
 377   comp->seq_num = gst_video_overlay_get_seqnum ();
 378
 379   /* since the rectangle was created earlier, its seqnum is smaller than ours */
 380   comp->min_seq_num_used = rectangle->seq_num;
 381
 382   GST_LOG ("new composition %p: seq_num %u with rectangle %p", comp,
 383       comp->seq_num, rectangle);
 384
 385   return comp;
 386 }
 387
 388 /**
 389  * gst_video_overlay_composition_add_rectangle:
 390  * @comp: a #GstVideoOverlayComposition
 391  * @rectangle: (transfer none): a #GstVideoOverlayRectangle to add to the
 392  *     composition
 393  *
 394  * Adds an overlay rectangle to an existing overlay composition object. This
 395  * must be done right after creating the overlay composition.
 396  *
 397  * Since: 0.10.36
 398  */
 399 void
 400 gst_video_overlay_composition_add_rectangle (GstVideoOverlayComposition * comp,
 401     GstVideoOverlayRectangle * rectangle)
 402 {
 403   g_return_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp));
 404   g_return_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle));
 405   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (comp) == 1);
 406
 407   if (comp->num_rectangles % RECTANGLE_ARRAY_STEP == 0) {
 408     comp->rectangles =
 409         g_renew (GstVideoOverlayRectangle *, comp->rectangles,
 410         comp->num_rectangles + RECTANGLE_ARRAY_STEP);
 411   }
 412
 413   comp->rectangles[comp->num_rectangles] =
 414       gst_video_overlay_rectangle_ref (rectangle);
 415   comp->num_rectangles += 1;
 416
 417   comp->min_seq_num_used = MIN (comp->min_seq_num_used, rectangle->seq_num);
 418
 419   GST_LOG ("composition %p: added rectangle %p", comp, rectangle);
 420 }
 421
 422 /**
 423  * gst_video_overlay_composition_n_rectangles:
 424  * @comp: a #GstVideoOverlayComposition
 425  *
 426  * Returns the number of #GstVideoOverlayRectangle<!-- -->s contained in @comp.
 427  *
 428  * Returns: the number of rectangles
 429  *
 430  * Since: 0.10.36
 431  */
 432 guint
 433 gst_video_overlay_composition_n_rectangles (GstVideoOverlayComposition * comp)
 434 {
 435   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), 0);
 436
 437   return comp->num_rectangles;
 438 }
 439
 440 /**
 441  * gst_video_overlay_composition_get_rectangle:
 442  * @comp: a #GstVideoOverlayComposition
 443  * @n: number of the rectangle to get
 444  *
 445  * Returns the @n-th #GstVideoOverlayRectangle contained in @comp.
 446  *
 447  * Returns: (transfer none): the @n-th rectangle, or NULL if @n is out of
 448  *     bounds. Will not return a new reference, the caller will need to
 449  *     obtain her own reference using gst_video_overlay_rectangle_ref()
 450  *     if needed.
 451  *
 452  * Since: 0.10.36
 453  */
 454 GstVideoOverlayRectangle *
 455 gst_video_overlay_composition_get_rectangle (GstVideoOverlayComposition * comp,
 456     guint n)
 457 {
 458   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), NULL);
 459
 460   if (n >= comp->num_rectangles)
 461     return NULL;
 462
 463   return comp->rectangles[n];
 464 }
 465
 466 static gboolean
 467 gst_video_overlay_rectangle_needs_scaling (GstVideoOverlayRectangle * r)
 468 {
 469   return (r->width != r->render_width || r->height != r->render_height);
 470 }
 471
 472 /**
 473  * gst_video_overlay_composition_blend:
 474  * @comp: a #GstVideoOverlayComposition
 475  * @video_buf: a #GstBuffer containing raw video data in a supported format
 476  *
 477  * Blends the overlay rectangles in @comp on top of the raw video data
 478  * contained in @video_buf. The data in @video_buf must be writable. If
 479  * needed, use gst_buffer_make_writable() before calling this function to
 480  * ensure a buffer is writable. @video_buf must also have valid raw video
 481  * caps set on it.
 482  *
 483  * Since: 0.10.36
 484  */
 485 gboolean
 486 gst_video_overlay_composition_blend (GstVideoOverlayComposition * comp,
 487     GstBuffer * video_buf)
 488 {
 489   GstBlendVideoFormatInfo video_info, rectangle_info;
 490   GstVideoFormat fmt;
 491   gboolean ret = TRUE;
 492   guint n, num;
 493   int w, h;
 494
 495   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), FALSE);
 496   g_return_val_if_fail (GST_IS_BUFFER (video_buf), FALSE);
 497   g_return_val_if_fail (gst_buffer_is_writable (video_buf), FALSE);
 498   g_return_val_if_fail (GST_BUFFER_CAPS (video_buf) != NULL, FALSE);
 499
 500   if (!gst_video_format_parse_caps (GST_BUFFER_CAPS (video_buf), &fmt, &w, &h)) {
 501     gchar *str = gst_caps_to_string (GST_BUFFER_CAPS (video_buf));
 502     g_warning ("%s: could not parse video buffer caps '%s'", GST_FUNCTION, str);
 503     g_free (str);
 504     return FALSE;
 505   }
 506
 507   video_blend_format_info_init (&video_info, GST_BUFFER_DATA (video_buf),
 508       h, w, fmt, FALSE);
 509
 510   num = comp->num_rectangles;
 511   GST_LOG ("Blending composition %p with %u rectangles onto video buffer %p "
 512       "(%ux%u, format %u)", comp, num, video_buf, w, h, fmt);
 513
 514   for (n = 0; n < num; ++n) {
 515     GstVideoOverlayRectangle *rect;
 516     gboolean needs_scaling;
 517
 518     rect = comp->rectangles[n];
 519
 520     GST_LOG (" rectangle %u %p: %ux%u, format %u", n, rect, rect->height,
 521         rect->width, rect->format);
 522
 523     video_blend_format_info_init (&rectangle_info,
 524         GST_BUFFER_DATA (rect->pixels), rect->height, rect->width,
 525         rect->format,
 526         ! !(rect->flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA));
 527
 528     needs_scaling = gst_video_overlay_rectangle_needs_scaling (rect);
 529     if (needs_scaling) {
 530       video_blend_scale_linear_RGBA (&rectangle_info, rect->render_height,
 531           rect->render_width);
 532     }
 533
 534     ret = video_blend (&video_info, &rectangle_info, rect->x, rect->y,
 535         rect->global_alpha);
 536     if (!ret) {
 537       GST_WARNING ("Could not blend overlay rectangle onto video buffer");
 538     }
 539
 540     /* FIXME: should cache scaled pixels in the rectangle struct */
 541     if (needs_scaling)
 542       g_free (rectangle_info.pixels);
 543   }
 544
 545   return ret;
 546 }
 547
 548 /**
 549  * gst_video_overlay_composition_copy:
 550  * @comp: (transfer none): a #GstVideoOverlayComposition to copy
 551  *
 552  * Makes a copy of @comp and all contained rectangles, so that it is possible
 553  * to modify the composition and contained rectangles (e.g. add additional
 554  * rectangles or change the render co-ordinates or render dimension). The
 555  * actual overlay pixel data buffers contained in the rectangles are not
 556  * copied.
 557  *
 558  * Returns: (transfer full): a new #GstVideoOverlayComposition equivalent
 559  *     to @comp.
 560  *
 561  * Since: 0.10.36
 562  */
 563 GstVideoOverlayComposition *
 564 gst_video_overlay_composition_copy (GstVideoOverlayComposition * comp)
 565 {
 566   GstVideoOverlayComposition *copy;
 567   GstVideoOverlayRectangle *rect;
 568   guint n;
 569
 570   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), NULL);
 571
 572   if (G_LIKELY (comp->num_rectangles == 0))
 573     return gst_video_overlay_composition_new (NULL);
 574
 575   rect = gst_video_overlay_rectangle_copy (comp->rectangles[0]);
 576   copy = gst_video_overlay_composition_new (rect);
 577   gst_video_overlay_rectangle_unref (rect);
 578
 579   for (n = 1; n < comp->num_rectangles; ++n) {
 580     rect = gst_video_overlay_rectangle_copy (comp->rectangles[n]);
 581     gst_video_overlay_composition_add_rectangle (copy, rect);
 582     gst_video_overlay_rectangle_unref (rect);
 583   }
 584
 585   return copy;
 586 }
 587
 588 /**
 589  * gst_video_overlay_composition_make_writable:
 590  * @comp: (transfer full): a #GstVideoOverlayComposition to copy
 591  *
 592  * Takes ownership of @comp and returns a version of @comp that is writable
 593  * (i.e. can be modified). Will either return @comp right away, or create a
 594  * new writable copy of @comp and unref @comp itself. All the contained
 595  * rectangles will also be copied, but the actual overlay pixel data buffers
 596  * contained in the rectangles are not copied.
 597  *
 598  * Returns: (transfer full): a writable #GstVideoOverlayComposition
 599  *     equivalent to @comp.
 600  *
 601  * Since: 0.10.36
 602  */
 603 GstVideoOverlayComposition *
 604 gst_video_overlay_composition_make_writable (GstVideoOverlayComposition * comp)
 605 {
 606   GstVideoOverlayComposition *writable_comp;
 607
 608   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), NULL);
 609
 610   if (GST_MINI_OBJECT_REFCOUNT_VALUE (comp) == 1) {
 611     guint n;
 612
 613     for (n = 0; n < comp->num_rectangles; ++n) {
 614       if (GST_MINI_OBJECT_REFCOUNT_VALUE (comp->rectangles[n]) != 1)
 615         goto copy;
 616     }
 617     return comp;
 618   }
 619
 620 copy:
 621
 622   writable_comp = gst_video_overlay_composition_copy (comp);
 623   gst_video_overlay_composition_unref (comp);
 624
 625   return writable_comp;
 626 }
 627
 628 /**
 629  * gst_video_overlay_composition_get_seqnum:
 630  * @comp: a #GstVideoOverlayComposition
 631  *
 632  * Returns the sequence number of this composition. Sequence numbers are
 633  * monotonically increasing and unique for overlay compositions and rectangles
 634  * (meaning there will never be a rectangle with the same sequence number as
 635  * a composition).
 636  *
 637  * Returns: the sequence number of @comp
 638  *
 639  * Since: 0.10.36
 640  */
 641 guint
 642 gst_video_overlay_composition_get_seqnum (GstVideoOverlayComposition * comp)
 643 {
 644   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_COMPOSITION (comp), 0);
 645
 646   return comp->seq_num;
 647 }
 648
 649 /* ------------------------------ rectangles ------------------------------ -*/
 650
 651 static void gst_video_overlay_rectangle_instance_init (GstMiniObject * miniobj);
 652
 653 GType
 654 gst_video_overlay_rectangle_get_type (void)
 655 {
 656   static volatile gsize type_id = 0;
 657
 658   if (g_once_init_enter (&type_id)) {
 659     GType new_type_id = g_type_register_static_simple (GST_TYPE_MINI_OBJECT,
 660         g_intern_static_string ("GstVideoOverlayRectangle"),
 661         sizeof (GstVideoOverlayRectangleClass),
 662         (GClassInitFunc) gst_video_overlay_rectangle_class_init,
 663         sizeof (GstVideoOverlayRectangle),
 664         (GInstanceInitFunc) gst_video_overlay_rectangle_instance_init,
 665         (GTypeFlags) 0);
 666
 667     g_once_init_leave (&type_id, new_type_id);
 668   }
 669
 670   return type_id;
 671 }
 672
 673 static void
 674 gst_video_overlay_rectangle_finalize (GstMiniObject * mini_obj)
 675 {
 676   GstVideoOverlayRectangle *rect = (GstVideoOverlayRectangle *) mini_obj;
 677
 678   gst_buffer_replace (&rect->pixels, NULL);
 679
 680   while (rect->scaled_rectangles != NULL) {
 681     GstVideoOverlayRectangle *scaled_rect = rect->scaled_rectangles->data;
 682
 683     gst_video_overlay_rectangle_unref (scaled_rect);
 684
 685     rect->scaled_rectangles =
 686         g_list_delete_link (rect->scaled_rectangles, rect->scaled_rectangles);
 687   }
 688
 689   g_free (rect->initial_alpha);
 690   g_mutex_clear (&rect->lock);
 691
 692   /* not chaining up to GstMiniObject's finalize for now, we know it's empty */
 693 }
 694
 695 static void
 696 gst_video_overlay_rectangle_class_init (GstMiniObjectClass * klass)
 697 {
 698   klass->finalize = gst_video_overlay_rectangle_finalize;
 699   klass->copy = (GstMiniObjectCopyFunction) gst_video_overlay_rectangle_copy;
 700 }
 701
 702 static void
 703 gst_video_overlay_rectangle_instance_init (GstMiniObject * mini_obj)
 704 {
 705   GstVideoOverlayRectangle *rect = (GstVideoOverlayRectangle *) mini_obj;
 706
 707   g_mutex_init (&rect->lock);
 708 }
 709
 710 static inline gboolean
 711 gst_video_overlay_rectangle_check_flags (GstVideoOverlayFormatFlags flags)
 712 {
 713   /* Check flags only contains flags we know about */
 714   return (flags & ~(GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA |
 715           GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA)) == 0;
 716 }
 717
 718 static gboolean
 719 gst_video_overlay_rectangle_is_same_alpha_type (GstVideoOverlayFormatFlags
 720     flags1, GstVideoOverlayFormatFlags flags2)
 721 {
 722   return ((flags1 ^ flags2) & GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA)
 723       == 0;
 724 }
 725
 726
 727 /**
 728  * gst_video_overlay_rectangle_new_argb:
 729  * @pixels: (transfer none): a #GstBuffer pointing to the pixel memory
 730  * @width: the width of the rectangle in @pixels
 731  * @height: the height of the rectangle in @pixels
 732  * @stride: the stride of the rectangle in @pixels in bytes (&gt;= 4*width)
 733  * @render_x: the X co-ordinate on the video where the top-left corner of this
 734  *     overlay rectangle should be rendered to
 735  * @render_y: the Y co-ordinate on the video where the top-left corner of this
 736  *     overlay rectangle should be rendered to
 737  * @render_width: the render width of this rectangle on the video
 738  * @render_height: the render height of this rectangle on the video
 739  * @flags: flags
 740  *
 741  * Creates a new video overlay rectangle with ARGB pixel data. The layout
 742  * of the components in memory is B-G-R-A on little-endian platforms
 743  * (corresponding to #GST_VIDEO_FORMAT_BGRA) and A-R-G-B on big-endian
 744  * platforms (corresponding to #GST_VIDEO_FORMAT_ARGB). In other words,
 745  * pixels are treated as 32-bit words and the lowest 8 bits then contain
 746  * the blue component value and the highest 8 bits contain the alpha
 747  * component value. Unless specified in the flags, the RGB values are
 748  * non-premultiplied. This is the format that is used by most hardware,
 749  * and also many rendering libraries such as Cairo, for example.
 750  *
 751  * Returns: (transfer full): a new #GstVideoOverlayRectangle. Unref with
 752  *     gst_video_overlay_rectangle_unref() when no longer needed.
 753  *
 754  * Since: 0.10.36
 755  */
 756 GstVideoOverlayRectangle *
 757 gst_video_overlay_rectangle_new_argb (GstBuffer * pixels,
 758     guint width, guint height, guint stride, gint render_x, gint render_y,
 759     guint render_width, guint render_height, GstVideoOverlayFormatFlags flags)
 760 {
 761   GstVideoOverlayRectangle *rect;
 762
 763   g_return_val_if_fail (GST_IS_BUFFER (pixels), NULL);
 764   /* technically ((height-1)*stride)+width might be okay too */
 765   g_return_val_if_fail (GST_BUFFER_SIZE (pixels) >= height * stride, NULL);
 766   g_return_val_if_fail (stride >= (4 * width), NULL);
 767   g_return_val_if_fail (height > 0 && width > 0, NULL);
 768   g_return_val_if_fail (render_height > 0 && render_width > 0, NULL);
 769   g_return_val_if_fail (gst_video_overlay_rectangle_check_flags (flags), NULL);
 770
 771   rect = (GstVideoOverlayRectangle *)
 772       gst_mini_object_new (GST_TYPE_VIDEO_OVERLAY_RECTANGLE);
 773
 774 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 775   rect->format = GST_VIDEO_FORMAT_BGRA;
 776 #else
 777   rect->format = GST_VIDEO_FORMAT_ARGB;
 778 #endif
 779
 780   rect->pixels = gst_buffer_ref (pixels);
 781
 782   rect->width = width;
 783   rect->height = height;
 784   rect->stride = stride;
 785
 786   rect->x = render_x;
 787   rect->y = render_y;
 788   rect->render_width = render_width;
 789   rect->render_height = render_height;
 790
 791   rect->global_alpha = 1.0;
 792   rect->applied_global_alpha = 1.0;
 793   rect->initial_alpha = NULL;
 794
 795   rect->flags = flags;
 796
 797   rect->seq_num = gst_video_overlay_get_seqnum ();
 798
 799   GST_LOG ("new rectangle %p: %ux%u => %ux%u @ %u,%u, seq_num %u, format %u, "
 800       "flags %x, pixels %p, global_alpha=%f", rect, width, height, render_width,
 801       render_height, render_x, render_y, rect->seq_num, rect->format,
 802       rect->flags, pixels, rect->global_alpha);
 803
 804   return rect;
 805 }
 806
 807 /**
 808  * gst_video_overlay_rectangle_get_render_rectangle:
 809  * @rectangle: a #GstVideoOverlayRectangle
 810  * @render_x: (out) (allow-none): address where to store the X render offset
 811  * @render_y: (out) (allow-none): address where to store the Y render offset
 812  * @render_width: (out) (allow-none): address where to store the render width
 813  * @render_height: (out) (allow-none): address where to store the render height
 814  *
 815  * Retrieves the render position and render dimension of the overlay
 816  * rectangle on the video.
 817  *
 818  * Returns: TRUE if valid render dimensions were retrieved.
 819  *
 820  * Since: 0.10.36
 821  */
 822 gboolean
 823 gst_video_overlay_rectangle_get_render_rectangle (GstVideoOverlayRectangle *
 824     rectangle, gint * render_x, gint * render_y, guint * render_width,
 825     guint * render_height)
 826 {
 827   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), FALSE);
 828
 829   if (render_x)
 830     *render_x = rectangle->x;
 831   if (render_y)
 832     *render_y = rectangle->y;
 833   if (render_width)
 834     *render_width = rectangle->render_width;
 835   if (render_height)
 836     *render_height = rectangle->render_height;
 837
 838   return TRUE;
 839 }
 840
 841 /**
 842  * gst_video_overlay_rectangle_set_render_rectangle:
 843  * @rectangle: a #GstVideoOverlayRectangle
 844  * @render_x: render X position of rectangle on video
 845  * @render_y: render Y position of rectangle on video
 846  * @render_width: render width of rectangle
 847  * @render_height: render height of rectangle
 848  *
 849  * Sets the render position and dimensions of the rectangle on the video.
 850  * This function is mainly for elements that modify the size of the video
 851  * in some way (e.g. through scaling or cropping) and need to adjust the
 852  * details of any overlays to match the operation that changed the size.
 853  *
 854  * @rectangle must be writable, meaning its refcount must be 1. You can
 855  * make the rectangles inside a #GstVideoOverlayComposition writable using
 856  * gst_video_overlay_composition_make_writable() or
 857  * gst_video_overlay_composition_copy().
 858  *
 859  * Since: 0.10.36
 860  */
 861 void
 862 gst_video_overlay_rectangle_set_render_rectangle (GstVideoOverlayRectangle *
 863     rectangle, gint render_x, gint render_y, guint render_width,
 864     guint render_height)
 865 {
 866   g_return_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle));
 867   g_return_if_fail (GST_MINI_OBJECT_REFCOUNT_VALUE (rectangle) == 1);
 868
 869   rectangle->x = render_x;
 870   rectangle->y = render_y;
 871   rectangle->render_width = render_width;
 872   rectangle->render_height = render_height;
 873 }
 874
 875 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 876 # define ARGB_A 3
 877 # define ARGB_R 2
 878 # define ARGB_G 1
 879 # define ARGB_B 0
 880 #else
 881 # define ARGB_A 0
 882 # define ARGB_R 1
 883 # define ARGB_G 2
 884 # define ARGB_B 3
 885 #endif
 886
 887 /* FIXME: orc-ify */
 888 static void
 889 gst_video_overlay_rectangle_premultiply (GstBlendVideoFormatInfo * info)
 890 {
 891   int i, j;
 892   for (j = 0; j < info->height; ++j) {
 893     guint8 *line = info->pixels + info->stride[0] * j;
 894     for (i = 0; i < info->width; ++i) {
 895       int a = line[ARGB_A];
 896       line[ARGB_R] = line[ARGB_R] * a / 255;
 897       line[ARGB_G] = line[ARGB_G] * a / 255;
 898       line[ARGB_B] = line[ARGB_B] * a / 255;
 899       line += 4;
 900     }
 901   }
 902 }
 903
 904 /* FIXME: orc-ify */
 905 static void
 906 gst_video_overlay_rectangle_unpremultiply (GstBlendVideoFormatInfo * info)
 907 {
 908   int i, j;
 909   for (j = 0; j < info->height; ++j) {
 910     guint8 *line = info->pixels + info->stride[0] * j;
 911     for (i = 0; i < info->width; ++i) {
 912       int a = line[ARGB_A];
 913       if (a) {
 914         line[ARGB_R] = MIN ((line[ARGB_R] * 255 + a / 2) / a, 255);
 915         line[ARGB_G] = MIN ((line[ARGB_G] * 255 + a / 2) / a, 255);
 916         line[ARGB_B] = MIN ((line[ARGB_B] * 255 + a / 2) / a, 255);
 917       }
 918       line += 4;
 919     }
 920   }
 921 }
 922
 923
 924 static void
 925 gst_video_overlay_rectangle_extract_alpha (GstVideoOverlayRectangle * rect)
 926 {
 927   guint8 *src, *dst;
 928   int offset = 0;
 929   int alpha_size = rect->stride * rect->height / 4;
 930
 931   g_free (rect->initial_alpha);
 932   rect->initial_alpha = NULL;
 933
 934   rect->initial_alpha = g_malloc (alpha_size);
 935   src = GST_BUFFER_DATA (rect->pixels);
 936   dst = rect->initial_alpha;
 937   /* FIXME we're accessing possibly uninitialised bytes from the row padding */
 938   while (offset < alpha_size) {
 939     dst[offset] = src[offset * 4 + ARGB_A];
 940     ++offset;
 941   }
 942 }
 943
 944
 945 static void
 946 gst_video_overlay_rectangle_apply_global_alpha (GstVideoOverlayRectangle * rect,
 947     float global_alpha)
 948 {
 949   guint8 *src, *dst;
 950   guint offset = 0;
 951
 952   g_assert (!(rect->applied_global_alpha != 1.0
 953           && rect->initial_alpha == NULL));
 954
 955   if (global_alpha == rect->applied_global_alpha)
 956     return;
 957
 958   if (rect->initial_alpha == NULL)
 959     gst_video_overlay_rectangle_extract_alpha (rect);
 960
 961   src = rect->initial_alpha;
 962   rect->pixels = gst_buffer_make_writable (rect->pixels);
 963   dst = GST_BUFFER_DATA (rect->pixels);
 964   while (offset < (rect->height * rect->stride / 4)) {
 965     guint doff = offset * 4;
 966     guint8 na = (guint8) src[offset] * global_alpha;
 967     if (! !(rect->flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA)) {
 968       dst[doff + ARGB_R] =
 969           (guint8) ((double) (dst[doff + ARGB_R] * 255) / (double) dst[doff +
 970               ARGB_A]) * na / 255;
 971       dst[doff + ARGB_G] =
 972           (guint8) ((double) (dst[doff + ARGB_G] * 255) / (double) dst[doff +
 973               ARGB_A]) * na / 255;
 974       dst[doff + ARGB_B] =
 975           (guint8) ((double) (dst[doff + ARGB_B] * 255) / (double) dst[doff +
 976               ARGB_A]) * na / 255;
 977     }
 978     dst[doff + ARGB_A] = na;
 979     ++offset;
 980   }
 981
 982   rect->applied_global_alpha = global_alpha;
 983 }
 984
 985 static GstBuffer *
 986 gst_video_overlay_rectangle_get_pixels_argb_internal (GstVideoOverlayRectangle *
 987     rectangle, guint * stride, GstVideoOverlayFormatFlags flags,
 988     gboolean unscaled)
 989 {
 990   GstVideoOverlayFormatFlags new_flags;
 991   GstVideoOverlayRectangle *scaled_rect = NULL;
 992   GstBlendVideoFormatInfo info;
 993   GstBuffer *buf;
 994   GList *l;
 995   guint wanted_width = unscaled ? rectangle->width : rectangle->render_width;
 996   guint wanted_height = unscaled ? rectangle->height : rectangle->render_height;
 997   gboolean apply_global_alpha;
 998   gboolean revert_global_alpha;
 999
1000   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
1001   g_return_val_if_fail (stride != NULL, NULL);
1002   g_return_val_if_fail (gst_video_overlay_rectangle_check_flags (flags), NULL);
1003
1004   apply_global_alpha =
1005       (! !(rectangle->flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA)
1006       && !(flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA));
1007   revert_global_alpha =
1008       (! !(rectangle->flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA)
1009       && ! !(flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA));
1010
1011   /* This assumes we don't need to adjust the format */
1012   if (wanted_width == rectangle->width &&
1013       wanted_height == rectangle->height &&
1014       gst_video_overlay_rectangle_is_same_alpha_type (rectangle->flags,
1015           flags)) {
1016     /* don't need to apply/revert global-alpha either: */
1017     if ((!apply_global_alpha
1018             || rectangle->applied_global_alpha == rectangle->global_alpha)
1019         && (!revert_global_alpha || rectangle->applied_global_alpha == 1.0)) {
1020       *stride = rectangle->stride;
1021       return rectangle->pixels;
1022     } else {
1023       /* only apply/revert global-alpha */
1024       scaled_rect = rectangle;
1025       goto done;
1026     }
1027   }
1028
1029   /* see if we've got one cached already */
1030   GST_RECTANGLE_LOCK (rectangle);
1031   for (l = rectangle->scaled_rectangles; l != NULL; l = l->next) {
1032     GstVideoOverlayRectangle *r = l->data;
1033
1034     if (r->width == wanted_width &&
1035         r->height == wanted_height &&
1036         gst_video_overlay_rectangle_is_same_alpha_type (r->flags, flags)) {
1037       /* we'll keep these rectangles around until finalize, so it's ok not
1038        * to take our own ref here */
1039       scaled_rect = r;
1040       break;
1041     }
1042   }
1043   GST_RECTANGLE_UNLOCK (rectangle);
1044
1045   if (scaled_rect != NULL)
1046     goto done;
1047
1048   /* not cached yet, do the preprocessing and put the result into our cache */
1049   video_blend_format_info_init (&info, GST_BUFFER_DATA (rectangle->pixels),
1050       rectangle->height, rectangle->width, rectangle->format,
1051       ! !(rectangle->flags &
1052           GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA));
1053
1054   if (wanted_width != rectangle->width || wanted_height != rectangle->height) {
1055     /* we could check the cache for a scaled rect with global_alpha == 1 here */
1056     video_blend_scale_linear_RGBA (&info, wanted_height, wanted_width);
1057   } else {
1058     /* if we don't have to scale, we have to modify the alpha values, so we
1059      * need to make a copy of the pixel memory (and we take ownership below) */
1060     info.pixels = g_memdup (info.pixels, info.size);
1061   }
1062
1063   new_flags = rectangle->flags;
1064   if (!gst_video_overlay_rectangle_is_same_alpha_type (rectangle->flags, flags)) {
1065     if (rectangle->flags & GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA) {
1066       gst_video_overlay_rectangle_unpremultiply (&info);
1067       new_flags &= ~GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA;
1068     } else {
1069       gst_video_overlay_rectangle_premultiply (&info);
1070       new_flags |= GST_VIDEO_OVERLAY_FORMAT_FLAG_PREMULTIPLIED_ALPHA;
1071     }
1072   }
1073
1074   buf = gst_buffer_new ();
1075   GST_BUFFER_DATA (buf) = info.pixels;
1076   GST_BUFFER_MALLOCDATA (buf) = info.pixels;
1077   GST_BUFFER_SIZE (buf) = info.size;
1078
1079   scaled_rect = gst_video_overlay_rectangle_new_argb (buf,
1080       wanted_width, wanted_height, info.stride[0],
1081       0, 0, wanted_width, wanted_height, new_flags);
1082   if (rectangle->global_alpha != 1.0)
1083     gst_video_overlay_rectangle_set_global_alpha (scaled_rect,
1084         rectangle->global_alpha);
1085   gst_buffer_unref (buf);
1086
1087   GST_RECTANGLE_LOCK (rectangle);
1088   rectangle->scaled_rectangles =
1089       g_list_prepend (rectangle->scaled_rectangles, scaled_rect);
1090   GST_RECTANGLE_UNLOCK (rectangle);
1091
1092 done:
1093
1094   GST_RECTANGLE_LOCK (rectangle);
1095   if (apply_global_alpha
1096       && scaled_rect->applied_global_alpha != rectangle->global_alpha) {
1097     gst_video_overlay_rectangle_apply_global_alpha (scaled_rect,
1098         rectangle->global_alpha);
1099     gst_video_overlay_rectangle_set_global_alpha (scaled_rect,
1100         rectangle->global_alpha);
1101   } else if (revert_global_alpha && scaled_rect->applied_global_alpha != 1.0) {
1102     gst_video_overlay_rectangle_apply_global_alpha (scaled_rect, 1.0);
1103   }
1104   GST_RECTANGLE_UNLOCK (rectangle);
1105
1106   *stride = scaled_rect->stride;
1107   return scaled_rect->pixels;
1108 }
1109
1110
1111 /**
1112  * gst_video_overlay_rectangle_get_pixels_argb:
1113  * @rectangle: a #GstVideoOverlayRectangle
1114  * @stride: (out) (allow-none): address of guint variable where to store the
1115  *    row stride of the ARGB pixel data in the buffer
1116  * @flags: flags
1117  *    If a global_alpha value != 1 is set for the rectangle, the caller
1118  *    should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag
1119  *    if he wants to apply global-alpha himself. If the flag is not set
1120  *    global_alpha is applied internally before returning the pixel-data.
1121  *
1122  * Returns: (transfer none): a #GstBuffer holding the ARGB pixel data with
1123  *    row stride @stride and width and height of the render dimensions as per
1124  *    gst_video_overlay_rectangle_get_render_rectangle(). This function does
1125  *    not return a reference, the caller should obtain a reference of her own
1126  *    with gst_buffer_ref() if needed.
1127  *
1128  * Since: 0.10.36
1129  */
1130 GstBuffer *
1131 gst_video_overlay_rectangle_get_pixels_argb (GstVideoOverlayRectangle *
1132     rectangle, guint * stride, GstVideoOverlayFormatFlags flags)
1133 {
1134   return gst_video_overlay_rectangle_get_pixels_argb_internal (rectangle,
1135       stride, flags, FALSE);
1136 }
1137
1138 /**
1139  * gst_video_overlay_rectangle_get_pixels_unscaled_argb:
1140  * @rectangle: a #GstVideoOverlayRectangle
1141  * @width: (out): address where to store the width of the unscaled
1142  *    rectangle in pixels
1143  * @height: (out): address where to store the height of the unscaled
1144  *    rectangle in pixels
1145  * @stride: (out): address of guint variable where to store the row
1146  *    stride of the ARGB pixel data in the buffer
1147  * @flags: flags.
1148  *    If a global_alpha value != 1 is set for the rectangle, the caller
1149  *    should set the #GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA flag
1150  *    if he wants to apply global-alpha himself. If the flag is not set
1151  *    global_alpha is applied internally before returning the pixel-data.
1152  *
1153  * Retrieves the pixel data as it is. This is useful if the caller can
1154  * do the scaling itself when handling the overlaying. The rectangle will
1155  * need to be scaled to the render dimensions, which can be retrieved using
1156  * gst_video_overlay_rectangle_get_render_rectangle().
1157  *
1158  * Returns: (transfer none): a #GstBuffer holding the ARGB pixel data with
1159  *    row stride @stride. This function does not return a reference, the caller
1160  *    should obtain a reference of her own with gst_buffer_ref() if needed.
1161  *
1162  * Since: 0.10.36
1163  */
1164 GstBuffer *
1165 gst_video_overlay_rectangle_get_pixels_unscaled_argb (GstVideoOverlayRectangle *
1166     rectangle, guint * width, guint * height, guint * stride,
1167     GstVideoOverlayFormatFlags flags)
1168 {
1169   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
1170   g_return_val_if_fail (width != NULL, NULL);
1171   g_return_val_if_fail (height != NULL, NULL);
1172   g_return_val_if_fail (stride != NULL, NULL);
1173
1174   *width = rectangle->width;
1175   *height = rectangle->height;
1176   return gst_video_overlay_rectangle_get_pixels_argb_internal (rectangle,
1177       stride, flags, TRUE);
1178 }
1179
1180 /**
1181  * gst_video_overlay_rectangle_get_flags:
1182  * @rectangle: a #GstVideoOverlayRectangle
1183  *
1184  * Retrieves the flags associated with a #GstVideoOverlayRectangle.
1185  * This is useful if the caller can handle both premultiplied alpha and
1186  * non premultiplied alpha, for example. By knowing whether the rectangle
1187  * uses premultiplied or not, it can request the pixel data in the format
1188  * it is stored in, to avoid unnecessary conversion.
1189  *
1190  * Returns: the #GstVideoOverlayFormatFlags associated with the rectangle.
1191  *
1192  * Since: 0.10.37
1193  */
1194 GstVideoOverlayFormatFlags
1195 gst_video_overlay_rectangle_get_flags (GstVideoOverlayRectangle * rectangle)
1196 {
1197   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle),
1198       GST_VIDEO_OVERLAY_FORMAT_FLAG_NONE);
1199
1200   return rectangle->flags;
1201 }
1202
1203 /**
1204  * gst_video_overlay_rectangle_get_global_alpha:
1205  * @rectangle: a #GstVideoOverlayRectangle
1206  *
1207  * Retrieves the global-alpha value associated with a #GstVideoOverlayRectangle.
1208  *
1209  * Returns: the global-alpha value associated with the rectangle.
1210  *
1211  * Since: 0.10.37
1212  */
1213 gfloat
1214 gst_video_overlay_rectangle_get_global_alpha (GstVideoOverlayRectangle *
1215     rectangle)
1216 {
1217   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), -1);
1218
1219   return rectangle->global_alpha;
1220 }
1221
1222 /**
1223  * gst_video_overlay_rectangle_set_global_alpha:
1224  * @rectangle: a #GstVideoOverlayRectangle
1225  *
1226  * Sets the global alpha value associated with a #GstVideoOverlayRectangle. Per-
1227  * pixel alpha values are multiplied with this value. Valid
1228  * values: 0 <= global_alpha <= 1; 1 to deactivate.
1229  *
1230  # @rectangle must be writable, meaning its refcount must be 1. You can
1231  * make the rectangles inside a #GstVideoOverlayComposition writable using
1232  * gst_video_overlay_composition_make_writable() or
1233  * gst_video_overlay_composition_copy().
1234  *
1235  * Since: 0.10.37
1236  */
1237 void
1238 gst_video_overlay_rectangle_set_global_alpha (GstVideoOverlayRectangle *
1239     rectangle, gfloat global_alpha)
1240 {
1241   g_return_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle));
1242   g_return_if_fail (global_alpha >= 0 && global_alpha <= 1);
1243
1244   if (rectangle->global_alpha != global_alpha) {
1245     rectangle->global_alpha = global_alpha;
1246     if (global_alpha != 1)
1247       rectangle->flags |= GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA;
1248     else
1249       rectangle->flags &= ~GST_VIDEO_OVERLAY_FORMAT_FLAG_GLOBAL_ALPHA;
1250     /* update seq_num automatically to signal the consumer, that data has changed
1251      * note, that this might mislead renderers, that can handle global-alpha
1252      * themselves, because what they want to know is whether the actual pixel data
1253      * has changed. */
1254     rectangle->seq_num = gst_video_overlay_get_seqnum ();
1255   }
1256 }
1257
1258 /**
1259  * gst_video_overlay_rectangle_copy:
1260  * @rectangle: (transfer none): a #GstVideoOverlayRectangle to copy
1261  *
1262  * Makes a copy of @rectangle, so that it is possible to modify it
1263  * (e.g. to change the render co-ordinates or render dimension). The
1264  * actual overlay pixel data buffers contained in the rectangle are not
1265  * copied.
1266  *
1267  * Returns: (transfer full): a new #GstVideoOverlayRectangle equivalent
1268  *     to @rectangle.
1269  *
1270  * Since: 0.10.36
1271  */
1272 GstVideoOverlayRectangle *
1273 gst_video_overlay_rectangle_copy (GstVideoOverlayRectangle * rectangle)
1274 {
1275   GstVideoOverlayRectangle *copy;
1276
1277   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), NULL);
1278
1279   copy = gst_video_overlay_rectangle_new_argb (rectangle->pixels,
1280       rectangle->width, rectangle->height, rectangle->stride,
1281       rectangle->x, rectangle->y,
1282       rectangle->render_width, rectangle->render_height, rectangle->flags);
1283   if (rectangle->global_alpha != 1)
1284     gst_video_overlay_rectangle_set_global_alpha (copy,
1285         rectangle->global_alpha);
1286
1287   return copy;
1288 }
1289
1290 /**
1291  * gst_video_overlay_rectangle_get_seqnum:
1292  * @rectangle: a #GstVideoOverlayRectangle
1293  *
1294  * Returns the sequence number of this rectangle. Sequence numbers are
1295  * monotonically increasing and unique for overlay compositions and rectangles
1296  * (meaning there will never be a rectangle with the same sequence number as
1297  * a composition).
1298  *
1299  * Using the sequence number of a rectangle as an indicator for changed
1300  * pixel-data of a rectangle is dangereous. Some API calls, like e.g.
1301  * gst_video_overlay_rectangle_set_global_alpha(), automatically update
1302  * the per rectangle sequence number, which is misleading for renderers/
1303  * consumers, that handle global-alpha themselves. For them  the
1304  * pixel-data returned by gst_video_overlay_rectangle_get_pixels_*()
1305  * wont be different for different global-alpha values. In this case a
1306  * renderer could also use the GstBuffer pointers as a hint for changed
1307  * pixel-data.
1308  *
1309  * Returns: the sequence number of @rectangle
1310  *
1311  * Since: 0.10.36
1312  */
1313 guint
1314 gst_video_overlay_rectangle_get_seqnum (GstVideoOverlayRectangle * rectangle)
1315 {
1316   g_return_val_if_fail (GST_IS_VIDEO_OVERLAY_RECTANGLE (rectangle), 0);
1317
1318   return rectangle->seq_num;
1319 }