LibGIIGIC Functions =================== Initialize and uninitialize LibGIIGIC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicInit gicExit Synopsis -------- :: #include int gicInit(void); int gicExit(void); Description ----------- `gicInit` initializes the library. This function must be called before using other LibGIIGIC functions; otherwise the results will be undefined. `gicExit` uninitializes the library (after being initialized by `gicInit`) and automatically cleans up if necessary. This should be called after an application finished using the library. If any GIC functions are called after the library has been uninitialized, the results will be undefined. `gicInit` allows multiple invocations. A reference count is maintained, and to completely uninitialize the library, `gicExit` must be called as many times as `gicInit` has been called beforehand. Return value ------------ `gicInit` returns `0` for OK, otherwise an :man:`gii-error(3)` code. `gicExit` returns: `0` after successfully cleaning up, `>0` the number of 'open' `gicInit` calls, if there has been more than one call to `gicInit`. As `gicInit` and `gicExit` must be used in properly nested pairs, e.g. the first `gicExit` after two `gicInit`'s will return `1`. `<0` :man:`gii-error(3)`, especially if more `gicExit` calls have been done than `gicInit` calls. Examples -------- Initialize and uninitialize LibGIIGIC:: if (gicInit() < 0) { fprintf(stderr, "Cannot initialize LibGIIGIC!\n"); exit(1); } /* Do some LibGIIGIC stuff */ gicExit(); See Also -------- :man:`gicOpen(3)` Open and close a recognizer ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicOpen gicClose Synopsis -------- :: #include gic_handle_t gicOpen(const char *recognizers,...); int gicClose(gic_handle_t hand); Description ----------- `gicOpen` opens a recognizer. This function is given the name of an recognizer driver to load. If only `NULL` is specified, the default recognizer target is opened. The optional arguments are a `NULL`-terminated list of pointers, which are used to give additional information to the targets. Currently only the first pointer is specified: `void *` :p:`argptr`, a pointer to a library-specific struct. It is used to pass parameters that are not easily transferable in textual form. Parameters which can be represented in text format are usually transfered in the :p:`input` parameter, in the format: ``library_name:arguments`` `gicClose` releases and destroys an open recognizer and its associated internal control structures. This will put back input streams to their default modes, etc. Return value ------------ `gicOpen` returns the opened recognizer or `NULL` for error. The `gic_handle_t` type is opaque to the programmer and can only be used through GIC functions. `gicClose` returns `GGI_OK` (== 0) for OK, otherwise an :man:`gii-error(3)` code. See Also -------- :man:`gicInit(3)` Associate a gii handle with gic ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicInputRegister Synopsis -------- :: #include int gicInputRegister(gic_handle_t hand,gii_input_t inp); Description ----------- `gicInputRegister` registers a GII gii_input_t with the GIC instance. This is needed by some recognizers to be able to store their configuration in a portable way. Return value ------------ `gicInputRegister` returns `0` for success, otherwise an :man:`gii-error(3)` code. See Also -------- :man:`gicOpen(3)` Adjust Recognizers ~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicRecognizerDriverRegister gicRecognizerDriverUnregister gicRecognizerDriverLookup Synopsis -------- :: #include int gicRecognizerDriverRegister(gic_handle_t hand, gic_recognizerdriver *driver); int gicRecognizerDriverUnregister(gic_handle_t hand, gic_recognizerdriver *driver); gic_recognizerdriver *gicRecognizerDriverLookup(gic_handle_t hand, const char *name); Description ----------- Recognizerdrivers. The work-monkeys. The recognizers given in :man:`gicOpen(3)` are automatically open. But you might want to adjust that list. `gicRecognizerDriverRegister` registers additional recognizers into the gic_handle_t. `gicRecognizerDriverUnregister` unregisters the given recognizer from the gic_handle_t. `gicRecognizerDriverLookup` searches for the recognizers with the given name. Return value ------------ `gicRecognizerDriverRegister` and `gicRecognizerDriverUnregister` return `0` for success, otherwise an :man:`gii-error(3)` code. `gicRecognizerDriverLookup` returns a pointer to the recognizer if found, otherwise NULL. See Also -------- :man:`gicOpen(3)` Recognizer dump ~~~~~~~~~~~~~~~ .. manpage:: 3 gicRecognizerWrite Synopsis -------- :: #include int gicRecognizerWrite(gic_handle_t hand, gic_recognizer *recognizer, FILE *file); Description ----------- Writes out a dump of the recognizer into the given file. TODO Write something useful here - be more verbose Return value ------------ `gicRecognizerWrite` returns `0` for success, otherwise an :man:`gii-error(3)` code. See Also -------- :man:`gicActionWrite(3)` Train recognizers ~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicRecognizerTrain gicRecognizerTrainStart gicRecognizerTrainStop gicRecognizerTrainAdd gicRecognizerTrainMove gicRecognizerFindConflict gicRecognizerGetName gicRecognizerGetOpposite Synopsis -------- :: #include int gicRecognizerTrain(gic_handle_t hand, gic_recognizer **recognizerlist, gii_event *event); #define gicRecognizerTrainStart(hand,x) \ gicRecognizerTrain(hand,x,NULL) #define gicRecognizerTrainStop(hand,x) \ gicRecognizerTrain(hand,x,NULL) int gicRecognizerTrainAdd(gic_handle_t hand, gic_recognizer **recognizerlist, gic_recognizer *newone); int gicRecognizerTrainMove(gic_handle_t hand, gic_recognizer **recognizerlist, gic_recognizer *newone); int gicRecognizerFindConflict(gic_handle_t hand, gic_recognizer *recognizer, gic_recognizer *compare_to); int gicRecognizerGetName(gic_handle_t hand, gic_recognizer *recognizer, char *string, size_t maxlen); int gicRecognizerGetOpposite(gic_handle_t hand, gic_recognizer *recognizer, gic_recognizer **opposite); Description ----------- TODO Write something useful here Return value ------------ All functions return `0` for success, otherwise an :man:`gii-error(3)` code. See Also -------- :man:`gicOpen(3)` Action handling ~~~~~~~~~~~~~~~ .. manpage:: 3 gicActionWrite gicActionMapActions Synopsis -------- :: #include int gicActionWrite(gic_handle_t hand, gic_actionlist *aclist, FILE *where); int gicActionMapActions(gic_handle_t hand, gic_actionlist *aclist, gic_actionlist *actions); Description ----------- `gicActionWrite` writes out a dump to the :p:`where` file. TODO Describe `gicActionMapActions` here Return value ------------ `gicActionWrite` and `gicActionMapActions` return `0` for success, otherwise an :man:`gii-error(3)` code. See Also -------- :man:`gicRecognizerWrite(3)` Allocate Features ~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicFeatureAllocate gicFeatureFree Synopsis -------- :: #include gic_feature *gicFeatureAllocate(gic_handle_t hand, char *name,char *shortname); void gicFeatureFree(gic_handle_t hand, gic_feature *feature); Description ----------- TODO Write something useful here Return value ------------ TODO Write something useful here See Also -------- TODO Bind Features with Recognizers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicFeatureAttachRecognizerDriver gicFeatureAttachRecognizer gicFeatureDetachRecognizer gicFeatureGetRecognizer gicFeatureNumRecognizers gicFeatureGetName Synopsis -------- :: #include int gicFeatureAttachRecognizerDriver(gic_handle_t hand, gic_feature *feature, gic_recognizerdriver *driver,void *privdata); int gicFeatureAttachRecognizer(gic_handle_t hand, gic_feature *feature, gic_recognizer *recognizer); int gicFeatureDetachRecognizer(gic_handle_t hand, gic_feature *feature, gic_recognizer *recognizer); gic_recognizer *gicFeatureGetRecognizer(gic_handle_t hand, gic_feature *feature, int number); int gicFeatureNumRecognizers(gic_handle_t hand, gic_feature *feature); int gicFeatureGetName(gic_handle_t hand, gic_feature *feature, char *string, size_t maxlen); Description ----------- TODO Write something useful here Return value ------------ TODO Write something useful here See Also -------- TODO Bind Features and Actions ~~~~~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicFeatureAttachAction gicFeatureDetachAction gicFeatureWrite gicFeatureRead Synopsis -------- :: #include int gicFeatureAttachAction(gic_handle_t hand, gic_feature *feature, void (*action)(gic_handle_t hand, gic_actionlist *action, gic_feature *feature,gic_state newstate, gic_flag flag,int recnum), void *privdata, char *name); int gicFeatureDetachAction(gic_handle_t hand, gic_feature *feature, void (*action)(gic_handle_t hand, gic_actionlist *action, gic_feature *feature,gic_state newstate, gic_flag flag,int recnum), void *privdata, char *name); Description ----------- `gicFeatureAttachAction()` and `gicFeatureDetachAction()` are used to bind an action (i.e. a callback function) to a feature. This is usually handled by higher layers, which map whole sets of actions using a gic_actionlist. Return value ------------ `gicFeatureAttachAction()` and `gicFeatureDetachAction()` return 0 on success and an :man:`gii-error(3)` code on failure. See Also -------- TODO Load and Save Feature ~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicFeatureWrite gicFeatureRead Synopsis -------- :: #include int gicFeatureWrite(gic_handle_t hand, gic_feature *feature, FILE *file); gic_feature *gicFeatureRead(gic_handle_t hand, FILE *file); Description ----------- `gicFeatureWrite` writes a description of the feature given to the given file. It can be read back with `gicFeatureRead` which will allocate and return a feature if successful. Afterwards `gicFeatureMapActions` should be called to reestablish the mapping between actions and callbacks. Return value ------------ TODO Write something useful here See Also -------- :man:`gicFeatureMapActions(3)` Feature mappings ~~~~~~~~~~~~~~~~ .. manpage:: 3 gicFeatureMapActions gicFeatureFindConflict Synopsis -------- :: #include int gicFeatureMapActions(gic_handle_t hand, gic_feature *feature, gic_actionlist *actions); int gicFeatureFindConflict(gic_handle_t hand, gic_feature *feature, gic_recognizer *rec, gic_recognizer **start_and_return); Description ----------- `gicFeatureMapActions` is called to reestablish the connection between the actions and the action callbacks. In learning-mode, `gicFeatureFindConflict` is useful to check, if there are conflicting features. Return value ------------ TODO Write something useful here See Also -------- TODO Event handling ~~~~~~~~~~~~~~ .. manpage:: 3 gicFeatureActivate gicFeatureHandleEvent Synopsis -------- :: #include int gicFeatureActivate(gic_handle_t hand, gic_feature *feature,gic_state newstate,gic_flag flag,int recnum); int gicFeatureHandleEvent(gic_handle_t hand, gic_feature *feature, gii_event *event); Description ----------- To manually activate a feature, call `gicFeatureActivate`. This will activate the relevant callbacks. You can feed events to `gicFeatureHandleEvent` to activate the relevant callbacks. However, usually one uses `gicContextHandleEvent`. Return value ------------ TODO Write something useful here See Also -------- :man:`gicContextHandleEvent(3)` Controls ~~~~~~~~ .. manpage:: 3 gicControlAllocate gicControlFree gicControlAttachFeature gicControlDetachFeature gicControlLookupFeature gicControlGetFeature gicControlNumFeatures gicControlGetName gicControlWrite gicControlRead gicControlMapActions gicControlFindConflict gicControlHandleEvent Synopsis -------- :: #include gic_control *gicControlAllocate(gic_handle_t hand, char *name,char *shortname); void gicControlFree(gic_handle_t hand, gic_control *control); int gicControlAttachFeature(gic_handle_t hand, gic_control *control,gic_feature *feature); int gicControlDetachFeature(gic_handle_t hand, gic_control *control,gic_feature *feature); gic_feature *gicControlLookupFeature(gic_handle_t hand, gic_control *context,const char *name); gic_feature *gicControlGetFeature(gic_handle_t hand, gic_control *context,int number); int gicControlNumFeatures(gic_handle_t hand, gic_control *context); int gicControlGetName(gic_handle_t hand, gic_control *control, char *string, size_t maxlen); int gicControlWrite(gic_handle_t hand, gic_control *control,FILE *file); gic_control *gicControlRead(gic_handle_t hand, FILE *file); int gicControlMapActions(gic_handle_t hand, gic_control *control,gic_actionlist *actions); int gicControlFindConflict(gic_handle_t hand, gic_control *control,gic_recognizer *feature, gic_recognizer **start_and_return,gic_feature **optional); int gicControlHandleEvent(gic_handle_t hand, gic_control *control, gii_event *event); Description ----------- A gic_control is LIBGIIGIC's notion of a collection of things that control a motion or similar. Usually applications do not need to handle this themselves. To allocate a new :man:`gic_control(3)`, call `gicControlAllocate`. To free a context that is not needed anymore, call `gicControlFree`. `gicControlAttachFeature` and `gicControlDetachFeature` are used to attach and detach features from a control. Multiple features like up/down/left/right make up a control (like sliding). `gicControlLookupFeature` and `gicControlGetFeature` can be used to get access to features attached to a control. The former accesses the features by name, the latter by number. You can use `gicControlNumFeatures` to query for the number of controls. `gicControlGetName` can be used to query for the name of a control. `gicControlWrite` writes a description of the control given to the given :p:`file`. It can be read back with `gicContextRead` which will allocate and return a control if successful. Afterwards `gicControlMapActions` should be called to reestablish the mapping between actions and callbacks. In learning-mode, `gicControlFindConflict` is useful to check, if there are conflicting controls. You can feed events to `gicControlHandleEvent` to activate the relevant callbacks. However, usually one uses `gicContextHandleEvent`. Return value ------------ `gicControlRead` and `gicControlAllocate` return the read/allocated context on return or NULL on failure. `gicControlAttachFeature`, `gicControlDetachFeature`, `gicControlWrite` and `gicControlMapActions` return `0` on success and an :man:`gii-error(3)` code on failure. `gicControlLookupFeature` and `gicControlGetFeature` return the requested feature or NULL on failure. `gicControlNumFeatures` return the number of features attached to the control. See Also -------- :man:`gicContextRead(3)` Contexts ~~~~~~~~ .. manpage:: 3 gicContextAllocate gicContextFree gicContextAttachControl gicContextDetachControl gicContextLookupControl gicContextGetControl gicContextNumControls gicContextGetName gicContextWrite gicContextRead gicContextMapActions gicContextFindConflict gicContextHandleEvent Synopsis -------- :: #include gic_context *gicContextAllocate(gic_handle_t hand,char *name); void gicContextFree(gic_handle_t hand,gic_context *context); int gicContextAttachControl(gic_handle_t hand, gic_context *context,gic_control *control); int gicContextDetachControl(gic_handle_t hand, gic_context *context,gic_control *control); gic_control *gicContextLookupControl(gic_handle_t hand, gic_context *context,const char *name); gic_control *gicContextGetControl(gic_handle_t hand, gic_context *context,int number); int gicContextNumControls(gic_handle_t hand, gic_context *context); int gicContextGetName(gic_handle_t hand, gic_context *context, char *string, size_t maxlen); int gicContextWrite(gic_handle_t hand, gic_context *context,FILE *file); gic_context *gicContextRead(gic_handle_t hand,FILE *file); int gicContextMapActions(gic_handle_t hand, gic_context *context,gic_actionlist *actions); int gicContextFindConflict(gic_handle_t hand, gic_context *context,gic_recognizer *rec, gic_recognizer **start_and_return,gic_feature **optional); int gicContextHandleEvent(gic_handle_t hand, gic_context *context, gii_event *event); Description ----------- A gic_context is a collection of controls that make sense in a given situation (context) of the application. A control is an abstract object that usually describes a type of motion (e.g. sliding). It can have multiple subobjects (called features) that can further break that down (e.g. into up/down/left/right). Most applications will not need to handle that themselves. `gicHeadRead` will provide all they need. For those that want to build up contexts themselves, the following functions are provided: To allocate a new gic_context, call `gicContextAllocate`. To free a context that is not needed anymore, call `gicContextFree`. `gicContextAttachControl` and `gicContextDetachControl` are used to attach and detach controls from a context. A control refers to a collection of features that describe a common motion. Most contexts will have multiple such controls, like one for sliding and one for turning a player. `gicContextLookupControl` and `gicContextGetControl` can be used to get access to controls attached to a context. The former accesses the controls by name, the latter by number. You can use `gicContextNumControls` to query for the number of controls. `gicContextGetName` can be used to query for the name of a context. `gicContextWrite` writes a description of the context given to the given file. It can be read back with `gicContextRead` which will allocate and return context if successful. Afterwards `gicContextMapActions` should be called to reestablish the mapping between actions and callbacks. In learning-mode, `gicContextFindConflict` is useful to check, if there are conflicting controls. When the context is active, you feed it with events using `gicContextHandleEvent` which will cause it to activate the relevant callbacks. When an application is in a context, you should feed the events to `gicContextHandleEvent` to activate the relevant callbacks. Return value ------------ `gicContextRead` and `gicContextAllocate` return the read/allocated context on return or NULL on failure. `gicContextAttachControl`, `gicContextDetachControl`, `gicContextWrite` and `gicContextMapActions` return 0 on success and an :man:`gii-error(3)` code on failure. `gicContextLookupControl` and `gicContextGetControl` return the requested control or NULL on failure. `gicContextNumControls` return the number of controls attached to the context. See Also -------- :man:`gicHeadRead(3)`, :man:`gic_context(3)` Heads ~~~~~ .. manpage:: 3 gicHeadAllocate gicHeadFree gicHeadAttachContext gicHeadDetachContext gicHeadLookupContext gicHeadGetContext gicHeadNumContexts gicHeadWrite gicHeadRead gicHeadMapActions Synopsis -------- :: #include gic_head *gicHeadAllocate (gic_handle_t hand, char *name); void gicHeadFree (gic_handle_t hand, gic_head *head); int gicHeadAttachContext(gic_handle_t hand, gic_head *head,gic_context *context); int gicHeadDetachContext(gic_handle_t hand, gic_head *head,gic_context *context); gic_context *gicHeadLookupContext(gic_handle_t hand, gic_head *head,const char *name); gic_context *gicHeadGetContext (gic_handle_t hand, gic_head *head,int number); int gicHeadNumContexts (gic_handle_t hand, gic_head *head); int gicHeadWrite (gic_handle_t hand, gic_head *head,FILE *file); gic_head *gicHeadRead (gic_handle_t hand, FILE *file); int gicHeadMapActions (gic_handle_t hand, gic_head *head,gic_actionlist *actions); Description ----------- A gic_head is LIBGIIGIC's notion of a collection of contexts. Each context describes the mappings between inputs and actions for a given situation in a program. Thus a head usually describes all the contexts of a program that are managed by libgiigic. Usually a program will not have to bother with most functions as it will read its config via `gicHeadRead`. However when building apps that can (re)build the configuration files, the other functions become useful. A gic_head is allocated using `gicHeadAllocate`, which takes the gic handle it will be associated with and a name for the Head. It returns the allocated head or NULL on failure. `gicHeadFree` frees an allocated gic_head. `gicHeadAttachContext` and `gicHeadDetachContext` are used to attach and detach contexts from a head. A context refers to a situation in a program that has an input mapping attached to it. Most programs will have multiple such contexts, like one for accessing the menus, one for the game mode, etc. `gicHeadLookupContext` and `gicHeadGetContext` can be used to get access to contexts attached to a head. The former accesses the contexts by name, the latter by number. You can use `gicHeadNumContexts` to query for the number of contexts. `gicHeadWrite` can be used to write out a textual description of the head. This is usually used to write out a config file after it changed. `gicHeadRead` will read such a :p:`file`, allocate a gic_head and fill it with the read data. After that, you should call `gicHeadMapActions` to reestablish the connection between the actions and the action callbacks. Return value ------------ `gicHeadRead` and `gicHeadAllocate` return the read/allocated head on return or NULL on failure. `gicHeadAttachContext`, `gicHeadDetachContext`, `gicHeadWrite` and `gicHeadMapActions` return 0 on success and an :man:`gii-error(3)` code on failure. `gicHeadLookupContext` and `gicHeadGetContext` return the requested context or NULL on failure. `gicHeadNumContexts` return the number of contexts attached to the head. See Also -------- TODO Predefined callback functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. manpage:: 3 gicActionLazyAction gicActionLazyGetstate gicActionLazyReset Synopsis -------- :: #include void gicActionLazyAction(gic_handle_t hand, gic_actionlist *action, gic_feature *feature, gic_state newstate, gic_flag flag, int recnum); gic_state gicActionLazyGetstate(gicActionActionLazyData *data); void gicActionLazyReset(gicActionLazyData *data); Description ----------- TODO Return value ------------ TODO See Also -------- TODO