The scaler subsystem interface.
More...Functions
| resolution_s | ks_base_resolution() |
| const image_scaler_s* | ks_default_scaler() |
| ks_indicate_invalid_signal() | |
| ks_indicate_no_signal() | |
| subsystem_releaser_t | ks_initialize_scaler() |
| bool | ks_is_custom_scaler_active() |
| resolution_s | ks_output_resolution() |
| ks_scale_frame(const captured_frame_s &frame) | |
| image_s | ks_scaler_frame_buffer() |
| std::vector<std::string> | ks_scaler_names() |
| 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
| struct | image_scaler_s |
Events
| void | ks_evCustomScalerDisabled |
| void | ks_evCustomScalerEnabled |
| unsigned | ks_evFramesPerSecond |
| 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.
Usage
- 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.
- Use setter functions to customize scaler options:
ks_set_scaling_multiplier(0.75);ks_set_downscaling_filter("Linear");ks_set_base_resolution({640, 480}); - 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(); - 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);}); - VCS will automatically release the scaler subsystem on program exit.
Function documentation
Returns the resolution to which the scaler will scale input frames, prior to the application of resolution-influencing modifiers like a scaling multiplier.
In most cases, you'd be interested in ks_output_resolution(), instead.
Returns a pointer to the currently-active 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.
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.
Returns true if a custom output scaling filter is currently active; false otherwise.
Returns the resolution to which the scaler would currently scale an input 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);});
ks_frame_buffer(), ks_evNewScaledImage
Returns a reference to the scaler subsystem's frame buffer.
The frame buffer contains the most recent image produced by the subsystem. This may be a scaled frame (produced by ks_scale_frame()) or some other type of image (e.g. one produced by ks_indicate_no_signal()).
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", ...}.
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);
Enables or disables the scaler subsystem's overridable base resolution.
If disabled, the base resolution will be the resolution of the input frame.
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().
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);
Enables or disables the scaler subsystem's scaling multiplier.
Event documentation
An event fired when there's no longer an output scaling filter being used to scale captured frames.
An event fired when an output scaling filter becomes active, i.e. when captured frames begin being scaled using such a filter.
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);});
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);
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);});