VCS Dev Docs File src/display/display.h

The display subsystem interface.

More...

Functions

subsystem_releaser_tkd_acquire_output_window()
boolkd_is_fullscreen()
kd_load_aliases(const std::string &filename)
kd_load_filter_graph(const std::string &filename)
kd_load_video_presets(const std::string &filename)
kd_prevent_screensaver()
kd_recalculate_filter_graph_chains()
kd_show_headless_assert_error_message(const char *const msg, const char *const filename, const uint lineNum)
kd_show_headless_error_message(const char *const title, const char *const msg)
kd_show_headless_info_message(const char *const title, const char *const msg)
kd_spin_event_loop()
kd_update_output_window_size()
kd_update_output_window_title()

Data structures

structabstract_filter_graph_node_s
structfilter_graph_option_s
structimage_s
structresolution_s

Events

voidkd_evDirty

Detailed description

The display subsystem interface.

The VCS GUI is responsible for providing the user with real-time means to enter information (e.g. configuring capture parameters), for directing such input to VCS, and for displaying captured frames and other information about VCS's run-time state to the user.

The display interface decouples the GUI's implementation from the rest of VCS, making it possible to replace the GUI with fairly minimal modification to the rest of VCS.

VCS's default GUI uses Qt, and its implementation of the display interface can be found in src/display/qt/d_main.cpp.

Warning:

As of VCS 2.0.0, this interface is undergoing refactoring. Many of its functions are expected to become renamed or removed.

Function documentation

subsystem_releaser_t kd_acquire_output_window()

Asks the GUI to create and open the output window. The output window is a surface on which VCS's output frames are to be displayed by the GUI.

If the GUI makes use of child windows and/or dialogs, this may be a good time to create them, as well.

By default, VCS will call this function automatically on program startup.

Returns a function that closes and releases the output window.

bool kd_is_fullscreen()

Returns true if the output window is in fullscreen mode; false otherwise.

kd_load_aliases(const std::string &filename)

Asks the GUI to load alias resolutions from the given file.

The GUI is expected to inform VCS's alias subsystem of the new aliases.

kd_load_filter_graph(const std::string &filename)

Asks the GUI to load a filter graph from the given file.

The GUI is expected to inform VCS's filter subsystem of the new graph.

kd_load_video_presets(const std::string &filename)

Asks the GUI to load video presets from the given file.

The GUI is expected to inform VCS's video presets subsystem of the new presets.

kd_prevent_screensaver()

Request the display subsystem to prevent the system's screensaver or display hibernation from activating while VCS is running.

kd_recalculate_filter_graph_chains()

Asks the GUI to inform the filter interface, src/filter/filter.h, of all filter chains currently configured in the GUI.

This assumes that the GUI provides a dialog of some sort in which the user can create and modify filter chains. When this function is called, the GUI is expected to enumerate those filter chains into a format consumed by the filter interface and then to submit them to the filter interface.

In pseudocode, the GUI would do something like the following:

kf_unregister_all_filter_chains(); for (chain: guiFilterChains){    const standardFilterChain = ...convert chain into standard format...    kf_register_filter_chain(standardFilterChain);}
kd_show_headless_assert_error_message(const char *const msg, const char *const filename, const uint lineNum)
kd_show_headless_error_message(const char *const title, const char *const msg)
kd_show_headless_info_message(const char *const title, const char *const msg)

Asks the GUI to display an info message to the user.

The message should be deliverable with a headless GUI, i.e. requiring minimal prior GUI initialization.

The following sample Qt 5 code creates a conforming message box:

QMessageBox mb; mb.setWindowTitle(strlen(title)? title : "VCS has this to say");mb.setText(msg);mb.setStandardButtons(QMessageBox::Ok);mb.setIcon(QMessageBox::Information);mb.setDefaultButton(QMessageBox::Ok); mb.exec();

kd_spin_event_loop()

Asks the GUI to execute one spin of its event loop.

Spinning the event loop would involve e.g. repainting the output window, processing any user input, etc.

The following sample Qt 5 code executes one spin of the event loop:

QCoreApplication::sendPostedEvents();QCoreApplication::processEvents();

VCS will generally call this function at the capture's refresh rate, e.g. 70 times per second when capturing VGA mode 13h.

Note:

If the GUI wants to match the capture's refresh rate, it should repaint its output only when VCS calls this function.

kd_update_output_window_size()

Lets the GUI know that the size of output frames has changed. The GUI should update the size of its output window accordingly.

VCS expects the size of the output window to match the size of output frames; although the GUI may choose not to honor this.

The current size of output frames can be obtained via the scaler interface, src/scaler/scaler.h, by calling ks_output_resolution().

The following sample Qt 5 code sizes the output window to match the size of VCS's output frames (this is the output window's instance):

resolution_s r = ks_output_resolution();this->setFixedSize(r.w, r.h);

kd_update_output_window_title()

Asks the GUI to refresh the output window's title bar text.

VCS assumes that the output window's title bar displays certain information about VCS's state - e.g. the current capture resolution. VCS will thus call this function to let the GUI know that the relevant state has changed.

If your custom GUI implementation displays different state variables than VCS's default GUI does, you may need to do custom polling of the relevant state in order to be aware of changes to it.

Event documentation

event kd_evDirty ⇒ void

An event that can be fired by subsystems to indicate that the output window should redraw its contents.