VCS Dev Docs File src/scaler/scaler.h

The scaler subsystem interface.

More...

Functions

scaler_aspect_ratio_eks_aspect_ratio(void)
resolution_sks_base_resolution(void)
const std::string&ks_downscaling_filter_name(void)
const captured_frame_s&ks_frame_buffer(void)
ks_indicate_invalid_signal(void)
ks_indicate_no_signal(void)
ks_initialize_scaler(void)
boolks_is_aspect_ratio_enabled(void)
resolution_sks_output_resolution(void)
ks_release_scaler(void)
ks_scale_frame(const captured_frame_s &frame)
std::vector<std::string>ks_scaling_filter_names(void)
ks_set_aspect_ratio(const scaler_aspect_ratio_e aspect)
ks_set_aspect_ratio_enabled(const bool state)
ks_set_base_resolution(const resolution_s &r)
ks_set_base_resolution_enabled(const bool enabled)
ks_set_downscaling_filter(const std::string &name)
ks_set_scaling_multiplier(const double s)
scaler_aspect_ratio_eks_set_scaling_multiplier(void)
ks_set_scaling_multiplier_enabled(const bool enabled)
ks_set_upscaling_filter(const std::string &name)
const std::string&ks_upscaling_filter_name(void)

Enumerations

enum classscaler_aspect_ratio_e

Events

eventks_evFramesPerSecond<unsigned>
eventks_evNewOutputResolution<const resolution_s&>
eventks_evNewScaledImage<const captured_frame_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 captured_frame_s &frame){    printf("A frame was scaled to %lu x %lu.\n", frame.r.w, frame.r.h);});
  5. Call ks_release_scaler() to release the subsystem. This is VCS's default exit behavior.

Enumeration type documentation

enum class scaler_aspect_ratio_e
native

An image's native aspect ratio (width / height).

traditional_4_3

An image's native aspect ratio (width / height), except for certain historically 4:3 aspect ratio resolutions like 720 x 400.

all_4_3

An aspect ratio of 4:3, disregarding the image's native ratio.

Function documentation

scaler_aspect_ratio_e ks_aspect_ratio(void)
resolution_s ks_base_resolution(void)
const std::string& ks_downscaling_filter_name(void)
const captured_frame_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_aspect_ratio_enabled(void)

Returns true if the scaler is currently forcing scaled frames into a particular aspect ratio.

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 captured_frame_s &frame){    printf("A frame was scaled to %lu x %lu.\n", frame.r.w, frame.r.h);});

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

Returns a list of the names of the scaling filters available in this build of VCS.

const auto list = ks_scaling_filter_names();// list == {"Nearest", "Linear", "Area", ...}.
Note:

The presence or absence of the USE_OPENCV build flag affects the availability of scaling filters.

ks_set_aspect_ratio(const scaler_aspect_ratio_e aspect)

Sets the aspect ratio to which the scaler subsystem scales input frames.

When scaling to a particular aspect ratio, input frames are squished to the given ratio, then padded with black borders as necessary to fit the output size.

// A frame of size 640 x 400 (16:10 aspect ratio).auto frame = ...; ks_set_base_resolution({640, 400});ks_set_aspect_ratio(scaler_aspect_ratio_e::all_4_3);ks_scale_frame(frame); // The scaled frame will have been padded to 640 x 400, with the original// frame's pixels squished to 533 x 400 (4:3 aspect ratio).auto scaledFrame = ks_frame_buffer();

ks_set_aspect_ratio_enabled(const bool state)

Enables or disables the scaler subsystem's aspect ratio.

If disabled, input frames will be scaled to their native aspect ratios.

ks_set_base_resolution(const resolution_s &r)

Sets the resolution to which input frames are to be scaled, before applying size modifiers like aspect ratio correction or a 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_downscaling_filter(const std::string &name)

Sets the scaling filter to be used when frames are downscaled, i.e. when the scaling multiplier is < 1. The desired filter is identified by name.

// Produce an image downscaled by 0.75x using a linearly sampling scaler.ks_set_downscaling_filter("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_scaling_filter_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);

scaler_aspect_ratio_e ks_set_scaling_multiplier(void)
ks_set_scaling_multiplier_enabled(const bool enabled)
ks_set_upscaling_filter(const std::string &name)

Sets the scaling filter to be used when frames are upscaled, i.e. when the scaling multiplier is > 1. The desired filter is identified by name.

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

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

const std::string& ks_upscaling_filter_name(void)

Event documentation

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 captured_frame_s&>

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

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