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.
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.
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.
A mode where the values of the pixels represent an index into a fixed, small table of actual colors to display.
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; }
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 represents any 2D coordinate or dimension as x,y pixels.
Use of multiple buffering is specified in the frames member of the ggi_mode struct, as the number of screen buffers needed.
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.
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 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 specifies the graphic type. There are four sets of information, packed into ggi_graphtype using the indicated macros.
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)"
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)"
One of:
text modes
pixel is a direct RGB value
no color (!!!)
each pixel is an index to a colormap
Macros: "GT_SCHEME(gt)", "GT_SETSCHEME(gt,subscheme)"
Miscellaneous information about the pixel. Any of the following flags are bitwise-or'd together:
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.
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.
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:
Equivalent to GGI_AUTO for graphic types. It indicates that any value may be taken.
Text modes with word- and longword-aligned characters and attributes
Palettized modes with respective number of bits per pixel
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.
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.
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.
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.