ggiCheckTextMode3ggi

Return value

For ggiCheckTextMode and ggiCheckGraphMode, a return of 0 means that the corresponding set mode call for this mode would succeed. Otherwise, the mode given cannot be set. In this case, suggested_mode is changed to the suggested mode.

If the only modifications made to the structure is replacing GGI_AUTO or GT_AUTO value, the functions return success.

Rules for mode negotiation

First, if GGI_AUTO (or GT_AUTO for the graphtype) is specified for any of the members of *tm, these are filled in with the recommended values. The values could be to a maximum, preferred, or GGI_DEFMODE resolution, and will be compatible with any other constraints.

An application that does not care about a specific paramater should always specify GGI_AUTO or GT_AUTO for it.

The resulting mode is guaranteed to be valid; if not, the application can assume that it cannot set any mode on the given visual and give up.

The suggested mode is derived as follows:

•

Resolutions are always adjusted up. If you want the next lower, start out at 1x1 (or somewhere else reasonable) and jump up the ladder.

Only if the maximum resolution would be exceeded, resolutions are adjusted down to the maximum.

The above applies to visible and virtual size. If there is interference between them, the visible size is satified first if possible, then the virtual size.

The adjustment of one value do not normally affect other values. For example, if (visible) 320x100 (virtual 320x200) is requested, the visible size may be adjusted to 320x200, but virtual size will be left alone. Of course, if the virtual size becomes less than visible size, then it will be adjusted as well.

•

Font sizes are handled the other way round: they are adjusted down except when there is nothing below.

•

A specific graphtype is changed only if the card does not support it at all. If the maximum resolution is exceeded, then that is adjusted down and not the graphtype. This assumes, that if you request true-color, you really want that and not so badly the resolution you requested. If this is not the case, you can still retry with another graphtype or GT_AUTO.

If graphtype is changed, it is adjusted in ascending order if possible: e.g. i.e. 1->4->8->15->16->24/32 bit. So you always get a mode which can do more than you requested. Only when no better modes are available, the type is adjusted down.

Examples

err = ggiCheckGraphMode(vis, 320, 200, GGI_AUTO, GGI_AUTO, GT_8BIT, 
                        &sug_mode, NULL);
if(err) {
        /* Check if returned mode is ok... */
}
else {
        ggiSetMode(&sug_mode);
}