Skip to content

Text overlays

Text over video frames

Each text overlay is identified by its index, passed as the first parameter of the SetTextOverlay... and GetTextOverlay... functions: index 0 for the 1st text overlay, index 1 for the 2nd text overlay, etc.

To draw a text overlay over the video frames:

E.g., frame number drawn in the top-left corner by the 1st text overlay (index 0):

VideoGrabber.SetTextOverlay_String (0, "frame number: %frame_count%")
VideoGrabber.SetTextOverlay_Left (0, 10)
VideoGrabber.SetTextOverlay_Top (0, 10)
VideoGrabber.SetTextOverlay_FontSize (0, 12)
VideoGrabber.SetTextOverlay_Transparent (0, true)
VideoGrabber.SetTextOverlay_Enabled (0, true)

A shadow can be drawn under the text overlay when SetTextOverlay_Shadow is enabled, according to the SetTextOverlay_ShadowDirection and SetTextOverlay_ShadowColor values.

Text overlays on 4K / 8K videos

The font size and the positions of a text overlay are given in pixels of the video, so the same font size looks 4 times smaller on an 8K video than on a 1080p video.

Enable SetTextOverlay_Proportional (Index, true) to give the font size, the Left, Top and Right positions and the scrolling speed for a video of 1080 lines: they are scaled to the height of the video (x2 for a 4K video, x4 for an 8K video, x2/3 for a 720-line video), and the text keeps the same size relative to the picture whatever the video resolution.

Performance: a text that does not change is rendered once, then blended into each frame. A text whose variables change on every frame (%frame_count%, %time_full%, %time_sec%, %time_100ns%...) is drawn again on every frame, which costs several ms per frame on 4K / 8K videos: prefer a fixed text, or variables that change once per second (e.g. %sys_time[hh:nn:ss]%).

See also 4K and 8K playback.

Alpha blending

To enable the alpha blending of a text overlay:

Text scrolling

The text scrolling is activated by SetTextOverlay_Scrolling (Index, true). The scrolling speed is adjusted with SetTextOverlay_ScrollingSpeed (Index, Speed):

  • Speed > 0: scrolling from right to left,
  • Speed < 0: scrolling from left to right,
  • Speed = 0: stops the scrolling.

When the scrolling is completed (when the last character disappears from the video frame), the OnTextOverlayScrollingCompleted event occurs. Its TextOverlayIndex parameter returns the index of the related text overlay (0 for the 1st text overlay, 1 for the 2nd, etc.).

Custom fonts

A fully customized font can be created by invoking TextOverlay_CreateCustomFont (Index, ...): the parameters after the index are those of the Windows CreateFont function.

E.g., Wingdings font for the 1st text overlay (index 0):

VideoGrabber.TextOverlay_CreateCustomFont (0, 16, 30, 0, 0, 200, true, false, false, 2, 0, 0, 0, 0, "Wingdings")

Using several text overlays, each one having its own font / color / background

Up to 1000 text overlays can be drawn at the same time over the video frames, each one with its own string, font, colors, location, etc. Pass the index of the text overlay as the first parameter of the SetTextOverlay... functions.

E.g., frame number in the top-left corner for the 1st text overlay (index 0):

VideoGrabber.SetTextOverlay_String (0, "frame number: %frame_count%")
VideoGrabber.SetTextOverlay_Left (0, 10)
VideoGrabber.SetTextOverlay_Top (0, 10)
VideoGrabber.SetTextOverlay_FontSize (0, 12)
VideoGrabber.SetTextOverlay_Transparent (0, true)
VideoGrabber.SetTextOverlay_Enabled (0, true)

Frame time in the top-right corner, on an opaque background, for the 2nd text overlay (index 1):

VideoGrabber.SetTextOverlay_String (1, "frame time: %time_100ns%")
VideoGrabber.SetTextOverlay_Left (1, VideoGrabber.VideoWidth - 120)
VideoGrabber.SetTextOverlay_Right (1, VideoGrabber.VideoWidth)
VideoGrabber.SetTextOverlay_Top (1, 60)
VideoGrabber.SetTextOverlay_FontSize (1, 8)
VideoGrabber.SetTextOverlay_Transparent (1, false)
VideoGrabber.SetTextOverlay_Enabled (1, true)

Hiding the frame time drawn by the 2nd text overlay (index 1):

VideoGrabber.SetTextOverlay_Enabled (1, false)

Note

TVideoGrabber does not allocate the resources of the 1000 text overlays at startup. The font and the settings of a text overlay are allocated the first time its index is used, together with all the lower indexes not yet allocated.

E.g. if the text overlays 0 to 4 are already allocated and the index 20 is used, the text overlays 5 to 20 are allocated as well (16 new fonts and parameter sets, for a total of 21).

So use consecutive indexes starting at 0: e.g. for 5 different text overlays, use the indexes 0 to 4 and never a greater index, to prevent allocating useless fonts and parameter sets.