# PRC_GetRecognizedEntry*

## C Specification

      #include <nitro/prc.h>

      fx32 PRC_GetRecognizedEntry(
      PRCPrototypeEntry**         resultEntry,
      void*                       buffer,
      const PRCInputPattern*      input,
      const PRCPrototypeDB*       protoDB );

      fx32 PRC_GetRecognizedEntryEx(
      PRCPrototypeEntry**         resultEntry,
      void*                       buffer,
      const PRCInputPattern*      input,
      const PRCPrototypeDB*       protoDB,
      u32                         kindMask,
      const PRCRecognizeParam*    param );

      int PRC_GetRecognizedEntries(
      PRCPrototypeEntry**         resultEntries,
      fx32*                       resultScores,
      int                         numRanking,
      void*                       buffer,
      const PRCInputPattern*      input,
      const PRCPrototypeDB*       protoDB );

      int PRC_GetRecognizedEntriesEx(
      PRCPrototypeEntry**         resultEntries,
      fx32*                       resultScores,
      int                         numRanking,
      void*                       buffer,
      const PRCInputPattern*      input,
      const PRCPrototypeDB*       protoDB,
      u32                         kindMask,
      const PRCRecognizeParam*    param );

## Arguments

resultEntry | Pointer for receiving the `PRCPrototypeEntry*` recognition results.
buffer | Pointer to the memory region used by the recognition algorithm.
input | Input pattern data to be recognized.
protoDB | Sample DB.
kindMask | Bit field specification of the pattern type that is used to qualify match targets.
param | Other parameter values that are dependent on the recognition algorithm (use NULL as the default).

resultEntries | Pointer to the array that receives the `PRCPrototypeEntry*` recognition results.
resultScores | Pointer to the array that receives the recognition result score.
numRanking | Specifies up to what rank of the recognition results will be accepted.

## Return Values

`PRC_GetRecognizedEntry` and `PRC_GetRecognizedEntryEx` return the recognition result score as a `fx32` type.

`PRC_GetRecognizedEntries` and `PRC_GetRecognizedEntriesEx` return how many of the sample DB patterns are matching targets.

## Description

Performs pattern recognition. This function matches the `PRCInputPattern` type input pattern and each entry in the `PRCPrototypeDB` type sample DB and returns those that have high scores.

When matching, the logical AND is taken of `kind` for each sample DB entry in `protoDB` and the value of `kindMask`. If the result is non-0, the entry will be targeted for matching. Specifying `PRC_KIND_ALL` in `kindMask` will select all `kinds`. If the `enabled` flag is FALSE, the DB entry will not be targeted for matching, even if the `kind` values match.

`PRC_GetRecognizedEntry` and `PRC_GetRecognizedEntryEx` return a pointer to the sample DB entry that has the highest score in `*resultEntry`. If no recognition was achieved, `NULL` will be returned to `*resultEntry`.

`PRC_GetRecognizedEntries` and `PRC_GetRecognizedEntriesEx` return pointers to high scoring sample DB entries scores above `numRanking`, in descending order according to score in `resultEntries[]`. It returns the numerical value of each score in `resultScores[]`. If the number of matching target sample DB entries does not reach `numRanking`, `NULL` will be assigned to the unfilled regions of `resultEntries[]`.

Note that depending on the selected recognition algorithm and the complexity of the input pattern, depending on the number and complexity of the sample DB entries, and depending on other conditions, the cost of this process can become extremely high. Based on the fact that multiple frames will be involved in recognition, we recommend that this function run on a thread other than the main process. For a sample implementation see `prc/characterRecognition-1` in the demos.

Use `buffer` to specify the memory region that the recognition algorithm will use. First obtain the amount of memory required using `PRC_GetRecognitionBufferSize*` and allocate at least that amount.

Scores are returned as an `fx32`. The range will be `0 <= range <= FX32_ONE`.

Higher scores indicate a recognition result that has a closer resemblance to the pattern. Calling `PRC_GetRecognizedEntry, PRC_GetRecognizedEntries`, is the same as calling `PRC_GetRecognizedEntryEx, PRC_GetRecognizedEntriesEx` with `kindMask` set to `PRC_KIND_ALL`, and `param` set to `NULL`.

For details on recognition algorithms see `docs/TechnicalNotes/AboutPatternRecognition.pdf`.

## See Also

`PRC_GetRecognitionBufferSize*`, `PRCRecognizeParam`, `PRC_Init`, `PRC_InitPrototypeDB*`, `PRC_InitInputPattern*`, `PRC_GetEntryCode`, `PRC_GetEntryData`

## Revision History

02/18/2005 Revised file name of reference document
06/23/2004 Initial Version