`disp_draw_corefuncs_t`

Table of a driver's core drawing functions

Synopsis:

#include <draw.h>

typedef struct disp_draw_corefuncs {
    void (*wait_idle) (…);

    void (*draw_span) (…);
    void (*draw_span_list) (…);
    void (*draw_solid_rect) (…);
    void (*draw_line_pat8x1) (…);
    void (*draw_line_trans8x1) (…);
    void (*draw_rect_pat8x8) (…);
    void (*draw_rect_trans8x8) (…);

    void (*blit1) (…);
    void (*blit2) (…);
    void (*draw_bitmap) (…);

    void (*update_draw_surface) (…);
    void (*update_pattern) (…);


    void (*scaled_blit) (…);

    void (*draw_line) (…);
    int (*fill_poly) (…);

    int (*get_bresenham_params) (…);

    void (*update_transform) (…);
    void (*update_clipping) (…);


} disp_draw_corefuncs_t;

The disp_draw_corefuncs_t structure is a table that your driver uses to define the core 2D drawing functions that it provides to the graphics framework. Your driver's devg_get_corefuncs() entry point must fill in this structure.

The core functions need to obey only the target information from the disp_draw_context_t structure, unless otherwise noted.

wait_idle()

The graphics framework calls this function when it needs to wait for the hardware to become idle. The prototype is:

void (*wait_idle) (disp_draw_context_t *context);

This function must not return until the hardware is idle. It's safe to directly access the draw target surface after this function returns.

Fallback function: ffb_wait_idle()

draw_span()

The graphics framework calls this function to draw a single horizontal line. The prototype is:

void (*draw_span) (disp_draw_context_t *context,
                   disp_color_t color,
                   int x1,
                   int x2,
                   int y)

This function should draw a solid, opaque, horizontal line with the given color from (x1, y) to (x2, y). It doesn't use any pattern information — the line is a single, solid color.

Fallback functions: ffb_draw_span_8(), ffb_draw_span_16(), ffb_draw_span_24(), ffb_draw_span_32()

draw_span_list()

The graphics framework calls this function to draw a list of horizontal lines. The prototype is:

void (*draw_span_list) (
         disp_draw_context_t *context,
         int count,
         disp_color_t color,
         int *x1,
         int *x2,
         int *y)

It's identical to draw_span() above, except a list of lines is passed, with count indicating how many elements are present in the x1, x2, and y arrays.

Fallback functions: ffb_draw_span_list_8(), ffb_draw_span_list_16(), ffb_draw_span_list_24(), ffb_draw_span_list_32()

draw_solid_rect()

The graphics framework calls this function to draw a solid rectangle. The prototype is:

void (*draw_solid_rect) (
         disp_draw_context_t *context,
         disp_color_t color,
         int x1,
         int y1,
         int x2,
         int y2)

It draws a solid, opaque rectangle with the given color (in color), from (x1, y1) to (x2, y2). It doesn't use any pattern information — the rectangle is a single, solid color.

Fallback functions: ffb_draw_solid_rect_8(), ffb_draw_solid_rect_16(), ffb_draw_solid_rect_24(), ffb_draw_solid_rect_32()

draw_line_pat8x1()

The graphics framework calls this function to draw an opaque, patterned line. The prototype is:

void (*draw_line_pat8x1) (
         disp_draw_context_t *context,
         disp_color_t bgcolor,
         disp_color_t fgcolor,
         int x1,
         int x2,
         int y,
         uint8_t pattern)

It uses the pattern argument to determine the color to use for each pixel. An active bit (1) is drawn with the fgcolor color, and an inactive bit (0) is drawn with the bgcolor color. The pattern is consumed from left to right, with the most significant bit of the pattern being using for the first pixel drawn.

For more information, see “Patterns” in the Writing a Graphics Driver chapter.

Fallback functions: ffb_draw_line_pat8x1_8(), ffb_draw_line_pat8x1_16(), ffb_draw_line_pat8x1_24(), ffb_draw_line_pat8x1_32()

draw_line_trans8x1()

The graphics framework calls this function to draw a transparent, patterned line. The prototype is:

void (*draw_line_trans8x1) (
         disp_draw_context_t *context,
         disp_color_t color,
         int x1,
         int x2,
         int y,
         uint8_t pattern)

It uses the passed pattern to determine which pixels to draw. An active bit (1) is drawn with the color color, and an inactive bit (0) doesn't affect existing pixels. The pattern is consumed from left to right, with the most significant bit of the pattern being using for the first pixel drawn.

Fallback functions: ffb_draw_line_trans8x1_8(), ffb_draw_line_trans8x1_16(), ffb_draw_line_trans8x1_24(), ffb_draw_line_trans8x1_32()

draw_rect_pat8x8()

The graphics framework calls this function to draw an opaque, patterned rectangle. The prototype is:

void (*draw_rect_pat8x8) (
         disp_draw_context_t *context,
         disp_color_t fgcolor,
         disp_color_t bgcolor,
         int x1,
         int y1,
         int x2,
         int y2)

It uses the draw context structure's members pat, pat_xoff, pat_yoff, (but not pattern_format as it's already defined implicitly by virtue of this function being called). The pattern is used as described in the “Patterns” section of “Conventions,” in the Writing a Graphics Driver chapter. An active bit is drawn with the fgcolor color, and an inactive bit is drawn with the bgcolor color.

Fallback functions: ffb_draw_rect_pat8x8_8(), ffb_draw_rect_pat8x8_16(), ffb_draw_rect_pat8x8_24(), ffb_draw_rect_pat8x8_32()

draw_rect_trans8x8()

The graphics framework calls this function to draw a transparent, patterned rectangle. The prototype is:

void (*draw_rect_trans8x8) (
         disp_draw_context_t *context,
         disp_color_t color,
         int x1,
         int y1,
         int x2,
         int y2)

It uses the context structure's members pat, pat_xoff, pat_yoff, (but not pattern_format as it's already defined implicitly by virtue of this function being called). The pattern is used as described in the “Patterns” section of “Conventions,” in the Writing a Graphics Driver chapter. An active bit is drawn with the color color, and an inactive bit doesn't affect existing pixels.

Fallback functions: ffb_draw_rect_trans8x8_8(), ffb_draw_rect_trans8x8_16(), ffb_draw_rect_trans8x8_24(), ffb_draw_rect_trans8x8_32()

blit1()

The graphics framework calls this function to blit an area within a surface. The prototype is:

void (*blit1) (disp_draw_context_t *context,
               int sx,
               int sy,
               int dx,
               int dy,
               int width,
               int height)

It blits within the surface defined by the context structure's dsurf member (i.e., the source and destination are within the same surface). The contents of the area defined by the coordinates (sx, sy) for width width and height height are copied to the same-sized area defined by the coordinates (dx, dy).

This function must be able to deal with overlapping blits, i.e. where the source area intersects with the destination area.

Fallback function: ffb_core_blit1()

blit2()

The graphics framework calls this function to blit an area from one surface to another. The prototype is:

void (*blit2) (disp_draw_context_t *context,
               disp_surface_t *src,
               disp_surface_t *dst,
               int sx,
               int sy,
               int dx,
               int dy,
               int width,
               int height)

This function blits from the source surface specified by the disp_surface_t structure pointed to by src to the destination surface specified by dst. The contents of the area defined by the coordinates (sx, sy) for width width and height height, within the source surface, are transferred to the same-sized area defined by the coordinates (dx, dy), within the destination surface.

The src and dst surfaces are guaranteed to be different, whereas in blit1(), the operation takes place on the same surface (as implied by the lack of a destination surface parameter). Your driver may need to check the surface flags to see where the src and dst images are (either in system memory or video memory) before performing the operation, since the draw engine may not be able to copy the image directly from system RAM.

Fallback function: ffb_core_blit2()

draw_bitmap()

The graphics framework calls this function to draw an image in the destination surface by expanding the monochrome bitmap data in the buffer pointed to by “image”. The prototype is:

void (*draw_bitmap) (disp_draw_context_t *context,
                     uint8_t *image,
                     int sstride,
                     int bit0_offset,
                     disp_color_t fgcolor,
                     disp_color_t bgcolor,
                     int transparent,
                     int dx,
                     int dy,
                     int width,
                     int height)

The sstride argument specifies the stride of the source bitmap image, in bytes. The bit0_offset specifies an index into the first byte of the source bitmap. For each scanline of the bitmap that's drawn, this index specifies the bit within the first byte of the scanline's source data that corresponds to the first pixel of the scanline that's drawn.

The fgcolor specifies the color to use when drawing a pixel when the corresponding bit in the source image is a 1. The bgcolor argument specifies the color to use when drawing a pixel when the corresponding bit in the source image is a 0, and the image is monochrome (as opposed to transparent).

For the transparent argument, a value of 0 specifies that the bitmap is a monochrome bitmap. Otherwise, the bitmap is a transparent bitmap. For transparent bitmaps, a bit value of 0 in the source image means that the corresponding pixel shouldn't be drawn. For monochrome bitmaps, a bit value of 0 in the source image means that the corresponding pixel should be drawn using the color specified by bgcolor.

The point (dx, dy) specifies the pixel offset within the draw surface where the image is to be drawn, and the width and height arguments specify the size of the bitmap, in pixels.

Fallback functions: ffb_draw_bitmap_8(), ffb_draw_bitmap_16(), ffb_draw_bitmap_24(), ffb_draw_bitmap_32()

update_draw_surface()

The graphics framework calls this function whenever the members of the structure pointed to by the dsurf member of the context structure have changed. The prototype is:

void (*update_draw_surface) (
         disp_draw_context_t *context)

All subsequent 2D drawing operations should be performed on the surface specified by dsurf (except for functions where the target surfaces are specified explicitly by parameters to the function).

Fallback function: ffb_update_draw_surface()

update_pattern()

The graphics framework calls this function whenever pattern information in the context structure has changed. The prototype is:

void (*update_pattern) (
         disp_draw_context_t *context)

This information includes the flags, pat, pat_xoff, pat_yoff and pattern_format members.

Fallback function: ffb_update_pattern()

scaled_blit()

The graphics framework calls this function to copy pixels from an area of the source surface to an area of the destination surface. The prototype is:

void (*scaled_blit) (disp_draw_context_t *context,
        disp_surface_t *src,
        disp_surface_t *dst,
        int sx1, int sy1, int sx2, int sy2,
        int dx1, int dy1, int dx2, int dy2);

The source and destination areas may be different, and this function must scale the image data to make it fit into the destination area. The source area is specified by (sx1, sy1, sx2, sy2). The destination area is specified by (dx1, dy1, dx2, dy2). The image data may need to be scaled up, or down in both the horizontal and vertical directions. Scaling up in one direction, while scaling down in the other, must be supported.

Fallback function: ffb_core_scaled_blit()

draw_line()

The graphics framework calls this function to draw a single-pixel wide line, using Bresenham's algorithm, from the point (x1, y1) to the point (x2, y2). The prototype is:

void (*draw_line) (disp_draw_context_t *context,
    disp_color_t color,
    int x1,
    int y1,
    int x2,
    int y2,
    unsigned flags);

Fallback function: ffb_core_draw_line()

fill_poly()

The graphics framework calls this function to draw a filled polygon with npoints vertexes whose vertex values are specified as a list of points. The prototype is:

int (*fill_poly) (disp_draw_context_t *ctx,
    disp_color_t color,
    disp_point_t *pointlist,
    int npoints,
    unsigned flags);

There is no FFB fallback for this function. If the driver is unable to render the polygon correctly, it should return -1, without performing any drawing, so that the software fallback can be performed at a higher level.

get_bresenham_params()

The graphics framework calls this function to query the hardware for Bresenham algorithm parameters for drawing a line. The prototype is:

int (*get_bresenham_params) (disp_draw_context_t *ctx,
        int x1,
        int y1,
        int x2,
        int y2,
        int *initial_error,
        int *major_inc,
        int *minor_inc);

This function is used by higher-level software to render primitives (such as polygons) whose edges line up pixel-for-pixel with lines that are drawn with the same vertexes. Implementations of Bresenham's algorithm are known to have subtle differences which cause different pixels to be output to the framebuffer. By being able to query the initial error term, and the major and minor increment values that the hardware would use when rendering the line specified by the points (x1, y1) and (x2, y2), a software algorithm can produce exactly the same results as the hardware would. If you have hardware that does not render lines in exactly the same way as the implementation in the FFB library, your driver will need to implement this function.

Fallback function: ffb_get_bresenham_params()

update_transform()

The graphics framework calls this function to notify the driver that members of the context structure relating to line and polygon transformations have changed. This applies to the following members:

xform_matrix
xlate_x
xlate_y

The prototype is:

void (*update_transform) (disp_draw_context_t *context);

Fallback function: ffb_update_transform()

update_clipping()

The graphics framework calls this function to notify the driver that members of the context structure relating to primitive clipping has changed. This applies to the following members:

clip_left
clip_top
clip_right
clip_bottom