This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`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 (*hw_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) (...);
} 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()

hw_idle()

The graphics framework calls this function to determine whether or not the 2D hardware is idle. The prototype is:

void (*hw_idle) (disp_adapter_t *context,
                 void *ignored )

This function should return a nonzero value if the 2D hardware is idle, in which case it's safe to directly access the draw target surface. If the hardware isn't idle, this function should return 0.

Fallback function: ffb_hw_idle()

draw_span()

The graphics framework calls this function to draw a single 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 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()

Classification:

Photon