Frame capture features

Frame capture overview.

Description

Frame capture

It is possible to capture video frames during preview, recording and play back when the frame grabber is enabled.
The frame grabber can be inserted on the preview stream, capture stream, or both. See the FrameGrabber property.
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 allows you to capture directly the bitmap bits.

This is the method that requires the less 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 you have to copy them to another buffer immediately.

Noet 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 rate frames will be dropped.

So it recommended rather 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 (seach "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 (OR PREVIOUS FRAMES)

You can invoke GetLastFrameAsHBitmap (all versions) or GetLastFrameAsTBitmap (only with the Delphi/C++Builder versions), to get a copy of the current (or previous) frame with the size of your choice, and with or without overlays.

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

A 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 send 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 allows 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 overlayed (objects drawn over video frames appear on captured frames).
Enable the FrameCaptureWithoutOverlay property to capture unmodified frames before they are overlayed.

Example of asynchonous frame capture

The method is the same as described above, excepted that you have to set UseClock = false before opening the clip, to play it at the maximal 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 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 the frame through the OnFrameCaptureCompleted , and then function returns true upon success, exactly like for the asychronous 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, allowing 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, specify to FrameCaptureZoomSize a zooming percentage.

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)