Skip to content

Frame capture features

Frame capture

It is possible to capture video frames during preview, recording and playback when the frame grabber is enabled.
The frame grabber can be inserted on the preview stream, capture stream, or both. See the FrameGrabber property.
In the evaluation version the frame grabber is always inserted on both streams and the frames carry the evaluation watermark, see Evaluation version.
Frames may be captured to:
- memory bitmaps,
- BMP files,
- JPEG files,
- clipboard (CF_BITMAP)
one by one or automatically in burst mode.

===========================================================================

I. DIRECT COPY OF THE BITMAP HANDLE (OR DIRECTLY THE BITMAP BITS ARRAY) OF THE CURRENT VIDEO FRAME FROM THE OnFrameBitmap EVENT
For each video frame travelling through the graph, the OnFrameBitmap event occurs and makes it possible to directly capture the bitmap bits.

This is the method that requires the least CPU, however as the OnFrameBitmap event is called directly from a thread (1), the bitmap handle and the bitmap bits are valid only when the event occurs so it is necessary to copy them to another buffer immediately.

Note that this method can slow down the graph and/or produce a jerky preview, because the processing time added in the event is included in the frame processing time, so if the time to process 2 frames becomes longer than the frame interval, frames will be dropped.

So it is recommended mainly when the graph is previewing (by invoking StartPreview ), in this case dropped frames are less critical than during a recording (this could produce a jerky recording) or during playback (that may appear jerky).

Sample code can be found in the OnFrameBitmap event of the MainDemo project (search "FrameBitmap" in the MainForm)
(1) the event can be synchronized with the Windows main thread if the OnFrameBitmapEventSynchrone property is enabled.

===========================================================================

II. DIRECT FRAME CAPTURE OF THE CURRENT FRAME (OR PREVIOUS FRAMES)
It is possible to invoke GetLastFrameAsHBitmap (all versions) or GetLastFrameAsTBitmap (only with the Delphi/C++Builder versions), to get a copy of the current (or previous) frame at the desired size, with or without overlays.

This way does not slow down the graph and does not generate dropped frames.

Sample code is shown in the MotionDetected event of the MainDemo project, that displays a copy of the last frame detected with motion in the "Overlay" tab.

===========================================================================

III. FRAME CAPTURE OF THE CURRENT FRAME (OR NEXT FRAMES AUTOMATICALLY IN BURST MODE)
by using CaptureFrameTo (or enabling the burst mode) + the OnFrameCaptureCompleted event

This way does not slow down the graph and does not generate dropped frames.
With or without overlays
If the application performs graphic or text overlays, by default the frames are captured with overlays.
To capture the frames without overlays, enable the FrameCaptureWithoutOverlay property.

ASYNCHRONOUS VS. SYNCHRONOUS FRAME CAPTURE
A) Asynchronous frame capture
to capture frames one by one
Invoke CaptureFrameTo. The function sends a "capture order" and exits immediately. Then the captured frame is returned by the OnFrameCaptureCompleted event.

to capture frames automatically in burst mode
The burst mode makes it possible to capture frames automatically. It is activated by enabling the BurstMode property.

Frames can be captured to TBitmap, BMP file or JPEG file according to the BurstType property.
Frames are captured indefinitely if BurstCount = 0, otherwise frame capture stops when a BurstCount number of frames have been captured.
If BurstInterval > 0, a BurstInterval number of frames will be skipped between each frame captured.

The burst mode is activated by enabling BurstMode.

The burst mode is deactivated:
- by disabling BurstMode,
- if BurstCount > 0, when a BurstCount number of frames have been captured.

When capturing video frames to BMP or JPEG files:
- if no file name is specified when invoking CaptureFrameTo or CaptureFrameSyncTo, the file name is generated automatically (1).
- in burst mode file names are always generated automatically (1).

(1) according to StoragePath, AutoFileName and AutoFilePrefix.

Frame capture of unmodified frames when performing frame overlay
When drawing over video frames by using the Frame Overlay feature, by default the frame capture occurs AFTER frames have been overlaid (objects drawn over video frames appear on captured frames).
Enable the FrameCaptureWithoutOverlay property to capture unmodified frames before they are overlaid.

Example of asynchronous frame capture The method is the same as described above, except that it is necessary to set UseClock = false before opening the clip, to play it at maximum speed.

E.g.:

VideoGrabber.BurstMode = true
VideoGrabber.BurstCount = 5
VideoGrabber.BurstInterval = 10
VideoGrabber.BurstType = fc_BmpFile
VideoGrabber.PlayerFileName = "... the file name of my video clip..."
VideoGrabber.UseClock = false
VideoGrabber.OpenPlayer

Size of the captured frames
Default size - by default, the size of the captured frames is the current size of the video frames (returned by the VideoWidth and VideoHeight properties).

Zoomed size - it is possible to zoom the captured frames by specifying a FrameCaptureZoomSize percentage.
The default value is 100 (100%)

Custom size - it is possible to stretch the captured frames to a specified width, height or both by assigning a value to FrameCaptureWidth and/or FrameCaptureHeight.
The default value for both is -1 (disabled)

NB: if a value <> 100 is assigned to FrameCaptureZoomSize, FrameCaptureWidth and FrameCaptureHeight are ignored.

B) Synchronous frame capture through the frame grabber. The function will wait for the frame capture to be completed before returning.

invoke CaptureFrameSyncTo. The function waits for the frame to be captured. The frame is returned through the OnFrameCaptureCompleted, and then the function returns true upon success, exactly like for the asynchronous CaptureFrameTo described above.

C) Synchronous frame capture with the frame grabber disabled

It is possible to capture the frame being displayed in the video renderer by invoking CaptureFrameRenderedTo, which makes it possible to disable the frame grabber to save CPU load and memory.

HOW TO CAPTURE A SUB-RECTANGLE OF THE VIDEO FRAME
To capture a sub-rectangle, invoke SetFrameCaptureBounds (Left, Top, Right, Bottom) before invoking CaptureFrameTo or CaptureFrameSyncTo.
(to retrieve the current size of the video frame use VideoWidth and VideoHeight )

HOW TO STRETCH THE CAPTURED VIDEO FRAME. To resize the video frame as desired, specify a FrameCaptureWidth and/or FrameCaptureHeight value

HOW TO ZOOM THE CAPTURED VIDEO FRAME
To resize the captured frame, assign a zoom percentage to FrameCaptureZoomSize.

TOP-DOWN AND LEFT-RIGHT FRAME CAPTURE
This can be easily achieved by invoking SetFrameCaptureBounds and specifying the bottom instead of the top, and/or the left instead of the right.
(to retrieve the current size of the video frame use VideoWidth and VideoHeight )