> *** libgg ***
> - libgg functions are not documented. (I suppose they are all 'private'
> - though)
Yes. Though after looking through them I found some that are of more or less
general usability, even to usermode programs.
Marcus: Should we document those ? I can write up the text for them in this
case - if you promise to proofread it :-).
> *** libgii ***
> - giiGetConfDir,
NAME
giiGetConfDir - get LibGII configuration directory
SYNOPSIS
#include <ggi/gii.h>
const char *giiGetConfDir(void);
DESCRIPTION
giiGetConfDir gets the name of the directory where LibGII
configuration data is located (without a trailing slash).
It should be used only by GII modules like filters or inputs
to locate their private configuration data.
It is recommended to put such data under input/inputname or
filter/filtername respectively.
Depending on the security requirements of the config data in
question it is recommended to also scan the directory given by
ggGetUserDir() (maybe in a restricted fashion) with the same
subpath for additions.
RETURN VALUE
giiGetConfDir returns a pointer to a string that contains the
configuration directory. The string is _const_. Do not overwrite !
> - giiMTInit,
NAME
giiMTInit - Turn on thread safe operation
SYNOPSIS
#include <ggi/gii.h>
int giiMTInit(void)
DESCRIPTION
You need to call giiMTInit before using LibGII in a mutithreaded
program. This will enable extra checks and locks that are off by
default to avoid overhead.
RETURN VALUE
giiMTInit returns 0 on sucessful execution.
> - giiQueryDeviceInfo,giiQueryDeviceInfoByNumber
NAME
giiQueryDeviceInfo - get information about a given GII input source
SYNOPSIS
#include <ggi/gii.h>
int giiQueryDeviceInfo(gii_input_t inp, uint32 origin,
gii_cmddata_getdevinfo *info)
int giiQueryDeviceInfoByNumber(gii_input_t inp, uint32 number,
uint32 *origin,
gii_cmddata_getdevinfo *info)
DESCRIPTION
Though when using GII inputs the exact type of device is fully
transparent to the program, information about the device that
is actually attached to a given gii input and origin id can be
queried, e.g. for configuration interfaces.
For giiQueryDeviceInfo the parameters inp and origin select the
input to query. This version is usually used, if you want to
identify a device after getting an event from it.
For giiQueryDeviceInfoByNumber the parameters inp and number
select the input to query - origin gets set to the origin ID
the queried device has. This version is used, when you want to
query all known devices.
The queried data is put into info, which has the following fields:
longname : Name of the device (string, 74+\0 chars max)
shortname: Abbreviated devicename (string, 4+\0 chars max)
gii_event_mask can_generate: Events this device can generate
num_buttons: Number of keys/buttons this device has
num_axes: Number of valuator axes the device has
RETURN VALUE
Returns 0 on success (info is valid, then) or -1 otherwise.
> - giiQueryValInfo are not documented.
NAME
giiQueryValInfo - Get data about valuators
SYNOPSIS
#include <ggi/gii.h>
int giiQueryValInfo(gii_input_t inp, uint32 origin,
uint32 valnumber,
gii_cmddata_getvalinfo *info)
DESCRIPTION
Though when using GII inputs the exact type of device is fully
transparent to the program, information about the device that
is actually attached to a given gii input and origin id can be
queried, e.g. for configuration interfaces.
For giiQueryValInfo is used on devices, where giiQueryDeviceInfo
has indicated that the device has one or more valuator axes and you
want to gather additional info about the physical equivalent of
each axis.The parameters inp and origin select the input to query
and valnumber selects the specific valuator (an input can have
multiple valuators).
The queried data is put into info, which has the following fields:
number : Number of the queried valuator.
longname : Name of the device (string, 74+\0 chars max)
shortname: Abbreviated devicename (string, 4+\0 chars max)
gii_valrange range: struct with sint32 min, center, max;
Contains the minimum, center and maximum values for this
valuator. Note, that this range may change on some
devices due to calibration, but it is usually not
expected that a device recalibrates while in use.
You should react gracefully to values received from
the valuator that are outside the specified range,
though.
gii_phystype phystype: gives the physical quantity the device
measures. The idea is to report the thing the user
actually controls. I.e. a Joystick actually measures
resistance, but should report GII_PT_ANGLE or
GII_PT_FORCE, as that is what the user does to the
stick and what results in the changed resistance.
sint32 SI_add,SI_mul,SI_div,SI_shift:
Using these values, it is possible to give calibration
data to the application. In gii.h there is a base unit
(according to SI) specified for each phystype.
The SI value can be computed using these values
and the following formula (unless SI_mul is 0, which
means the device is non-linear or the factor is unknown).
SI = (float) (SI_add + value[n]) * (float) SI_mul
/ (float) SI_div * pow(2.0, SI_shift);
RETURN VALUE
Returns 0 on success (info is valid, then) or -1 otherwise.
> - giiPanic prototype is:
> void giiPanic(char *format, ...)
> but documented as:
> int giiPanic(const char *format, ...);
Umm Marcus: Is there a specific reason, why the prototype doesn't have const ?
void is right, as giiPanic never returns.
> - first argument of giiEventSelect is 'gii_input_t' in source and
> *'gii_input ' in manpage (gii-unix.h)
Should be gii_input_t.
> *** libggi ***
> - ggiEventSelect,
take it from giiEventSelect.
> giiGetConfDir,
Umm - ggiGetConfDir - or ? Adapt from the above.
> ggiExtension*, ggiGetAPI, ggiIndicateChange,
> are not documented
These are internal for making extensions.
Should we document those ?
> - ggiPanic : same as gii.
See above.
> - ggiCrossBlit : args should be 'ggi_visual_t' instead of 'ggi_visual *' in man
Yes.
> - ggiSetTextMode: the 'ggi_graphtype type' argument is not mentioned in manpage.
You will probably want to redirect users to include/ggi/types.h or mention
the GT_[xx]BIT and GT_AUTO values or do the full thing and explain both the
predefined values and how to construct ones' own with GT_CONSTRUCT.
> - ggiCheckTextMode:
> int ggiCheckTextMode(ggi_visual_t visual,int cols,int rows,
> int vcols,int vrows, int fontx,int fonty,
> ggi_graphtype type, ggi_mode *suggested_mode);
>
> but stated in manpage as:
> int ggiCheckTextMode(ggi_visual_t visual, int cols, int
> rows, int vcols, int vrows, int fontx, int fonty,
> ggi_mode *suggested_mode, ...);
>
> - ggiCheckGraphMode: doesn't expect additionnal args, but ends with ... in
> manpage.
Take away the ... .
CU, ANdy
--
= Andreas Beck | Email : <[EMAIL PROTECTED]> =
