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

`disp_draw_miscfuncs_t`

Table of miscellaneous drawing functions

Synopsis:

#include <draw.h>

typedef struct disp_draw_miscfuncs {
    int  (*init) (...);
    void (*fini) (...);
    void (*module_info) (...);

    void (*set_palette) (...);

    int  (*set_hw_cursor) (...);
    void (*enable_hw_cursor) (...);
    void (*disable_hw_cursor) (...);
    void (*set_hw_cursor_pos) (...);

    void (*flushrect) (...);

    void (*get_2d_caps) (...);
    int  (*get_corefuncs_sw) (...);
    int  (*get_contextfuncs_sw) (...);
} disp_draw_miscfuncs_t;

The disp_draw_miscfuncs_t structure is a table that your driver uses to define the miscellaneous drawing functions that it provides to the graphics framework. Your driver's devg_get_miscfuncs() entry point must fill in this structure.

Note that if the driver doesn't support hardware cursors, it should set all of the hardware cursor entry points in this structure to NULL. If any one of the hardware cursor entry points is non-NULL, your driver must provide all the hardware cursor entry points.

init()

The graphics framework calls this function to initialize the drawing hardware, allocate resources, and so on. The prototype is:

int (*init) (disp_adapter_t *adapter,
             char *optstring )

For more information on where this function fits into the general flow, see "Calling sequence" in the Writing a Graphics Driver chapter.

fini()

The graphics framework calls this function to shut down the driver by shutting off hardware, freeing resources, and so on. The prototype is:

void (*fini) (disp_adapter_t *adapter)

For more information on where this function fits into the general flow, see "Calling sequence" in the Writing a Graphics Driver chapter.

module_info()

The graphics framework calls this function to get information about the 2D driver module. The prototype is:

void (*module_info) (
         disp_adapter_t *adapter,
         disp_module_info_t *module_info)

This function must fill in the disp_module_info_t structure pointed to by module_info.

set_palette()

The graphics framework calls this function to set the palette. The prototype is:

void (*set_palette) (disp_adapter_t *ctx,
                     int index,
                     int count,
                     disp_color_t *pal)

If the modeswitcher version of this function (disp_modefuncs->set_palette) is present, it's called instead (i.e. the modeswitcher function overrides this one).

set_hw_cursor()

The graphics framework calls this function to set the attributes of the hardware cursor. The prototype is:

int (*set_hw_cursor) (disp_adapter_t *ctx,
                      uint8_t *bmp0,
                      uint8_t *bmp1,
                      unsigned color0,
                      unsigned color1,
                      int hotspot_x,
                      int hotspot_y,
                      int size_x,
                      int size_y,
                      int bmp_stride)

The hotspot represents the "active" point of the cursor (e.g. the tip of the arrow in case of an arrow cursor, or the center of the crosshairs in case of a crosshair cursor).

If the cursor can't be displayed properly, this function should return -1, which causes the framework to show a software cursor instead. For example, if sizex or sizey is too big for the hardware to handle, this function should return -1.

The cursor image itself is defined by two bitmaps. The two colors, color0 and color1 apply to the two bitmaps bmp0 and bmp1. Both bitmaps have the same width (size_x), height (size_y), and stride (bmp_stride) values.

For a given pixel within the cursor image, a 0 in both bitmap locations means this pixel is transparent. A 1 in bmp0 means draw the corresponding pixel using the color given by color0. A 1 in bmp1 means draw the corresponding pixel using the color given by color1. If there's a 1 in both bitmaps, then color1 is to be used.

enable_hw_cursor()

The graphics framework calls this function to make the cursor visible. The prototype is:

void (*enable_hw_cursor) (disp_adapter_t *ctx)

disable_hw_cursor()

The graphics framework calls this function to make the cursor invisible. The prototype is:

void (*disable_hw_cursor) (disp_adapter_t *ctx)

set_hw_cursor_pos()

The graphics framework calls this function to set the position of the hardware cursor. The prototype is:

void (*set_hw_cursor_pos) (disp_adapter_t *ctx,
                           int x,
                           int y)

Position the cursor such that the hotspot is located at (x, y) in screen coordinates.

flushrect()

The graphics framework calls this function to flush a modified area to the draw surface. The prototype is:

void (*flushrect) (disp_draw_context_t *ctx,
                   int x1,
                   int y1,
                   int x2,
                   int y2)

The area defined by (x1, y1), (x2, y2) has been modified. Higher level software keeps track of which parts of the screen have been modified (or "dirtied"), since the last call to this function, and this function is called to flush the dirtied area to the targeted draw surface.

This function is optional; supply it only if you wish to implement a "dirty rectangle" driver. The sample VGA driver provided with the DDK is a good example of a dirty rectangle driver.

Even though the frame buffer organization is non-linear, the VGA driver is still able to use the standard rendering functions from the FFB lib. It does this by keeping a "shadow" copy of the frame buffer in system RAM. The format of the shadow buffer is linear (8-bit palette format). The FFB renders into the shadow buffer, then this function is used to flush the appropriate area of the shadow buffer out to the planar VGA frame buffer, by converting the data from linear to planar format.

get_2d_caps()

The graphics framework calls this function to get information about the 2D capabilities of the graphics hardware's accelerator. The prototype is:

void (*get_2d_caps) (disp_adapter_t *ctx,
                     disp_surface_t *surface,
                     disp_2d_caps_t *caps)

The surface argument points to a disp_surface_t structure that describes a targetable 2D surface. Your driver must fill in the disp_2d_caps_t structure pointed to by caps with information about how 2D drawing to that surface is to be performed.

get_corefuncs_sw()

The graphics framework calls this function to get your driver's core 2D drawing functions. The prototype is:

int (*get_corefuncs_sw)(
        disp_adapter_t *adapter,
        unsigned pixel_format,
        disp_draw_corefuncs_t *fns,
        int tabsize );

This function should be similar to devg_get_corefuncs(), but get_corefuncs_sw() should get only the ones that are guaranteed to render into system RAM.

get_contextfuncs_sw()

The graphics framework calls this function to get your driver's context 2D drawing functions. The prototype is:

int (*get_contextfuncs_sw)(
        disp_adapter_t *adapter,
        disp_draw_contextfuncs_t *fns,
        int tabsize );

This function should be similar to devg_get_contextfuncs(), but get_contextfuncs_sw() should get only the ones that are guaranteed to render into system RAM.

Classification:

Photon