Video Capture

Files
file	video_capture.h
file	video_capture_params.cpp
file	video_capture_params.h

Classes
struct	video_capture_info

Macros
#define	VIDCAP_NO_GENERIC_FPS_INDICATOR   NULL
#define	VIDEO_CAPTURE_ABI_VERSION   13

Functions
int	initialize_video_capture (struct module *parent, struct vidcap_params *params, struct vidcap **state)
	Initializes video capture.
void	list_video_capture_devices (bool)
void	vidcap_done (struct vidcap *state)
	Destroys vidap state.
const char *	vidcap_get_fps_print_prefix (struct vidcap *state)
struct video_frame *	vidcap_grab (struct vidcap *state, struct audio_frame **audio)
	Grabs video frame. This function may block for a short period if waiting for incoming frame. This period, however, should not be longer than few frame times, a second at maximum.

vidcap_retval
Video capture init return values
#define	VIDCAP_INIT_OK   0
	initialization successful
#define	VIDCAP_INIT_NOERR   1
	state not initialized, other action performed (typically help)
#define	VIDCAP_INIT_FAIL   (-1)
	error ocured
#define	VIDCAP_INIT_AUDIO_NOT_SUPPORTED   (-2)
	card does not support audio

Detailed Description

Workflow for video capture

Normal operation is something like:

v = vidcap_init(id);
...
while (!done) {
    ...
    f = vidcap_grab(v, &a);
    ...use the video frame "f"
    ...use the audio frame "a"
}
vidcap_done(v);

Where the "id" parameter to vidcap_init() is obtained from the probing API. The vidcap_grab() function returns a pointer to the frame, or NULL if no frame is currently available.

The vidcap_grab() may block, but not indefinitely (ideally no longer than 2x frame time) or it should observe global exit status with register_should_exit_callback() and yield control when notified.

API for video capturers

Each module should implement API from video_capture_info. Furthermore, it should register the module with REGISTER_MODULE(). E.g.:

REGISTER_MODULE(dvs, &vidcap_dvs_info, LIBRARY_CLASS_VIDEO_CAPTURE, VIDEO_CAPTURE_ABI_VERSION);

Note

The lifetime of captured frame is determined by the fact whether video_frame_callbacks::dispose is set. If so, the caller calls the callback when the frame is no longer needed. When set to NULL, the lifetime of the frame is limited to a next call to vidcap_grab().

Macro Definition Documentation

VIDCAP_INIT_AUDIO_NOT_SUPPORTED

#define VIDCAP_INIT_AUDIO_NOT_SUPPORTED   (-2)

card does not support audio

Definition at line 124 of file video_capture.h.

Referenced by initialize_video_capture(), vidcap_bitflow_init(), vidcap_deltacast_dvi_init(), vidcap_dshow_init(), vidcap_dvs_init(), vidcap_gpustitch_init(), vidcap_null_init(), vidcap_pw_init(), vidcap_screen_osx_init(), vidcap_screen_x11_init(), vidcap_spout_init(), vidcap_syphon_init(), vidcap_v4l2_init(), and vidcap_ximea_init().

VIDCAP_INIT_FAIL

#define VIDCAP_INIT_FAIL   (-1)

error ocured

Definition at line 123 of file video_capture.h.

Referenced by initialize_video_capture(), parse_fmt(), parse_params(), vidcap_aggregate_init(), vidcap_aja_init(), vidcap_bluefish444_init(), vidcap_decklink_init(), vidcap_deltacast_dvi_init(), vidcap_deltacast_init(), vidcap_dshow_init(), vidcap_dvs_init(), vidcap_file_init(), vidcap_gpustitch_init(), vidcap_import_init(), vidcap_ndi_init(), vidcap_rtsp_init(), vidcap_screen_osx_init(), vidcap_screen_win_init(), vidcap_screen_x11_init(), vidcap_spout_init(), vidcap_switcher_init(), vidcap_swmix_init(), vidcap_syphon_init_common(), vidcap_testcard2_init(), vidcap_testcard_init(), vidcap_ug_input_init(), vidcap_v4l2_init(), vidcap_ximea_init(), and vidcap_ximea_parse_params().

VIDCAP_INIT_NOERR

#define VIDCAP_INIT_NOERR   1

state not initialized, other action performed (typically help)

Definition at line 122 of file video_capture.h.

Referenced by initialize_video_capture(), parse_fmt(), parse_params(), vidcap_aggregate_init(), vidcap_aja_init(), vidcap_bluefish444_init(), vidcap_decklink_init(), vidcap_deltacast_dvi_init(), vidcap_deltacast_init(), vidcap_dshow_init(), vidcap_dvs_init(), vidcap_file_init(), vidcap_gpustitch_init(), vidcap_import_init(), vidcap_ndi_init(), vidcap_rtsp_init(), vidcap_screen_osx_init(), vidcap_screen_win_init(), vidcap_screen_x11_init(), vidcap_spout_init(), vidcap_swmix_init(), vidcap_syphon_init_common(), vidcap_testcard2_init(), vidcap_testcard_init(), vidcap_ug_input_init(), vidcap_v4l2_init(), and vidcap_ximea_parse_params().

VIDCAP_INIT_OK

#define VIDCAP_INIT_OK   0

initialization successful

Definition at line 121 of file video_capture.h.

Referenced by initialize_video_capture(), parse_params(), test_video_capture(), vidcap_aggregate_init(), vidcap_aja_init(), vidcap_bitflow_init(), vidcap_bluefish444_init(), vidcap_decklink_init(), vidcap_deltacast_dvi_init(), vidcap_deltacast_init(), vidcap_dshow_init(), vidcap_dvs_init(), vidcap_file_init(), vidcap_gpustitch_init(), vidcap_import_init(), vidcap_ndi_init(), vidcap_null_init(), vidcap_pw_init(), vidcap_rtsp_init(), vidcap_screen_osx_init(), vidcap_screen_x11_init(), vidcap_spout_init(), vidcap_switcher_init(), vidcap_swmix_init(), vidcap_syphon_init(), vidcap_syphon_init_common(), vidcap_syphon_probe(), vidcap_testcard2_init(), vidcap_testcard_init(), vidcap_ug_input_init(), vidcap_v4l2_init(), and vidcap_ximea_init().

VIDCAP_NO_GENERIC_FPS_INDICATOR

#define VIDCAP_NO_GENERIC_FPS_INDICATOR   NULL

Definition at line 127 of file video_capture.h.

VIDEO_CAPTURE_ABI_VERSION

#define VIDEO_CAPTURE_ABI_VERSION   13

Definition at line 109 of file video_capture.h.

Referenced by initialize_video_capture(), and list_video_capture_devices().

Function Documentation

initialize_video_capture()

int initialize_video_capture	(	struct module *	parent,
		struct vidcap_params *	param,
		struct vidcap **	state )

Initializes video capture.

Parameters

[in]	parent	parent module
[in]	param	driver parameters
[out]	state	returned state

Return values

0	if initialization was successful
<0	if initialization failed
>0	if initialization was successful but no state was returned (eg. only having shown help).

check appropriate cmdline parameters order (–capture-filter then -t) only if one capture device specified, allow setting -F after -t

Definition at line 96 of file video_capture.c.

{
        struct vidcap_params *tlast = param;
        struct vidcap_params *tprev = param;
        while ((vidcap_params_get_next(tlast))) {
                tprev = tlast;
                tlast = vidcap_params_get_next(tlast);
        }
        if (vidcap_params_get_driver(tlast) == NULL
                        && vidcap_params_get_capture_filter(tlast) != NULL) {
                if (tprev != param) { // more than one -t
                        log_msg(LOG_LEVEL_ERROR, "Capture filter (--capture-filter) needs to be "
                                "specified before capture (-t)\n");
                        return -1;
                }
                if (vidcap_params_get_capture_filter(tprev) != NULL) { // one -t but -F specified both before and after it
                        log_msg(LOG_LEVEL_ERROR, "Multiple capture filter specification.\n");
                        return -1;
                }
                vidcap_params_set_capture_filter(tprev, vidcap_params_get_capture_filter(tlast));
        }
        // similarly for audio connection
        if (vidcap_params_get_driver(tlast) == NULL
                        && vidcap_params_get_flags(tlast) != 0) {
                if (tprev != param) { // more than one -t
                        log_msg(LOG_LEVEL_ERROR, "Audio connection (-s) needs to be "
                                "specified before capture (-t)\n");
                        return -1;
                }
                if (vidcap_params_get_flags(tprev) != 0) { // one -t but -s specified both before and after it
                        log_msg(LOG_LEVEL_ERROR, "Multiple audio connection specification.\n");
                        return -1;
                }
                vidcap_params_set_flags(tprev, vidcap_params_get_flags(tlast));
        }
 
        const struct video_capture_info *vci = (const struct video_capture_info *)
                load_library(vidcap_params_get_driver(param), LIBRARY_CLASS_VIDEO_CAPTURE, VIDEO_CAPTURE_ABI_VERSION);
 
        if (vci == NULL) {
                log_msg(LOG_LEVEL_ERROR, "WARNING: Selected '%s' capture card "
                        "was not found.\n", vidcap_params_get_driver(param));
                return -1;
        }
 
        struct vidcap *d =
                (struct vidcap *)malloc(sizeof(struct vidcap));
        d->magic = VIDCAP_MAGIC;
        d->funcs = vci;
 
        module_init_default(&d->mod);
        d->mod.cls = MODULE_CLASS_CAPTURE;
        module_register(&d->mod, parent);
 
        vidcap_params_set_parent(param, &d->mod);
        int ret = vci->init(param, &d->state);
 
        switch (ret) {
        case VIDCAP_INIT_OK:
                break;
        case VIDCAP_INIT_NOERR:
                break;
        case VIDCAP_INIT_FAIL:
                log_msg(LOG_LEVEL_ERROR,
                                "Unable to start video capture device %s\n",
                                vidcap_params_get_driver(param));
                break;
        case VIDCAP_INIT_AUDIO_NOT_SUPPORTED:
                log_msg(LOG_LEVEL_ERROR,
                                "Video capture driver does not support selected embedded/analog/AESEBU audio.\n");
                break;
        }
        if (ret != 0) {
                module_done(&d->mod);
                free(d);
                return ret;
        }
 
        ret = capture_filter_init(&d->mod, vidcap_params_get_capture_filter(param),
                &d->capture_filter);
        if (ret < 0) {
                log_msg(LOG_LEVEL_ERROR, "Unable to initialize capture filter: %s.\n",
                        vidcap_params_get_capture_filter(param));
        }
 
        if (ret != 0) {
                module_done(&d->mod);
                free(d);
                return ret;
        }
 
        *state = d;
        return 0;
}

References capture_filter, capture_filter_init(), module::cls, funcs, video_capture_info::init, LIBRARY_CLASS_VIDEO_CAPTURE, load_library(), LOG_LEVEL_ERROR, log_msg(), magic, mod, MODULE_CLASS_CAPTURE, module_done(), module_init_default(), module_register(), param, parent, state, state, VIDCAP_INIT_AUDIO_NOT_SUPPORTED, VIDCAP_INIT_FAIL, VIDCAP_INIT_NOERR, VIDCAP_INIT_OK, VIDCAP_MAGIC, vidcap_params_get_capture_filter(), vidcap_params_get_driver(), vidcap_params_get_flags(), vidcap_params_get_next(), vidcap_params_set_capture_filter(), vidcap_params_set_flags(), vidcap_params_set_parent(), and VIDEO_CAPTURE_ABI_VERSION.

Referenced by grab_worker(), main(), slave_worker(), test_video_capture(), vidcap_aggregate_init(), vidcap_screen_linux_init(), vidcap_switcher_grab(), and vidcap_switcher_init().

Here is the call graph for this function:

list_video_capture_devices()

void list_video_capture_devices

(

bool

full

)

Definition at line 82 of file video_capture.c.

{
        printf("Available capture devices:\n");
        list_modules(LIBRARY_CLASS_VIDEO_CAPTURE, VIDEO_CAPTURE_ABI_VERSION, full);
}

References LIBRARY_CLASS_VIDEO_CAPTURE, list_modules(), and VIDEO_CAPTURE_ABI_VERSION.

Referenced by parse_options_internal(), and test_video_capture().

Here is the call graph for this function:

vidcap_done()

void vidcap_done

(

struct vidcap *

state

)

Destroys vidap state.

Parameters

state

state to be destroyed (must have been successfully initialized with vidcap_init())

Definition at line 197 of file video_capture.c.

{
        assert(state->magic == VIDCAP_MAGIC);
        state->funcs->done(state->state);
        capture_filter_destroy(state->capture_filter);
        module_done(&state->mod);
        free(state);
}

References capture_filter_destroy(), module_done(), state, and VIDCAP_MAGIC.

Referenced by grab_worker(), main(), slave_worker(), vidcap_aggregate_done(), vidcap_aggregate_init(), vidcap_screen_linux_done(), vidcap_switcher_done(), and vidcap_switcher_grab().

Here is the call graph for this function:

vidcap_get_fps_print_prefix()

const char * vidcap_get_fps_print_prefix

(

struct vidcap *

state

)

Returns

nullptr if display has own FPS indicator

otherwise the prefix (without trailing space, eg. "[GL]") to be used in a generic fps indicator

Definition at line 233 of file video_capture.c.

{
        assert(state->magic == VIDCAP_MAGIC);
        if (state->funcs->generic_fps_indicator_prefix == NULL) {
                return NULL;
        }
        _Thread_local static char buf[SHORT_STR];
 
        unsigned len = snprintf(buf, sizeof buf, "%s",
                                state->funcs->generic_fps_indicator_prefix);
        if (len > sizeof buf - 1) { // truncated
                len = sizeof buf - 1;
        }
        if (len > 0 && buf[len - 1] == ' ') { // trim trailing ' '
                buf[len - 1] = '\0';
        }
        return buf;
}

References len, SHORT_STR, state, and VIDCAP_MAGIC.

Referenced by capture_thread().

vidcap_grab()

struct video_frame * vidcap_grab	(	struct vidcap *	state,
		struct audio_frame **	audio )

Grabs video frame. This function may block for a short period if waiting for incoming frame. This period, however, should not be longer than few frame times, a second at maximum.

The decision of blocking behavior is on the vidcap driver.

The returned video frame is valid only until next vidcap_grab() call.

Parameters

[in]	state	vidcap state
[out]	audio	contains audio frame if driver is grabbing audio

Returns

video frame. If no frame was grabbed (or timeout passed) NULL is returned.

Definition at line 218 of file video_capture.c.

{
        assert(state->magic == VIDCAP_MAGIC);
        struct video_frame *frame;
        frame = state->funcs->grab(state->state, audio);
        if (frame != NULL)
                frame = capture_filter(state->capture_filter, frame);
        return frame;
}

References audio, capture_filter(), frame, state, and VIDCAP_MAGIC.

Referenced by capture_thread(), grab_worker(), slave_worker(), vidcap_aggregate_grab(), vidcap_screen_linux_grab(), and vidcap_switcher_grab().

Here is the call graph for this function: