Frame: igt-gpu-tools Reference Manual

## Frame Frame — Library for frame-related tests |

## Functions

bool | igt_frame_dump_is_enabled ()
void | igt_write_compared_frames_to_png ()
bool | igt_check_analog_frame_match ()
bool | igt_check_checkerboard_frame_match ()

## Includes

    #include <igt_frame.h>

## Description

This library contains helpers for frame-related tests. This includes common frame dumping as well as frame comparison helpers.

## Functions

### igt_frame_dump_is_enabled ()

    bool
    igt_frame_dump_is_enabled (void);

Get whether frame dumping is enabled.

#### Returns

A boolean indicating whether frame dumping is enabled

### igt_write_compared_frames_to_png ()

    void
    igt_write_compared_frames_to_png (cairo_surface_t *reference,
                                      cairo_surface_t *capture,
                                      const char *reference_suffix,
                                      const char *capture_suffix);

Write previously compared frames to png files.

#### Parameters

reference | The reference cairo surface |
capture | The captured cairo surface |
reference_suffix | The suffix to give to the reference png file |
capture_suffix | The suffix to give to the capture png file |

### igt_check_analog_frame_match ()

    bool
    igt_check_analog_frame_match (cairo_surface_t *reference,
                                  cairo_surface_t *capture);

Checks that the analog image contained in the chamelium frame dump matches the given framebuffer.

In order to determine whether the frame matches the reference, the following reasoning is implemented:

1. The absolute error for each color value of the reference is collected.

2. The average absolute error is calculated for each color value of the reference and must not go above 60 (23.5 % of the total range).

3. A linear fit for the average absolute error from the pixel value is calculated, as a DAC-ADC chain is expected to have a linear error curve.

4. The linear fit is correlated with the actual average absolute error for the frame and the correlation coefficient is checked to be > 0.985, indicating a match with the expected error trend.

Most errors (e.g. due to scaling, rotation, color space, etc) can be reliably detected this way, with a minimized number of false-positives. However, the brightest values (250 and up) are ignored as the error trend is often not linear there in practice due to clamping.

#### Parameters

reference | The reference cairo surface |
capture | The captured cairo surface |

#### Returns

a boolean indicating whether the frames match

### igt_check_checkerboard_frame_match ()

    bool
    igt_check_checkerboard_frame_match (cairo_surface_t *reference,
                                        cairo_surface_t *capture);

Checks that the reference frame matches the captured frame using a method designed for checkerboard patterns. These patterns are made of consecutive rectangular shapes with alternating solid colors.

The intent of this method is to cover cases where the captured result is not pixel-perfect due to features such as scaling or YUV conversion and subsampling. Such effects are mostly noticeable on the edges of the patterns, so they are detected and excluded from the comparison.

The algorithm works with two major steps. First, the edges of the reference pattern are detected on the x and y axis independently. The detection is done by calculating an absolute difference with a span of a few pixels before and after the current position on the given axis, accumulated for each color component. If the sum is above a given threshold on one of the axis, the position is marked as an edge. In the second step, the pixel values are compared per-component, excluding positions that were marked as edges or that are at a transition between an edge and a non-edge. An error threshold (for each individual color component) is used to mark the position as erroneous or not. The ratio of erroneous pixels over compared pixels (that does not count excluded pixels) is then calculated and compared to the error rate threshold to determine whether the frames match or not.

#### Parameters

reference | The reference cairo surface |
capture | The captured cairo surface |

#### Returns

a boolean indicating whether the frames match