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:
- set the text string to write with SetTextOverlay_String (string options),
- set the font with SetTextOverlay_Font, its color with SetTextOverlay_FontColor, and only its size with SetTextOverlay_FontSize,
- set the text transparency with SetTextOverlay_Transparent,
- set the background color with SetTextOverlay_BkColor (useful only when SetTextOverlay_Transparent is disabled),
- set the text alignment with SetTextOverlay_Align,
- set the text location with SetTextOverlay_Left, SetTextOverlay_Right and SetTextOverlay_Top,
- invoke SetTextOverlay_Enabled to activate the text overlay.
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:
- enable SetTextOverlay_AlphaBlend,
- set SetTextOverlay_AlphaBlendValue to a transparency value in the 0..255 range.
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.