Provided by: libgiigic1-dev_1.1.2-2_i386 bug

NAME

       libgiigic-usage - LibGIIGIC Overview

PURPOSE

       LibGIIGIC  is intended to help the game developer with a flexible input
       mapping system which enables the user to  easily  adjust  the  bindings
       between game actions and the input device movements.

NO FEAR

       Please  do  not  get  confused  by the tons of API calls. Most are only
       useful if you are developing new configmanagers  or  applications  that
       have  very  special  needs,  like reconfiguring their controlset on the
       fly.

       A "normal" game will usually only  use  a  very  small  subset  of  the
       LibGIIGIC  API,  depending  if  it  wants  to  just  use  a  given  GIC
       configuration, or  if  it  also  wants  to  implement  a  configuration
       manager.

       Actually  it  is a good idea, to at least allow the user to run his own
       config manager if he wants to.

TERMINOLOGY

       LibGIIGIC has its own terminology that describes how an application and
       the  actions  that  can  be  triggered  within  it  relate. This can be
       confusing at first, so please make sure you read this section carefully
       and refer to it, if unsure.

       From  LibGIIGIC’s  point  of  view,  an application is represented as a
       "Head".  This term stems from the fact, that an application might serve
       multiple  displays  (heads)  with different configurations. LibGGI will
       usually have its own inputs for each head, then.

       Within each head, applications will usually have  different  needs  for
       input  mapping,  depending  on the current state of the application. In
       LibGIIGIC this is called a "Context".

       Each context (like "in game",  "main  menu",  ...)  will  usually  have
       several  aspects  that  can be controlled, for example movement, weapon
       choice, etc.  This is what LibGIIGIC calls a "Control".

       Most Controls have several subunits. For example movement  may  contain
       "forward",  "backward",  "left"  and  "right".  LibGIIGIC  calls  these
       "Features".

       Most of the time, one feature can be controlled by a single  keystroke,
       mouse-click,  joystick  movement, etc. However sometimes it makes sense
       to have multiple bindings for the same feature.

       Any such user input that  is  associated  to  a  feature  is  called  a
       "Recognizer".

       This hierarchy of types that builds the skeleton of LibGIIGIC.

       It     can     be     represented     as     a     file.     Look    at
       programs/demos/configmanager.gic for an  example.  Such  a  ".gic-file"
       contains all the configuration info for a given head.

       Of  course  it is not enough to just recognize, that a feature has been
       activated by some input. One usually wants to act on that.

       LibGIIGIC allows to bind callback functions to features that get called
       when a Recognizer triggers. These are called "Actions".

SIMPLE EXAMPLE

       Now let’s have a look at a very simple sample program - demo.c

       When  working with LibGIIGIC, you first need to initialize the library.
       Do this using gicInit(). When you don’t need LibGIIGIC  anymore,  close
       it  down  using  gicExit(). Don’t be afraid to use that in higher level
       libraries.  LibGIIGIC is aware of being initialized and exited multiple
       times,  and  will  handle it correctly, as long as the calls are nested
       properly.

       These calls only initialize the lib. To interact with it, you  need  to
       allocate  a gic_handle_t using gicOpen(NULL). The parameter is reserved
       for future expansion. When you are done with  it,  free  the  allocated
       handle using gicClose(handle).

       If you have an existing configuration file, you just read it:

       config = fopen("demo.gic", "r");
       head = gicHeadRead(handle, config);
       fclose(config);

       Simple - right?

       You  can  of course stuff your other data there, too. gicHeadRead(3) is
       aware of where to stop, so you can store your data before and after the
       LibGIIGIC data to your liking.

       If  you  are  interested  in rehearsing the terminoloy chapter, you may
       want to look at the demo.gic file yourself. It is  human  readable  and
       you will find the hierarchy of objects in there.

       Now what you got back is an object "head" which is of type gic_head(3).

       However, you will usually work with contexts, as the  application  will
       normally enter different states associated with gic_context(3)’s.

       You can extract the contexts from the head like this:

       menu = gicHeadLookupContext(handle, head, "Menu context");

       Now we have one point that needs to be cleaned up: the file also stores
       actions, which are basically callbacks.  However  how  does  one  store
       function  pointers  in  a config file in a way that does not break when
       moving the config file between platforms etc. ?

       You don’t. The next step is to reestablish the  "action  mapping"  -  a
       connection  between  a  symbolic  name  of  the  action, and the actual
       callback function. This  mapping  is  stored  in  a  variable  of  type
       gic_actionlist.

       A sample list would be:

       gic_actionlist actionmapping[]= {
             {NULL,"mynextaction",   my_action,      NULL},
             {NULL,"myprevaction",   my_action2,     (void *)0x12345678},
             {NULL,NULL,NULL,NULL}
       };

       The  first  element of each gic_actionlist-entry here is reserved for a
       chaining pointer and always NULL.

       The second element is the name of the action as it appears in the .gic-
       file.   The  third  is  the  callback  function,  and the fourth a void
       pointer to some private data which will be given to the callback.

       The fourth entry  allows  to  reuse  the  same  callback  function  for
       multiple  purposes,  which  makes  a  lot  of  sense,  as many callback
       functions are usually very similar.

       You can now re-map the actions using this call:

       gicHeadMapActions(handle,head,actionmapping);

       This will cause LibGIIGIC to iterate through the  head  and  its  child
       objects and find any actions attached. If the action names match a name
       in the actionmapping list, the respective callbacks are set up.

       From then on, LibGIIGIC is ready to receive events. You just receive  a
       gii_event from LibGII (or LibGGI which uses LibGII for input), or build
       one yourself, if you insist not to use LibGII.

       You can then feed the event to LibGIIGIC using:

       gicContextHandleEvent(handle,menu, &event);

       Note, that it does not make sense to send an event to a  head,  as  the
       event  might  have different meanings depending on context. So you just
       feed it to the right context.

       Now if an event matches the description in the .gic file, the requested
       action  callbacks  will fire. We will discuss them in greater detail in
       the next section.

       When we are done with LibGIIGIC, we should close down  all  handles  we
       opened using gicClose(handle) and finally call gicExit().

CALLBACK FUNCTIONS (ACTIONS)

       If  a  recognizer triggers, it will activate the feature it is attached
       to, which will in turn call the actions bound to it.

       Action functions have the following prototype:

       void my_action(gic_handle_t hand, gic_actionlist *action,
             gic_feature *feature, gic_state newstate,gic_flag flag,
             int recnum);

       When it gets called, it is given a lot of data that  allows  to  derive
       why it was called.

       First  of  all it gets the gic_handle_t that triggered the action. This
       is useful, if you want to call LibGIIGIC functions within the callback.

       Then  you get the gic_actionlist of the action that caused the callback
       to be actived. This  datatype  was  already  covered  in  the  previous
       section.   It’s  most common uses are differentiating calls to a common
       callback that serves multiple  purposes.  To  achieve  this,  the  most
       interesting  entries  are action->name and action->privdata, which will
       commonly be used to find out which action triggered  and  to  point  to
       some common data structure that will be modified by the actions.

       The  gic_feature(3)  points to the feature that this action is bound to
       and can as well be used to differentiate when binding a  single  action
       function to multiple features.

       When  a  feature  gets activated, it can have an "extent to which it is
       activated". This is used  by  features  that  don’t  only  have  on/off
       characteristics,  but  rather a linear notion of "how active they are".
       An example for this is e.g. a control for turning. Simple input devices
       like  keyboards  can  only say turn left/don’t turn left, while mice or
       joysticks can say how fast or far to turn.

       gic_state  carries  this   information.   The   macros   GIC_STATE_MIN,
       GIC_STATE_MAX,  GIC_STATE_MIDDLE  and  GIC_NOACTION can be used to find
       out how strong the respective measure of activation was.

       gic_flag can carry additional information about the  action.  If  flags
       are  set,  that  are  within GIC_FLAG_MUSTKNOWMASK, you are expected to
       handle them.  Set flags outside that bitmask are optional  and  can  be
       ignored for application development.

       Up  to  now, only one such flag is defined: GIC_FLAG_PULSE.  If set, it
       indicates, that the events triggering the action is of a "pulsed" type,
       i.e.  it  is expected to be released immediately after it was received,
       so you should handle it similar to the case of an event  like  the  one
       you  received,  immediately  followed  by  one  of  the  same kind with
       gic_state containing GIC_STATE_MIN.

       The integer recnum gives the number of the recognizer that caused  this
       event to trigger. This can be used when implementing "adding policies",
       like if turning with joystick and mouse at the same time will  add  up,
       or will just use the highest value, or whatever.

USING THE LAZY ACTION HELPERS

       Many simple programs will prefer not to use their own action callbacks,
       but rather just use this predefined callback system.

       For this to work, you have to bind all relevant actions you do not want
       to handle yourself to gicActionLazyAction(3).

       The privdata field must point to a gicActionLazyData(3) variable.

       When using the Lazy action helpers, you usually do something like this:

       ggiEventRead(vis,&event,emAll);               /* get an event. */
       /* Let LibGIC evaluate it for the menu context */
       gicContextHandleEvent(hand, menucon, &event);

       Now the gicActionLazyAction(3) callbacks are run, and you can check how
       much the individual gicActionLazyData(3) elements are active.

       For  this, you do: gicActionLazyGetstate(&lazydata) which will return a
       gic_state  you  can  evaluate.  (The  gicActionLazyAction(3)   callback
       implement  a  "max  activation  is  returned"  policy  with  respect to
       multiple active recognizers).

       This will also handle the case of pulsed inputs, which will be returned
       and then deleted.

       If  you are unsure about the state of the variables (e.g. at startup or
       after retraining the mappings),  you  can  reset  the  variables  using
       gicActionLazyReset(3).

TRAINING

       TODO

CONFLICTS

       TODO

SEE ALSO

       libgiigic(7)