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