gstvideooverlaycomposition

gstvideooverlaycomposition — Video Buffer Overlay Compositions (Subtitles, Logos)

Synopsis

#include <gst/video/video-overlay-composition.h>

                    GstVideoOverlayComposition;
                    GstVideoOverlayCompositionClass;
GstVideoOverlayComposition * gst_video_overlay_composition_new
                                                        (GstVideoOverlayRectangle *rectangle);
GstVideoOverlayComposition * gst_video_overlay_composition_ref
                                                        (GstVideoOverlayComposition *comp);
void                gst_video_overlay_composition_unref (GstVideoOverlayComposition *comp);
void                gst_video_overlay_composition_add_rectangle
                                                        (GstVideoOverlayComposition *comp,
                                                         GstVideoOverlayRectangle *rectangle);
guint               gst_video_overlay_composition_n_rectangles
                                                        (GstVideoOverlayComposition *comp);
GstVideoOverlayRectangle * gst_video_overlay_composition_get_rectangle
                                                        (GstVideoOverlayComposition *comp,
                                                         guint n);
guint               gst_video_overlay_composition_get_seqnum
                                                        (GstVideoOverlayComposition *comp);
GstVideoOverlayComposition * gst_video_overlay_composition_copy
                                                        (GstVideoOverlayComposition *comp);
GstVideoOverlayComposition * gst_video_overlay_composition_make_writable
                                                        (GstVideoOverlayComposition *comp);
gboolean            gst_video_overlay_composition_blend (GstVideoOverlayComposition *comp,
                                                         GstBuffer *video_buf);

GstVideoOverlayComposition * gst_video_buffer_get_overlay_composition
                                                        (GstBuffer *buf);
void                gst_video_buffer_set_overlay_composition
                                                        (GstBuffer *buf,
                                                         GstVideoOverlayComposition *comp);

enum                GstVideoOverlayFormatFlags;
                    GstVideoOverlayRectangle;
                    GstVideoOverlayRectangleClass;
GstVideoOverlayRectangle * gst_video_overlay_rectangle_new_argb
                                                        (GstBuffer *pixels,
                                                         guint width,
                                                         guint height,
                                                         guint stride,
                                                         gint render_x,
                                                         gint render_y,
                                                         guint render_width,
                                                         guint render_height,
                                                         GstVideoOverlayFormatFlags flags);
GstVideoOverlayRectangle * gst_video_overlay_rectangle_ref
                                                        (GstVideoOverlayRectangle *comp);
void                gst_video_overlay_rectangle_unref   (GstVideoOverlayRectangle *comp);
GstBuffer *         gst_video_overlay_rectangle_get_pixels_argb
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         guint *stride,
                                                         GstVideoOverlayFormatFlags flags);
GstBuffer *         gst_video_overlay_rectangle_get_pixels_unscaled_argb
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         guint *width,
                                                         guint *height,
                                                         guint *stride,
                                                         GstVideoOverlayFormatFlags flags);
gboolean            gst_video_overlay_rectangle_get_render_rectangle
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         gint *render_x,
                                                         gint *render_y,
                                                         guint *render_width,
                                                         guint *render_height);
guint               gst_video_overlay_rectangle_get_seqnum
                                                        (GstVideoOverlayRectangle *rectangle);
void                gst_video_overlay_rectangle_set_render_rectangle
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         gint render_x,
                                                         gint render_y,
                                                         guint render_width,
                                                         guint render_height);
GstVideoOverlayRectangle * gst_video_overlay_rectangle_copy
                                                        (GstVideoOverlayRectangle *rectangle);

Description

Functions to create and handle overlay compositions on video buffers.

An overlay composition describes one or more overlay rectangles to be blended on top of a video buffer.

This API serves two main purposes:

GstOverlayComposition
  • it can be used to attach overlay information (subtitles or logos) to non-raw video buffers such as GL/VAAPI/VDPAU surfaces. The actual blending of the overlay can then be done by e.g. the video sink that processes these non-raw buffers.
  • it can also be used to blend overlay rectangles on top of raw video buffers, thus consolidating blending functionality for raw video in one place.

Details

GstVideoOverlayComposition

typedef struct _GstVideoOverlayComposition GstVideoOverlayComposition;

An opaque video overlay composition object. A composition contains multiple overlay rectangles.

Since 0.10.36

GstVideoOverlayCompositionClass

typedef struct _GstVideoOverlayCompositionClass GstVideoOverlayCompositionClass;

gst_video_overlay_composition_new ()

GstVideoOverlayComposition * gst_video_overlay_composition_new
                                                        (GstVideoOverlayRectangle *rectangle);

Creates a new video overlay composition object to hold one or more overlay rectangles.

rectangle :

 a GstVideoOverlayRectangle to add to the composition. [transfer none]

Returns :

 a new GstVideoOverlayComposition. Unref with gst_video_overlay_composition_unref() when no longer needed. [transfer full]

Since 0.10.36

gst_video_overlay_composition_ref ()

GstVideoOverlayComposition * gst_video_overlay_composition_ref
                                                        (GstVideoOverlayComposition *comp);

Increases the refcount of the given composition by one.

Note that the refcount affects the writeability of comp, use gst_video_overlay_composition_make_writable() to ensure a composition and its rectangles can be modified.

comp :

 a a GstVideoOverlayComposition.

Returns :

 comp. [transfer full]

Since 0.10.36

gst_video_overlay_composition_unref ()

void                gst_video_overlay_composition_unref (GstVideoOverlayComposition *comp);

Decreases the refcount of the composition. If the refcount reaches 0, the composition will be freed.

comp :

 a GstVideoOverlayComposition. [transfer full]

Since 0.10.36

gst_video_overlay_composition_add_rectangle ()

void                gst_video_overlay_composition_add_rectangle
                                                        (GstVideoOverlayComposition *comp,
                                                         GstVideoOverlayRectangle *rectangle);

Adds an overlay rectangle to an existing overlay composition object. This must be done right after creating the overlay composition.

comp :

 a GstVideoOverlayComposition

rectangle :

 a GstVideoOverlayRectangle to add to the composition. [transfer none]

Since 0.10.36

gst_video_overlay_composition_n_rectangles ()

guint               gst_video_overlay_composition_n_rectangles
                                                        (GstVideoOverlayComposition *comp);

Returns the number of GstVideoOverlayRectangles contained in comp.

comp :

 a GstVideoOverlayComposition

Returns :

 the number of rectangles

Since 0.10.36

gst_video_overlay_composition_get_rectangle ()

GstVideoOverlayRectangle * gst_video_overlay_composition_get_rectangle
                                                        (GstVideoOverlayComposition *comp,
                                                         guint n);

Returns the n-th GstVideoOverlayRectangle contained in comp.

comp :

 a GstVideoOverlayComposition

n :

 number of the rectangle to get

Returns :

 the n-th rectangle, or NULL if n is out of bounds. Will not return a new reference, the caller will need to obtain her own reference using gst_video_overlay_rectangle_ref() if needed. [transfer none]

Since 0.10.36

gst_video_overlay_composition_get_seqnum ()

guint               gst_video_overlay_composition_get_seqnum
                                                        (GstVideoOverlayComposition *comp);

Returns the sequence number of this composition. Sequence numbers are monotonically increasing and unique for overlay compositions and rectangles (meaning there will never be a rectangle with the same sequence number as a composition).

comp :

 a GstVideoOverlayComposition

Returns :

 the sequence number of comp

Since 0.10.36

gst_video_overlay_composition_copy ()

GstVideoOverlayComposition * gst_video_overlay_composition_copy
                                                        (GstVideoOverlayComposition *comp);

Makes a copy of comp and all contained rectangles, so that it is possible to modify the composition and contained rectangles (e.g. add additional rectangles or change the render co-ordinates or render dimension). The actual overlay pixel data buffers contained in the rectangles are not copied.

comp :

 a GstVideoOverlayComposition to copy. [transfer none]

Returns :

 a new GstVideoOverlayComposition equivalent to comp. [transfer full]

Since 0.10.36

gst_video_overlay_composition_make_writable ()

GstVideoOverlayComposition * gst_video_overlay_composition_make_writable
                                                        (GstVideoOverlayComposition *comp);

Takes ownership of comp and returns a version of comp that is writable (i.e. can be modified). Will either return comp right away, or create a new writable copy of comp and unref comp itself. All the contained rectangles will also be copied, but the actual overlay pixel data buffers contained in the rectangles are not copied.

comp :

 a GstVideoOverlayComposition to copy. [transfer full]

Returns :

 a writable GstVideoOverlayComposition equivalent to comp. [transfer full]

Since 0.10.36

gst_video_overlay_composition_blend ()

gboolean            gst_video_overlay_composition_blend (GstVideoOverlayComposition *comp,
                                                         GstBuffer *video_buf);

Blends the overlay rectangles in comp on top of the raw video data contained in video_buf. The data in video_buf must be writable. If needed, use gst_buffer_make_writable() before calling this function to ensure a buffer is writable. video_buf must also have valid raw video caps set on it.

comp :

 a GstVideoOverlayComposition

video_buf :

 a GstBuffer containing raw video data in a supported format

Since 0.10.36

gst_video_buffer_get_overlay_composition ()

GstVideoOverlayComposition * gst_video_buffer_get_overlay_composition
                                                        (GstBuffer *buf);

Get the overlay composition that has previously been attached to a buffer with gst_video_buffer_get_overlay_composition(), usually by another element upstream.

buf :

 a GstBuffer

Returns :

 the GstVideoOverlayComposition attached to this buffer, or NULL. Does not return a reference to the composition, caller must obtain her own ref via gst_video_overlay_composition_ref() if needed. [transfer none]

Since 0.10.36

gst_video_buffer_set_overlay_composition ()

void                gst_video_buffer_set_overlay_composition
                                                        (GstBuffer *buf,
                                                         GstVideoOverlayComposition *comp);

Sets an overlay composition on a buffer. The buffer will obtain its own reference to the composition, meaning this function does not take ownership of comp.

buf :

 a GstBuffer

comp :

 a GstVideoOverlayComposition, or NULL to clear a previously-set composition. [allow-none]

Since 0.10.36

enum GstVideoOverlayFormatFlags

typedef enum {
  GST_VIDEO_OVERLAY_FORMAT_FLAG_NONE = 0
} GstVideoOverlayFormatFlags;

Overlay format flags.

GST_VIDEO_OVERLAY_FORMAT_FLAG_NONE

 no flags

Since 0.10.36

GstVideoOverlayRectangle

typedef struct _GstVideoOverlayRectangle GstVideoOverlayRectangle;

An opaque video overlay rectangle object. A rectangle contains a single overlay rectangle which can be added to a composition.

Since 0.10.36

GstVideoOverlayRectangleClass

typedef struct _GstVideoOverlayRectangleClass GstVideoOverlayRectangleClass;

gst_video_overlay_rectangle_new_argb ()

GstVideoOverlayRectangle * gst_video_overlay_rectangle_new_argb
                                                        (GstBuffer *pixels,
                                                         guint width,
                                                         guint height,
                                                         guint stride,
                                                         gint render_x,
                                                         gint render_y,
                                                         guint render_width,
                                                         guint render_height,
                                                         GstVideoOverlayFormatFlags flags);

Creates a new video overlay rectangle with ARGB pixel data. The layout of the components in memory is B-G-R-A on little-endian platforms (corresponding to GST_VIDEO_FORMAT_BGRA) and A-R-G-B on big-endian platforms (corresponding to GST_VIDEO_FORMAT_ARGB). In other words, pixels are treated as 32-bit words and the lowest 8 bits then contain the blue component value and the highest 8 bits contain the alpha component value. The RGB values are non-premultiplied. This is the format that is used by most hardware, and also many rendering libraries such as Cairo, for example.

pixels :

 a GstBuffer pointing to the pixel memory. [transfer none]

width :

 the width of the rectangle in pixels

height :

 the height of the rectangle in pixels

stride :

 the stride of the rectangle in pixels in bytes (>= 4*width)

x :

 the X co-ordinate on the video where the top-left corner of this overlay rectangle should be rendered to

y :

 the Y co-ordinate on the video where the top-left corner of this overlay rectangle should be rendered to

render_width :

 the render width of this rectangle on the video

render_height :

 the render height of this rectangle on the video

flags :

 flags (currently unused)

Returns :

 a new GstVideoOverlayRectangle. Unref with gst_video_overlay_rectangle_unref() when no longer needed. [transfer full]

Since 0.10.36

gst_video_overlay_rectangle_ref ()

GstVideoOverlayRectangle * gst_video_overlay_rectangle_ref
                                                        (GstVideoOverlayRectangle *comp);

Increases the refcount of the given rectangle by one.

Note that the refcount affects the writeability of comp, use gst_video_overlay_rectangle_copy() to ensure a rectangle can be modified (there is no gst_video_overlay_rectangle_make_writable() because it is unlikely that someone will hold the single reference to the rectangle and not know that that's the case).

comp :

 a a GstVideoOverlayRectangle.

Returns :

 comp. [transfer full]

Since 0.10.36

gst_video_overlay_rectangle_unref ()

void                gst_video_overlay_rectangle_unref   (GstVideoOverlayRectangle *comp);

Decreases the refcount of the rectangle. If the refcount reaches 0, the rectangle will be freed.

comp :

 a GstVideoOverlayRectangle. [transfer full]

Since 0.10.36

gst_video_overlay_rectangle_get_pixels_argb ()

GstBuffer *         gst_video_overlay_rectangle_get_pixels_argb
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         guint *stride,
                                                         GstVideoOverlayFormatFlags flags);

rectangle :

 a GstVideoOverlayRectangle

stride :

 address of guint variable where to store the row stride of the ARGB pixel data in the buffer. [out][allow-none]

flags :

 flags (unused)

Returns :

 a GstBuffer holding the ARGB pixel data with row stride stride and width and height of the render dimensions as per gst_video_overlay_rectangle_get_render_rectangle(). This function does not return a reference, the caller should obtain a reference of her own with gst_buffer_ref() if needed. [transfer none]

Since 0.10.36

gst_video_overlay_rectangle_get_pixels_unscaled_argb ()

GstBuffer *         gst_video_overlay_rectangle_get_pixels_unscaled_argb
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         guint *width,
                                                         guint *height,
                                                         guint *stride,
                                                         GstVideoOverlayFormatFlags flags);

Retrieves the pixel data as it is. This is useful if the caller can do the scaling itself when handling the overlaying. The rectangle will need to be scaled to the render dimensions, which can be retrieved using gst_video_overlay_rectangle_get_render_rectangle().

rectangle :

 a GstVideoOverlayRectangle

width :

 address where to store the width of the unscaled rectangle in pixels. [out]

width :

 address where to store the height of the unscaled rectangle in pixels. [out]

stride :

 address of guint variable where to store the row stride of the ARGB pixel data in the buffer. [out]

flags :

 flags for future use (unused)

Returns :

 a GstBuffer holding the ARGB pixel data with row stride stride. This function does not return a reference, the caller should obtain a reference of her own with gst_buffer_ref() if needed. [transfer none]

Since 0.10.36

gst_video_overlay_rectangle_get_render_rectangle ()

gboolean            gst_video_overlay_rectangle_get_render_rectangle
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         gint *render_x,
                                                         gint *render_y,
                                                         guint *render_width,
                                                         guint *render_height);

Retrieves the render position and render dimension of the overlay rectangle on the video.

rectangle :

 a GstVideoOverlayRectangle

render_x :

 address where to store the X render offset. [out][allow-none]

render_y :

 address where to store the Y render offset. [out][allow-none]

render_width :

 address where to store the render width. [out][allow-none]

render_height :

 address where to store the render height. [out][allow-none]

Returns :

 TRUE if valid render dimensions were retrieved.

Since 0.10.36

gst_video_overlay_rectangle_get_seqnum ()

guint               gst_video_overlay_rectangle_get_seqnum
                                                        (GstVideoOverlayRectangle *rectangle);

Returns the sequence number of this rectangle. Sequence numbers are monotonically increasing and unique for overlay compositions and rectangles (meaning there will never be a rectangle with the same sequence number as a composition).

rectangle :

 a GstVideoOverlayRectangle

Returns :

 the sequence number of rectangle

Since 0.10.36

gst_video_overlay_rectangle_set_render_rectangle ()

void                gst_video_overlay_rectangle_set_render_rectangle
                                                        (GstVideoOverlayRectangle *rectangle,
                                                         gint render_x,
                                                         gint render_y,
                                                         guint render_width,
                                                         guint render_height);

Sets the render position and dimensions of the rectangle on the video. This function is mainly for elements that modify the size of the video in some way (e.g. through scaling or cropping) and need to adjust the details of any overlays to match the operation that changed the size.

rectangle must be writable, meaning its refcount must be 1. You can make the rectangles inside a GstVideoOverlayComposition writable using gst_video_overlay_composition_make_writable() or gst_video_overlay_composition_copy().

rectangle :

 a GstVideoOverlayRectangle

render_x :

 render X position of rectangle on video

render_y :

 render Y position of rectangle on video

render_width :

 render width of rectangle

render_height :

 render height of rectangle

Since 0.10.36

gst_video_overlay_rectangle_copy ()

GstVideoOverlayRectangle * gst_video_overlay_rectangle_copy
                                                        (GstVideoOverlayRectangle *rectangle);

Makes a copy of rectangle, so that it is possible to modify it (e.g. to change the render co-ordinates or render dimension). The actual overlay pixel data buffers contained in the rectangle are not copied.

rectangle :

 a GstVideoOverlayRectangle to copy. [transfer none]

Returns :

 a new GstVideoOverlayRectangle equivalent to rectangle. [transfer full]

Since 0.10.36

Generated by GTK-Doc V1.18