overlaycomposition: GStreamer Base Plugins 1.0 Plugins Reference Manual

## overlaycomposition overlaycomposition |

## Signals

void | caps-changed |
GstVideoOverlayComposition* | draw |

## Types and Values

struct | GstOverlayComposition

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstOverlayComposition

## Description

The overlaycomposition element renders an overlay using an application provided draw function.

A more interesting example can be found at https://cgit.freedesktop.org/gstreamer/gst-plugins-base/tree/tests/examples/overlaycomposition/overlaycomposition.c

### Example code

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    #include <gst/gst.h>
    #include <gst/video/video.h>

    ...

    typedef struct {
      gboolean valid;
      GstVideoInfo info;
    } OverlayState;

    ...

    static void
    prepare_overlay (GstElement * overlay, GstCaps * caps, gint window_width,
        gint window_height, gpointer user_data)
    {
      OverlayState *s = (OverlayState *)user_data;

      if (gst_video_info_from_caps (&s->info, caps))
        s->valid = TRUE;
    }

    static GstVideoOverlayComposition *
    draw_overlay (GstElement * overlay, GstSample * sample, gpointer user_data)
    {
      OverlayState *s = (OverlayState *)user_data;
      GstBuffer *buffer;
      GstVideoOverlayRectangle *rect;
      GstVideoOverlayComposition *comp;
      GstVideoInfo info;
      GstVideoFrame frame;
      gint x, y;
      guint8 *data;

      if (!s->valid)
        return NULL;

      gst_video_info_set_format (&info, GST_VIDEO_FORMAT_BGRA, 16, 16);
      buffer = gst_buffer_new_and_alloc (info.size);
      gst_buffer_add_video_meta (buffer, GST_VIDEO_FRAME_FLAG_NONE,
          GST_VIDEO_INFO_FORMAT(&info),
          GST_VIDEO_INFO_WIDTH(&info),
          GST_VIDEO_INFO_HEIGHT(&info));

      gst_video_frame_map (&frame, &info, buffer, GST_MAP_WRITE);

      // Overlay a half-transparent blue 16x16 rectangle in the middle
      // of the frame
      data = GST_VIDEO_FRAME_PLANE_DATA(&frame, 0);
      for (y = 0; y < 16; y++) {
        guint8 *line = &data[y * GST_VIDEO_FRAME_PLANE_STRIDE (&frame, 0)];
        for (x = 0; x < 16; x++) {
          guint8 *pixel = &line[x * 4];

          pixel[0] = 255;
          pixel[1] = 0;
          pixel[2] = 0;
          pixel[3] = 127;
        }
      }

      gst_video_frame_unmap (&frame);
      rect = gst_video_overlay_rectangle_new_raw (buffer,
          s->info.width / 2 - 8,
          s->info.height / 2 - 8,
          16, 16,
          GST_VIDEO_OVERLAY_FORMAT_FLAG_NONE);
      comp = gst_video_overlay_composition_new (rect);
      gst_video_overlay_rectangle_unref (rect);
      gst_buffer_unref (buffer);

      return comp;
    }

    ...

    overlay = gst_element_factory_make ("overlaycomposition", "overlay");

    g_signal_connect (overlay, "draw", G_CALLBACK (draw_overlay),
      overlay_state);
    g_signal_connect (overlay, "caps-changed",
      G_CALLBACK (prepare_overlay), overlay_state);
    ...

## Synopsis

### Element Information

plugin | overlaycomposition
author | Sebastian Dröge <sebastian@centricular.com>
class | Filter/Editor/Video

### Element Pads

name | sink
direction | sink
presence | always
details | video/x-raw, format=(string){ BGRx, RGBx, xRGB, xBGR, RGBA, BGRA, ARGB, ABGR, RGB, BGR, I420, YV12, AYUV, YUY2, UYVY, v308, Y41B, Y42B, Y444, NV12, NV21, A420, YUV9, YVU9, IYU1, GRAY8 }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw(ANY), format=(string){ I420, YV12, YUY2, UYVY, AYUV, VUYA, RGBx, BGRx, xRGB, xBGR, RGBA, BGRA, ARGB, ABGR, RGB, BGR, Y41B, Y42B, YVYU, Y444, v210, v216, Y210, Y410, NV12, NV21, GRAY8, GRAY16_BE, GRAY16_LE, v308, RGB16, BGR16, RGB15, BGR15, UYVP, A420, RGB8P, YUV9, YVU9, IYU1, ARGB64, AYUV64, r210, I420_10BE, I420_10LE, I422_10BE, I422_10LE, Y444_10BE, Y444_10LE, GBR, GBR_10BE, GBR_10LE, NV16, NV24, NV12_64Z32, A420_10BE, A420_10LE, A422_10BE, A422_10LE, A444_10BE, A444_10LE, NV61, P010_10BE, P010_10LE, IYU2, VYUY, GBRA, GBRA_10BE, GBRA_10LE, BGR10A2_LE, GBR_12BE, GBR_12LE, GBRA_12BE, GBRA_12LE, I420_12BE, I420_12LE, I422_12BE, I422_12LE, Y444_12BE, Y444_12LE, GRAY10_LE32, NV12_10LE32, NV16_10LE32, NV12_10LE40 }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]

name | src
direction | source
presence | always
details | video/x-raw, format=(string){ BGRx, RGBx, xRGB, xBGR, RGBA, BGRA, ARGB, ABGR, RGB, BGR, I420, YV12, AYUV, YUY2, UYVY, v308, Y41B, Y42B, Y444, NV12, NV21, A420, YUV9, YVU9, IYU1, GRAY8 }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]
| video/x-raw(ANY), format=(string){ I420, YV12, YUY2, UYVY, AYUV, VUYA, RGBx, BGRx, xRGB, xBGR, RGBA, BGRA, ARGB, ABGR, RGB, BGR, Y41B, Y42B, YVYU, Y444, v210, v216, Y210, Y410, NV12, NV21, GRAY8, GRAY16_BE, GRAY16_LE, v308, RGB16, BGR16, RGB15, BGR15, UYVP, A420, RGB8P, YUV9, YVU9, IYU1, ARGB64, AYUV64, r210, I420_10BE, I420_10LE, I422_10BE, I422_10LE, Y444_10BE, Y444_10LE, GBR, GBR_10BE, GBR_10LE, NV16, NV24, NV12_64Z32, A420_10BE, A420_10LE, A422_10BE, A422_10LE, A444_10BE, A444_10LE, NV61, P010_10BE, P010_10LE, IYU2, VYUY, GBRA, GBRA_10BE, GBRA_10LE, BGR10A2_LE, GBR_12BE, GBR_12LE, GBRA_12BE, GBRA_12LE, I420_12BE, I420_12LE, I422_12BE, I422_12LE, Y444_12BE, Y444_12LE, GRAY10_LE32, NV12_10LE32, NV16_10LE32, NV12_10LE40 }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]

## Functions

## Types and Values

### struct GstOverlayComposition

    struct GstOverlayComposition;

## Signal Details

### The `“caps-changed”` signal

    void
    user_function (GstOverlayComposition *overlay,
                   GstCaps               *caps,
                   guint                  window_width,
                   guint                  window_height,
                   gpointer               user_data)

This signal is emitted when the caps of the element has changed.

The window width and height define the resolution at which the frame is going to be rendered in the end by e.g. a video sink (i.e. the window size).

#### Parameters

overlay | Overlay element emitting the signal. |
caps | The GstCaps of the element. |
window_width | The window render width of downstream, or 0. |
window_height | The window render height of downstream, or 0. |
user_data | user data set when the signal handler was connected. |

### The `“draw”` signal

    GstVideoOverlayComposition*
    user_function (GstOverlayComposition *overlay,
                   GstSample             *sample,
                   gpointer               user_data)

This signal is emitted when the overlay should be drawn.

#### Parameters

overlay | Overlay element emitting the signal. |
sample | GstSample containing the current buffer, caps and segment. |
user_data | user data set when the signal handler was connected. |

#### Returns

GstVideoOverlayComposition or `NULL`