![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
 |
This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs. |
Table of your driver's modeswitcher functions
#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 (...);
int (*layer_query (...);
int (*layer_select_format (...);
int (*layer_enable (...);
int (*layer_disable (...);
int (*layer_set_surface (...);
int (*layer_set_source_viewport (...);
int (*layer_set_dest_viewport (...);
int (*layer_set_blending (...);
int (*layer_set_chromakey (...);
int (*layer_set_brightness (...);
int (*layer_set_saturation (...);
int (*layer_set_contrast (...);
int (*layer_set_flags (...);
void (*layer_update_begin (...);
void (*layer_update_end (...);
void (*layer_reset (...);
} disp_modefuncs_t;
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.
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.
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.
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.
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.
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. |
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.
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);
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:
| Mode | Meaning |
|---|---|
| 0 | On |
| 1 | Standby |
| 2 | Suspend |
| 4 (not a typo) | Off |
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.
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 (...);
}
|
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.
The graphics framework calls this function to query the capabilities of a given layer. The prototype is:
int (*layer_query) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int fmt_idx,
disp_layer_query_t *info);
The arguments to layer_query are:
If the layer_idx or fmt_idx indexes are out of range, this function should return -1, otherwise it should return 0.
The graphics framework calls this function to select the pixel format of the the layer specified by layer_idx. The prototype is:
int (*layer_select_format) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int fmt_idx )
The format specified by fmt_idx corresponds to the fmt_idx that was passed to layer_query.
The arguments to layer_select_format are:
If the dispno, layer_idx, or fmt_idx indexes are out of range, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to make the layer specified by layer_idx visible. The prototype is:
int (*layer_enable) (
disp_adapter_t *adapter,
int dispno,
int layer_idx )
The arguments to layer_enable are:
If the dispno or layer_idx indexes are out of range, or the layer can't be disabled or reenabled, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to make the layer specified by layer_idx invisible. The prototype is:
int (*layer_enable) (
disp_adapter_t *adapter,
int dispno,
int layer_idx )
The arguments to layer_disable are:
If the dispno, or layer_idx indexes are out of range, or the layer can't be disabled or re-enabled, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to associate a memory surface with the layer specified by layer_idx. The prototype is:
int (*layer_set_surface) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int surface_idx,
disp_surface_t *surf )
The arguments to layer_set_surface are:
Some layer formats split the image components across multiple buffers. A planar YUV surface, for example, requires three buffers to store a valid image. In this case, the surface_idx argument specifies whether a Y, U, or V buffer gets allocated.
The memory surface was created by the driver's alloc_layer_surface() management entry point. The layer_select_format entry point is called before this entry point.
If the dispno or layer_idx indexes are out of range, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the size of the source viewport for the layer that layer_idx specifies. The prototype is:
int (*layer_set_source_viewport) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int x1, y1,
int x2, y2 )
The arguments to layer_set_source_viewport are:
This function should return -1 if:
Or:
Or:
Otherwise the function should return 0.
The graphics framework calls this function to set the size of the destination viewport for the layer that layer_idx specifies. The prototype is:
int (*layer_set_dest_viewport) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int x1, y1,
int x2, y2 )
The arguments to layer_set_dest_viewport are:
If the dispno or layer_idx indexes are out of range, or the viewport width for the capabilities structure for this layer is outside the ranges specified by dst_max_height, dst_min_height, dst_max_width, and dst_min_width, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the layer's blending configuration for the layer specified by layer_idx. The prototype is:
int (*layer_set_blending) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned alpha_mode,
int m1,
int m2 )
The arguments to layer_set_blending are:
If the dispno or layer_idx indexes are out of range, this function should return -1 to indicate an error, otherwise it should return 0.
If the layer selected by layer_idx doesn't support the combination of flags specified by alpha_mode, this function should return -1, otherwise it should return 0.
For more information on global alpha multipliers, and the currently defined flags, see "Alpha mode bits."
The graphics framework calls this function to set the layer's chroma-key configuration for the layer specified by layer_idx. The prototype is:
int (*layer_set_chromakey) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned chroma_mode,
disp_color_t color0,
disp_color_t color1,
disp_color_t mask );
The arguments to layer_set_chromakey are:
DISP_CHROMA_OP_SRC_MATCH and DISP_CHROMA_OP_DST_MATCH are mutually exclusive.
DISP_CHROMA_OP_DRAW and DISP_CHROMA_OP_NO_DRAW are also mutually exclusive.
If 0 is passed for chroma-mode, chroma-keying is disabled.
For more information on chroma key mode bits, see "Chroma mode bits"
If the layer selected by layer_idx doesn't support the combination of flags specified by chroma_mode, this function should return -1, otherwise it should return 0.
The graphics framework calls this function to set the brightness attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_brightness) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int brightness );
The arguments to layer_set_brightness are:
If the selected layer doesn't support brightness adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the color saturation attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_saturation) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int saturation );
The arguments to layer_set_saturation are:
If the selected layer doesn't support saturation adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set the contrast attribute of the layer specified by layer_idx. The prototype is:
int (*layer_set_contrast) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
int contrast );
The arguments to layer_set_contrast are:
If the selected layer doesn't support contrast adjustment, this function should return -1 to indicate an error, otherwise it should return 0.
The graphics framework calls this function to set various attributes of the layer specified by layer_idx. The prototype is:
int (*layer_set_flags) (
disp_adapter_t *adapter,
int dispno,
int layer_idx,
unsigned flag_mask
unsigned flag_values );
The arguments to layer_set_flags are:
The following flags are supported:
If the selected layer isn't supported by one or more of the flags specified by flag_mask, this function should return -1 to indicate an error, otherwise it should return 0.
This function must be called before you make any adjustments to the layer configuration. The driver should attempt to make multiple adjustments atomic, by having the adjustments take effect at the time layer_update_end() is called. The prototype is:
void (*layer_update_begin) (
disp_adapter_t *adapter,
int dispno,
int layer_idx );
The arguments to layer_update_begin are:
The prototype is:
void (*layer_update_end) (
disp_adapter_t *adapter,
int dispno,
int layer_idx );
The arguments to layer_update_end are:
Before any calls are made that affect the layer configuration, layer_update_begin() is called, and subsequently layer_update_end() makes the changes effective.
This function runs after adjustments are made to the layer configuration. Any adjustments made since layer_update_begin() was called, will now take effect.
|
The layer_query() function doesn't affect the layer configuration and is therefore an exception to this rule. |
The prototype is:
void (*layer_reset) (
disp_adapter_t *adapter,
int dispno,
int layer_idx );
The arguments to layer_reset are:
This function resets the specified layer to its initial state.
A layer should be reset to its initial state after a modeswitch.
The initial state is defined as one where:
Photon
devg_get_modefuncs(), disp_adapter_t, disp_crtc_settings_t, disp_mode_info_t, disp_module_info_t, disp_surface_t
|
|
|
|