VCS Dev Docs File src/anti_tear/anti_tear.h

The anti-tear subsystem interface.

More...

Functions

u8*kat_anti_tear(u8 *const pixels, const resolution_s &r)
kat_initialize_anti_tear(void)
kat_release_anti_tear(void)
kat_set_anti_tear_enabled(const bool state)
kat_set_domain_size(const u32 ds)
kat_set_matches_required(const u32 mr)
kat_set_range(const u32 min, const u32 max)
kat_set_scan_direction(const anti_tear_scan_direction_e newDirection)
kat_set_scan_hint(const anti_tear_scan_hint_e newHint)
kat_set_step_size(const u32 s)
kat_set_threshold(const u32 t)
kat_set_visualization(const bool visualizeTear, const bool visualizeRange)

Enumerations

enum classanti_tear_scan_direction_e
enum classanti_tear_scan_hint_e

Detailed description

The anti-tear subsystem interface.

The anti-tear subsystem is responsible for reducing temporal tearing artifacts in captured frames.

Generally, tearing artifacts occur when the capture device samples an image of the input signal while the signal source is still in the process of drawing the image. The captured frame will then consists of parts of new image data and parts of old image data, with tears occurring where new and old parts meet.

The anti-tear subsystem takes as input a series of images and produces as output a second, reduced series of images in which the input images' new parts have been combined into un-torn images. For instance, if you input two captured frames in which the top half of the first frame contains one half of an image and the bottom half of the second frame contains the second half of the image, the output will be one whole image.

The gist of the anti-tearing algorithm is that it first compares pixels in the current input image against the pixels in the previous input image (scanning pixels row by row) to find which areas of the image have changed, then copies the new areas' pixels into a back buffer. The algorithm repeats itself across successive input images until the back buffer contains a full de-torn image. A major source of uncertainty in the algorithm comes from the fact that captured frames may contain extraneous analog noise etc., making it less obvious which parts of the image have changed from the previous one.

Usage

  1. Call kat_initialize_anti_tear() to initialize the subsystem. This is VCS's default startup behavior.
  2. Call kat_anti_tear() with the image data on which you want to apply anti-tearing.
  3. Optionally, call any of the setter functions (kat_set_xxxx) to adjust the anti-tearer's operation.
  4. Call kat_release_anti_tear() to release the subsystem. This is VCS's default exit behavior.

Enumeration type documentation

enum class anti_tear_scan_direction_e

Enumerates the directions in which the anti-tear subsystem can scan images for tears.

The scan direction determines which parts of an image following and preceding a tear are considered by the anti-tearer to be new or old relative to the previous image. For instance, if the scan begins from the top and encounters a tear in the middle, the upper half of the image would be considered new; whereas the lower half would be considered new if the scan had started from the bottom.

For correct anti-tearing results, the scan direction should match the direction in which the capture source draws the image (which in turn may depend e.g. on the video mode).

up

Scans input images from bottom to top.

down

Scans input images from top to bottom.

enum class anti_tear_scan_hint_e

Enumerates the tear-scanning hints which can be given to the anti-tear subsystem (see kat_set_scan_hint()). These hints provide insight about the input data which may improve the anti-tearer's performance.

look_for_one_tear

Tells the anti-tear subsystem that input images are expected to have at most one tear. In other words, a single un-torn image will span no more than two consecutive input images. This may allow the anti-tearer to apply performance optimizations, but will lead to incorrect anti-tearing results if any input image has more than one tear.

look_for_multiple_tears

Tells the anti-tear subsystem that input images may have several tears. In other words, a single un-torn image may span any number of consecutive input images. The anti-tearer may, however, choose to only scan a certain maximum number of consecutive input images before declaring the result to be a fully de-torn image.

Function documentation

u8* kat_anti_tear(u8 *const pixels, const resolution_s &r)

Submits an image into the anti-tearing process. The parts of the image that are found by the anti-tearer to be new relative to the previous submitted image(s) will be integrated into the anti-tearer's back buffer and eventually made available in its output.

If anti-tearing is enabled in VCS, this function returns a pointer to a subsystem-managed pixel buffer containing a copy of the most recent fully de-torn image. The buffer's data will be re-written by each call to this function. The caller is free to modify this buffer's data; doing so will have no effect on the anti-tearing process.

If anti-tearing is disabled in VCS, this function acts as a passive passthrough and just returns pixels.

The input data won't be modified.

Note:

This function returns the most recent fully de-torn image; meaning e.g. that if an image is torn into two consecutive frames, the effective frame rate of the function's output is half of its input, as each output image requires two input images (two consecutive calls will return the same output image until the next fully de-torn image is available).

Warning:

This function should not be called before the subsystem has been initialized with kat_initialize_anti_tear().

Warning:

The pointer returned by this function should be considered invalid after kat_release_anti_tear() has been called.

kat_initialize_anti_tear(void)

Initializes the anti-tear subsystem.

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

Note:

Will trigger an assertion failure if the initialization fails.

kat_release_anti_tear(void)

Releases the anti-tear subsystem, including all of its memory buffers.

By default, VCS will call this function on program exit.

Returns true on success; false otherwise.

Warning:

Calling this function – regardless of its return value – invalidates the pointer returned by kat_anti_tear().

kat_set_anti_tear_enabled(const bool state)

Sets anti-tearing to enabled/disabled.

When disabled, kat_anti_tear() will act as a passive passthrough and no anti-tearing processing will be performed.

kat_set_domain_size(const u32 ds)

Sets the size of the tear scanner's horizontal sampling window.

When scanning input images for tears, the anti-tearer averages together a number of adjacent horizontal pixels' color values to reduce the negative effect of temporal analog noise on the accuracy of the scan. The size of the sampling window determines the number of adjacent pixels to average together.

With no temporal pixel noise present, smaller values of ds should result in a more accurate tear scan. The more noise there is, the larger the value of ds needs to be.

kat_set_matches_required(const u32 mr)

Sets the number of pixels in the row of an input image that must pass the delta value threshold for the row to be considered new data relative to the previous input image.

Due to analog noise etc., the tear scanner is expected to generate some false positives when comparing pixels between adjacent captured frames. This setting reduces the scanner's sensitivity by allowing a greater number of false positives without triggering a false detection of a tear.

The less temporal pixel noise in the input images, the lower the value of mr can be.

kat_set_range(const u32 min, const u32 max)

Sets the vertical range over which the anti-tearer will scan input images for tears.

min is the vertical pixel row offset from the first pixel row in the image toward the last row, while max is the vertical pixel row offset from the last pixel row in the image toward the first row. If the current scan direction is down, the first pixel row is at the top of the image and the last row is at the bottom, whereas if the scan direction is up, the first pixel row is at the bottom of the image and the last row is at the top.

For example, to scan the bottom half of a 640 x 480 image when the scan direction is down, pass 240 for min (start at the 240th vertical pixel row from the top) and 0 for max (scan down to the 480 - max = 480th vertical pixel row). To scan the same region of the image when the scan direction is up, pass 0 for min (start at the 480 - min = 480th pixel row) and 240 for max (scan up to the 240th pixel row).

kat_set_scan_direction(const anti_tear_scan_direction_e newDirection)

Sets the current anti-tearing scan direction.

kat_set_scan_hint(const anti_tear_scan_hint_e newHint)

Sets the current anti-tearing scan hint.

kat_set_step_size(const u32 s)

Sets the number of horizontal pixels to skip when scanning for tears.

The tear scanner will examine every s pixels in a given pixel row to determine whether the row has changed between the current input image and the image before that.

Smaller values of s will result in a more accurate scan, but higher values will make the scan faster.

Note:

A step size of 0 would result in an infinite loop, so that value will be converted to 1. A step size larger than the width of the input image will be interpreted as a step size equal to the width of the image, which will result in the scanner only examining the the first pixel on each row.

kat_set_threshold(const u32 t)

Sets the threshold amount by which pixel color values are required to change between two consecutive input images for the pixel to be considered to have changed (accounting for analog noise etc.).

The less temporal pixel noise in the input images, the lower the value of t can be.

kat_set_visualization(const bool visualizeTear, const bool visualizeRange)

Toggles visualizing options.

The anti-tear subsystem provides some visual metaoutput of the anti-tearing process.

visualizeTear sets whether detected tears are visually indicated in the output image. If true, horizontal lines will be drawn at the locations of the tears out of which the image was constructed.

visualizeRange sets whether the current scan range should be visually indicated in the output image. If true, the region in the output image over which the anti-tearer scanned for tears will be shaded.