From 3d9e63f2ad0c676b3efba4c854ef645ae60ee7e1 Mon Sep 17 00:00:00 2001 From: Daniel Vetter Date: Wed, 26 Mar 2014 16:37:15 +0100 Subject: lib/igt_fb: api documentation Also realign function parameters and replace abort() with igt_fail() while at it. v2: Forgotten to add a nice intro. Signed-off-by: Daniel Vetter --- lib/igt_fb.c | 226 +++++++++++++++++++++++++++++++++++++++++++++++++++++++---- lib/igt_fb.h | 9 ++- 2 files changed, 217 insertions(+), 18 deletions(-) (limited to 'lib') diff --git a/lib/igt_fb.c b/lib/igt_fb.c index 60b582fb..ef486f97 100644 --- a/lib/igt_fb.c +++ b/lib/igt_fb.c @@ -38,6 +38,17 @@ * @short_description: Framebuffer handling and drawing library * @title: i-g-t framebuffer * @include: igt_fb.h + * + * 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. */ /* drm fourcc/cairo format maps */ @@ -107,25 +118,68 @@ static int create_bo_for_fb(int fd, int width, int height, int bpp, return 0; } +/** + * igt_paint_color: + * @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 + * + * This functions draws a solid rectangle with the given color using the drawing + * context @cr. + */ void igt_paint_color(cairo_t *cr, int x, int y, int w, int h, - double r, double g, double b) + double r, double g, double b) { cairo_rectangle(cr, x, y, w, h); cairo_set_source_rgb(cr, r, g, b); cairo_fill(cr); } +/** + * igt_paint_color_alpha: + * @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 + * + * This functions draws a rectangle with the given color and alpha values using + * the drawing context @cr. + */ void igt_paint_color_alpha(cairo_t *cr, int x, int y, int w, int h, - double r, double g, double b, double a) + double r, double g, double b, double a) { cairo_rectangle(cr, x, y, w, h); cairo_set_source_rgba(cr, r, g, b, a); cairo_fill(cr); } +/** + * igt_paint_color_gradient: + * @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 + * + * This functions draws a gradient into the rectangle which fades in from black + * to the given values using the drawing context @cr. + */ void igt_paint_color_gradient(cairo_t *cr, int x, int y, int w, int h, - int r, int g, int b) + int r, int g, int b) { cairo_pattern_t *pat; @@ -162,6 +216,21 @@ paint_test_patterns(cairo_t *cr, int width, int height) igt_paint_color_gradient(cr, x, y, gr_width, gr_height, 1, 1, 1); } +/** + * igt_cairo_printf_line: + * @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 + * + * 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. + * + * Returns: + * The width of the drawn text. + */ int igt_cairo_printf_line(cairo_t *cr, enum igt_text_align align, double yspacing, const char *fmt, ...) { @@ -236,6 +305,20 @@ paint_marker(cairo_t *cr, int x, int y) igt_cairo_printf_line(cr, align, 0, "(%d, %d)", x, y); } +/** + * igt_paint_test_pattern: + * @cr: cairo drawing context + * @width: width of the visible area + * @height: height of the visible area + * + * 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. + */ void igt_paint_test_pattern(cairo_t *cr, int width, int height) { paint_test_patterns(cr, width, height); @@ -251,8 +334,21 @@ void igt_paint_test_pattern(cairo_t *cr, int width, int height) igt_assert(!cairo_status(cr)); } +/** + * igt_paint_image: + * @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 + * + * 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. + */ void igt_paint_image(cairo_t *cr, const char *filename, - int dst_x, int dst_y, int dst_width, int dst_height) + int dst_x, int dst_y, int dst_width, int dst_height) { cairo_surface_t *image; int img_width, img_height; @@ -279,8 +375,28 @@ void igt_paint_image(cairo_t *cr, const char *filename, cairo_restore(cr); } +/** + * igt_create_fb: + * @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 + * @tiled: X-tiled or linear framebuffer + * @fb: pointer to an #igt_fb structure + * + * 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. + * + * Returns: + * The kms id of the created framebuffer on success or a negative error code on + * failure. + */ unsigned int igt_create_fb(int fd, int width, int height, uint32_t format, - bool tiled, struct igt_fb *fb) + bool tiled, struct igt_fb *fb) { uint32_t handles[4]; uint32_t pitches[4]; @@ -318,10 +434,33 @@ unsigned int igt_create_fb(int fd, int width, int height, uint32_t format, return fb_id; } +/** + * igt_create_color_fb: + * @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 + * @tiled: X-tiled or linear 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 + * + * 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. + * + * Returns: + * The kms id of the created framebuffer on success or a negative error code on + * failure. + */ unsigned int igt_create_color_fb(int fd, int width, int height, - uint32_t format, bool tiled, - double r, double g, double b, - struct igt_fb *fb /* out */) + uint32_t format, bool tiled, + double r, double g, double b, + struct igt_fb *fb /* out */) { unsigned int fb_id; cairo_t *cr; @@ -345,7 +484,7 @@ static cairo_format_t drm_format_to_cairo(uint32_t drm_format) if (f->drm_id == drm_format) return f->cairo_id; - abort(); + igt_fail(101); } static void __destroy_cairo_surface(void *arg) @@ -374,6 +513,19 @@ static cairo_surface_t *get_cairo_surface(int fd, struct igt_fb *fb) return cairo_surface_reference(fb->cairo_surface); } +/** + * igt_get_cairo_ctx: + * @fd: open i915 drm file descriptor + * @fb: pointer to an #igt_fb structure + * + * 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. + * + * Returns: + * The created cairo drawing context. + */ cairo_t *igt_get_cairo_ctx(int fd, struct igt_fb *fb) { cairo_surface_t *surface; @@ -391,6 +543,14 @@ cairo_t *igt_get_cairo_ctx(int fd, struct igt_fb *fb) return cr; } +/** + * @fd: open i915 drm file descriptor + * @fb: pointer to an #igt_fb structure + * @filename: target name for the png image + * + * This function stores the contents of the supplied framebuffer into a png + * image stored at @filename. + */ void igt_write_fb_to_png(int fd, struct igt_fb *fb, const char *filename) { cairo_surface_t *surface; @@ -403,6 +563,15 @@ void igt_write_fb_to_png(int fd, struct igt_fb *fb, const char *filename) igt_assert(status == CAIRO_STATUS_SUCCESS); } +/** + * igt_remove_fb: + * @fd: open i915 drm file descriptor + * @fb: pointer to an #igt_fb structure + * + * 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. + */ void igt_remove_fb(int fd, struct igt_fb *fb) { cairo_surface_destroy(fb->cairo_surface); @@ -410,7 +579,15 @@ void igt_remove_fb(int fd, struct igt_fb *fb) gem_close(fd, fb->gem_handle); } -/* helpers to handle drm fourcc codes */ +/** + * igt_bpp_depth_to_drm_format: + * @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. + */ uint32_t igt_bpp_depth_to_drm_format(int bpp, int depth) { struct format_desc_struct *f; @@ -419,10 +596,17 @@ uint32_t igt_bpp_depth_to_drm_format(int bpp, int depth) if (f->bpp == bpp && f->depth == depth) return f->drm_id; - abort(); + igt_fail(101); } -/* Return fb_id on success, 0 on error */ +/** + * igt_drm_format_to_bpp: + * @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. + */ uint32_t igt_drm_format_to_bpp(uint32_t drm_format) { struct format_desc_struct *f; @@ -431,9 +615,17 @@ uint32_t igt_drm_format_to_bpp(uint32_t drm_format) if (f->drm_id == drm_format) return f->bpp; - abort(); + igt_fail(101); } +/** + * igt_format_str: + * @drm_format: drm fourcc pixel format code + * + * Returns: + * Human-readable fourcc pixel format code for @drm_format or "invalid" no match + * was found. + */ const char *igt_format_str(uint32_t drm_format) { struct format_desc_struct *f; @@ -445,6 +637,14 @@ const char *igt_format_str(uint32_t drm_format) return "invalid"; } +/** + * igt_get_all_formats: + * @formats: pointer to pointer to store the allocated formats array + * @format_count: pointer to integer to store the size of the allocated array + * + * 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(). + */ void igt_get_all_formats(const uint32_t **formats, int *format_count) { static uint32_t *drm_formats; diff --git a/lib/igt_fb.h b/lib/igt_fb.h index d5e728cc..5f0ff51c 100644 --- a/lib/igt_fb.h +++ b/lib/igt_fb.h @@ -56,17 +56,13 @@ enum igt_text_align { align_hcenter = 0x08, }; -int igt_cairo_printf_line(cairo_t *cr, enum igt_text_align align, - double yspacing, const char *fmt, ...) - __attribute__((format (printf, 4, 5))); - unsigned int igt_create_fb(int fd, int width, int height, uint32_t format, bool tiled, struct igt_fb *fb); unsigned int igt_create_color_fb(int fd, int width, int height, uint32_t format, bool tiled, double r, double g, double b, struct igt_fb *fb /* out */); -void igt_remove_fb(int fd, struct igt_fb *fb_info); +void igt_remove_fb(int fd, struct igt_fb *fb); /* cairo-based painting */ cairo_t *igt_get_cairo_ctx(int fd, struct igt_fb *fb); @@ -80,6 +76,9 @@ void igt_paint_test_pattern(cairo_t *cr, int width, int height); void igt_paint_image(cairo_t *cr, const char *filename, int dst_x, int dst_y, int dst_width, int dst_height); void igt_write_fb_to_png(int fd, struct igt_fb *fb, const char *filename); +int igt_cairo_printf_line(cairo_t *cr, enum igt_text_align align, + double yspacing, const char *fmt, ...) + __attribute__((format (printf, 4, 5))); /* helpers to handle drm fourcc codes */ uint32_t igt_bpp_depth_to_drm_format(int bpp, int depth); -- cgit v1.2.3