VCS Dev Docs File src/scaler/scaler.h

The scaler subsystem interface.



const image_scaler_s*ks_default_scaler()
ks_scale_frame(const captured_frame_s &frame)
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_enabled(const bool enabled)

Data structures



const resolution_s&ks_evNewOutputResolution
const image_s&ks_evNewScaledImage

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.


  1. Call ks_initialize_scaler() to initialize the subsystem. This is VCS's default startup behavior. Note that this function should be called only once per program execution.
  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. VCS will automatically release the scaler subsystem on program exit.

Function documentation

resolution_s ks_base_resolution()
const image_scaler_s* ks_default_scaler()

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


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);


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


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

subsystem_releaser_t ks_initialize_scaler()

Initializes the scaler subsystem.

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

Returns a function that releases the scaler subsystem.


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

bool ks_is_custom_scaler_active()

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

resolution_s ks_output_resolution()
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);});
See also

ks_frame_buffer(), ks_evNewScaledImage

image_s ks_scaler_frame_buffer()
std::vector<std::string> ks_scaler_names()

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

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);});