The RCRESULT Structure - Microsoft Windows Pen API Programmer's Reference (penapi.hlp)

Microsoft Windows Pen API
Programmer's Reference

The RCRESULT Structure

A recognizer can store its results in any format the developer wishes. It need not create an RCRESULT structure except in response to calls to certain superseded functions such as Recognize and RecognizeData. For completeness, this section describes the RCRESULT structure, which the developer may wish to use as a model for storage. Although a recognizer must calculate the information found in an RCRESULT structure, it need not organize the information in the same format.

Note The RCRESULT structure is not required in version 2.0 of the Pen API and is supported only to maintain compatibility with older applications that use version 1.0 recognizer API.

The first member of the RCRESULT structure is a list called the symbol graph, which contains all the recognizer's guesses. An application can read the guesses in order of likelihood by walking through the symbol graph.

The Symbol Graph
The best way to understand the symbol graph is to first diagram its contents before describing how to actually read it. The following discussion again takes up the example in the section "Getting Results" in Chapter 5, in which the recognizer generated the five guesses "clear," "dear," "clean," "dean," and "deer." A diagram of the symbol graph that represents all these possibilities might look like this:

Letter: { cl | d } e { a | e } { r | n }

Confidence: 80% 60% 100% 85% 20% 80% 50%

Average: clear 86%

dear 81%

clean 79%

dean 74%

deer 58%

If you study the diagram a moment, you will see its logic. Alternative letters appear separated by a C bitwise-OR symbol, with the most likely alternative first. All the guesses in this example, however, agree that the second (or third) character is the letter "e," so it has no alternatives. Taking the first letter in each alternative set produces the most likely of the guesses

in this case, the word "clear."

The symbol graph includes confidence values for each character or character set (as in the case of the interpretation "cl"). The recognizer can determine a confidence value for an entire word by averaging the values for each character or character set, as shown in the diagram above. (Note that this hypothesis is purely for purposes of discussion. The pen API does not mandate how a recognizer determines its confidence levels. The influence of word lists and other factors may also change confidence levels.)

Symbol graphs must, therefore, contain three types of information:

All characters (or character sets) determined as likely interpretations for a set of pen strokes
A map identifying the pen strokes that correspond to each interpretation
A confidence level for each interpretation

As described in Chapter 11, "Pen Application Programming Interface Structures," the symbol graph is a structure of type SYG. The SYG structure contains two additional data structures that provide the needed information: symbol correspondence and symbol element structures.

A symbol correspondence structure SYC delineates a specific subset of the strokes entered by the user. Each SYC contains the first and last strokes of a subset; these strokes and the strokes between them define the subset of pen data associated with the SYC. The symbol graph contains an array of SYC structures, each of which corresponds to a different part of the ink input. Taken together, the SYC structures define all the ink gathered during the input session.

A SYG structure also contains an array of symbol element SYE structures. An SYE contains a symbol value, a confidence level, and an index into the array of SYC structures. Each character or character set in the recognized input has its own symbol element.

The Best Guess
The RCRESULT structure also provides information about the recognizer's "best guess." The best guess is simply the first interpretation in the symbol graph, which lists interpretations in descending order of probability. Since an application is often interested only in the most likely interpretation, the recognizer should place in the RCRESULT the following three members specifically to identify the best guess:

The lpsyv member points to a null-terminated symbol string containing the best guess.
The cSyv member contains the number of symbols in the best guess string.
The hSyv member is the handle to the memory block to which lpsyv points.

Location and Position of the Input
The RCRESULT structure also contains information regarding the location and position of the ink entered by the user.

The nBaseLine member is the recognizer's estimate of the baseline of the ink entered by the user. (For a definition of baseline, see "Noise Reduction and Normalization" earlier in this chapter.) If the baseline is not known, the recognizer sets this value to 0. The Microsoft Handwriting Recognizer (GRECO.DLL) sets nBaseLine to 0.
The nMidLine member is the recognizer's estimate of the midline of the ink entered by the user. If the midline is not known, the recognizer sets this value to 0. The Microsoft Handwriting Recognizer sets nMidLine to 0.
The rectBoundInk member is a Windows RECT structure. It holds the bounding rectangle that circumscribes the area of the screen on which the user has written. Typically, an application uses rectBoundInk to invalidate the screen area to update the display in the appropriate location. This occurs, for example, when Windows replaces ink on the screen with recognized text.

Contextual Information
Two elements of the RCRESULT structure provide information about the recognition event, but not as a part of the results of recognition. They are lprc, a far pointer to the RC structure passed to the Recognize function, and wResultsType, a flag that describes how the recognition event proceeded. The wResultsType flag contains a combination of RCRT_ constants, described in Chapter 13, "Pen Application Programming Interface Constants."

The Ink
The final two members of the RCRESULT structure contain information about the ink entered by the user.

The pntEnd member contains the last point of the ink data from the user only if PCM_RECTBOUND or PCM_RECTEXCLUDE have been specified. An application sets these flags either in the lPcm member of the RC structure or the dwPcm member of the PCMINFO structure.
The hpendata member is a handle to a pen data memory block that contains all of the ink information entered by the user.

More Online Helps

Win32 Programmer's Reference (win32.hlp)
Win32 Multimedia Programmer's Reference (mmedia.hlp)
OLE Programmer's Reference (ole.hlp)
Microsoft Windows Sockets 2 Reference (sock2.hlp)
Microsoft Windows Telephony API (TAPI) Programmer's Reference (tapi.hlp)
Unix Manual Pages

greatis just4fun network