Overlay (Watermark)
[Video Filters]


Detailed Description

The overlay video filter is a filter used to apply a PNG image to the output video. In addition this filter supports positioning the overlay and treating sections of the image as transparent either by specifying a pixel of the image to use as a reference, specifying a RGB value to use as a reference or using the alpha channel of the image.

Filter Parameters:

   Name                                |   Type   | Opt/Reqd |    Range
   =======================================================================================
   FE2_OVERLAY_FILE                    | String   | Required | N/A
   FE2_OVERLAY_MASK_XY                 | Boolean  | Optional | [on2false,on2true]
   FE2_OVERLAY_MASK_X                  | Numeric  | Optional | [0,video width)
   FE2_OVERLAY_MASK_Y                  | Numeric  | Optional | [0,video height)
   FE2_OVERLAY_MASK_RGB                | Boolean  | Optional | [on2false,on2true]
   FE2_OVERLAY_MASK_R                  | Numeric  | Optional | [0,255]
   FE2_OVERLAY_MASK_G                  | Numeric  | Optional | [0,255]
   FE2_OVERLAY_MASK_B                  | Numeric  | Optional | [0,255]
   FE2_OVERLAY_POS                     | Numeric  | Optional | [FE2_OverlayPositionMode]
   FE2_OVERLAY_POS_X                   | Numeric  | Optional | [0,video width)
   FE2_OVERLAY_POS_Y                   | Numeric  | Optional | [0,video height)

Example Usage:

   sc = Flix2_AddFilter(&filter, flix, FE2_FILTER_OVERLAY);
   //apply image.png to the top left of the output video
   if(sc == ON2_OK)
       sc = Flix2_FilterSetParamAsStr(filter, FE2_OVERLAY_FILE, "/tmp/image.png");


Deprecated functions

on2sc overlay_options_Reset (const FLIX2HANDLE flix)
 Resets the overlay options.
on2sc overlay_options_GetUseOverlay (const FLIX2HANDLE flix, on2bool *pUseOverlay)
 Determines if an overlay is to be used.
on2sc overlay_options_SetUseOverlay (FLIX2HANDLE flix, const on2bool bUseOverlay)
 Enables or disables overlay usage.
on2sc overlay_options_GetOverlayPath (const FLIX2HANDLE flix, on2tc *pOverlayFilePath, int32_t *pLen)
 Returns the path to the overlay image file.
on2sc overlay_options_SetOverlayPath (FLIX2HANDLE flix, const on2tc *pOverlayFilePath)
 Set the path to the overlay image file.
on2sc overlay_options_GetMaskPixelXY (const FLIX2HANDLE flix, int32_t *pMaskPixelX, int32_t *pMaskPixelY)
 Return the X and Y coordinates of the mask pixel.
on2sc overlay_options_SetMaskPixelXY (FLIX2HANDLE flix, int32_t maskPixelX, int32_t maskPixelY)
 Set the X and Y coordinates of the mask pixel.
on2sc overlay_options_GetMaskPixelRGB (FLIX2HANDLE flix, uint8_t *pMaskPixelR, uint8_t *pMaskPixelG, uint8_t *pMaskPixelB)
 Return the Red, Green, and Blue component values of the mask pixel.
on2sc overlay_options_SetMaskPixelRGB (FLIX2HANDLE flix, uint8_t maskPixelR, uint8_t maskPixelG, uint8_t maskPixelB)
 Set the Red, Green, and Blue component values of the mask pixel.
on2sc overlay_options_GetOverlayPosition (FLIX2HANDLE flix, FE2_OverlayPositionMode *pMode, uint32_t *pX, uint32_t *pY)
 Return the overlay position.
on2sc overlay_options_SetOverlayPosition (FLIX2HANDLE flix, FE2_OverlayPositionMode mode, uint32_t x, uint32_t y)
 Set the overlay position.

Defines

#define FE2_FILTER_OVERLAY
 Filter name for use with Flix2_AddFilter().
#define FE2_OVERLAY_FILE
 Set the path to the overlay image file.
#define FE2_OVERLAY_MASK_XY
 Use the pixel at coordinates (FE2_OVERLAY_MASK_X,FE2_OVERLAY_MASK_Y) to determine the transparent color.
#define FE2_OVERLAY_MASK_X
 X coordinate of pixel to use for transparency.
#define FE2_OVERLAY_MASK_Y
 Y coordinate of pixel to use for transparency.
#define FE2_OVERLAY_MASK_RGB
 Use the RGB value (FE2_OVERLAY_MASK_R, FE2_OVERLAY_MASK_G, FE2_OVERLAY_MASK_B) as the transparency color.
#define FE2_OVERLAY_MASK_R
 Red component of the transparency color.
#define FE2_OVERLAY_MASK_G
 Green component of the transparency color.
#define FE2_OVERLAY_MASK_B
 Blue component of the transparency color.
#define FE2_OVERLAY_POS
 Set the overlay position. Valid modes are defined by FE2_OverlayPositionMode.
#define FE2_OVERLAY_POS_X
 X coordinate of overlay top left on video.
#define FE2_OVERLAY_POS_Y
 Y coordinate of overlay top left on video.

Enumerations

enum  FE2_OverlayPositionMode {
  FE2_OVERLAY_POS_MODE_TOPLEFT,
  FE2_OVERLAY_POS_MODE_BOTLEFT,
  FE2_OVERLAY_POS_MODE_CENTER,
  FE2_OVERLAY_POS_MODE_TOPRIGHT,
  FE2_OVERLAY_POS_MODE_BOTRIGHT,
  FE2_OVERLAY_POS_MODE_XY
}
 Position modes for use with FE2_OVERLAY_POS. More...

Define Documentation

#define FE2_FILTER_OVERLAY

Filter name for use with Flix2_AddFilter().

Definition at line 76 of file overlay.h.

#define FE2_OVERLAY_FILE

Set the path to the overlay image file.

Remarks:
Only PNG images, 24 bit bitmaps, and 32 bit bitmaps are supported. Use of PNG images is highly recommended.
Images with an uneven width or uneven height will be cropped.
Overlay images larger than the video image will be cropped.
When both the video and overlay images contain an alpha channel, the overlay and video alpha will be averaged. For example, if the video at the overlay position was fully transparent, and the overlay was fully opaque, the region of the exported video where the overlay was placed would become 50% opaque.
Note:
Linux Only: flixd, the encoding server, gets its input from, and writes its output to, the host file system. FE2_OVERLAY_FILE must be accessible in this context. An absolute path should be given to help ensure this is the case.
See also:
Flix2_SetInputFile()

Definition at line 96 of file overlay.h.

#define FE2_OVERLAY_MASK_B

Blue component of the transparency color.

Remarks:
Default value: 0
Note:
Only used if FE2_OVERLAY_MASK_RGB is set to on2true

Definition at line 156 of file overlay.h.

#define FE2_OVERLAY_MASK_G

Green component of the transparency color.

Remarks:
Default value: 0
Note:
Only used if FE2_OVERLAY_MASK_RGB is set to on2true

Definition at line 150 of file overlay.h.

#define FE2_OVERLAY_MASK_R

Red component of the transparency color.

Remarks:
Default value: 0
Note:
Only used if FE2_OVERLAY_MASK_RGB is set to on2true

Definition at line 144 of file overlay.h.

#define FE2_OVERLAY_MASK_RGB

Use the RGB value (FE2_OVERLAY_MASK_R, FE2_OVERLAY_MASK_G, FE2_OVERLAY_MASK_B) as the transparency color.

Remarks:
The color specified will become transparent when the overlay image is drawn on the video image.
Setting this parameter will disable FE2_OVERLAY_MASK_XY if it has been set.
Using a PNG or bitmap with full alpha channel will produce better results than using a transparency color.
If using this method to add an overlay to video with an existing alpha channel, the transparent portions of the overlay will be transparent in the output video. Opaque portions of the overlay will be averaged with the existing alpha data.

Definition at line 138 of file overlay.h.

#define FE2_OVERLAY_MASK_X

X coordinate of pixel to use for transparency.

Remarks:
Default value: 0

Definition at line 117 of file overlay.h.

#define FE2_OVERLAY_MASK_XY

Use the pixel at coordinates (FE2_OVERLAY_MASK_X,FE2_OVERLAY_MASK_Y) to determine the transparent color.

Remarks:
The color at the specified coordinate will become transparent when the overlay image is drawn on the video image.
Setting this parameter will disable FE2_OVERLAY_MASK_RGB if it has been set.
Using a PNG or bitmap with full alpha channel will produce better results than using a transparency color.
If using this method to add an overlay to video with an existing alpha channel, the transparent portions of the overlay will be transparent in the output video. Opaque portions of the overlay will be averaged with the existing alpha data.

Definition at line 112 of file overlay.h.

#define FE2_OVERLAY_MASK_Y

Y coordinate of pixel to use for transparency.

Remarks:
Default value: 0

Definition at line 122 of file overlay.h.

#define FE2_OVERLAY_POS

Set the overlay position. Valid modes are defined by FE2_OverlayPositionMode.

Remarks:
If the mode is equal to FE2_OVERLAY_POS_MODE_XY, and either coordinate value is invalid (x > video width or y > video height), the invalid coordinate will be set to 0.
If the value of the x and/or y coordinates cause any portion of the overlay to be outside of the video image bounds, the portion of the overlay image that is out of bounds will be cropped. Default: FE2_OVERLAY_POS_MODE_TOPLEFT

Definition at line 169 of file overlay.h.

#define FE2_OVERLAY_POS_X

X coordinate of overlay top left on video.

Note:
value is only used when FE2_OVERLAY_POS has been set to FE2_OVERLAY_POS_MODE_XY

Definition at line 175 of file overlay.h.

#define FE2_OVERLAY_POS_Y

Y coordinate of overlay top left on video.

Note:
value is only used when FE2_OVERLAY_POS has been set to FE2_OVERLAY_POS_MODE_XY

Definition at line 181 of file overlay.h.


Enumeration Type Documentation

Position modes for use with FE2_OVERLAY_POS.

Enumerator:
FE2_OVERLAY_POS_MODE_TOPLEFT  draw overlay image on the top left corner of the video
FE2_OVERLAY_POS_MODE_BOTLEFT  draw overlay image on the bottom left corner of the video
FE2_OVERLAY_POS_MODE_CENTER  draw overlay image on the center of the video
FE2_OVERLAY_POS_MODE_TOPRIGHT  draw overlay image on the top right corner of the video
FE2_OVERLAY_POS_MODE_BOTRIGHT  draw overlay image on the bottom right corner of the video
FE2_OVERLAY_POS_MODE_XY  draw overlay image on the video at the x and y coordinates specified

Definition at line 57 of file overlay.h.


Function Documentation

on2sc overlay_options_GetMaskPixelRGB ( FLIX2HANDLE  flix,
uint8_t pMaskPixelR,
uint8_t pMaskPixelG,
uint8_t pMaskPixelB 
)

Return the Red, Green, and Blue component values of the mask pixel.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pMaskPixelR pointer to variable that will receive the R value
[out] pMaskPixelG pointer to variable that will receive the G value
[out] pMaskPixelB pointer to variable that will receive the B value
Return values:
ON2_OK the color component values were retrieved successfully
ON2_INVALID_PARAMS a precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pMaskPixelR is not NULL
pMaskPixelG is not NULL
pMaskPixelB is not NULL
Remarks:
This method returns the values set in previous call to overlay_options_SetMaskPixelRGB(), if no coordinates were previously set, the Red, Green, and Blue component values will be set to 0.
Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_MASK_R, FE2_OVERLAY_MASK_G and FE2_OVERLAY_MASK_B parameters. This function will be removed in a future release.

on2sc overlay_options_GetMaskPixelXY ( const FLIX2HANDLE  flix,
int32_t pMaskPixelX,
int32_t pMaskPixelY 
)

Return the X and Y coordinates of the mask pixel.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pMaskPixelX pointer to variable that will receive the X value
[out] pMaskPixelY pointer to variable that will receive the Y value
Return values:
ON2_OK the coordinate values were retrieved successfully
ON2_INVALID_PARAMS a precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pMaskPixelX is not NULL
pMaskPixelY is not NULL
Remarks:
This method returns the values set in previous call to overlay_options_SetMaskPixelXY(), if no coordinates were previously set, the X and Y coordinate values will be set to 0.

The color at the specified coordinate will become transparent when the overlay image is drawn on the video image.

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_MASK_X and FE2_OVERLAY_MASK_Y parameters. This function will be removed in a future release.

on2sc overlay_options_GetOverlayPath ( const FLIX2HANDLE  flix,
on2tc pOverlayFilePath,
int32_t pLen 
)

Returns the path to the overlay image file.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pOverlayFilePath string that will receive the file path
[in,out] pLen length of pOverlayFilePath
Return values:
ON2_OK success
ON2_INVALID_PARAMS a precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pLen is not NULL
Remarks:
if pOverlayFilePath is not NULL, the value pointed to by pLen must be set to the maximum number of characters that can be written to pOverlayFilePath.

If pOverlayFilePath is NULL, pLen will be set to the length of the path to the overlay image

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_FILE parameter. This function will be removed in a future release.

on2sc overlay_options_GetOverlayPosition ( FLIX2HANDLE  flix,
FE2_OverlayPositionMode pMode,
uint32_t pX,
uint32_t pY 
)

Return the overlay position.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pMode pointer to variable that will receive the mode value
[out] pX pointer to variable that will receive the X value
[out] pY pointer to variable that will receive the Y value
Return values:
ON2_OK the values were retrieved successfully
ON2_INVALID_PARAMS a precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pMode is not NULL
pX is not NULL
pY is not NULL
Remarks:
This method returns the values set in previous call to overlay_options_SetOverlayPosition(), if no call was made previously, mode will default to FE2_OVERLAY_POS_MODE_TOPLEFT. The X/Y coordinates will default to 0.
Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_POS, FE2_OVERLAY_POS_X, FE2_OVERLAY_POS_Y parameters. This function will be removed in a future release.

on2sc overlay_options_GetUseOverlay ( const FLIX2HANDLE  flix,
on2bool pUseOverlay 
)

Determines if an overlay is to be used.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] pUseOverlay pointer to the on2bool variable that will receive the usage state
Return values:
ON2_OK pUseOverlay was set successfully
ON2_INVALID_PARAMS a precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pUseOverlay is not NULL
Remarks:
Call this function to determine if an overlay is to be drawn on the encoded video output.
Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY. This function will be removed in a future release.

on2sc overlay_options_Reset ( const FLIX2HANDLE  flix  ) 

Resets the overlay options.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
Return values:
ON2_OK reset of overlay options was successful
ON2_INVALID_PARAMS the precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Remarks:
Call this function if you wish to reset all overlay options to their default values.
Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY. This function will be removed in a future release.

on2sc overlay_options_SetMaskPixelRGB ( FLIX2HANDLE  flix,
uint8_t  maskPixelR,
uint8_t  maskPixelG,
uint8_t  maskPixelB 
)

Set the Red, Green, and Blue component values of the mask pixel.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] maskPixelR the R component value
[in] maskPixelG the G component value
[in] maskPixelB the B component value
Return values:
ON2_OK the component values were set successfully
ON2_INVALID_PARAMS the precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Remarks:
The color specified will become transparent when the overlay image is drawn on the video image.

Once this function has been called successfully, overlay_options_Reset() must be called to turn transparency off.

Calling this method will disable masking based on XY coordinate.

Using a PNG or bitmap with full alpha channel will produce better results than using a transparency color.

If using this method to add an overlay to video with an existing alpha channel, the transparent portions of the overlay will be transparent in the output video. Opaque portions of the overlay will be averaged with the existing alpha data.

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_MASK_R, FE2_OVERLAY_MASK_G and FE2_OVERLAY_MASK_B parameters. This function will be removed in a future release.

on2sc overlay_options_SetMaskPixelXY ( FLIX2HANDLE  flix,
int32_t  maskPixelX,
int32_t  maskPixelY 
)

Set the X and Y coordinates of the mask pixel.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] maskPixelX the X coordinate value
[in] maskPixelY the Y coordinate value
Return values:
ON2_OK the coordinate values were set successfully
ON2_INVALID_PARAMS the precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Remarks:
The color at the specified coordinate will become transparent when the overlay image is drawn on the video image.

Once this function has been called successfully, overlay_options_Reset() must be called to turn transparency off.

Calling this method will disable masking based on RGB components.

Using a PNG or bitmap with full alpha channel will produce better results than using a transparency color.

If using this method to add an overlay to video with an existing alpha channel, the transparent portions of the overlay will be transparent in the output video. Opaque portions of the overlay will be averaged with the existing alpha data.

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_MASK_X and FE2_OVERLAY_MASK_Y parameters. This function will be removed in a future release.

on2sc overlay_options_SetOverlayPath ( FLIX2HANDLE  flix,
const on2tc pOverlayFilePath 
)

Set the path to the overlay image file.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] pOverlayFilePath the path to the overlay image
Return values:
ON2_OK the path to the overlay image was set successfully
ON2_INVALID_PARAMS a precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
pOverlayFilePath is not NULL
Remarks:
This method does not check for the existence of the file at the specified path.

Only PNG images, 24 bit bitmaps, and 32 bit bitmaps are supported. Use of PNG images is highly recommended.

Images with an uneven width or uneven height will be cropped.

Overlay images larger than the video image will be cropped.

When both the video and overlay images contain an alpha channel, the overlay and video alpha will be averaged. For example, if the video at the overlay position was fully transparent, and the overlay was fully opaque, the region of the exported video where the overlay was placed would become 50% opaque.

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_FILE parameter. This function will be removed in a future release.

on2sc overlay_options_SetOverlayPosition ( FLIX2HANDLE  flix,
FE2_OverlayPositionMode  mode,
uint32_t  x,
uint32_t  y 
)

Set the overlay position.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[out] mode the position mode
[out] x the x coordinate value
[out] y the y coordinate value
Return values:
ON2_OK success
ON2_INVALID_PARAMS the precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is not NULL
Remarks:
The x and y values are ignored unless mode is equal to FE2_OVERLAY_POS_MODE_XY.

If mode is equal to FE2_OVERLAY_POS_MODE_XY, and either coordinate value is invalid (x > video width or y > video height), the invalid coordinate will be set to 0.

If the the value of the x and/or y coordinates cause any portion of the overlay to be outside of the video image bounds, the portion of the overlay image that is out of bounds will be cropped.

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY and the FE2_OVERLAY_POS, FE2_OVERLAY_POS_X, FE2_OVERLAY_POS_Y parameters. This function will be removed in a future release.

on2sc overlay_options_SetUseOverlay ( FLIX2HANDLE  flix,
const on2bool  bUseOverlay 
)

Enables or disables overlay usage.

Parameters:
[in] flix Handle to the flix engine returned from Flix2_Create() or Flix2_CreateEx()
[in] bUseOverlay on2bool value set to the desired overlay state
Return values:
ON2_OK the overlay status was changed successfully
ON2_INVALID_PARAMS the precondition failed
ON2_NET_ERROR the underlying communication layer failed
Precondition:
flix is NULL
Remarks:
Set bUseOverlay to on2true to enable overlay usage. Set bUseOverlay to on2false to disable usage.

Only PNG images, 24 bit bitmaps, and 32 bit bitmaps are supported. Use of PNG images is highly recommended.

Images with an uneven width or uneven height will be cropped.

Overlay images larger than the video image will be cropped.

When both the video and overlay images contain an alpha channel, the overlay and video alpha will be averaged. For example, if the video at the overlay position was fully transparent, and the overlay was fully opaque, the region of the exported video where the overlay was placed would become 50% opaque.

Deprecated:
Use the Filter Interface along with FE2_FILTER_OVERLAY. This function will be removed in a future release.


On2 Technologies, Inc Flix Engine Linux documentation, generated on Tue Nov 2 16:53:00 2010 by doxygen 1.5.5