disp_modefuncs_t

Table of your driver's modeswitcher functions

Synopsis:

#include <mode.h>

typedef struct disp_modefuncs {
    int  (*init) (...);
    void (*fini) (...);
    void (*module_info) (...);
    int  (*get_modeinfo) (...);
    void (*get_modelist) (...);
    int  (*set_mode) (...);
    int  (*wait_vsync) (...);
    int  (*set_dpms_mode) (...);
    int  (*set_display_offset) (...);
    int  (*set_palette) (...);
    void (*set_scroll_position (...);
} disp_modefuncs_t;

Description:

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

init()

The graphics framework calls this function to initialize your hardware. The prototype is:

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

This function should return the number of displays that this modeswitcher controls, or -1 to indicate an error. For example, if a display card controls both a flat-panel and a monitor simultaneously, this function should return 2.

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 return your hardware to the uninitialized state, deallocate resources, and so on. The prototype is:

void (*fini) (disp_adapter_t *ctx)

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 module, such as its description and revision numbers. The prototype is:

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

This function should fill in the disp_module_info_t structure pointed to by info.

get_modeinfo()

The graphics framework calls this function to get mode information. The prototype is:

int (*get_modeinfo) (disp_adapter_t *ctx,
                     int dispno,
                     unsigned mode,
                     disp_mode_info_t *info)

This function should populate the disp_module_info_t structure pointed to by info with information pertaining to the mode specified in mode for the display referenced by dispno. See the note about modes in get_modelist() below for more information.

get_modelist()

The graphics framework calls this function to get a list of the modes that your driver supports. The prototype is:

void (*get_modelist) (disp_adapter_t *ctx,
                      int dispno,
                      disp_mode_t *list,
                      int index,
                      int size)

This function should place a maximum of size modes into the array list, starting at the index index, for the display referenced by dispno. The index parameter is in place to allow multiple calls to the get_modelist() function in case there are more modes than will fit into the list array on any given call.

The list of modes is terminated with the constant DISP_MODE_LISTEND -- don't return this as a valid mode. The list of modes must be returned in the exact same order each time, but there's no requirement to arrange the list by any sorting criteria.

It's the mode number (the content of the list array) that's important for subsequent calls, and not the mode index itself.

For example, if your driver returns the following array:

list [0] = 0x1234;
list [1] = 0x070B;
list [2] = 0x4321;
list [3] = DISP_MODE_LISTEND; // terminate list

then your get_modeinfo() and set_mode() functions are called with, for example, 0x4321 and not the index 2.

The driver should use only the 15 least significant bits of the disp_mode_t type. Thus each entry in list must be less than or equal to 0x7fff.

set_mode()

The graphics framework calls this function to set the hardware for the display referenced by dispno to the mode specified by mode. The prototype is:

int (*set_mode) (disp_adapter_t *ctx,
                 int dispno,
                 unsigned mode,
                 disp_crtc_settings_t *settings,
                 disp_surface_t *surf,
                 unsigned flags)

See the note about modes in get_modelist() above for more information.

The settings parameter is valid only if the mode is a generic mode, which means that the framework can pass an arbitrary X and Y resolution and refresh rate. The driver advertises that it can support generic modes by setting the appropriate flag in the disp_mode_info_t structure when get_modeinfo() is called.

If your driver supports virtual panning, the virtual screen might be larger than the physical screen resolution of the requested mode. The virtual x and y resolutions are passed in surf->width and surf->height. The surf->stride member specifies the stride, in bytes, that the driver should use to program the CRTC controller.

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

wait_vsync()

This function must wait until the display controller for the display referenced by dispno enters the vertical-retrace period. The prototype is:

int  (*wait_vsync) (disp_adapter_t *adapter,
                    int dispno);

set_dpms_mode()

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

void (*set_dpms_mode) (disp_adapter_t *ctx,
                       int dispno,
                       int mode)

Select a DPMS mode for the display referenced by dispno as follows:

set_display_offset()

The graphics framework calls this function to set the frame buffer base of the visible display for the display controller referenced by dispno. The prototype is:

void (*set_display_offset) (disp_adapter_t *ctx,
                            int dispno,
                            unsigned offset,
                            int wait_vsync)

The offset member must be a multiple of the crtc_start_gran member of the disp_mode_info_t structure.

If wait_vsync is nonzero, your driver should wait for the next vertical retrace period before returning from this function.

set_palette()

The graphics framework calls this function to set the palette for the display referenced by dispno. The prototype is:

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

One or more entries in the palette can be set at a time with this function call. The index indicates the starting palette index, and count indicates the number of entries being set. Finally, pal contains an array of color values, one per entry, to set.

If this function is specified (i.e. not NULL in the function pointer set_palette), then it's called regardless of whether or not the set_palette() function in the miscellaneous callouts structure, disp_draw_miscfuncs_t, has been supplied: if (disp_modefuncs -> set_palette) { (*disp_modefuncs -> set_palette) (...); } else if (disp_draw_miscfuncs -> set_palette) { (*disp_draw_miscfuncs -> set_palette (...); }

set_scroll_position()

The graphics framework calls this function to scroll, or pan around a virtual desktop when the virtual display surface is bigger than the physical display. If your driver supports Virtual Panning, you must provide this function. The prototype is:

void (*set_scroll_position) (
        disp_adapter_t *adapter,
        int dispno,
        int xoff,
        int yoff )

This function should set the physical viewport into the virtual display surface such that the point (xoff, yoff) within the virtual display appears at the upper left corner of the physical display.

Classification:

Photon

See also:

devg_get_modefuncs(), disp_adapter_t, disp_crtc_settings_t, disp_mode_info_t, disp_module_info_t, disp_surface_t