The filter subsystem interface.

The filter subsystem provides facilities for manipulating captured frames' pixel data.

The building block of this subsystem is the image filter. They're subclasses of abstract_filter_c that modify image pixels in some way: blurring, sharpening, rotation, and so on.

Instances of image filters are organized into filter chains. A filter chain consists of one or more filters, each of which will be applied in turn to an input frame. A filter chain consisting of a blur filter, a sharpen filter, and a rotation filter would first blur the frame, then sharpen it, and finally rotate it.

Each filter chain is associated with an input condition and an output condition, based on which the subsystem makes a choice about which of the chains to apply to an input frame. A chain's input condition dictates the resolution the input frame must be in to be acted on by the chain's filters, and the output condition specifies the resolution the scaler subsystem must be outputting in for the chain to be applied. The first filter chain whose input and output conditions are fulfilled will be applied to the input frame.

For example, a filter chain with an input condition of 640 x 480 and an output condition of 800 x 600 will be applied to an input frame if the frame's resolution is 640 x 480 and the scaler subsystem is set to produce its output in 800 x 600 (i.e. it'll scale this frame to 800 x 600 at a later stage in VCS's capture pipeline). If there's a second filter chain with these same conditions, only the first chain will be applied and not the second.

Usage

1. Call kf_initialize_filters() to initialize the filter subsystem. This is VCS's default startup behavior. Note that this function should only be called once per program execution.
2. Use kf_create_filter_instance() to create instances of filters:

   // Create an instance of a blurring filter.auto *blur = kf_create_filter_instance<filter_blur_c>(); // You can also use the non-templated instancer, which takes a UUID string// identifying the type of filter to create.auto *flip = kf_create_filter_instance("80a3ac29-fcec-4ae0-ad9e-bbd8667cc680"); // "80a3ac29-fcec-4ae0-ad9e-bbd8667cc680" == filter_flip_c().uuid().

3. Get and set filters' parameter values:

   auto *blur = kf_create_filter_instance<filter_blur_c>(); // Increase the blurring radius.const double radius = blur->parameter(filter_blur_c::PARAM_KERNEL_SIZE);blur->set_parameter(filter_blur_c::PARAM_KERNEL_SIZE, (radius + 1)); // Use a box kernel instead of the default Gaussian.blur->set_parameter(filter_blur_c::PARAM_TYPE, filter_blur_c::BLUR_BOX); // Note: Each filter also includes a GUI widget that provides the end-user graphical// controls for adjusting the filter parameters. VCS's display subsystem provides an// interactive filter graph that exposes these widgets to the user.

4. Combine filters into filter chains:

   // Create some filters.auto *blur = kf_create_filter_instance<filter_blur_c>();auto *flip = kf_create_filter_instance<filter_flip_c>(); // Create the chain's input and output conditions. This chain will be applied to// frames of size 640 x 480 when the scaler subsystem's output size is 800 x 600.auto *in = kf_create_filter_instance<filter_input_gate_c>({{0, 640}, {1, 480}});auto *out = kf_create_filter_instance<filter_output_gate_c>({{0, 800}, {1, 600}}); // Create the chain. Note that chains must begin with an input condition and end// with an output condition.std::vector<abstract_filter_c*> chain = {in, blur, flip, out}; // Make the filter subsystem aware of the chain.kf_register_filter_chain(chain); // Note: VCS's display subsystem provides the end-user an interactive filter// graph for building filter chains via the GUI.

5. Apply suitable filter chains to captured frames:

   kc_evNewCapturedFrame.listen([](const captured_frame_s &frame){    image_s image(frame.pixels.data, frame.r);    kf_apply_matching_filter_chain(&image);});

6. (Optional) Apply filters individually:

   auto *blur = kf_create_filter_instance<filter_blur_c>(); // Filter a dummy image of 1 x 2 resolution (BGRA/8888 format).uint8_t pixels[8];resolution_s resolution = {1, 2, 32};blur->apply(pixels, resolution); // When we no longer need the filter.kf_delete_filter_instance(blur);

7. VCS will automatically release the subsystem on program termination.