Overlay helper library for creating and rendering custom overlays. More...

#include <glib.h>

Include dependency graph for axoverlay.h:

Data Structures
struct	axoverlay_stream_data

struct	axoverlay_overlay_data

struct	axoverlay_palette_color

struct	axoverlay_settings

Macros
#define	AXOVERLAY_QUAD_CAMERA_ID 0

#define	AXOVERLAY_DEFAULT_CAMERA_ID 1

#define	AXOVERLAY_Z_PRIO_LOW 0

#define	AXOVERLAY_Z_PRIO_MEDIUM 1000

#define	AXOVERLAY_Z_PRIO_HIGH 2000

#define	AXOVERLAY_Z_PRIO_VERY_HIGH 3000

Typedefs
typedef gboolean(*	axoverlay_stream_select_function) (gint camera, gint width, gint height, gint rotation, gboolean is_mirrored, enum axoverlay_stream_type type)

typedef void(*	axoverlay_adjustment_function) (gint id, struct axoverlay_stream_data stream, enum axoverlay_position_type postype, gfloat overlay_x, gfloat overlay_y, gint overlay_width, gint overlay_height, gpointer user_data)

typedef void(*	axoverlay_render_function) (gpointer rendering_context, gint id, struct axoverlay_stream_data *stream, enum axoverlay_position_type postype, gfloat overlay_x, gfloat overlay_y, gint overlay_width, gint overlay_height, gpointer user_data)

Enumerations
enum	axoverlay_error_code { AXOVERLAY_ERROR_INVALID_VALUE = 1000, AXOVERLAY_ERROR_INTERNAL = 2000, AXOVERLAY_ERROR_UNEXPECTED = 3000, AXOVERLAY_ERROR_GENERIC = 4000, AXOVERLAY_ERROR_INVALID_ARGUMENT = 5000, AXOVERLAY_ERROR_SERVICE_UNAVAILABLE = 6000, AXOVERLAY_ERROR_BACKEND = 7000 }

enum	axoverlay_colorspace { AXOVERLAY_COLORSPACE_ARGB32, AXOVERLAY_COLORSPACE_4BIT_PALETTE, AXOVERLAY_COLORSPACE_1BIT_PALETTE, AXOVERLAY_COLORSPACE_UNDEFINED }

enum	axoverlay_position_type { AXOVERLAY_TOP_LEFT, AXOVERLAY_TOP_RIGHT, AXOVERLAY_BOTTOM_LEFT, AXOVERLAY_BOTTOM_RIGHT, AXOVERLAY_CUSTOM_NORMALIZED, AXOVERLAY_CUSTOM_SOURCE }

enum	axoverlay_backend_type { AXOVERLAY_CAIRO_IMAGE_BACKEND = 1, AXOVERLAY_OPENGLES_BACKEND = 2, AXOVERLAY_OPEN_BACKEND = 3 }

enum	axoverlay_anchor_point { AXOVERLAY_ANCHOR_TOP_LEFT, AXOVERLAY_ANCHOR_CENTER }

enum	axoverlay_stream_type { AXOVERLAY_STREAM_JPEG, AXOVERLAY_STREAM_H264, AXOVERLAY_STREAM_H265, AXOVERLAY_STREAM_YCBCR, AXOVERLAY_STREAM_VOUT, AXOVERLAY_STREAM_OTHER }

Functions
void	axoverlay_init_axoverlay_settings (struct axoverlay_settings *axoverlay_settings)

void	axoverlay_init (struct axoverlay_settings axoverlay_settings, GError *error)

void	axoverlay_cleanup (void)

void	axoverlay_reload_streams (GError **error)

void	axoverlay_redraw (GError **error)

void	axoverlay_init_overlay_data (struct axoverlay_overlay_data *data)

gint	axoverlay_create_overlay (struct axoverlay_overlay_data data, gpointer user_data, GError *error)

void	axoverlay_destroy_overlay (gint id, GError **error)

void	axoverlay_set_overlay_position (gint id, enum axoverlay_position_type postype, gfloat x, gfloat y, GError **error)

void	axoverlay_set_overlay_size (gint id, gint width, gint height, GError **error)

gint	axoverlay_get_max_resolution_width (gint camera, GError **error)

gint	axoverlay_get_max_resolution_height (gint camera, GError **error)

gboolean	axoverlay_is_backend_supported (enum axoverlay_backend_type backend)

gint	axoverlay_get_number_of_palette_colors (GError **error)

void	axoverlay_get_palette_color (gint index, struct axoverlay_palette_color color, GError *error)

void	axoverlay_set_palette_color (gint index, struct axoverlay_palette_color color, GError *error)

Detailed Description

Overlay helper library for creating and rendering custom overlays.

Author: Martin Danielsson

Date: 21 Feb 2019

axoverlay contains a number of functions that simplifies the task of creating and rendering custom overlays.

Macro Definition Documentation

◆ AXOVERLAY_DEFAULT_CAMERA_ID

#define AXOVERLAY_DEFAULT_CAMERA_ID 1

Id used for the default camera.

◆ AXOVERLAY_QUAD_CAMERA_ID

#define AXOVERLAY_QUAD_CAMERA_ID 0

Id used for the quad camera.

◆ AXOVERLAY_Z_PRIO_HIGH

#define AXOVERLAY_Z_PRIO_HIGH 2000

Predefined value for high z order priority.

◆ AXOVERLAY_Z_PRIO_LOW

#define AXOVERLAY_Z_PRIO_LOW 0

Predefined value for low z order priority.

◆ AXOVERLAY_Z_PRIO_MEDIUM

#define AXOVERLAY_Z_PRIO_MEDIUM 1000

Predefined value for medium z order priority.

◆ AXOVERLAY_Z_PRIO_VERY_HIGH

#define AXOVERLAY_Z_PRIO_VERY_HIGH 3000

Predefined value for very high z order priority.

Typedef Documentation

◆ axoverlay_adjustment_function

typedef void(* axoverlay_adjustment_function) (gint id, struct axoverlay_stream_data *stream, enum axoverlay_position_type *postype, gfloat *overlay_x, gfloat *overlay_y, gint *overlay_width, gint *overlay_height, gpointer user_data)

The purpose of this callback is to let developers make adjustments to the size and position of their overlays for each stream. This callback function is called prior to rendering every time when an overlay is rendered on a stream. This may happen when a stream opens/changes or when you manually force a redraw. If the size of the overlay differs between invokations it will be restarted and may flicker. It is adviced to keep the size constant for performance reasons.

Note that there is no need to modify the size of the overlay to match the stream resolution since the is done automatically unless scale_to_stream was set to FALSE when the overlay was created..

Parameters

id	The id of the overlay
stream	The stream that the overlay is displayed on
postype	The position type.
overlay_x	The x coordinate of the overlay, may be changed
overlay_y	The y coordinate of the overlay, may be changed
overlay_width	The width of the overlay, may be changed
overlay_height	The height of the overlay, may be changed
user_data	Optional user data associated with this overlay

◆ axoverlay_render_function

typedef void(* axoverlay_render_function) (gpointer rendering_context, gint id, struct axoverlay_stream_data *stream, enum axoverlay_position_type postype, gfloat overlay_x, gfloat overlay_y, gint overlay_width, gint overlay_height, gpointer user_data)

A callback function called whenever the system redraws an overlay. This can happen in two cases, axoverlay_redraw() is called or a new stream is started. In the first case the callback will execute in the thread that calls axoverlay_redraw() and in the second case it will execute in the thread that called axoverlay_init().

Parameters

rendering_context	A pointer to the rendering context used by the backend. For the Cairo backend ithas the type 'cairo_t'.
id	The id of the overlay
stream	Information about the stream that is currently being rendered to, usually you do not need this information unless you want to rotate your overlay when the stream is rotated.
postype	The position type.
overlay_x	The x coordinate of the overlay, may be changed
overlay_y	The y coordinate of the overlay, may be changed
overlay_width	The width of the overlay, may be changed
overlay_height	The height of the overlay, may be changed
user_data	Optional user data associated with this overlay

◆ axoverlay_stream_select_function

typedef gboolean(* axoverlay_stream_select_function) (gint camera, gint width, gint height, gint rotation, gboolean is_mirrored, enum axoverlay_stream_type type)

Callback that can be used to select which streams to render overlays to. Note that YCBCR streams are always skipped since these are used for analytics.

Parameters

camera	The id of the camera that the stream is for.
width	The width of the stream For further details see the comments for the stream_data struct.
height	The height of the stream For further details see the comments for the stream_data struct.
rotation	The rotation of the stream.
is_mirrored	TRUE if mirroring is enabled for the stream.

Returns: Returns TRUE if overlays should be rendered for the stream.

Enumeration Type Documentation

◆ axoverlay_anchor_point

enum axoverlay_anchor_point

This enum contains constants for the different anchor points of the overlay. All custom coordinates are fr the anchor point of the overlay. So the the nomalized position 0x0 menas that the top-left of the overlay is placed at 0x0 if anchor point is set to AXOVERLAY_ANCHOR_TOP_LEFT.

Enumerator
AXOVERLAY_ANCHOR_TOP_LEFT	Anchor point top-left
AXOVERLAY_ANCHOR_CENTER	Anchor center

◆ axoverlay_backend_type

enum axoverlay_backend_type

This enum contains the different backend types that are currrently supported by axoverlay.

Enumerator
AXOVERLAY_CAIRO_IMAGE_BACKEND	Cairo image backend
AXOVERLAY_OPENGLES_BACKEND	OpenGL ES backend
AXOVERLAY_OPEN_BACKEND	Open (raw pointer) backend

◆ axoverlay_colorspace

enum axoverlay_colorspace

This enum contains constants for the different types of colorspaces the overlays can be created with. ARGB32 is the default, however the 1/4 bit palette formats may also be used. Note that when using the palette formats only the alpha channel matters (when rendering with cairo) and you also need to set the palette colors manually using dbus-commands.

Enumerator
AXOVERLAY_COLORSPACE_ARGB32	ARGB32 color format
AXOVERLAY_COLORSPACE_4BIT_PALETTE	4-bit palette color format
AXOVERLAY_COLORSPACE_1BIT_PALETTE	1-bit palette color format
AXOVERLAY_COLORSPACE_UNDEFINED	Undefined color format

◆ axoverlay_error_code

enum axoverlay_error_code

Axoverlay error codes.

Enumerator
AXOVERLAY_ERROR_INVALID_VALUE	An invalid value was received from a callback function
AXOVERLAY_ERROR_INTERNAL	Internal error
AXOVERLAY_ERROR_UNEXPECTED	An unexpected error happened
AXOVERLAY_ERROR_GENERIC	Currently not used
AXOVERLAY_ERROR_INVALID_ARGUMENT	An invalid argument was passed to a function
AXOVERLAY_ERROR_SERVICE_UNAVAILABLE	The overlay service was not available
AXOVERLAY_ERROR_BACKEND	An error has occured in the axoverlay backend functionality

◆ axoverlay_position_type

enum axoverlay_position_type

This enum contains constants for the different position types. For the first four types any x and y coordinates specified are ignored.

If the type is set to AXOVERLAY_CUSTOM_NORMALIZED then x and y coordinates should be normalized between -1 and 1.
If the type is set to AXOVERLAY_CUSTOM_SOURCE then the overlay will be placed relative to the video source and not the video frame. If DPTZ is used the overlay will remain locked to the scene and not the video frame. Coordinates should be between 0 and max witdh and max height respectivly. In case the video is rotated the coordinates have be transformed to an unrotated coordinate system.

Enumerator
AXOVERLAY_TOP_LEFT	Top-left position
AXOVERLAY_TOP_RIGHT	Top-right position
AXOVERLAY_BOTTOM_LEFT	Bottom-left position
AXOVERLAY_BOTTOM_RIGHT	Bottom-right position
AXOVERLAY_CUSTOM_NORMALIZED	Custom position normalized between [-1, 1]
AXOVERLAY_CUSTOM_SOURCE	Custom position in absolute coordinates relative to the max resolution

Function Documentation

◆ axoverlay_cleanup()

void axoverlay_cleanup ( void )

Frees up allocated resources.

◆ axoverlay_create_overlay()

gint axoverlay_create_overlay	(	struct axoverlay_overlay_data *	data,
		gpointer	user_data,
		GError **	error
	)

Creates an overlay at the specified position. The overlay will be rendered once for each stream.

Note that this function does not cause the overlay to be drawn. To get the the overlay to show you have to call axoverlay_redraw().

Parameters

data	Description of the overlay to create.
user_data	Pointer to optional user data associated with this overlay. The user data pointer will be passed to the adjust and render callbacks
error	Location to store potential error at.

Returns: Returns the id of the overlay. It is used when removing overlays and can be used in the render function to differentiate overlays.

◆ axoverlay_destroy_overlay()

void axoverlay_destroy_overlay	(	gint	id,
		GError **	error
	)

Destroys the overlay with the given id if it exists.

Note that this functions will trigger a redraw of all overlays on all streams.

Parameters

id	The id of the overlay to destroy. This would be the id returned by the axoverlay_create_overlay() function.
error	Location to store potential error at.

◆ axoverlay_get_max_resolution_height()

gint axoverlay_get_max_resolution_height	(	gint	camera,
		GError **	error
	)

Reads the width of the camera's base resolution.

Parameters

camera	The camera to get resolution for.
error	Location to store potential error at.

Returns: Returns the width of the camera's base resolution.

◆ axoverlay_get_max_resolution_width()

gint axoverlay_get_max_resolution_width	(	gint	camera,
		GError **	error
	)

Reads the width of the camera's base resolution.

Parameters

camera	The camera to get resolution for.
error	Location to store potential error at.

Returns: Returns the width of the camera's base resolution.

◆ axoverlay_get_number_of_palette_colors()

gint axoverlay_get_number_of_palette_colors ( GError ** error )

Get the number of palette colors.

Parameters

error Location to store potential error at.

Returns: Returns the number of palette colors.

◆ axoverlay_get_palette_color()

void axoverlay_get_palette_color	(	gint	index,
		struct axoverlay_palette_color *	color,
		GError **	error
	)

Get the palette color with a specific index.

Parameters

index	The index of the color to get.
color	Location to store the returned color at.
error	Location to store potential error at.

◆ axoverlay_init()

void axoverlay_init	(	struct axoverlay_settings *	axoverlay_settings,
		GError **	error
	)

Initializes the axoverlay system. This function must be called before any other axoverlay function. The thread that calls this function must have a glib main-loop.

Parameters

axoverlay_settings	A setting struct where general callbacks.
error	Location to store potential error at.

◆ axoverlay_init_axoverlay_settings()

void axoverlay_init_axoverlay_settings ( struct axoverlay_settings * axoverlay_settings )

Initializes an axoverlay_settings struct with default values;

◆ axoverlay_init_overlay_data()

void axoverlay_init_overlay_data ( struct axoverlay_overlay_data * data )

Initialize an overlay_data struct with default values.

Parameters

data	The struct to initialize.

◆ axoverlay_is_backend_supported()

gboolean axoverlay_is_backend_supported ( enum axoverlay_backend_type backend )

Enables for axoverlay user to check if the intended backend to be used is supported.

◆ axoverlay_redraw()

void axoverlay_redraw ( GError ** error )

Signals to the system that a redraw should be done. This will in turn call the render function provided in axoverlay_init().

Parameters

error Location to store potential error at.

◆ axoverlay_reload_streams()

void axoverlay_reload_streams ( GError ** error )

Reload all stream information. All information about running streams will be cleared and loaded again. The select callback will be invoked for each stream.

Note that all overlays will disappear for a short while since they are destroyed and then created again.

Parameters

error Location to store potential error at.

◆ axoverlay_set_overlay_position()

void axoverlay_set_overlay_position	(	gint	id,
		enum axoverlay_position_type	postype,
		gfloat	x,
		gfloat	y,
		GError **	error
	)

Updates the position of the overlay with the given id if it exists. Calling this function will not trigger the overlay to be redrawn. The new position will be applied the next time axoverlay_redraw() is called.

Parameters

id	The id of the overlay.
postype	The postion type. This parameter controls how the x and y parameters are interpreted. See documentation of position_type for details.
x	The x position of the top-left corner of the overlay.
y	The y position of the top-left corner of the overlay.
error	Location to store potential error at.

◆ axoverlay_set_overlay_size()

void axoverlay_set_overlay_size	(	gint	id,
		gint	width,
		gint	height,
		GError **	error
	)

Updates the size of the overlay with the given id if it exists. Calling this function will not trigger the overlay to be redrawn. The new size will be applied the next time axoverlay_redraw() is called.

Parameters

id	The id of the overlay.
width	The width of the overlay in pixels.
height	The height of the overlay in pixels.
error	Location to store potential error at.

◆ axoverlay_set_palette_color()

void axoverlay_set_palette_color	(	gint	index,
		struct axoverlay_palette_color *	color,
		GError **	error
	)

Set the palette color with a specific index.

Parameters

index	The index of the color to set.
color	The color to set.
error	Location to store potential error at.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ AXOVERLAY_DEFAULT_CAMERA_ID

◆ AXOVERLAY_QUAD_CAMERA_ID

◆ AXOVERLAY_Z_PRIO_HIGH

◆ AXOVERLAY_Z_PRIO_LOW

◆ AXOVERLAY_Z_PRIO_MEDIUM

◆ AXOVERLAY_Z_PRIO_VERY_HIGH

Typedef Documentation

◆ axoverlay_adjustment_function

◆ axoverlay_render_function

◆ axoverlay_stream_select_function

Enumeration Type Documentation

◆ axoverlay_anchor_point

◆ axoverlay_backend_type

◆ axoverlay_colorspace

◆ axoverlay_error_code

◆ axoverlay_position_type

Function Documentation

◆ axoverlay_cleanup()

◆ axoverlay_create_overlay()

◆ axoverlay_destroy_overlay()

◆ axoverlay_get_max_resolution_height()

◆ axoverlay_get_max_resolution_width()

◆ axoverlay_get_number_of_palette_colors()

◆ axoverlay_get_palette_color()

◆ axoverlay_init()

◆ axoverlay_init_axoverlay_settings()

◆ axoverlay_init_overlay_data()

◆ axoverlay_is_backend_supported()

◆ axoverlay_redraw()

◆ axoverlay_reload_streams()

◆ axoverlay_set_overlay_position()

◆ axoverlay_set_overlay_size()

◆ axoverlay_set_palette_color()