Chapter 5. Visual management

Table of Contents
Introduction on GGI visual
Mode management
Working with visuals

Introduction on GGI visual

A visual is simply a thing you can draw on. For example, a virtual console in fullscreen mode, an X window, an invisible memory area, or a printer. It is identified by its handle of type ggi_visual_t, which is given to all drawing functions to indicate which visual to operate on.

Each visual is completely independent of other visuals. You can open different visuals to display on multiple monitors and/or in multiple windows or to work on "virtual" graphics devices like in-memory pixmaps or even PPM files on disk.

A visual may also encompass any inputs that are associated with the underlying graphics device. For example, an X window visual usually receives input from the X keyboard and pointer.

Most LibGGI functions are passed a visual returned by ggiOpen to know on which display they should operate on.

ggi_visual_t is opaque to the user. Do not try to access any part of the structure directly. It may change without notice.

Other graphics terms used by LibGGI

Pixel

or 'picture element' refers to a small rectangular part of an image. It has some attributes associated, e.g. a certain color, texture etc, which are assumed to be constant over the whole area covered by it. All pixels are assumed to have the same shape and size. A pixel is the smallest element of a picture that can be controlled independently of the other pixels in its attributes.

Dot

The smallest unit that can be addressed for an image. For uniform pixels this may be the pixel itself; for textured pixels, such as character glyphs, a dot is a pixel of the texture which is assumed to be uniform. We will use this to refer to sub-pixel coordinates, e.g. for a graphical pointer in text mode. As with pixels, dots are assumed to have the same shape, size, color and intensity over the whole area covered. They have only a uniform texture.

Most LibGGI functions and structures use pixels rather than dots. This makes a difference for text modes, because a character is treated as one pixel, but consists of a dpp.x * dpp.y sized matrix of dots.

Colormap, Palette, CLUT (color lookup table)

A mode where the values of the pixels represent an index into a fixed, small table of actual colors to display.

Getting a visual

The first thing before using GGI is to initialize the library with the ggiInit function. A visual can be opened with ggiOpen.

Example 5-1. Opening a visual

#include <ggi/ggi.h>

int main() {

   ggi_visual_t vis;

   if(ggiInit()<0)) {
   printf("Couldn't initialize GGI...\n");
   exit(1);
   }

   if(!(vis=ggiOpen(NULL))) {
   printf("Couldn't open a visual...\n");
   } else {
      printf("Got a default visual!\n");
      ggiClose(vis);
   }

   ggiExit();
   return 0;
}

Mode management

A mode describes the graphical characteristics of a visual, such as its visible and virtual dimensions in pixels, and the number of colors. After opening the visual, you must set a mode before you can do anything useful with it, such as drawing.

A mode in LibGGI is defined by the following in ggi/ggi.h:

typedef struct { sint16   x, y; } ggi_coord;

typedef struct          /* requested by user and changed by driver	*/
{
        uint32          frames;         /* frames needed                */
        ggi_coord       visible;        /* vis. pixels, may change slightly */
        ggi_coord       virt;           /* virtual pixels, may change   */
        ggi_coord       size;           /* size of visible in mm        */
        ggi_graphtype   graphtype;      /* which mode ?                 */
        ggi_coord       dpp;            /* dots per pixel               */
} ggi_mode;

You usually don't need to manipulate this structure yourself, if you want to set a mode, but it is necessary if you want to find out the mode actually being set.

ggi_coord

ggi_coord represents any 2D coordinate or dimension as x,y pixels.

frames

Use of multiple buffering is specified in the frames member of the ggi_mode struct, as the number of screen buffers needed.

visible

The visible area is the subset of the virtual area that is visible to the user. visible specifies the size of this area or the screen resolution.

virtual

The virtual area is the available drawing area of a visual. virtual specifies the size of this area for each frame. (If all of the drawing area is to be visible on the screen, then visible is equal to virtual.)

dpp

dpp specifies the number of dots per pixel. For graphic modes, it is 1x1 by definition. In text modes, it represents the font size.

The value of GGI_AUTO may also be set to any of these fields, except graphtype which may be set to GT_AUTO, to indicate to the mode-setting and mode-checking functions to recommend a real value to the LibGGI application.

ggi_graphtype

ggi_graphtype specifies the graphic type. There are four sets of information, packed into ggi_graphtype using the indicated macros.

depth

Number of significant bits (i.e. those that represent the actual color or some other property of the pixel)

Macros: "GT_DEPTH(gt)", "GT_SETDEPTH(gt,depth)"

size

Number of physical bits per pixel, or its access size. Bits that are not significant bits (whose number is specified by depth above) are padding.

Macros: "GT_SIZE(gt)", "GT_SETSIZE(gt,size)"

scheme

One of:

GT_TEXT

text modes

GT_TRUECOLOR

pixel is a direct RGB value

GT_GREYSCALE

no color (!!!)

GT_PALETTE

each pixel is an index to a colormap

Macros: "GT_SCHEME(gt)", "GT_SETSCHEME(gt,subscheme)"

subscheme

Miscellaneous information about the pixel. Any of the following flags are bitwise-or'd together:

GT_SUB_REVERSE_ENDIAN

This is only relevant for modes where a bitfield (such as the red, green or blue component of pixels) crosses a byte boundary. For example the green component in common 15- and 16-bit modes does this. This flags means that after composing a pixel according to the masks/shifts in ggi_pixelformat the pixel should be byteswapped.

GT_SUB_HIGHBIT_RIGHT

This is only relevant for modes where more than one pixel is contained in each byte and means that the high bit/bits corresponds to the rightmost pixel.

GT_SUB_PACKED_GETPUT

Normally ggiGet/Put* buffers use "((GT_SIZE(gt)+7)&(~7))" bits per pixel. This flag requests that they use exactly "GT_SIZE(gt)" bits per pixel instead. Thus it's only relevant for modes where the pixelsize is not a multiple of 8 bits.

Macros: "GT_SUBSCHEME(gt)", "GT_SETSUBSCHEME(gt,subscheme)"

Applications can set any of these fields to GT_AUTO when setting or checking a mode to get a recommended value.

There are also macros which are aliases for some common ggi_graphtypes:

GT_AUTO

Equivalent to GGI_AUTO for graphic types. It indicates that any value may be taken.

GT_TEXT16, GT_TEXT32

Text modes with word- and longword-aligned characters and attributes

GT_1BIT, GT_4BIT, GT_8BIT

Palettized modes with respective number of bits per pixel

GT_15BIT, GT_16BIT

Truecolor modes with an access size of 16 bits. GT_15BIT uses 5 bits for each color component, while GT_16BIT uses an additional 1 bit for green.

GT_24BIT, GT_32BIT

Truecolor modes with the a depth of 24 bits. GT_24BIT uses an access size of 24 bits while GT_32BIT uses an access size of 32 bits.

GGI_AUTO replacement recommendations

When GGI_AUTO is encountered in a parameter, it is replaced with corresponding values specified by GGI_DEFMODE variable.

If the corresponding value is not found in GGI_DEFMODE or that value is also GGI_AUTO, then it is up to the driver to select a reasonable value satisfying as many of the given contraints as possible. The following are some recommendations:

  • If a visible size is given but no virtual, the lowest reasonable (taking alignment and accelleration constraints into account) should be used.

  • If either visible x or y is given, the other one should give a x/y ratio close to that of the screen size, normally about 4/3.

  • If a virtual size is given but no visible size, the highest possible visible size is selected.

  • If no size is given, the driver uses some builtin default.

  • If the graphtype is unspecified, the highest possible graphtype that meets the geometry constraints is set or suggested.

  • dpp.x and dpp.y will be 1 for graphics. For text modes the largest possible dpp.x and dpp.y (the most fine-grained font) should be used.

  • frames will be 1 if not specified.

Note: The rules above are only recommendations (which are hoped to best capture user expectations) to the driver implementer and in no way guaranteed.

Working with visuals

Once a visual is opened and a mode is set, it is ready for operation. In addition to drawing operations which are presented in the next chapter, a GGI visual support a couple of features which are forth describing here.