2. Resolved issues

2.1 ggiCircle

Is this going to be completely removed?

Decision

Yes. It has been moved to libggi2d.

2.2 Reporting internal state

There is currently no way to report information like the timing information to a ggilib application. At least for some diagnostics this might be useful.

Decision

There was some very good discussion, and the most interesting points were:

• There is no interesting libggi state.
• The driver state (KGI state) is interesting to some diagnostic programs, but not to 'normal' applications.
• a /proc/ or /dev/ggistat-based solution is not very portable, so it can not be the only choice. It would be handy for debugging though. (Think Windows here :-)

There was only one remark in favor of putting this functionality into the libggi, and a valid one, that too many small libraries will be impractical, and that a larger lib is easier to handle.

So the final word from The Lord Of The Library is:

• we will want some interface to the driver state
• this does not go into LibGGI. It is simply not needed widely enough to justify adding this call to this library.
• as soon as need arises, some portable solution (some LibGGItweak) has to be suggested, implemented and discussed.

2.3 ggiGetRayPos, ggiWaitRayPos

These two have been implemented for the SVGAlib target, but nowhere else. Should these really become part of the libggi API, or should they move somewhere else? What are they supposed to do?

Decision

The RayPos functions are CRT specific and are moved from libggi to an extension, libggimisc.

2.4 extensionInit/extensionExit, ggiInit, ggiExit

Decision

• ggiInit() and ggiExit() will get counting behaviour, because multiple ggiInit invocations are needed for extension library initialisation.
• ggiExit() will return the number of 'open' ggiInit's, i.e. after two ggiInit invocations, the first ggiExit will return 1 and don't do anything else, the second ggiExit will shut down the library and return 0 (i.e. success), the third will return -1.

2.5 Removing the "display-" prefix

It was suggested to drop the "display-" prefix from all LIBGGI_DISPLAY parameters. There was a very easy solution suggested (editing libggi.conf), so it's the political question: with the prefix or not, allow both and recommend one, then which?

Decision

Both ways are allowed. A string that does not contain a dash ('-') is considered an abbreviation of and equivalent to 'display-' plus this string, so 'KGI' is equivalent to 'display-KGI'.

2.6 ggiPuts

How should ggiPuts behave (if the string does not fit into the line)?

Decisions

• Clip, i.e. obey the clipping area.
  1. ggiPuts() always draws the characters in a single line; formatting characters like tab, newline, etc. are not treated specially (Only '\000' is treated specially: end of string. But that's C :-)
  2. text is always clipped by the clipping region (of course)
  3. if the text origin specified to ggiPuts() is outside the visual's clipping area (in any direction), the text is displayed anyway, clipped properly.
• ggiPut* is documented to work in text and graphics mode.
• there is a function to query the char cell size:

  ggi_error ggiGetCharCellSize(vis, int * width, int * height);

  (Note: please remember that the char cell size is not a *mode* property, except for text mode, where it is 1x1 by definition!)

• The font is guaranteed to be at least 8x8 (fixed for all chars) and nobody is encouraged to implement something bigger, except for good (hardware) reasons. (Note: Once again, the ggiPuts implementation is dependent on the frame buffer layout, not on it's *size*.)
• ggiPuts supports only the basic ASCII charset, characters 0x20 to 0x7f. As it is meant for simple debug output ar very simple GUIs, using 'national' characters is not recommended.
• ggiPuts will not support loadable hardware charsets. This is VGA-centric anyway and of limited use, and shouldn't go into the base library. A libggitext is the right place for these functions, as it is for loadable fonts in general.

2.7 Alpha values

There was the suggestion to enhance ggi_color, which currently holds three shorts for r,g, and b, with an additional alpha value (transparency).

Decision

The ggi_color struct will have a short a added, but the libggi itself will not use it.

2.8 Auxiliary buffers

Some cards support auxiliary buffers like Z-Buffers. There is currently no method for requesting them.

Decision

This is going to be solved outside the base libggi. The new extension methos allow overriding mode setting functions, so this type of requests is going to be handled by an extension library to the lkibggi.

2.9 Frames

These changes are done to support multiple frames (screen 'pages' of the same size).

• The frames field in the ggi_mode struct indicates the number of screen buffers requested. It will default to 1.
• Frames will be numbered 0 ... <frameno> -1
• After mode setting frame 0 is active for reading, writing and display.
• Three additional functions are required, to switch between these frames for drawing, reading back (ggiGet*) and for displaying, e.g.:
  • ggiSetDisplayFrame(vis, int frameno);
  • ggiSetWriteFrame(vis, int frameno);
  • ggiSetReadFrame(vis, int frameno);
  These return 0 if they succeed, and -1 if they fail.
• Three functions are added to read back the current frame:
  • int ggiGetDisplayFrame(vis);
  • int ggiGetWriteFrame(vis);
  • int ggiGetReadFrame(vis);
  These return the frame number or -1, if they fail. Side note: setting different frames for reading and writing the screen is necessary to be able to copy across the frames. Separating that into two function calls makes the Get function easier - a ggiSetDrawingFrames(vis, src,dest) would lead to a ggiGetDrawingFrames(vis,&src,&dest) ... I like this better (HN).
• The current ggiSet*Mode calls will not be changed. So this feature will currently be only accessible thru changing the mode struct and using ggiSetMode.

2.10 ggiCrossBlit

This function is supposed to transfer pictures between different visuals. It has been decided that this function will move somewhere else.

There was the proposal to include a 'small' version that will copy from one visual to another, but without stretching/shrinking, and possibly without colour conversion.

Decision

The full crossblit will be moved to libggi2d.

A version without stretching, i.e. one that copies a rectangular piece from one visual to another visual, will be included:

int ggiSimpleCrossBlit(ggi_visual_t src,int sx,int sy,int sw,int sh, ggi_visual_t dst,int dx,int dy);

This will do colour conversion as necessary.

2.11 Palettes

Several topics have been discussed, this is the final word:

• No start-up palette is guaranteed. While a target should have some default setting, this is not required.
• The palette setting is not necessarily kept on a focus switch, so when an application needs to redraw the screen, it has to re-set the palette as well.
• A len==0 will be legal for ggiSetPalette and ggiGetPalette, and allow for easy checking the existence. With a len 0 the functions will return 0 if there is a palette that can be set and read out, respectively, without moving any actual data, i.e. the ggi_color pointer may be NULL.
• A target may implement only ggiGetPalette, but not ggiSetPalette, if that makes sense (CGA, maybe Borland BGI).
• A new function is introduced to request the bpp of a display. It has to be discussed whether it should take a mode, a graphtype or a visual as it's argument.
• A start value of GGI_AUTO allows the placement of the CLUT entries chosen by the target. The decision algorithm can be as complicated as you want, but it will normally very simple, and I see good reason for this.
  • normally you put all entries into the palette you want to have at startup, so each application sets the palette only once.
  • For all those applications that set only one palette at startup, it usually doesn't matter where in the CLUT a certain value is, as long as ggiMapColor works as expected.
  • For a fullscreen mode, there is nobody competing about the CLUT, so set s=0. If you don't want to implement it differently, too.
  • On X it might be good to allocate from the end, to have the 'general' colours not messed up. Wouter (?) said he had code to copy the system-wide X palette into a private one and to allocate some colours there.
  • and if someone thinks he needs a real 'allocation' scheme, he'll be able to build one.
  Side note: most targets will place all entries at the beginning of the CLUT, assuming s=0, but some (in windowing targets especially) will use other schemes. If you know at program startup, that you will need n different colours, you set these n colours in the palette and don't care where. Only very few programs will set the palette more than once AND want to retain old values. For a windowing environment it could very well make sense to assign positions 0 to 20 to the window manager, 30 to 100 to app1, and 101 to 200 to app2. So if we leave this assignment to the library, it *might* help. And if someone doesnt want to implement fancy strategies, if (s==GGI_AUTO) s=0; is all enhancements necessary. This leads to the following change in semantics:
• ggiSetPalette returns the number of the first entry changed (or -1 for failure). Side note: This allows to find out where GGI_AUTO'ed entries were put.

2.12 Get/Put buffers: opaque or not?

Decision

The buffers used by the ggiGet* and ggiPut* functions will be guaranteed to have several properties:

• The pixel layout used for Get/PutHline and friends is guaranteed to be the same as for the frame buffer (if there is a frame buffer). Then (either the direct buffer or the enhanced) mode struct (see the (memory) visual memory layout and graphtype chapters) carry this information.
• one pixel consumes either k bytes (packed true colour) or 2**n bits (covering 1,2,4-bpp modes). If the hardware has other sizes (like 30 bits), they will be padded. (This is IMHO needed to reduce bit-shifting). The buffer is guaranteed to have a maximum size width*height*sizeof (ggi_pixel).
• the pixels are stored linearly on all targets, i.e. a rectangle with a width of three and a height of two will be stored pixel (0,0) (1,0) (2,0) (0,1) (1,1), (2,1) in that order.

  Note: We need to care for strange things like 5x7 rectangles in 2bpp modes! Does the stride need to be an integral byte count?

• the exact pixel layout will define
  • how many bits per pixel
  • what colour model
  • what bits are where (rrrrgggg as oposed to ggggrrrr) and will be part of the mode struct.
• ggiPackColors and ggiUnpackPixels pack/unpack complete buffers from/to ggi_colors and/or ggi_pixels. Maybe these have to be renamed, made more consistent, and maybe have to be split into several calls for boxes, hlines and vlines?

2.13 Memory visual memory layout

Decision

The mode struct will be enhanced to provide information about the exact pixel layout. This information is not only needed to request 'suitable' memory displays minimising crossblit work, but for get/putbuffer access as well.

The first candidate is a struct ggi_mode member pixelfmt of ggi_common_plb_setup type.

The canonical way for getting a memory visual of the same type as the main visual will be:

ggi_mode memmode;
ggi_visual_t mainvis,memvis;
 ...
ggiGetMode(mainvis,&memmode);
memvis=ggiOpen("memory",NULL);
ggiCheckMode(memvis,&memmode);
ggiSetMode(memvis,&memmode);

2.14 Graphics context save/resore

It seems to me that the application is guaranteed that all graphics state is saved and restored transparently (including the CLUT) except for the screen content itself, where the application is supposed to redraw after receiving an appropriate redraw event.

2.15 Behaviour on switch-away and switch-back

What is this about?

What has to be done when a program is switched away (either the window (in X) becomes inactive, or the VT is switched), and on re-activation?

This is currently not defined at all.

What are the options for each case? What are pros/cons? How can this be implemented?

Is the application notified? How? Does it get a chance to save screen content, does it need to? Time limit for that?

Decision

If an application is deactivated, depending on the target it may be stopped.

An application can receive several events, for updating screen size, or redrawing or ... (I don't have a documentation about these events yet - HN).