Measurement commands

GLfloat* glcGetMaxCharMetric	(	GLCenum	inMetric,
		GLfloat *	outVec
	)

This command measures the layout that would result from rendering all mapped characters at the same origin.

This contrast with glcGetStringCharMetric(), which measures characters as part of a string, that is, influenced by kerning, ligatures, and so on.

This command evaluates the metrics of every fonts in the GLC_CURRENT_FONT_LIST. Fonts that are not listed in GLC_CURRENT_FONT_LIST are ignored.

The command stores in outVec the value of the metric identified by inMetric. If the command does not raise an error, its return value is outVec.

The command raises GLC_PARAMETER_ERROR if outVec is NULL.

Parameters:

	inMetric	The metric to measure, either GLC_BASELINE or GLC_BOUNDS.
	outVec	A vector in which to store value of inMetric for all mapped character.

Returns:: outVec if the command succeeds, NULL otherwise.

See also:

glcGetCharMetric()

GLfloat* glcGetStringCharMetric	(	GLint	inIndex,
		GLCenum	inMetric,
		GLfloat *	outVec
	)

This command retrieves a character metric from the GLC measurement buffer and stores it in outVec.

To store a string in the measurement buffer, call glcMeasureCountedString() or glcMeasureString().

The character is identified by inIndex, and the metric is identified by inMetric.

The command raises GLC_PARAMETER_ERROR if inIndex is less than zero or is greater than or equal to the value of the variable GLC_MEASURED_CHAR_COUNT or outVec is NULL. If the command does not raise an error, its return value is outVec.

Example:: The following example first calls glcMeasureString() to store the string "hello" in the measurement buffer. It then retrieves both the baseline and the bounding box for the whole string, then for each individual character.

  GLfloat overallBaseline[4];
  GLfloat overallBoundingBox[8];

  GLfloat charBaslines[5][4];
  GLfloat charBoundingBoxes[5][8];

  GLint i;

  glcMeasureString(GL_TRUE, "hello");

  glcGetStringMetric(GLC_BASELINE, overallBaseline);
  glcGetStringMetric(GLC_BOUNDS, overallBoundingBox);

  for (i = 0; i < 5; i++) {
      glcGetStringCharMetric(i, GLC_BASELINE, charBaselines[i]);
      glcGetStringCharMetric(i, GLC_BOUNDS, charBoundingBoxes[i]);
  }

Note:: glcGetStringCharMetric is useful if you're interested in the metrics of a character as it appears in a string, that is, influenced by kerning, ligatures, and so on. To measure a character as if it started at the origin, call glcGetCharMetric().

Parameters:

	inIndex	Specifies which element in the string to measure.
	inMetric	The metric to measure, either GLC_BASELINE or GLC_BOUNDS.
	outVec	A vector in which to store value of inMetric for the character identified by inIndex.

Returns:: outVec if the command succeeds, NULL otherwise.

See also:

glcGetCharMetric()

glcGetMaxCharMetric()

GLfloat* glcGetStringMetric	(	GLCenum	inMetric,
		GLfloat *	outVec
	)

This command retrieves a string metric from the GLC measurement buffer and stores it in outVec.

The metric is identified by inMetric. To store a string from the GLC measurement buffer, call glcMeasureCountedString() or glcMeasureString().

The command raises GLC_PARAMETER_ERROR if outVec is GLC_NONE

If the command does not raise an error, its return value is outVec.

Parameters:

	inMetric	The metric to measure, either GLC_BASELINE or GLC_BOUNDS.
	outVec	A vector in which to store value of inMetric for the character identified by inIndex.

Returns:: outVec if the command succeeds, NULL otherwise.

See also:

glcGetCharMetric()

glcGetMaxCharMetric()

GLint glcMeasureCountedString	(	GLboolean	inMeasureChars,
		GLint	inCount,
		const GLCchar *	inString
	)

This command is identical to the command glcRenderCountedString(), except that instead of rendering a string, the command measures the resulting layout and stores the measurement in the GLC measurement buffer.

The string comprises the first inCount elements of the array inString, which need not be followed by a zero element.

If the value inMeasureChars is nonzero, the command computes metrics for each character and for the overall string, and it assigns the value inCount to the variable GLC_MEASURED_CHARACTER_COUNT. Otherwise, the command computes metrics only for the overall string, and it assigns the value zero to the variable GLC_MEASURED_CHARACTER_COUNT.

If the command does not raise an error, its return value is the value of the variable GLC_MEASURED_CHARACTER_COUNT.

The command raises GLC_PARAMETER_ERROR if inCount is less than zero.

Parameters:

	inMeasureChars	Specifies whether to compute metrics only for the string or for the characters as well.
	inCount	The number of elements to measure, starting at the first element.
	inString	The string to be measured.

Returns:: The variable GLC_MEASURED_CHARACTER_COUNT if the command succeeds, zero otherwise.

See also:

glcGeti() with argument GLC_MEASURED_CHAR_COUNT

glcGetStringMetric()

GLint glcMeasureString	(	GLboolean	inMeasureChars,
		const GLCchar *	inString
	)

This command measures the layout that would result from rendering a string and stores the measurements in the GLC measurement buffer.

This command is identical to the command glcMeasureCountedString(), except that inString is zero terminated, not counted.

If the command does not raise an error, its return value is the value of the variable GLC_MEASURED_CHARACTER_COUNT.

Parameters:

	inMeasureChars	Specifies whether to compute metrics only for the string or for the characters as well.
	inString	The string to be measured.

Returns:: The variable GLC_MEASURED_CHARACTER_COUNT if the command succeeds, zero otherwise.

See also:

glcGeti() with argument GLC_MEASURED_CHAR_COUNT