VCS Dev Docs File src/display/display.h

The display subsystem interface.

More...

Functions

kd_acquire_output_window(void)
boolkd_add_log_entry(const log_entry_s e)
boolkd_is_fullscreen(void)
kd_load_aliases(const std::string &filename)
kd_load_filter_graph(const std::string &filename)
kd_load_video_presets(const std::string &filename)
kd_recalculate_filter_graph_chains(void)
kd_release_output_window(void)
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(void)
kd_update_output_window_size(void)
kd_update_output_window_title(void)

Data structures

structabstract_filter_graph_node_s
structfilter_graph_option_s
structresolution_s

Events

eventkd_evDirty ⇉ <void>

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

kd_acquire_output_window(void)

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.

It's expected that VCS will only call this function once, at program launch.

bool kd_add_log_entry(const log_entry_s e)

Lets the GUI know that VCS has created a new log entry, and provides a copy of it as a parameter.

If the GUI has a view to VCS's log entries, it should update that view accordingly.

bool kd_is_fullscreen(void)

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_recalculate_filter_graph_chains(void)

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_release_output_window(void)

Asks the GUI to close and destroy the output window; as well as any child windows and/or dialogs.

It's expected that VCS will only call this function once, when the program is about to exit.

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(void)

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(void)

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(void)

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.