i-g-t framebuffer

i-g-t framebuffer — Framebuffer handling and drawing library

Functions

Types and Values

typedef cairo_surface_t
typedef cairo_t
struct igt_fb
enum igt_text_align

Includes

#include <igt_fb.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 framebufffer 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_create_fb_with_bo_size ()

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

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

 

fb

pointer to an igt_fb structure

 

bo_size

size of the backing bo (0 for minimum needed size)

 

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,
               unsigned int 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,
                     unsigned int 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

gree 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_stereo_fb ()

unsigned int
igt_create_stereo_fb (int drm_fd,
                      drmModeModeInfo *mode,
                      uint32_t format,
                      unsigned int 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_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

gree 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

gree 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

gree value to use as fill color

 

b

blue value to use as fill 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. This is currently only used by the CR-code based testing in the "testdisplay" testcase.

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

void
igt_write_fb_to_png (int fd,
                     struct igt_fb *fb,
                     const char *filename);

This function stores the contents of the supplied framebuffer into a png image stored at filename .

Parameters

fd

open i915 drm file descriptor

 

fb

pointer to an igt_fb structure

 

filename

target name for the png image

 

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

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

This functions returns an array of all the drm fourcc codes supported by this library. The caller must free the allocated array again with free().

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

cairo_surface_t

typedef struct _cairo_surface cairo_surface_t;

cairo_t

typedef struct _cairo cairo_t;

struct igt_fb

struct igt_fb {
	uint32_t fb_id;
	uint32_t gem_handle;
	uint32_t drm_format;
	int width;
	int height;
	unsigned stride;
	unsigned tiling;
	unsigned size;
	cairo_surface_t *cairo_surface;
};

enum igt_text_align

Members

align_left

   

align_bottom

   

align_right

   

align_top

   

align_vcenter

   

align_hcenter