## Framebuffer Framebuffer — Framebuffer handling and drawing library |

## Functions

void | igt_get_fb_tile_size ()
void | igt_calc_fb_size ()
unsigned int | igt_create_fb_with_bo_size ()
unsigned int | igt_create_fb ()
unsigned int | igt_create_color_fb ()
unsigned int | igt_create_pattern_fb ()
unsigned int | igt_create_color_pattern_fb ()
unsigned int | igt_create_image_fb ()
unsigned int | igt_create_stereo_fb ()
void | igt_remove_fb ()
int | igt_dirty_fb ()
int | igt_create_bo_with_dimensions ()
uint64_t | igt_fb_mod_to_tiling ()
uint64_t | igt_fb_tiling_to_mod ()
cairo_surface_t * | igt_get_cairo_surface ()
cairo_surface_t * | igt_cairo_image_surface_create_from_png ()
cairo_t * | igt_get_cairo_ctx ()
void | igt_paint_color ()
void | igt_paint_color_alpha ()
void | igt_paint_color_gradient ()
void | igt_paint_color_gradient_range ()
void | igt_paint_test_pattern ()
void | igt_paint_image ()
int | igt_cairo_printf_line ()
uint32_t | igt_bpp_depth_to_drm_format ()
uint32_t | igt_drm_format_to_bpp ()
const char * | igt_format_str ()
void | igt_get_all_cairo_formats ()

## Types and Values

| igt_fb_t
enum | igt_text_align

## Includes

    #include <igt.h>

## Description

This library contains helper functions for handling kms framebuffer objects using igt_fb structures to track all the metadata. `igt_create_fb()` creates a basic framebuffer and `igt_remove_fb()` cleans everything up again.

It also supports drawing using the cairo library and provides some simplified helper functions to easily draw test patterns. The main function to create a cairo drawing context for a framebuffer object is `igt_get_cairo_ctx()`.

Finally it also pulls in the drm fourcc headers and provides some helper functions to work with these pixel format codes.

## Functions

### igt_get_fb_tile_size ()

    void
    igt_get_fb_tile_size (int fd,
                          uint64_t tiling,
                          int fb_bpp,
                          unsigned *width_ret,
                          unsigned *height_ret);

This function returns width and height of a tile based on the given tiling format.

#### Parameters

fd | the DRM file descriptor |
tiling | tiling layout of the framebuffer (as framebuffer modifier) |
fb_bpp | bits per pixel of the framebuffer |
width_ret | width of the tile in bytes |
height_ret | height of the tile in lines |

### igt_calc_fb_size ()

    void
    igt_calc_fb_size (int fd,
                      int width,
                      int height,
                      int bpp,
                      uint64_t tiling,
                      unsigned *size_ret,
                      unsigned *stride_ret);

This function returns valid stride and size values for a framebuffer with the specified parameters.

#### Parameters

fd | the DRM file descriptor |
width | width of the framebuffer in pixels |
height | height of the framebuffer in pixels |
bpp | bytes per pixel of the framebuffer |
tiling | tiling layout of the framebuffer (as framebuffer modifier) |
size_ret | returned size for the framebuffer |
stride_ret | returned stride for the framebuffer |

### igt_create_fb_with_bo_size ()

    unsigned int
    igt_create_fb_with_bo_size (int fd,
                                int width,
                                int height,
                                uint32_t format,
                                uint64_t tiling,
                                struct igt_fb *fb,
                                unsigned  bo_size,
                                unsigned  bo_stride);

This function allocates a gem buffer object suitable to back a framebuffer with the requested properties and then wraps it up in a drm framebuffer object of the requested size. All metadata is stored in `fb` .

The backing storage of the framebuffer is filled with all zeros, i.e. black for rgb pixel formats.

#### Parameters

fd | open i915 drm file descriptor |
width | width of the framebuffer in pixel |
height | height of the framebuffer in pixel |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer (as framebuffer modifier) |
fb | pointer to an igt_fb structure |
bo_size | size of the backing bo (0 for automatic size) |
bo_stride | stride of the backing bo (0 for automatic stride) |

#### Returns

The kms id of the created framebuffer.

### igt_create_fb ()

    unsigned int
    igt_create_fb (int fd,
                   int width,
                   int height,
                   uint32_t format,
                   uint64_t tiling,
                   struct igt_fb *fb);

This function allocates a gem buffer object suitable to back a framebuffer with the requested properties and then wraps it up in a drm framebuffer object. All metadata is stored in `fb` .

The backing storage of the framebuffer is filled with all zeros, i.e. black for rgb pixel formats.

#### Parameters

fd | open i915 drm file descriptor |
width | width of the framebuffer in pixel |
height | height of the framebuffer in pixel |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer |
fb | pointer to an igt_fb structure |

#### Returns

The kms id of the created framebuffer.

### igt_create_color_fb ()

    unsigned int
    igt_create_color_fb (int fd,
                         int width,
                         int height,
                         uint32_t format,
                         uint64_t tiling,
                         double r,
                         double g,
                         double b,
                         struct igt_fb *fb);

This function allocates a gem buffer object suitable to back a framebuffer with the requested properties and then wraps it up in a drm framebuffer object. All metadata is stored in `fb` .

Compared to `igt_create_fb()` this function also fills the entire framebuffer with the given color, which is useful for some simple pipe crc based tests.

#### Parameters

fd | open i915 drm file descriptor |
width | width of the framebuffer in pixel |
height | height of the framebuffer in pixel |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer |
r | red value to use as fill color |
g | green value to use as fill color |
b | blue value to use as fill color |
fb | pointer to an igt_fb structure |

#### Returns

The kms id of the created framebuffer on success or a negative error code on failure.

### igt_create_pattern_fb ()

    unsigned int
    igt_create_pattern_fb (int fd,
                           int width,
                           int height,
                           uint32_t format,
                           uint64_t tiling,
                           struct igt_fb *fb);

This function allocates a gem buffer object suitable to back a framebuffer with the requested properties and then wraps it up in a drm framebuffer object. All metadata is stored in `fb` .

Compared to `igt_create_fb()` this function also draws the standard test pattern into the framebuffer.

#### Parameters

fd | open i915 drm file descriptor |
width | width of the framebuffer in pixel |
height | height of the framebuffer in pixel |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer |
fb | pointer to an igt_fb structure |

#### Returns

The kms id of the created framebuffer on success or a negative error code on failure.

### igt_create_color_pattern_fb ()

    unsigned int
    igt_create_color_pattern_fb (int fd,
                                 int width,
                                 int height,
                                 uint32_t format,
                                 uint64_t tiling,
                                 double r,
                                 double g,
                                 double b,
                                 struct igt_fb *fb);

This function allocates a gem buffer object suitable to back a framebuffer with the requested properties and then wraps it up in a drm framebuffer object. All metadata is stored in `fb` .

Compared to `igt_create_fb()` this function also fills the entire framebuffer with the given color, and then draws the standard test pattern into the framebuffer.

#### Parameters

fd | open i915 drm file descriptor |
width | width of the framebuffer in pixel |
height | height of the framebuffer in pixel |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer |
r | red value to use as fill color |
g | green value to use as fill color |
b | blue value to use as fill color |
fb | pointer to an igt_fb structure |

#### Returns

The kms id of the created framebuffer on success or a negative error code on failure.

### igt_create_image_fb ()

    unsigned int
    igt_create_image_fb (int drm_fd,
                         int width,
                         int height,
                         uint32_t format,
                         uint64_t tiling,
                         const char *filename,
                         struct igt_fb *fb);

Create a framebuffer with the specified image. If `width` is zero the image width will be used. If `height` is zero the image height will be used.

#### Parameters

drm_fd | open i915 drm file descriptor |
width | width of the framebuffer in pixel or 0 |
height | height of the framebuffer in pixel or 0 |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer |
filename | filename of the png image to draw |
fb | pointer to an igt_fb structure |

#### Returns

The kms id of the created framebuffer on success or a negative error code on failure.

### igt_create_stereo_fb ()

    unsigned int
    igt_create_stereo_fb (int drm_fd,
                          drmModeModeInfo *mode,
                          uint32_t format,
                          uint64_t tiling);

Create a framebuffer for use with the stereo 3D mode specified by `mode` .

#### Parameters

drm_fd | open i915 drm file descriptor |
mode | A stereo 3D mode. |
format | drm fourcc pixel format code |
tiling | tiling layout of the framebuffer |

#### Returns

The kms id of the created framebuffer on success or a negative error code on failure.

### igt_remove_fb ()

    void
    igt_remove_fb (int fd,
                   struct igt_fb *fb);

This function releases all resources allocated in `igt_create_fb()` for `fb` . Note that if this framebuffer is still in use on a primary plane the kernel will disable the corresponding crtc.

#### Parameters

fd | open i915 drm file descriptor |
fb | pointer to an igt_fb structure |

### igt_dirty_fb ()

    int
    igt_dirty_fb (int fd,
                  struct igt_fb *fb);

Flushes out the whole framebuffer.

#### Parameters

fd | open drm file descriptor |
fb | pointer to an igt_fb structure |

#### Returns

0 upon success.

### igt_create_bo_with_dimensions ()

    int
    igt_create_bo_with_dimensions (int fd,
                                   int width,
                                   int height,
                                   uint32_t format,
                                   uint64_t modifier,
                                   unsigned  stride,
                                   unsigned *stride_ret,
                                   unsigned *size_ret,
                                   bool *is_dumb);

This function allocates a gem buffer object matching the requested properties.

#### Parameters

fd | open drm file descriptor |
width | width of the buffer object in pixels |
height | height of the buffer object in pixels |
format | drm fourcc pixel format code |
modifier | modifier corresponding to the tiling layout of the buffer object |
stride | stride of the buffer object in bytes (0 for automatic stride) |
size_ret | size of the buffer object as created by the kernel |
stride_ret | stride of the buffer object as created by the kernel |
is_dumb | whether the created buffer object is a dumb buffer or not |

#### Returns

The kms id of the created buffer object.

### igt_fb_mod_to_tiling ()

    uint64_t
    igt_fb_mod_to_tiling (uint64_t modifier);

This function converts a DRM framebuffer modifier to its corresponding tiling constant.

#### Parameters

modifier | DRM framebuffer modifier |

#### Returns

A tiling constant

### igt_fb_tiling_to_mod ()

    uint64_t
    igt_fb_tiling_to_mod (uint64_t tiling);

This function converts a DRM framebuffer tiling to its corresponding modifier constant.

#### Parameters

tiling | DRM framebuffer tiling |

#### Returns

A modifier constant

### igt_get_cairo_surface ()

    cairo_surface_t *
    igt_get_cairo_surface (int fd,
                           struct igt_fb *fb);

This function stores the contents of the supplied framebuffer into a cairo surface and returns it.

#### Parameters

fd | open drm file descriptor |
fb | pointer to an igt_fb structure |

#### Returns

A pointer to a cairo surface with the contents of the framebuffer.

### igt_cairo_image_surface_create_from_png ()

    cairo_surface_t *
    igt_cairo_image_surface_create_from_png
                                   (const char *filename);

### igt_get_cairo_ctx ()

    cairo_t *
    igt_get_cairo_ctx (int fd,
                       struct igt_fb *fb);

This initializes a cairo surface for `fb` and then allocates a drawing context for it. The return cairo drawing context should be released by calling `cairo_destroy()`. This also sets a default font for drawing text on framebuffers.

#### Parameters

fd | open i915 drm file descriptor |
fb | pointer to an igt_fb structure |

#### Returns

The created cairo drawing context.

### igt_paint_color ()

    void
    igt_paint_color (cairo_t *cr,
                     int x,
                     int y,
                     int w,
                     int h,
                     double r,
                     double g,
                     double b);

This functions draws a solid rectangle with the given color using the drawing context `cr` .

#### Parameters

cr | cairo drawing context |
x | pixel x-coordination of the fill rectangle |
y | pixel y-coordination of the fill rectangle |
w | width of the fill rectangle |
h | height of the fill rectangle |
r | red value to use as fill color |
g | green value to use as fill color |
b | blue value to use as fill color |

### igt_paint_color_alpha ()

    void
    igt_paint_color_alpha (cairo_t *cr,
                           int x,
                           int y,
                           int w,
                           int h,
                           double r,
                           double g,
                           double b,
                           double a);

This functions draws a rectangle with the given color and alpha values using the drawing context `cr` .

#### Parameters

cr | cairo drawing context |
x | pixel x-coordination of the fill rectangle |
y | pixel y-coordination of the fill rectangle |
w | width of the fill rectangle |
h | height of the fill rectangle |
r | red value to use as fill color |
g | green value to use as fill color |
b | blue value to use as fill color |
a | alpha value to use as fill color |

### igt_paint_color_gradient ()

    void
    igt_paint_color_gradient (cairo_t *cr,
                              int x,
                              int y,
                              int w,
                              int h,
                              int r,
                              int g,
                              int b);

This functions draws a gradient into the rectangle which fades in from black to the given values using the drawing context `cr` .

#### Parameters

cr | cairo drawing context |
x | pixel x-coordination of the fill rectangle |
y | pixel y-coordination of the fill rectangle |
w | width of the fill rectangle |
h | height of the fill rectangle |
r | red value to use as fill color |
g | green value to use as fill color |
b | blue value to use as fill color |

### igt_paint_color_gradient_range ()

    void
    igt_paint_color_gradient_range (cairo_t *cr,
                                    int x,
                                    int y,
                                    int w,
                                    int h,
                                    double sr,
                                    double sg,
                                    double sb,
                                    double er,
                                    double eg,
                                    double eb);

This functions draws a gradient into the rectangle which fades in from one color to the other using the drawing context `cr` .

#### Parameters

cr | cairo drawing context |
x | pixel x-coordination of the fill rectangle |
y | pixel y-coordination of the fill rectangle |
w | width of the fill rectangle |
h | height of the fill rectangle |
sr | red value to use as start gradient color |
sg | green value to use as start gradient color |
sb | blue value to use as start gradient color |
er | red value to use as end gradient color |
eg | green value to use as end gradient color |
eb | blue value to use as end gradient color |

### igt_paint_test_pattern ()

    void
    igt_paint_test_pattern (cairo_t *cr,
                            int width,
                            int height);

This functions draws an entire set of test patterns for the given visible area using the drawing context `cr` . This is useful for manual visual inspection of displayed framebuffers.

The test patterns include

- corner markers to check for over/underscan and

- a set of color and b/w gradients.

#### Parameters

cr | cairo drawing context |
width | width of the visible area |
height | height of the visible area |

### igt_paint_image ()

    void
    igt_paint_image (cairo_t *cr,
                     const char *filename,
                     int dst_x,
                     int dst_y,
                     int dst_width,
                     int dst_height);

This function can be used to draw a scaled version of the supplied png image, which is loaded from the package data directory.

#### Parameters

cr | cairo drawing context |
filename | filename of the png image to draw |
dst_x | pixel x-coordination of the destination rectangle |
dst_y | pixel y-coordination of the destination rectangle |
dst_width | width of the destination rectangle |
dst_height | height of the destination rectangle |

### igt_cairo_printf_line ()

    int
    igt_cairo_printf_line (cairo_t *cr,
                           enum igt_text_align align,
                           double yspacing,
                           const char *fmt,
                           ...);

This is a little helper to draw text onto framebuffers. All the initial setup (like setting the font size and the moving to the starting position) still needs to be done manually with explicit cairo calls on `cr` .

#### Parameters

cr | cairo drawing context |
align | text alignment |
yspacing | additional y-direction feed after this line |
fmt | format string |
... | optional arguments used in the format string |

#### Returns

The width of the drawn text.

### igt_bpp_depth_to_drm_format ()

    uint32_t
    igt_bpp_depth_to_drm_format (int bpp,
                                 int depth);

#### Parameters

bpp | desired bits per pixel |
depth | desired depth |

#### Returns

The rgb drm fourcc pixel format code corresponding to the given `bpp` and `depth` values. Fails hard if no match was found.

### igt_drm_format_to_bpp ()

    uint32_t
    igt_drm_format_to_bpp (uint32_t drm_format);

#### Parameters

drm_format | drm fourcc pixel format code |

#### Returns

The bits per pixel for the given drm fourcc pixel format code. Fails hard if no match was found.

### igt_format_str ()

    const char *
    igt_format_str (uint32_t drm_format);

#### Parameters

drm_format | drm fourcc pixel format code |

#### Returns

Human-readable fourcc pixel format code for `drm_format` or "invalid" no match was found.

### igt_get_all_cairo_formats ()

    void
    igt_get_all_cairo_formats (const uint32_t **formats,
                               int *format_count);

This functions returns an array of all the drm fourcc codes supported by cairo and this library.

#### Parameters

formats | pointer to pointer to store the allocated formats array |
format_count | pointer to integer to store the size of the allocated array |

## Types and Values

### igt_fb_t

    typedef struct {
    	uint32_t fb_id;
    	int fd;
    	uint32_t gem_handle;
    	bool is_dumb;
    	uint32_t drm_format;
    	int width;
    	int height;
    	unsigned int stride;
    	uint64_t tiling;
    	unsigned int size;
    	cairo_surface_t *cairo_surface;
    	unsigned int domain;
    } igt_fb_t;

Tracking structure for KMS framebuffer objects.

#### Members

uint32_t `fb_id`; | KMS ID of the framebuffer |
int `fd`; | DRM device fd this framebuffer is created on |
uint32_t `gem_handle`; | GEM handler of the underlying backing storage |
bool `is_dumb`; | Whether this framebuffer was allocated using the dumb buffer API |
uint32_t `drm_format`; | DRM FOURCC code |
int `width`; | width in pixels |
int `height`; | height in pixels |
unsigned int `stride`; | line stride in bytes |
uint64_t `tiling`; | tiling mode as a DRM framebuffer modifier |
unsigned int `size`; | size in bytes of the underlying backing storage |
cairo_surface_t *`cairo_surface`; | optionally attached cairo drawing surface |
unsigned int `domain`; | current domain for cache flushing tracking on i915.ko |

### enum igt_text_align

Alignment mode for text drawing using `igt_cairo_printf_line()`.

#### Members

align_left | align left |
align_bottom | align bottom |
align_right | align right |
align_top | align top |
align_vcenter | align vcenter |
align_hcenter | align hcenter |