VCS Dev Docs File src/scaler/scaler.h

The scaler subsystem interface.

More...

Functions

resolution_sks_base_resolution(void)
const image_scaler_s*ks_default_scaler(void)
image_sks_frame_buffer(void)
ks_indicate_invalid_signal(void)
ks_indicate_no_signal(void)
ks_initialize_scaler(void)
boolks_is_custom_scaler_active(void)
resolution_sks_output_resolution(void)
ks_release_scaler(void)
ks_scale_frame(const captured_frame_s &frame)
std::vector<std::string>ks_scaler_names(void)
ks_set_base_resolution(const resolution_s &r)
ks_set_base_resolution_enabled(const bool enabled)
ks_set_default_scaler(const std::string &name)
ks_set_scaling_multiplier(const double s)
ks_set_scaling_multiplier(void)
ks_set_scaling_multiplier_enabled(const bool enabled)

Data structures

structimage_scaler_s

Events

eventks_evCustomScalerDisabled<void>
eventks_evCustomScalerEnabled<void>
eventks_evFramesPerSecond<unsigned>
eventks_evNewOutputResolution<const resolution_s&>
eventks_evNewScaledImage<const image_s&>

Detailed description

The scaler subsystem interface.

The scaler subsystem provides facilities to VCS for scaling captured frames.

When an input frame is scaled, its pixel data is copied into the subsystem's frame buffer, from which callers can fetch it until the next image is scaled (or until the buffer's pixel data is modified in some other way).

By default, it's the state of the scaler subsystem's frame buffer that gets displayed to the end-user in VCS's capture window.

Usage

  1. Call ks_initialize_scaler() to initialize the subsystem. This is VCS's default startup behavior.
  2. Use setter functions to customize scaler options:
    ks_set_scaling_multiplier(0.75);ks_set_downscaling_filter("Linear");ks_set_base_resolution({640, 480});
  3. Feed captured frames into ks_scale_frame(), then read the scaled output from ks_frame_buffer():
    ks_scale_frame(frame);const auto &scaledImage = ks_frame_buffer();
  4. You can automate the scaling of captured frames using event listeners:
    // Executed each time the capture subsystem reports a new captured frame.kc_evNewCapturedFrame.listen([](const captured_frame_s &frame){    ks_scale_frame(frame);}); // Executed each time the scaler subsystem produces a new scaled image.ks_evNewScaledImage.listen([](const image_s &image){    printf("A frame was scaled to %lu x %lu.\n", image.resolution.w, image.resolution.h);});
  5. Call ks_release_scaler() to release the subsystem. This is VCS's default exit behavior.

Function documentation

resolution_s ks_base_resolution(void)
const image_scaler_s* ks_default_scaler(void)
image_s ks_frame_buffer(void)
ks_indicate_invalid_signal(void)

Draws an "invalid signal" image into the scaler subsystem's frame buffer, erasing any previous image there.

Note:

A subsequent call to ks_scale_frame() will overwite the image.

// Produce an "invalid signal" image when the capture device loses its signal.kc_evInvalidSignal.listen(ks_indicate_invalid_signal);

ks_indicate_no_signal(void)

Draws a "no signal" image into the scaler subsystem's frame buffer, erasing any previous image there.

Note:

A subsequent call to ks_scale_frame() will overwite the image.

// Produce a "no signal" image when the capture device loses its signal.kc_evSignalLost.listen(ks_indicate_no_signal); // Note: The kc_evSignalLost event fires when the capture device loses its// signal, but not in the case where the device already has no signal when// VCS is launched.
See also kc_evSignalLost

ks_initialize_scaler(void)

Initializes the scaler subsystem.

Note:

This function should be called before any other functions of the scaler interface.

bool ks_is_custom_scaler_active(void)

Returns true if a custom output scaling filter is currently active; false otherwise.

resolution_s ks_output_resolution(void)
ks_release_scaler(void)

Releases the scaler subsystem, deallocating any of its memory buffers etc.

Warning:

Between calling this function and ks_initialize_scaler(), no other scaler subsystem functions should be called.

ks_scale_frame(const captured_frame_s &frame)

Applies scaling to the given frame's pixels and stores the result in the scaler subsystem's frame buffer. The input data are not modified.

After this call, the scaled image is available via ks_frame_buffer().

ks_scale_frame(frame);const auto &scaledFrame = ks_frame_buffer();
// Feed captured frames into the scaler using a VCS event listener.kc_evNewCapturedFrame.listen([](const captured_frame_s &frame){    ks_scale_frame(frame);}); // Receive scaled frames from the scaler.ks_evNewScaledImage.listen([](const image_s &image){    printf("A frame was scaled to %lu x %lu.\n", image.resolution.w, image.resolution.h);});

std::vector<std::string> ks_scaler_names(void)

Returns a list of the names of the image scalers available in this build of VCS.

const auto list = ks_scaler_names();// list == {"Nearest", "Linear", "Area", ...}.
ks_set_base_resolution(const resolution_s &r)

Sets the resolution to which input frames are to be scaled, before applying size modifiers like scaling multiplier. By default, the scaler will apply the modifiers to each input frame's own resolution.

// Frames will be scaled to 2x of their original resolution.ks_set_base_resolution_enabled(false);ks_set_scaling_multiplier(2); // Frames will be scaled to 2x of 640 x 480.ks_set_base_resolution_enabled(true);ks_set_base_resolution({640, 480});ks_set_scaling_multiplier(2);

ks_set_base_resolution_enabled(const bool enabled)

Enables or disables the scaler subsystem's overridable base resolution.

If disabled, the base resolution will be the resolution of the input frame.

ks_set_default_scaler(const std::string &name)

Sets the scaler to be used when the resolution of captured frames doesn't match the resolution of the output window, such that the frames are scaled to the size of the window. The desired filter is identified by name.

// Produce an image downscaled by 0.75x using a linearly sampling scaler.ks_set_default_scaler("Linear");ks_set_scaling_multiplier(0.75);ks_scale_frame(frame);const auto &scaledImage = ks_frame_buffer();
Note:

name must be one of the strings returned by ks_scaler_names().

ks_set_scaling_multiplier(const double s)

Sets the multiplier by which input frames are scaled. The multiplier applies to both the width and height of the frame.

// Input frames will be upscaled by 2x using the current upscaling filter.ks_set_scaling_multiplier(2); // Input frames will be downscaled by half using the current downscaling filter.ks_set_scaling_multiplier(0.5);

ks_set_scaling_multiplier_enabled(const bool enabled)

Event documentation

event ks_evCustomScalerDisabled <void>

An event fired when there's no longer an output scaling filter being used to scale captured frames.

event ks_evCustomScalerEnabled <void>

An event fired when an output scaling filter becomes active, i.e. when captured frames begin being scaled using such a filter.

event ks_evFramesPerSecond <unsigned>

An event fired once per second, giving the number of input frames the scaler subsystem scaled during that time.

ks_evFramesPerSecond.listen([](unsigned numFrames){    printf("Scaled %u frames per second.\n", numFrames);});

event ks_evNewOutputResolution <const resolution_s&>

An event fired when the scaler subsystem scales a frame into a resolution different from the previous frame's.

ks_scale_frame(frame); ks_set_scaling_multiplier(ks_scaling_multiplier() + 1); // Fires ks_evNewOutputResolution.ks_scale_frame(frame);
event ks_evNewScaledImage <const image_s&>

An event fired when the scaler subsystem has finished scaling a frame.

ks_evNewScaledImage.listen([](const image_s &scaledImage){    printf("Scaled a frame to %lu x %lu.\n", scaledImage.resolution.w, scaledImage.resolution.h);});