From: WHS <wouters@cistron.nl>
  To  : ggi-develop@eskimo.com
  Date: Thu, 27 Aug 1998 09:50:51 +0200

Re: ggi man page & info [Re: kgicon troubles]

Steve Cheng wrote:

> > give good manpages), dump sgml for libggi. Josh Yelon mentioned a few
> > problems of ggi a while back, including docs. I have to agree there. Man
> > pages are essential.
> 
> I agree manpages are essential.  However, we don't need to dump SGML
> documentation to have manpages.  It will just create the same stupid
> situation with "This documentation is no longer being maintained blah and
> manpage is the authoritive source."  I personally like being able to generate

Not the same. The difference is that most people hate info (and its
inaccessibility), and that is not the case with man pages.

> multiple formats with SGML markup, but I'm not stopping anyone from making

yes, but the most essential one is missing, so it's the wrong choice to
do the libggi API documentation in sgml at the moment (one can later put
the man page output back in sgml format when sgml gives man page
output).

> manpages.  Maybe I'll do it sometime...

Well, I can put the sgml stuff in the manpage outline (see attched
manpage for try 2), but then whoever does some changes will have to
update both (shouldn't be much extra effort though).

I'm not going to update any further before next week so if you want to
try go ahead.
Btw, if you don't like the indentation for function descriptions put .PP
on a new line before the description.

Wouter

.\" -*- nroff -*-
.\"
.\" General graphics interface
.\" Man page by W.H.Scholten 1998
.\"
.\" This file is public domain
.\"
.\"
.\"
.\"
.\" ggi.3 - nroff -man source for ggi man page.
.\"
.\"
.\"
.TH "GGI" 3 "August 1998" "Version 1.5" "GRAPHICS"
.\"
.\"------------------------------------------------------------------
.\"
.SH NAME
ggi_* - GGI graphics functions
.\"
.\"------------------------------------------------------------------
.\"
.SH SYNTAX
.B #include <ggi/ggi.h>



.SH Library control 
.TP
.RB int\  ggiInit\  "(void);"
.PP
Initalizes the GGI library. This function must be called before using any other LibGGI function; otherwise results will be undefined. An application can call ggiInit multiple times.
Returns: 0 if all went ok, otherwise an error code.

.TP
.RB void\  ggiExit\  "(void);"
Frees all resources allocated by the library for the program. This function should be called after an application is finished with the library.
Returns: 0 if all closed, >0 if not all instances of ggiInit have been closed, <0 if an error occurred.
.TP
.RB void\  ggiPanic\  "(const char *format,...);"
Shuts down for fatal errors and prints the given error message (format is as in printf(3)). It will shut down the active graphics modes, close all visuals, print the given error message and exit the application.

ggiPanic() should only be used as a last resort. Libraries could use this too when data is corrupted.
.PP



.SH Visual management
A visual is simply a thing you can draw on. For example, a VT in
fullscreen-mode, an X window, an invisible memory area, and 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 each other. You can use these
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.

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


.TP
.RB ggi_visual_t\  ggiOpen\  "(const char *display,...);"
Opens a visual. This function is given a NULL terminated list of the
names of LibGGI dynamic drivers to load. This is usually one display
target. Once loaded, they will all be associated with the single
visual. Giving no arguments except the NULL instructs LibGGI to open
the default display target (e.g. display-X, set by LIBGGI_DISPLAY, see
chapter ``LIBGGI_DISPLAY'').

Return: The opened visual, or NULL for error.

Example:

__________________________________________________________________
.br
memory_visual = ggiOpen("display-memory", NULL);

/* Get from LIBGGI_DISPLAY enviroment variable */
.br
default_visual = ggiOpen(NULL);

if(!memory_visual || !default_visual)
.br
return EXIT_FAILURE;
.br
__________________________________________________________________

.TP
.RB int\  ggiClose\  "(ggi_visual_t vis);"
Releases and destroys the visual and the associated internal control
structures. This will close X windows, return KGI-consoles to text-
mode, etc.

If focus is on the closed visual, focus is set to NULL.

Return: 0 for OK, otherwise an error code.

Example:


__________________________________________________________________
.br
memory_visual = ggiOpen("display-memory", NULL);

/* do some drawing, save image, etc. */

ggiClose(memory_visual);
.br
__________________________________________________________________


.SH Mode management

The definition in ggi.h is:
.br
__________________________________________________________________

typedef struct { sint16   x, y; } ggi_coord;

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




You don't need to care about the internal definition, if you want to
set a mode, but it is necessary if you want to find out the mode actu-
ally set.

Please note that the visible and virtual size are given in pixels, not
dots. This makes a difference for text modes, because a character is
treated as one pixel, but consists of a text.x*text.y sized matrix of
dots.

.TP
.RB int\  ggiSetMode\  "(ggi_visual_t visual, ggi_mode *tm);"
Set any mode (text or graphics).

Return: 0 for OK, otherwise could not set mode.

Use this function only if you want something really strange that the
specific SetModes below cannot give you. You usually do not want to do
this, unless you really know what you are doing and understand the
values in ggi_mode.


.TP
.RB int\  ggiGetMode\  "(ggi_visual_t visual, ggi_mode *tm);"
Get the current mode. tm will be filled with the current mode on
return.

Return: 0 for OK, otherwise an error code.

.TP
.RB int\  ggiCheckMode\  "(ggi_visual_t visual, ggi_mode *tm);"
Check any mode (text or graphics).

Return: A return of 0 means that a setmode call for this mode would
succeed.  Otherwise, the mode is given cannot be set..TP

.TP
.RB int\  ggiSetTextMode\  "(ggi_visual_t visual, int cols, int rows, int fontx, int fonty);"
Set a textmode with given columns and rows, virtual columns and rows
and a font of the given size.

Return: 0 for OK, otherwise could not set mode.

The fontsize is actually the size of the pixel (ggi_mode.dpp), in
textmodes.



.TP
.RB int\  ggiCheckTextMode\  "(ggi_visual_t visual, int cols, int rows, int fontx, int fonty);"
Check a text mode, with a null-terminated list of mode features. The
last argument must be NULL.

Return: A return of 0 means that a setmode call for this mode would
succeed.  Otherwise, the mode is given cannot be set. In this case, tm
is changed to the suggested mode:

If suggested_mode is not NULL, then it will be filled with the
suggested mode, as documented under ggiCheckMode(). In the future,
there may be more arguments, but currently there is nothing that may
be put between the final NULL and suggested_mode.

.TP
.RB int\  ggiSetGraphMode\  "(ggi_visual_t visual, int x, int y, int xv, int yv, ggi_graphtype type);"
Set a graphics mode with a visible area of size x/y and a virtual area
of size vx/vy (you can pan aound the virtual area using the
ggiSetOrigin()) and the specified graphics type.

Return: 0 for OK, otherwise could not set mode.



.TP
.RB int\  ggiCheckGraphMode\  "(ggi_visual_t visual, int x, int y, int xv, int yv, ggi_graphtype type);"
Check a graphics mode, with a null-terminated list of mode features.
The last argument must be NULL.

Return: A return of 0 means that a setmode call for this mode would
succeed.  Otherwise, the mode is given cannot be set. In this case, tm
is changed to the suggested mode:

If suggested_mode is not NULL, then it will be filled with the
suggested mode, as documented under ggiCheckMode(). In the future,
there may be more arguments, but currently there is nothing that may
be put between the final NULL and suggested_mode.
Example:

_________________________________________________________________
.br
/* Use only my mode... but you really should try to negotiate though */
.br
err = ggiCheckGraphMode(vis, 320, 200, 320, 200, GT_8BIT, NULL, NULL);
.br
if(err)
.br
        return EXIT_FAILURE;

/* OR use a suggested mode */
.br
err = ggiCheckGraphMode(vis, 320, 200, 320, 200, GT_8BIT, &sug_mode, NULL);
.br
ggiSetMode(&sug_mode);
.br
_________________________________________________________________

.TP
.BR ggiParseMode "(const char * s, ggi_mode * m)"
This internal function will probably be replaced by some libggu
function.

This function parses a string into a mode, using the following
template:


visible-x x visible-y # virtual-x x virtual-y D dpp-x x dpp-y F
frames(T)[graphtype or bpp value]

Whitespace is ignored before and after each number.

All values can be omitted (and default to GGI_AUTO).

Please do export a fully defined LIBGGI_DEFMODE (e.g.
320x200#320x200D1x1[8]) if your KGI driver does not support GGI_AUTO
yet.

T indicates text modes, as an alternative the graphtype can be 'T'
also (or e.g. GT_TEXT16, of course).  (See lib/libggi/mode.c for the
details.)


.TP
.RB "ggi_flags " ggiGetFlags\  "(ggi_visual_t vis);"


.TP
.RB int\  ggiSetFlags\  "(ggi_visual_t vis, ggi_flags flags);"


.TP
.RB int\  ggiFlush\  "(ggi_visual_t vis);"



.SH The directBuffer API
.TP
.RB int \ ggiDBGetBuffer\  "(ggi_visual *vis, ggi_directbuffer_t *buf);"
.TP
.RB "ggi_buffer_layout " ggiDBGetLayout\  "(ggi_directbuffer_t buf);"
.TP
.RB "ggi_pixellinearbuffer " *ggiDBGetPLB\  "(ggi_directbuffer_t buf);"



.SH Graphics context 
.TP
.RB int\   ggiSetGCForeground  "(ggi_visual_t vis, ggi_pixel  color);"
.TP
.RB int\   ggiGetGCForeground  "(ggi_visual_t vis, ggi_pixel *color);"
.TP
.RB int\   ggiSetGCBackground  "(ggi_visual_t vis, ggi_pixel  color);"
.TP
.RB int\   ggiGetGCBackground  "(ggi_visual_t vis, ggi_pixel *color);"
.TP
.RB int\  ggiSetGCClipping  "(ggi_visual_t vis, int left, int top, int right, int bottom);"
.TP
.RB int\  ggiGetGCClipping  "(ggi_visual_t vis, int *left, int *top, int *right, int *bottom);"



.SH Palette and colour control 
.TP
.RB ggi_pixel\  ggiMapColor "(ggi_visual_t vis, ggi_color *col);"
.TP
.RB int\  ggiUnmapPixel "(ggi_visual_t vis, ggi_pixel pixel, ggi_color *col);"

.TP
.RB int\  ggiPackColors "(ggi_visual_t vis, void *buf, ggi_color *cols, int len);"
.TP
.RB int\  ggiUnpackPixels "(ggi_visual_t vis, void *buf, ggi_color *cols, int len);"

.TP
.RB int\  ggiSetPalette "(ggi_visual_t vis, int s, int len, ggi_color *cmap);"
.TP
.RB int\  ggiGetPalette "(ggi_visual_t vis, int s, int len, ggi_color *cmap);"



.SH Set origin and splitline
.TP
.RB int\  ggiSetOrigin "(ggi_visual_t vis, int x, int y);"
.TP
.RB int\  ggiSetSplitline "(ggi_visual_t vis, int y);"



.SH Graphics primitives 
.TP
.RB int\  ggiFillscreen "(ggi_visual_t vis);"

.TP
.RB int\  ggiDrawPixel " (ggi_visual_t vis, int x, int y);"
.TP
.RB int\  ggiPutPixel " (ggi_visual_t vis, int x, int y, ggi_pixel col);"
.TP
.RB int\  ggiGetPixel " (ggi_visual_t vis, int x, int y, ggi_pixel *col);"

.TP
.RB int\  ggiDrawLine " (ggi_visual_t vis, int x, int y, int xe, int ye);"
.TP
.RB int\  ggiDrawHLine " (ggi_visual_t vis, int x, int y, int w);"
.TP
.RB int\  ggiPutHLine " (ggi_visual_t vis, int x, int y, int w, void *buf);"
.TP
.RB int\  ggiGetHLine " (ggi_visual_t vis, int x, int y, int w, void *buf);"

.TP
.RB int\  ggiDrawVLine " (ggi_visual_t vis, int x, int y, int h);"
.TP
.RB int\  ggiPutVLine " (ggi_visual_t vis, int x, int y, int h, void *buf);"
.TP
.RB int\  ggiGetVLine " (ggi_visual_t vis, int x, int y, int h, void *buf);"

.TP
.RB int\  ggiDrawBox " (ggi_visual_t vis, int x, int y, int w, int h);"
.TP
.RB int\  ggiPutBox " (ggi_visual_t vis, int x, int y, int w, int h, void *buf);"
.TP
.RB int\  ggiGetBox " (ggi_visual_t vis, int x, int y, int w, int h, void *buf);"
.TP
.RB int\  ggiCopyBox " (ggi_visual_t vis, int x, int y, int w, int h, int nx, int ny);"



.SH Event handling 
Events are of type ggi_event:

_________________________________________________________________
.br
typedef union ggi_event {

    uint8       size;           /* size of this event   */

    ggi_any_event   any;        /* access COMMON_DATA   */
.br
    ggi_cmd_event   cmd;        /* command/broadcast    */
.br
    ggi_raw_event   raw;        /* raw data event       */
.br
    ggi_val_event   val;        /* valuator change      */
.br
    ggi_key_event   key;        /* key press/release    */
.br
    ggi_pmove_event pmove;      /* pointer move         */
.br
    ggi_pbutton_event pbutton;  /* pointer buttons      */

} ggi_event;




The first element, size, is the size of the given event (in bytes).
Then the COMMON_DATA follows:

    uint8   size;       /* size of event in bytes       */
.br
    uint8   type;       /* type of this event           */
.br
    uint8   focus;      /* focus this is reported from  */
.br
    uint8   device;     /* who sent this                */
.br
    uint32  time;       /* timestamp                    */


Type is the type of event, which may be the following:

typedef enum ggi_event_type {

    evNothing = 0,  /* event is not valid. (must be zero) */
.br
    evCommand,      /* report command/do action         */
.br
    evBroadcast,    /* notification of general interest */
.br
    evDeviceInfo,   /* report input device information  */

    evRawData,      /* raw data received from device    */

    evKeyPress,     /* key has been pressed             */
.br
    evKeyRelease,   /* key has been released            */
.br
    evKeyRepeat,    /* automatically repeated keypress  */
.br
    evKeyState,     /* resynchronize keys state         */

    evPtrRelative,  /* pointer movements reported relative  */
.br
    evPtrAbsolute,  /* pointer movements reported absolute  */
.br
    evPtrButtonPress,       /* pointer button pressed   */
.br
    evPtrButtonRelease,     /* pointer button released  */
.br
    evPtrState,     /* resynchronize pointer state      */

    evValRelative,  /* valuator change (reported relative)  */
.br
    evValAbsolute,  /* valuator change (reported absolute)  */
.br
    evValState,     /* resynchronize valuator state     */

    evLast          /* must be less than 33         */

}  ggi_event_type;
.br
_________________________________________________________________


.TP
.RB "ggi_event_mask " ggiEventPoll " (ggi_visual_t vis, ggi_event_mask mask, struct timeval *t);"
Check if any of the events given in EvMask is available. Using the
struct timeval *t, you can control the timeout, like select(2). Give
NULL to wait indefinitely or a filled out struct to wait for a given
time (which may be 0 to get non-blocking behaviour).

Return: a mask of events which are available (within the limits set by
the mask parameter).


.TP
.RB int\  ggiEventRead " (ggi_visual_t vis, ggi_event *ev, ggi_event_mask mask);"
Read an Event from the queue. This call blocks, if there is no such
Event present.


.SH Input and output 

.TP
.RB int\  ggiKbhit " (ggi_visual_t vis);"
Checks if a key has been hit on the keyboard. This does not consume
the key. It is basically for easy porting of old DOS applications.

Return: 0 if no key has been received yet, otherwise there is a key to
be consumed.

DO NOT poll like this: do while( ! ggiKbhit(vis) );. On a multitasking
OS you are wasting ressources which could be available to other
processes.  If you want to wait for a key, use the ggiGetc() call.

.TP
.RB int\  ggiGetc  " (ggi_visual_t vis);"
Gets a character from the keyboard. Blocks if no key is available.

Return: a 16-bit Unicode character.

As a simple heuristic, you may use 0xff to convert the return code to
ISO-Latin-1 for quickly porting an old application. Please do that
right later using the K_* symbols.

.TP
.RB int\  ggiPutc " (ggi_visual_t vis, int x, int y,char c);"
Puts a single character on a graphical visual. This is only a very
simple routine using (normally) a fixed-width 8x8 font.


Return: 0 for OK, otherwise an error code.


.TP
.RB int\  ggiPuts " (ggi_visual_t vis, int x, int y,const char *str);"
Puts multiple characters at once. No special handling is applied to
control characters like CR or LF. You will see the associated glyph
being displayed, so do this yourself if you need.

Puts obeys the clipping rectangle.

Return: 0 for OK, otherwise an error code.

Don't use ggiPutc() repeatedly for multiple characters, as ggiPuts()
might be able to optimize the output of muliple chars at once.






.\"
.\"------------------------------------------------------------------
.\"
.SH DATA

.\"
.\"------------------------------------------------------------------
.\"



.\"
.\"------------------------------------------------------------------
.\"
.SH ARGUMENTS

.\"
.\"------------------------------------------------------------------
.\"

.\"
.\"------------------------------------------------------------------
.\"
.SH ENVIRONMENT VARIABLES

.\"
.\"------------------------------------------------------------------
.\"



.SH EXAMPLE APPLICATION



.SH BUGS
Many. Esp. the function names which are not in the gsi style :-)

.SH FILES

.SH SEE ALSO
.BR kgi "(3) "

.SH AUTHOR
Man page by WHS & the authors of the original sgml version, GGI by many authors.

.B email:
??info@ggi-project.org
.br

.B WWW page:
http://www.ggi-project.org