Skip to content

Image overlays

Overview

It is possible to overlay one or several images at the same time over the video frames. Each image overlay is identified by its index, passed as the first parameter to the SetImageOverlay... and GetImageOverlay... functions: index 0 for the 1st image overlay, index 1 for the 2nd image overlay, etc. (see Setting and retrieving the overlay properties).

The origin of the image can be:

  • an image file
  • a bitmap handle
  • a TImage component (Delphi and C++Builder only)
  • a TBitmap component (Delphi and C++Builder only)

For image files, the following formats are supported: BMP, GIF, JPEG, EXIF, PNG, TIFF, WMF, EMF, EMF+, EMF+ Dual.

Unlike the logo, which is displayed in the video window when the component is not running, the image is overlaid on the video frames when the component is previewing, recording or playing back.

Source of the image overlay

The image is loaded into the image overlay specified by Index (0 for the 1st image overlay, 1 for the 2nd, etc.) by invoking:

Activation / deactivation

The image overlay can be enabled or disabled on the fly by SetImageOverlay_Enabled (Index, Value).

Location

The x, y location of the overlay over the video frames is specified by SetImageOverlay_LeftLocation and SetImageOverlay_TopLocation.

  • the left location must be in the [0..video width] range
  • the top location must be in the [0..video height] range

Size

The size (in pixels) to which the image is stretched is specified by SetImageOverlay_Width and SetImageOverlay_Height.

  • to use the real width of the image, set the width to -1 (default)
  • to use the real height of the image, set the height to -1 (default)

Stretching the image overlay to the video size

When SetImageOverlay_StretchToVideoSize is enabled, the image overlay is stretched to the video size (in this case the location, width and height settings above are ignored).

Alpha blending (semi-transparency)

Color-based transparency

So the alpha channel of a PNG file is taken into account only when SetImageOverlay_Transparent (Index, true) is enabled: otherwise its transparent pixels are drawn with their own color (usually black).

The transparency can be combined with the alpha blending, e.g. to make a PNG with alpha channel semi-transparent as a whole.

Other settings

Each setting can be read back by the corresponding GetImageOverlay... (Index) function, e.g. GetImageOverlay_TopLocation (1) for the 2nd image overlay (index 1).

Setting the main attributes in a single call

SetImageOverlay_Attributes2 (Index, LeftLocation, TopLocation, StretchedWidth, StretchedHeight, Transparent_Enabled, UseTransparentColor, Transparent_ColorValue, AlphaBlend_Enabled, AlphaBlend_Value) sets the location, size, color-based transparency and alpha blending of the image overlay specified by Index in a single call, instead of setting them one by one.

Applying several image overlays concurrently

Each image overlay is identified by its index, passed as the first parameter of the SetImageOverlay... and GetImageOverlay... functions: index 0 for the 1st image overlay, index 1 for the 2nd image overlay, and so on.

Up to 1000 image overlays can be used concurrently. This is a theoretical limit: the resources of an image overlay are allocated the first time its index is used, together with all the lower indexes not yet allocated, so use consecutive indexes starting at 0 (e.g. 0, 1 and 2 for 3 image overlays).

E.g.:

  • loading and showing myimage1.jpg for the 1st overlay (index 0):
VideoGrabber.SetImageOverlayFromImageFile2 (0, "myimage1.jpg")
VideoGrabber.SetImageOverlay_Enabled (0, true)
  • loading and showing myimage2.png at the (10, 20) location with its real size for the 2nd overlay (index 1):
VideoGrabber.SetImageOverlayFromImageFile2 (1, "myimage2.png")
VideoGrabber.SetImageOverlay_LeftLocation (1, 10)
VideoGrabber.SetImageOverlay_TopLocation (1, 20)
VideoGrabber.SetImageOverlay_Width (1, -1)
VideoGrabber.SetImageOverlay_Height (1, -1)
VideoGrabber.SetImageOverlay_Enabled (1, true)
  • hiding myimage1.jpg, displayed by the 1st overlay (index 0):
VideoGrabber.SetImageOverlay_Enabled (0, false)
  • moving myimage2.png, displayed by the 2nd overlay (index 1), to the (40, 60) location and resizing it to 120x90:
VideoGrabber.SetImageOverlay_LeftLocation (1, 40)
VideoGrabber.SetImageOverlay_TopLocation (1, 60)
VideoGrabber.SetImageOverlay_Width (1, 120)
VideoGrabber.SetImageOverlay_Height (1, 90)
  • showing myimage1.jpg again, semi-transparent, for the 1st overlay (index 0):
VideoGrabber.SetImageOverlay_AlphaBlend (0, true)
VideoGrabber.SetImageOverlay_AlphaBlendValue (0, 140)
VideoGrabber.SetImageOverlay_Enabled (0, true)
  • the same settings for the 2nd overlay (index 1) in a single call, with SetImageOverlay_Attributes2 (location, size, color-based transparency, alpha blending):
VideoGrabber.SetImageOverlay_Attributes2 (1, 40, 60, 120, 90, false, false, 0, false, 0)