MstrInquire
| Board | Supported |
|---|---|
| Host System | Yes |
| V4L2 | Yes |
| Clarity UHD | Yes |
| Concord PoE | No |
| GenTL | Yes |
| GevIQ | Yes |
| GigE Vision | Yes |
| Indio | No |
| Iris GTX | Yes |
| Radient eV-CL | Yes |
| Rapixo CL | Yes |
| Rapixo CoF | Yes |
| Rapixo CXP | Yes |
| USB3 Vision | Yes |
Inquire information about a specified String Reader context, string model, result buffer, font, or an error/warning code generated by
MstrExpert.
Syntax
AIL_INT MstrInquire(
AIL_ID ContextOrResultId, //in
AIL_INT Index, //in
AIL_INT64 InquireType, //in
void * UserVarPtr //out
)
Description
This function inquires information about a String Reader context, the string models or fonts contained therein, or a result buffer. In addition, this function can inquire from the String Reader context the meaning of an error/warning code generated by MstrExpert and retrieved using MstrGetResult with M_REPORT_ERRORS or M_REPORT_WARNINGS.
Unless otherwise specified, the inquire type settings are applicable to both font-based and fontless contexts.
If the inquired setting is set to M_DEFAULT (for example, in MstrControl), MstrInquire will return M_DEFAULT. To inquire the actual default value, add M_DEFAULT to the InquireType parameter.
Parameters
ContextOrResultId (in, AIL_ID)
Specifies the String Reader context or result buffer about which to inquire information. The String Reader context must have been previously allocated on the required system using MstrAlloc. The String Reader result buffer must have been previously allocated on the required system using MstrAllocResult.
Index (in, AIL_INT)
Specifies that information will be inquired about the String Reader context, a specific font, a specific string model, a specified error/warning code, or a result buffer. Set this parameter to one of the following values:
For a String Reader context, specific font, specific string model, result buffer, or a report generated by the last call to MstrExpert().
| Value | Description |
|---|---|
M_DEFAULT | Specifies the default. |
If a String Reader context is specified, same as M_CONTEXT.
If a String Reader result buffer is specified, same as M_GENERAL. |
| M_FONT_INDEX | Specifies the index of the font about which to inquire.
Note that this macro is only available for a font-based context. |
| M_STRING_INDEX | Specifies the index of the string about which to inquire. |
| M_CONTEXT | Specifies to inquire information about a general setting of a String Reader context. |
| M_GENERAL | Specifies to inquire information about a general setting of a String Reader result buffer. |
| Error or warning value | Specifies the error or warning code about which to inquire. Typically, these codes are generated by the last call to MstrExpert, and retrieved using MstrGetResult with either M_REPORT_ERRORS or M_REPORT_WARNINGS. |
| User label | Specifies the label of the font or string about which to inquire, assigned using MstrControl.
Set InquireType to either M_FONT_INDEX_FROM_LABEL or M_STRING_INDEX_FROM_LABEL to retrieve the font or string index associated with the user label, respectively. |
InquireType (in, AIL_INT64)
Specifies the type of setting about which to inquire.
UserVarPtr *(out, void)
Specifies the address in which to write the requested information. Since the MstrInquire function also returns the requested information, you can set this parameter to M_NULL.
Parameter Associations
For a context or an individual string
For a String Reader context (M_CONTEXT), or a specific string in the String Reader context (M_STRING_INDEX()), the InquireType parameter can be set to the following:
M_STRING_NUMBER
Inquires either the maximum (total) number of all strings that can be read with a String Reader context (M_CONTEXT), or the maximum number of a specific string (M_STRING_INDEX()) that can be read with a String Reader context.
| Value | Description |
|---|---|
M_DEFAULT | |
M_ALL | Specifies that all strings will be read. |
Value (default) | Specifies the maximum number of strings that can be read. |
For a context or a specific font
For a fontless context (M_CONTEXT), or font-based context (M_FONT_INDEX()), the InquireType parameter can be set to the following:
M_CHAR_VALUE
Inquires the character value for each character in the font-based or fontless context. Unless a data type from the table DataType is explicitly added to M_CHAR_VALUE, the string array must be of the right type for the encoding scheme selected (MstrInquire with M_ENCODING).
| Value | Description |
|---|---|
Value | Specifies the value of the character. |
M_NUMBER_OF_CHARS
Inquires the number of characters in the font-based or fontless context.
| Value | Description |
|---|---|
Value | Specifies the number of characters. |
M_SPACE_WIDTH
Inquires the width of the space character of the font or fontless context.
| Value | Description |
|---|---|
M_DEFAULT | |
M_INFINITE | Specifies that the width of the space character is infinite. |
M_MAX_CHAR_WIDTH | Specifies that the width of the space character is equal to the maximum character X-size of the font. |
M_MEAN_CHAR_WIDTH (default) | Specifies that the width of the space character is equal to the average character X-size of the font. |
M_MIN_CHAR_WIDTH | Specifies that the width of the space character is equal to the minimum character X-size of the font. |
M_QUARTER_MAX_CHAR_WIDTH | Specifies that the width of the space character is equal to a quarter of the maximum character width of the font. |
Value >= 1 | Specifies the width of the space character, in pixels. |
M_SPACE_WIDTH_VALUE
Inquires the actual width value of the space character of the font or fontless context.
| Value | Description |
|---|---|
Value >= 1 | Specifies the actual width value of the space character, in pixels. |
For a String reader context
For a String Reader context (M_CONTEXT), the InquireType parameter can be set to one of the following:
M_CHAR_STATUS
Inquires the status of each character in the context, where the status determines whether the String Reader module should search for the character in the image.
| Value | Description |
|---|---|
M_DISABLE | Specifies not to search for the character when performing a read operation. |
M_ENABLE | Specifies to search for the character when performing a read operation. |
M_CONTEXT_TYPE
Inquires the type of String Reader context.
| Value | Description |
|---|---|
M_FONT_BASED | Specifies a font-based context. Such contexts must be allocated, using MstrAlloc. |
M_FONTLESS | Specifies a fontless context. Such contexts must be restored, using MstrRestore. |
M_DRAW_LAST_SIZE_X
Inquires the width of the image buffer needed by the last call to MstrDraw. This allows you to allocate a buffer of optimal size, for the required drawing operation. Note that when you call MstrDraw for the first time, you can pass M_NULL as the destination image to get the size needed for the required drawing operation. For more information, see MstrDraw.
| Value | Description |
|---|---|
Value | Specifies the width of the image buffer. |
M_DRAW_LAST_SIZE_Y
Inquires the height of the image buffer needed by the last call to MstrDraw. This allows you to allocate a buffer of optimal size, for the required drawing operation. Note that when you call MstrDraw for the first time, you can pass M_NULL as the destination image to get the size needed for the required drawing operation. For more information, see MstrDraw.
| Value | Description |
|---|---|
Value | Specifies the height of the image buffer. |
M_ENCODING
Inquires the type of character encoding used by the String Reader context.
| Value | Description |
|---|---|
M_DEFAULT | |
M_ASCII (default) | Specifies an 8-bit ASCII standard. |
M_UNICODE | Specifies a 16-bit Unicode standard. |
M_MAX_CHAR_SIZE_X
Inquires the width (X-size) of the widest, enabled character in the fontless context when it has a height of M_REF_CHAR_SIZE_Y.
| Value | Description |
|---|---|
M_DEFAULT | |
0 <= Value <= 65536 (default) | Specifies the maximum character width, in pixels. |
M_MIN_CHAR_SIZE_X
Inquires the width (X-size) of the narrowest, enabled character in the fontless context when it has a height of M_REF_CHAR_SIZE_Y.
| Value | Description |
|---|---|
M_DEFAULT | |
0 <= Value <= 65536 (default) | Specifies the minimum character width, in pixels. |
M_MINIMUM_CONTRAST
Inquires the minimum contrast between a character in the target image and its background, in order for the character to be read by MstrRead.
| Value | Description |
|---|---|
M_DEFAULT | |
1 <= Value <= 255 (default) | Specifies the minimum contrast. |
M_MODIFICATION_COUNT
Inquires the current value of the modification counter. The modification counter is increased by one each time settings for the context are modified. Although you cannot identify the modification counter's contents, you can compare them throughout your application to know if the context has been altered. If the modification counter has changed you can, for example, prompt the user to save before closing the application.
| Value | Description |
|---|---|
Value | Specifies the current value of the modification counter. |
M_NUMBER_OF_FONTS
Inquires the number of fonts in the context.
| Value | Description |
|---|---|
Value | Specifies the number of fonts. |
M_NUMBER_OF_STRING_MODELS
Inquires the number of string models in the context.
| Value | Description |
|---|---|
Value | Specifies the number of string models. |
M_PREPROCESSED
Inquires whether the String Reader context is preprocessed. This will indicate whether preprocessing (using MstrPreprocess) is needed to prepare the context for use.
| Value | Description |
|---|---|
M_FALSE | Specifies that the context is not preprocessed; you should preprocess again. |
M_TRUE | Specifies that the context is preprocessed; you should not preprocess again. |
M_REF_CHAR_SIZE_Y
Inquires the reference height.
| Value | Description |
|---|---|
M_DEFAULT | |
0 <= Value <= 65536 (default) | Specifies the height, in pixels. |
M_REF_CHAR_THICKNESS
Inquires the stroke width of characters in the fontless context when they have a height of M_REF_CHAR_SIZE_Y.
| Value | Description |
|---|---|
M_DEFAULT | |
0 <= Value <= 65536 (default) | Specifies the thickness, in pixels. |
M_SEARCH_CHAR_ANGLE
Inquires whether strategies specific to angular-range will be calculated.
| Value | Description |
|---|---|
M_DEFAULT | |
M_DISABLE (default) | Specifies not to perform calculations specific to angular-range search strategies. |
M_ENABLE | Specifies to perform calculations specific to angular-range search strategies. |
M_SEARCH_SKEW_ANGLE
Inquires whether strategies specific to angular-range skew will be calculated.
| Value | Description |
|---|---|
M_DEFAULT | |
M_DISABLE (default) | Specifies not to perform calculations specific to angular-range skew search strategies. |
M_ENABLE | Specifies to perform calculations specific to angular-range skew search strategies. |
M_SEARCH_STRING_ANGLE
Inquires whether to search for the string angle.
| Value | Description |
|---|---|
M_DEFAULT | |
M_DISABLE | Specifies not to search for the string angle. |
M_ENABLE (default) | Specifies to search for the string angle. |
M_SPACE_CHARACTER
Inquires the character value to use as a space character within the formatted text that will be read.
| Value | Description |
|---|---|
M_DEFAULT | |
M_NONE | Specifies no space character. |
Value (default) | Specifies the space character, as its numerical code (ASCII or Unicode). |
M_SPEED
Inquires the search/read speed.
| Value | Description |
|---|---|
M_DEFAULT | |
M_HIGH | Specifies a high speed. |
M_MEDIUM (default) | Specifies a medium speed. |
M_STRING_SEPARATOR
Inquires the character value to use as a string separator within the formatted text that will be read.
| Value | Description |
|---|---|
M_DEFAULT | |
M_NONE | Specifies no separator character. |
Value (default) | Specifies the separator character, as its numerical code (ASCII or Unicode). |
M_THICKEN_CHAR
Inquires the number of character thickening iterations.
| Value | Description |
|---|---|
M_DEFAULT | |
0 <= Value <= 100 (default) | Specifies the number of character thickening iterations. |
M_THRESHOLD_MODE
Inquires the threshold method of the character blob extraction.
| Value | Description |
|---|---|
M_DEFAULT | |
M_LOCAL | Specifies a local thresholding that uses only one threshold step that is automatically computed by the module. |
M_LOCAL_WITH_RESEGMENTATION (default) | Specifies a local thresholding that uses multiple threshold steps and split and merge techniques. |
M_USER_DEFINED | Specifies a global thresholding that uses the threshold value set with M_THRESHOLD_VALUE. |
M_THRESHOLD_VALUE
Inquires the global threshold value when M_THRESHOLD_MODE is set to M_USER_DEFINED (otherwise it is ignored).
| Value | Description |
|---|---|
M_DEFAULT | |
M_AUTO_COMPUTE (default) | Specifies to automatically compute the global threshold value. |
0 <= Value <= 255 | Specifies the threshold value. |
M_TIMEOUT
Inquires the maximum read time for MstrRead, in msec.
| Value | Description |
|---|---|
M_DEFAULT | |
M_DISABLE | Specifies an infinite amount of read time. |
Value >= 0 (default) | Specifies the maximum read time, in msec. |
For an individual string
For a specific string (M_STRING_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:
M_CHAR_ACCEPTANCE
Inquires the acceptance level for the character score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies an acceptable score, as a percentage. |
M_CHAR_ASPECT_RATIO_MAX_FACTOR
Inquires the factor used to determine the upper limit of the aspect ratio for the characters in the string.
| Value | Description |
|---|---|
M_DEFAULT | |
1.0 <= Value <= 2.0 (default) | Specifies the factor that determines the maximum aspect ratio of the characters in the string. |
M_CHAR_ASPECT_RATIO_MIN_FACTOR
Inquires the factor used to determine the lower limit of the aspect ratio for the characters in the string.
| Value | Description |
|---|---|
M_DEFAULT | |
0.5 <= Value <= 1.0 (default) | Specifies the factor that determines the minimum aspect ratio of the characters in the string. |
M_CHAR_HOMOGENEITY_ACCEPTANCE
Inquires the acceptance level for the character's homogeneity score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies an acceptable score, as a percentage. |
M_CHAR_MAX_BASELINE_DEVIATION
Inquires the maximum deviation that a character can have from the string's baseline.
| Value | Description |
|---|---|
M_DEFAULT | |
0 <= Value <= 100 (default) | Specifies the character's maximum baseline deviation within the string model. |
M_CHAR_SCALE_MAX_FACTOR
Inquires the factor used to determine the upper limit (maximum permitted scale) of the scale range for the characters in the string.
| Value | Description |
|---|---|
M_DEFAULT | |
1.0 <= Value <= 2.0 (default) | Specifies the factor that determines the maximum scale of the characters in the string. |
M_CHAR_SCALE_MIN_FACTOR
Inquires the factor used to determine the lower limit (minimum permitted scale) of the scale range for the characters in the string.
| Value | Description |
|---|---|
M_DEFAULT | |
0.5 <= Value <= 1.0 (default) | Specifies the factor that determines the minimum scale of the characters in the string. |
M_CHAR_SIMILARITY_ACCEPTANCE
Inquires the acceptance level for the character's similarity score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies an acceptable score, as a percentage. |
M_DEFAULT_CONSTRAINT_FONT
Inquires the font index for each default font constraint. This information can also be inquired using MstrInquire with M_DEFAULT_CONSTRAINT_TYPE; however, it is encoded with other constant values. M_DEFAULT_CONSTRAINT_FONT always returns a single value.
| Value | Description |
|---|---|
(see M_FONT_INDEX FontIndex) |
M_DEFAULT_CONSTRAINT_TYPE
Inquires the default constraint type. M_DEFAULT_CONSTRAINT_TYPE always returns a single value.
| Value | Description |
|---|---|
Value | Specifies the default constraint type. |
M_FOREGROUND_VALUE
Inquires the foreground color of the string.
| Value | Description |
|---|---|
M_DEFAULT | |
M_FOREGROUND_BLACK (default) | Specifies that black is the foreground color of the string. |
M_FOREGROUND_BLACK_OR_WHITE | Specifies that the foreground color of the string can be either black or white. |
M_FOREGROUND_WHITE | Specifies that white is the foreground color of the string. |
M_NUMBER_OF_CONSTRAINTS
Inquires the number of positions in the string that have a non-default constraint. Non-default constraints are constraints that have been set to a value other than M_DEFAULT. Constraints are added to a string using MstrSetConstraint.
| Value | Description |
|---|---|
Value | Specifies the number of positions that have a constraint. |
M_SPACE_MAX_CONSECUTIVE
Inquires the maximum number of consecutive space characters allowed in the string.
| Value | Description |
|---|---|
M_DEFAULT | |
Value >= 0 (default) | Specifies the maximum number of consecutive space characters. |
M_STRING_ACCEPTANCE
Inquires the acceptance level for the string score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies an acceptable score, as a percentage. |
M_STRING_ANGLE
Inquires the nominal angle of the string.
| Value | Description |
|---|---|
M_DEFAULT | |
M_ACCORDING_TO_REGION (default) | Specifies to set the nominal angle to the angle of the rectangular ROI (set using MbufSetRegion) in the image. |
M_STRING_ANGLE_DELTA_NEG
Inquires the lower limit of the string's angular range, relative to the nominal angle (MstrControl with M_STRING_ANGLE).
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 10.0 (default) | Specifies the lower limit of the angular range, in degrees. |
M_STRING_ANGLE_DELTA_POS
Inquires the upper limit of the string's angular range, relative to the nominal angle (MstrControl with M_STRING_ANGLE).
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 10.0 (default) | Specifies the upper limit of the angular range, in degrees. |
M_STRING_ASPECT_RATIO
Inquires the nominal aspect ratio of the string.
| Value | Description |
|---|---|
M_DEFAULT | |
0.5 <= Value <= 2.0 (default) | Specifies the ratio of pixel width to pixel height of the target. |
M_STRING_ASPECT_RATIO_MAX_FACTOR
Inquires the factor used to determine the upper limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl with M_STRING_ASPECT_RATIO).
| Value | Description |
|---|---|
M_DEFAULT | |
1.0 <= Value <= 2.0 (default) | Specifies the factor that determines the maximum aspect ratio of the string. |
M_STRING_ASPECT_RATIO_MIN_FACTOR
Inquires the factor used to determine the lower limit of the string's aspect ratio. This value is relative to the nominal aspect ratio (MstrControl with M_STRING_ASPECT_RATIO).
| Value | Description |
|---|---|
M_DEFAULT | |
0.5 <= Value <= 1.0 (default) | Specifies the factor that determines the minimum aspect ratio of the string. |
M_STRING_CERTAINTY
Inquires the certainty level for the string score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies the certainty level for the string score, as a percentage. |
M_STRING_SCALE
Inquires the nominal scale of the string.
| Value | Description |
|---|---|
M_DEFAULT | |
0.25 <= Value <= 4.0 (default) | Specifies the value of the scale. |
M_STRING_SCALE_MAX_FACTOR
Inquires the factor used to determine the upper limit (maximum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl with M_STRING_SCALE).
| Value | Description |
|---|---|
M_DEFAULT | |
1.0 <= Value <= 2.0 (default) | Specifies the factor that determines the minimum scale of the string. |
M_STRING_SCALE_MIN_FACTOR
Inquires the factor used to determine the lower limit (minimum permitted scale) of the string's scale range. This value is relative to the nominal scale (MstrControl with M_STRING_SCALE).
| Value | Description |
|---|---|
M_DEFAULT | |
0.5 <= Value <= 1.0 (default) | Specifies the factor that determines the minimum scale of the string. |
M_STRING_SIZE_MAX
Inquires the maximum string size (number of characters) of the string model.
| Value | Description |
|---|---|
M_DEFAULT | |
M_INFINITE (default) | Specifies no maximum string size. |
Value >= 1 | Specifies the maximum string size. |
M_STRING_SIZE_MIN
Inquires the minimum string size (number of characters) of the string model.
| Value | Description |
|---|---|
M_DEFAULT | |
Value >= 1 (default) | Specifies the minimum string size. |
M_STRING_TARGET_ACCEPTANCE
Inquires the acceptance level for the string target score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies an acceptable string target score, as a percentage. |
M_STRING_TARGET_CERTAINTY
Inquires the certainty level for the string target score.
| Value | Description |
|---|---|
M_DEFAULT | |
0.0 <= Value <= 100.0 (default) | Specifies the certainty level for the string target score, as a percentage. |
M_STRING_TYPE
Inquires the type of the string model added to the String Reader context.
| Value | Description |
|---|---|
M_DEFAULT | |
M_USER_DEFINED (default) | Specifies a user-defined type of string model. |
M_STRING_USER_LABEL
Inquires the string model's user-defined label.
| Value | Description |
|---|---|
M_DEFAULT | |
M_NO_LABEL (default) | Specifies that no user label is associated with the string model. |
Value | Specifies the user label of the string model. |
For an individual string when specifying constraints
For a specific string (M_STRING_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:
M_CONSTRAINT
Inquires the constraint string at the specified index. Unless a data type from the table DataType is explicitly added to M_CONSTRAINT, the string array type corresponds to the encoding scheme selected with M_ENCODING. The string returned is null-terminated.
| Value | Description |
|---|---|
Value | Specifies the constraint string. |
M_CONSTRAINT_ALLOC_SIZE
Inquires the allocation size needed for each non-default constraint string. The allocation size of the constraint string includes the terminating null character ("\0").
| Value | Description |
|---|---|
Value | Specifies the size needed when retrieving the specified constraint string. |
M_CONSTRAINT_FONT
Inquires the font index for each non-default constraint of the string model. This information can also be inquired using MstrInquire with M_CONSTRAINT_TYPE; however, it is encoded with other constant values. You can inquire the position in the string model to which the constraint applies using MstrInquire with M_CONSTRAINT_POSITION.
| Value | Description |
|---|---|
(see M_FONT_INDEX FontIndex) |
M_CONSTRAINT_POSITION
Inquires the position of each non-default constraint in the string model (0, 255). The default constraint is therefore applied to all positions not returned in this array.
| Value | Description |
|---|---|
Value | Specifies the position of the constraint. |
M_CONSTRAINT_TYPE
Inquires the type of each non-default constraint of the string model (for example, M_LETTER, M_DIGIT). You can inquire the position in the string model to which this constraint applies using MstrInquire with M_CONSTRAINT_POSITION.
| Value | Description |
|---|---|
Value | Specifies the constraint's type. |
M_DEFAULT_CONSTRAINT
Inquires the default constraint string. The string array must be large enough to contain M_DEFAULT_CONSTRAINT + M_STRING_SIZE characters. Unless a data type from the table DataType is explicitly added to M_DEFAULT_CONSTRAINT, the string array type corresponds to the encoding scheme selected with M_ENCODING. The string returned is null-terminated.
| Value | Description |
|---|---|
Value | Specifies the default constraint string. |
Combination Constants — For getting the string size
Optional.
Usage: You can add one of the following values to the above-mentioned values to get the string's length.
M_STRING_SIZE
Retrieves the length of the constraint string, including the terminating null character ("\0").
Combination Constants — For
Essential.
Usage: You must add one of the following values to the above-mentioned values to get the constraint string at the specified index.
0 <= Value < M_NUMBER_OF_CONSTRAINTS
Inquires the constraint string at the specified index. The index you provide is the index of the constraint in the list of non-default constraints, and not its actual position in the string model. You can inquire the position in the string model that this constraint string applies to using MstrInquire with M_CONSTRAINT_POSITION.
For an individual font
For a specific font (M_FONT_INDEX()) in the String Reader context, the InquireType parameter can be set to one of the following:
M_CHAR_BASELINE
Inquires the setting for the baseline value for each character. To return the automatically calculated character baseline (when M_CHAR_BASELINE is set to M_AUTO_COMPUTE), use M_CHAR_BASELINE_VALUE.
| Value | Description |
|---|---|
(see M_CHAR_BASELINE) |
M_CHAR_BASELINE_VALUE
Inquires the baseline value for each character. Note that when M_CHAR_BASELINE is set to M_AUTO_COMPUTE, this value will return the calculated character baseline.
| Value | Description |
|---|---|
(see M_CHAR_BASELINE) |
M_CHAR_SIZE_X
Inquires the X-size of each character in the font.
| Value | Description |
|---|---|
Value | Specifies the X-size of the character, in pixels. |
M_CHAR_SIZE_Y
Inquires the Y-size of each character in the font.
| Value | Description |
|---|---|
Value | Specifies the Y-size of the character, in pixels. |
M_CHAR_THICKNESS
Inquires the average thickness of each character in the font.
| Value | Description |
|---|---|
Value | Specifies the thickness of the character, in pixels. |
M_CHAR_TYPE
Inquires the type of each character in the font.
| Value | Description |
|---|---|
(see M_CHAR_TYPE) |
M_CHAR_TYPE_VALUE
Inquires the type value of each character in the font. When the value of M_CHAR_TYPE is M_AUTO_COMPUTE, M_CHAR_TYPE_VALUE contains the auto-computed value (M_REGULAR or M_PUNCTUATION). For more information, see MstrEditFont with M_CHAR_TYPE.
| Value | Description |
|---|---|
(see M_CHAR_TYPE) |
M_DEFINITION_OFFSET_X
Inquires the X-offset for each character in the font. The X- and Y-offsets define where the character is found in the definition image. This inquire type is only valid for user-defined characters (MstrEditFont with M_USER_DEFINED).
| Value | Description |
|---|---|
M_NONE | Specifies that the font in the String Reader context is a system font (MstrEditFont with M_SYSTEM_FONT). |
X-offset value | Specifies the X-offset of the character, in pixels. |
M_DEFINITION_OFFSET_Y
Inquires the Y-offset for each character in the font. The X- and Y-offsets define where the character is found in the definition image. This inquire type is only valid for user-defined characters (MstrEditFont with M_USER_DEFINED).
| Value | Description |
|---|---|
M_NONE | Specifies that the font in the String Reader context is a system font (MstrEditFont with M_SYSTEM_FONT). |
Y-offset value | Specifies the Y-offset of the character, in pixels. |
M_DRAW_BOX_MARGIN_X
Inquires the margin in the X-direction, between the character box and the drawing box.
| Value | Description |
|---|---|
M_DEFAULT | |
Value >= 0 (default) | Specifies the horizontal margin, in pixels. |
M_DRAW_BOX_MARGIN_Y
Inquires the margin in the Y-direction, between the character box and the drawing box.
| Value | Description |
|---|---|
M_DEFAULT | |
Value >= 0 (default) | Specifies the vertical margin, in pixels. |
M_FONT_TYPE
Inquires the type of font added.
| Value | Description |
|---|---|
M_DEFAULT | |
M_USER_DEFINED (default) | Specifies a user-defined type of font. |
M_FONT_USER_LABEL
Inquires the font's user-defined label.
| Value | Description |
|---|---|
M_DEFAULT | |
M_NO_LABEL (default) | Specifies that no user label is associated with the font. |
Value | Specifies the user label of the font. |
For specifying the result for
For a string result buffer (M_GENERAL), the InquireType parameter can be set to one of the following:
M_RESULT_OUTPUT_UNITS
Inquires whether results are returned in pixel or world units.
| Value | Description |
|---|---|
M_DEFAULT | |
M_ACCORDING_TO_CALIBRATION (default) | Specifies that results are returned in world units if the result was calculated on an image associated with a camera calibration context; otherwise, specifies that results are returned in pixel units. |
M_PIXEL | Specifies that results are returned in pixel units, with respect to the pixel coordinate system. |
M_WORLD | Specifies that results are returned in world units, with respect to the relative coordinate system. |
M_DEFAULT | Specifies the default; the default is M_ACCORDING_TO_CALIBRATION. |
Combination Constants — For the default value of an inquire type
Optional.
Usage: You can add one of the following values to the above-mentioned values to determine the default value of an inquire type, regardless of the current value of the inquire type.
M_DEFAULT
Inquires the actual default value of the specified inquire type.
For inquiring about the system
To inquire about the system on which the String Reader context or result buffer has been allocated, set the InquireType parameter to the value below. Note that the Index parameter must be set to M_CONTEXT for a String Reader context or to M_GENERAL for a result buffer.
M_OWNER_SYSTEM
Inquires the identifier of the system on which the String Reader context or result buffer was allocated.
| Value | Description |
|---|---|
M_DEFAULT_HOST | Specifies the default Host system of the current Aurora Imaging Library application. |
System identifier | Specifies a valid system identifier, previously allocated using MsysAlloc. |
For retrieving the meaning of an error or warning report value generated by MstrExpert()
For retrieving the meaning of an error or warning code generated by MstrExpert, and retrieved using MstrGetResult with M_REPORT_..., the InquireType parameter can be set to the following value.
M_REPORT_STRING
Inquires the error message associated with an error or warning code generated by MstrExpert.
Combination Constants — For determining the required array size (number of elements) to store the returned values
Optional, cannot be used alone.
Usage: You can add one of the following values to the above-mentioned values to determine the required array size (number of elements) to store the returned values.
M_NB_ELEMENTS
Retrieves the required array size (number of elements) to store the returned values.
Combination Constants — For inquiring whether an inquire type is supported
Optional.
Usage: You can add one of the following values to the above-mentioned values to determine whether an inquire type is supported.
M_SUPPORTED
Inquires whether the specified inquire type is supported for the String Reader context.
| Value | Description |
|---|---|
M_FALSE | Specifies that the inquire type is not supported. |
M_TRUE | Specifies that the inquire type is supported. |
For user label inquiries
For user label inquiries, the InquireType parameter can be set to one of the following:
M_FONT_INDEX_FROM_LABEL
Inquires the font index associated with a font user label if the user label is used.
| Value | Description |
|---|---|
M_INVALID | Specifies that the user label is invalid. This is returned if the specified user label is not associated with a font. |
Value | Specifies the font index associated with the specified user label. |
M_STRING_INDEX_FROM_LABEL
Inquires the string model index associated with a string model user label if the user label is used.
| Value | Description |
|---|---|
M_INVALID | Specifies that the user label is invalid. This is returned if the specified user label is not associated with a string model. |
Value | Specifies the string model index associated with the specified user label. |
Combination Constants — For specifying the data type
Optional.
Usage: You can add one of the following values to the above-mentioned values to cast the requested results to the required data type.
M_TYPE_AIL_DOUBLE
Casts the requested results to an AIL_DOUBLE.
M_TYPE_AIL_FLOAT
Casts the requested results to an AIL_FLOAT.
M_TYPE_AIL_ID
Casts the requested results to an AIL_ID.
M_TYPE_AIL_INT
Casts the requested results to an AIL_INT.
M_TYPE_AIL_INT16
Casts the requested results to an AIL_INT16.
M_TYPE_AIL_INT32
Casts the requested results to an AIL_INT32.
M_TYPE_AIL_INT64
Casts the requested results to an AIL_INT64.
M_TYPE_CHAR
Casts the requested results to a char.
M_TYPE_TEXT_CHAR
Casts the requested results to an AIL_TEXT_CHAR.
Return Value
Type: AIL_INT
The returned value is the requested information, cast to an AIL_INT. If the requested information does not fit into an AIL_INT, this function will return M_NULLor truncate the information.
Note that this inquire type is only available for a fontless context.
Note that this inquire type is only available for a font-based context.
The default constraint is applied, by default, either for all positions of the string model, if no explicit constraint has been set, or for a specific position, if M_DEFAULT has been set for a specific position.