Framebuffer

Framebuffer — Framebuffer handling and drawing library

Functions

Types and Values

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_FORMAT_ARGS()

#define             IGT_FORMAT_ARGS(f)

igt_get_fb_tile_size ()

void
igt_get_fb_tile_size (int fd,
                      uint64_t modifier,
                      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

 

modifier

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,
                  uint32_t format,
                  uint64_t modifier,
                  uint64_t *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

 

format

drm fourcc pixel format code

 

modifier

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 modifier,
                            enum igt_color_encoding color_encoding,
                            enum igt_color_range color_range,
                            struct igt_fb *fb,
                            uint64_t 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

 

modifier

tiling layout of the framebuffer (as framebuffer modifier)

 

color_encoding

color encoding for YCbCr formats (ignored otherwise)

 

color_range

color range for YCbCr formats (ignored otherwise)

 

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 modifier,
               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

 

modifier

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 modifier,
                     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

 

modifier

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 modifier,
                       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

 

modifier

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 modifier,
                             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

 

modifier

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 modifier,
                     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

 

modifier

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 modifier);

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

 

modifier

tiling layout of the framebuffer

 

Returns

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


igt_fb_convert_with_stride ()

unsigned int
igt_fb_convert_with_stride (struct igt_fb *dst,
                            struct igt_fb *src,
                            uint32_t dst_fourcc,
                            uint64_t dst_modifier,
                            unsigned int stride);

This will convert a given src content to the dst_fourcc format, storing the result in the dst fb, allocating the dst fb underlying buffer with a stride of dst_stride stride.

Once done with dst , the caller will have to call igt_remove_fb() on it to free the associated resources.

Parameters

dst

pointer to the igt_fb structure that will store the conversion result

 

src

pointer to the igt_fb structure that stores the frame we convert

 

dst_fourcc

DRM format specifier to convert to

 

dst_modifier

DRM format modifier to convert to

 

dst_stride

Stride for the resulting framebuffer (0 for automatic stride)

 

Returns

The kms id of the created framebuffer.


igt_fb_convert ()

unsigned int
igt_fb_convert (struct igt_fb *dst,
                struct igt_fb *src,
                uint32_t dst_fourcc,
                uint64_t dst_modifier);

This will convert a given src content to the dst_fourcc format, storing the result in the dst fb, allocating the dst fb underlying buffer.

Once done with dst , the caller will have to call igt_remove_fb() on it to free the associated resources.

Parameters

dst

pointer to the igt_fb structure that will store the conversion result

 

src

pointer to the igt_fb structure that stores the frame we convert

 

dst_fourcc

DRM format specifier to convert to

 

dst_modifier

DRM format modifier to convert to

 

Returns

The kms id of the created framebuffer.


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_fb_map_buffer ()

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

This function will creating a new mapping of the buffer and return a pointer to the content of the supplied framebuffer's plane. This mapping needs to be deleted using igt_fb_unmap_buffer().

Parameters

fd

open drm file descriptor

 

fb

pointer to an igt_fb structure

 

Returns

A pointer to a buffer with the contents of the framebuffer


igt_fb_unmap_buffer ()

void
igt_fb_unmap_buffer (struct igt_fb *fb,
                     void *buffer);

This function will unmap a buffer mapped previously with igt_fb_map_buffer().

Parameters

fb

pointer to the backing igt_fb structure

 

buffer

pointer to the buffer previously mappped

 

igt_create_bo_for_fb ()

void
igt_create_bo_for_fb (int fd,
                      int width,
                      int height,
                      uint32_t format,
                      uint64_t modifier,
                      struct igt_fb *fb);

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,
                               uint64_t *size_ret,
                               unsigned *stride_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_calc_crc ()

void
igt_fb_calc_crc (struct igt_fb *fb,
                 igt_crc_t *crc);

This function calculate the 16-bit frame CRC of RGB components over all the active pixels.

Parameters

fb

pointer to an igt_fb structure

 

crc

pointer to an igt_crc_t structure

 

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's plane 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 igt_put_cairo_ctx(). 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_put_cairo_ctx ()

void
igt_put_cairo_ctx (int fd,
                   struct igt_fb *fb,
                   cairo_t *cr);

This releases the cairo surface cr returned by igt_get_cairo_ctx() for fb , and writes the changes out to the framebuffer if cairo doesn't have native support for the format.

Parameters

fd

open i915 drm file descriptor

 

fb

pointer to an igt_fb structure

 

cr

the cairo context returned by igt_get_cairo_ctx.

 

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_fb_supported_format ()

bool
igt_fb_supported_format (uint32_t drm_format);

This functions returns whether drm_format can be succesfully created by igt_create_fb() and drawn to by igt_get_cairo_ctx().

Parameters

drm_format

drm fourcc to test.

 

igt_format_is_yuv ()

bool
igt_format_is_yuv (uint32_t drm_format);

This functions returns whether drm_format is YUV (as opposed to RGB).

Parameters

drm_format

drm fourcc

 

igt_format_is_fp16 ()

bool
igt_format_is_fp16 (uint32_t drm_format);

Check if the format is fp16.

Parameters

drm_format

drm fourcc

 

igt_format_plane_bpp ()

int
igt_format_plane_bpp (uint32_t drm_format,
                      int plane);

This functions returns the number of bits per pixel for the given plane index of the drm_format .

Parameters

drm_format

drm fourcc

 

plane

format plane index

 

igt_format_array_fill ()

void
igt_format_array_fill (uint32_t **formats_array,
                       unsigned int *count,
                       bool allow_yuv);

This functions allocates and fills a formats_array that lists the DRM formats current available.

Parameters

formats_array

a pointer to the formats array pointer to be allocated

 

count

a pointer to the number of elements contained in the allocated array

 

allow_yuv

a boolean indicating whether YUV formats should be included

 

Types and Values

IGT_FORMAT_FLOAT

#define IGT_FORMAT_FLOAT fourcc_code('I', 'G', 'F', 'x')

IGT_FORMAT_FMT

#define IGT_FORMAT_FMT "%c%c%c%c(0x%08x)"

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;
	enum igt_color_encoding color_encoding;
	enum igt_color_range color_range;
	uint64_t modifier;
	uint64_t size;
	cairo_surface_t *cairo_surface;
	unsigned int domain;
	unsigned int num_planes;
	uint32_t strides[4];
	uint32_t offsets[4];
	unsigned int plane_bpp[4];
	unsigned int plane_width[4];
	unsigned int plane_height[4];
} 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

 

enum igt_color_encoding color_encoding;

   

enum igt_color_range color_range;

   

uint64_t modifier;

tiling mode as a DRM framebuffer modifier

 

uint64_t 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

 

unsigned int num_planes;

Amount of planes on this fb. >1 for planar formats.

 

uint32_t strides[4];

line stride for each plane in bytes

 

uint32_t offsets[4];

Offset for each plane in bytes.

 

unsigned int plane_bpp[4];

The bpp for each plane.

 

unsigned int plane_width[4];

The width for each plane.

 

unsigned int plane_height[4];

The height for each plane.

 

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