GStreamer Custom Plugin – DrawShape

A custom GStreamer plugin (drawshape) that enables drawing shapes (rectangle, circle, etc.) directly on NV12 video frames.
It provides configurable properties such as shape type, size, position, color, fill mode, and alpha blending.
This repository also includes a sample application (gst-app) that demonstrates how to use the plugin in a GStreamer pipeline.

---

System Overview

The project consists of two major parts:

• gst-plugin (DrawShape Plugin)

  • Implements the drawshape element.
  • Supports shapes like rectangle and circle.
  • Configurable via GStreamer properties (x/y position, width, height, color, alpha, fill).
  • Works on NV12 video format.

• gst-app (Sample Application)

  • Demonstrates usage of the drawshape plugin.
  • Builds a GStreamer pipeline programmatically.
  • Displays the processed video with shapes rendered.

---

Features

✔️ Custom GStreamer plugin written in C
✔️ Shape drawing on NV12 video frames
✔️ Configurable shape type, position, size, color, alpha, fill mode
✔️ Example application to test and showcase the plugin
✔️ Built using Meson and Ninja build system

---

Algorithms & Techniques Used

• Video Frame Processing → Operates on NV12 raw video buffers.
• Shape Rendering → Supports rectangle and circle primitives with RGB color.
• Alpha Blending → Supports transparency (0.0 – 1.0).
• Fill/Outline Mode → Shapes can be filled or drawn as outlines.
• Property Control → Shape parameters are exposed as GStreamer element properties for runtime configuration.
• Meson Build System → Used for modular compilation of plugin and application.

---

Project Structure

drawshape/
│── gst-app/
│ ├── meson.build
│ └── src/
│   └── main.c # Sample application using the plugin
│── gst-plugin/
│ ├── meson.build
│ └── src/
│   ├── gstdrawshape.c # Plugin implementation
│   └── gstdrawshape.h # Plugin header
│── meson.build # Top-level build file
│── README.md

---

Table of Contents

• Installation
• Usage
• Plugin Parameters
• License
• Authors

---

Installation

Before you install the drawshape Plugin, make sure you have GStreamer installed on your system. If not, you'll need to install it first. Here's a simplified guide to installing the plugin:

1. Check GStreamer Installation: Verify that GStreamer is already installed on your system. You can do this by running gst-inspect-1.0 --version in your terminal. If GStreamer is installed, you'll see the version number. If not, you'll need to install GStreamer before proceeding.

2. Clone the Plugin Repository: Clone the draw_shape plugin repository to your local machine. You can do this by running the following command in your terminal:

   git clone https://github.com/Manvendra199922/GStreamer-plugin.git

3. Navigate to the Repository: Change your current directory to the cloned repository. Use the following command:

   cd GStreamer-plugin/gst-template

4. Build the Plugin: Use meson to build the plugin. Run the following commands in your terminal:

   meson build
   ninja -C build

5. Install the Plugin: Once the plugin is built successfully, you can install it on your system. Run the following command in your terminal:

   cd build/gst-plugin/
   sudo cp libgstdrawshape.so /usr/lib/x86_64-linux-gnu/gstreamer-1.0/

Replace /usr/lib/x86_64-linux-gnu/gstreamer-1.0/ with the appropriate directory path if your system has a different location for GStreamer plugins.

---

Usage

Once you've successfully installed the GStreamer drawshape Plugin, you can incorporate it into your GStreamer pipelines. The plugin is identified in the pipeline as drawshape. You can utilize gst-inspect-1.0 to display all the properties and details of the drawshape plugin. To do this, simply type the following command in your terminal:

gst-inspect-1.0 drawshape

Below is an example demonstrating how to use the drawshape Plugin in a GStreamer pipeline:

Drawing a square with default settings

gst-launch-1.0 videotestsrc pattern=smpte ! video/x-raw,format=NV12,width=1280,height=720,framerate=30/1 ! drawshape shape=square shape-size=100 shape-color=red fill-mode=color ! autovideosink

Drawing a circle at a specific coordinate

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! drawshape shape=circle shape-size=150 shape-color=green fill-mode=color draw-coordinates='<400,300>' ! autovideosink

Copying a region of the frame into a triangle mask

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=1280,height=720,framerate=30/1 ! drawshape shape=triangle shape-size=200 fill-mode=copy draw-coordinates='<600,300>' copy-coordinates='<900,500>' ! autovideosink

Drawing a rectangle with alpha blending

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=1280,height=720,framerate=30/1 ! drawshape shape=rectangle shape-size=250 shape-color=blue fill-mode=color alpha=50 draw-coordinates='<700,400>' ! autovideosink

Strict mode enabled with invalid configuration (test failure)

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=640,height=480,framerate=30/1 ! drawshape shape=triangle shape-size=120 fill-mode=copy draw-coordinates='<200,200>' strict-mode=true ! autovideosink

(This will error out because copy-coordinates is missing and strict-mode=true enforces validation.)

Drawing two shapes sequentially (chaining drawshape elements)

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=1920,height=1080,framerate=30/1 ! drawshape shape=rectangle shape-size=150 shape-color=blue fill-mode=color draw-coordinates='<300,300>' ! drawshape shape=triangle shape-size=200 shape-color=red fill-mode=color draw-coordinates='<800,500>' ! autovideosink

Drawing a circle outline (no fill mode)

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=640,height=480,framerate=30/1 ! drawshape shape=circle shape-size=100 shape-color=green fill-mode=no-fill draw-coordinates='<320,240>' ! autovideosink

Copy with alpha blending

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=640,height=480,framerate=30/1 ! drawshape shape=square shape-size=100 fill-mode=copy draw-coordinates='<200,200>' copy-coordinates='<400,300>' alpha=40 ! autovideosink

Maximum resolution stress test (1960×1080)

gst-launch-1.0 videotestsrc ! video/x-raw,format=NV12,width=1960,height=1080,framerate=30/1 ! drawshape shape=circle shape-size=300 shape-color=red fill-mode=color draw-coordinates='<980,540>' ! autovideosink

Using live camera input with shape overlay

gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=1280,height=720,framerate=30/1 ! videoconvert ! video/x-raw,format=NV12 ! drawshape shape=rectangle shape-size=200 shape-color=green fill-mode=color draw-coordinates='<600,400>' ! autovideosink

---

Plugin Parameters

The drawshape plugin supports the following parameters:

Parameter	Description	Type	Options / Range	Default
shape	Shape to draw.	string	square, rectangle, circle, triangle	square
shape-size	Size of the shape in pixels.	int	Positive integer	100
shape-color	Color of the shape (for color or no-fill modes).	string	red, green, blue	red
fill-mode	Mode of filling the shape.	string	color (fill with color), no-fill (outline), copy (copy from source)	color
draw-coordinates	Coordinates where the shape will be drawn. Format: '<x,y>'.	string	Any valid pixel coordinates within resolution	'<0,0>'
copy-coordinates	Source coordinates for fill-mode=copy. Format: '<x,y>'.	string	Any valid pixel coordinates within resolution	'<0,0>'
alpha	Opacity blending. -1 disables alpha.	int	-1, or 0–100	-1
strict-mode	Treat warnings as errors. If true, invalid params stop the plugin.	boolean	true, false	false

---

License

This project is licensed under the MIT License - see the LICENSE file for details. GStreamer itself is licensed under the Lesser General Public License version 2.1 or (at your option) any later version: https://www.gnu.org/licenses/lgpl-2.1.html

---

Authors

• Manvendra Pratap Singh