PfExtentFractTextCharPositions()

Calculate individual character positions, using fractional scaling

Synopsis:

#include <photon/Pf.h>

int PfExtentFractTextCharPositions(
       PhRect_t * ptsExtent,
       PhPoint_t * ptsPos,
       char * psz,
       const char * pckFont,
       int32_t * piIndices,
       int32_t * piPenPositions,
       int32_t iArrayLen,
       uint32_t ulFlags,
       int32_t iBytes,
       uint32_t uiExtentLen,
       PhRect_t const * pktsClip,
       uint32_t uiXscale,
       uint32_t uiYscale );

Arguments:

ptsExtent
A pointer to a PhRect_t structure that's used to store the extent of the string.
ptsPos
A pointer to a PhPoint_t structure that's used as an offset to apply against the extent. If NULL, no offset is added to the extent values.
psz
A pointer to a NUL-terminated character string.
pckFont
A pointer to a NUL-terminated constant character string, containing the stem name of the particular font. You should use PfGenerateFontName() to create this.
iArrayLen
The number of integer entries in the piIndices and piPenPositions arrays.
piIndices
A pointer to an integer array of length iArrayLen. An index corresponds to a location within the string pointed to by psz.

For example, index 0 relates to the pen's x position at the start of the string, index 1 corresponds to the pen's x position after character 1, index 2 corresponds to the pen's x position after character 2, and so on.

The indexes must be in numerical order, in order to function as expected.

piPositions
A pointer to an integer array of length iArrayLen. This array contains the resulting pen x values (in pixels), for each index.
ulFlags
A 32-bit value used for flags. Values that can be ORed in are:
iBytes
The number of bytes in the string. If this is 0, the function assumes that the number of bytes is:
strlen( psz ) / wstrlen( psz )
  
uiExtentLen
The number of characters from the beginning of the string to include in the extent. If 0, the entire string is extented, as permitted by the clipping rectangle.
pktsClip
A clipping rectangle to be used to reduce processing, depending on the value of pktsClip->lr.x (in pixels). If pktsClip is NULL, no clipping is applied.
uiXscale, uiYscale
Horizontal and vertical scaling factors in 16.16 format.

Library:

ph

Description:

PfExtentFractTextCharPositions() lets you obtain the pen's x position after every index specified in the function call. It's similar to PfExtentTextCharPositions(), except that fractional scaling is applied.

Returns:

0
Success.
-1
An error occurred; errno is set.

Errors:

ERANGE
The font manager couldn't fulfill the request; one of the following is true:
EFAULT
One of ptsExtent, piIndices, piPenPositions, pckFont, or psz is NULL.
EINVAL
The font is fixed-width, and an error occurred when trying to retrieve the common width of all characters in that particular font.
EMORE
Something unexpected occurred while processing a run of characters.

Classification:

Photon

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

PfExtent(), PfExtentCx(), PfExtentText(), PfExtentTextCharPositions(), PfExtentTextCharPositionsCx(), PfExtentTextToRect(), PfFractionalExtentText(), PfGenerateFontName(), PhPoint_t, PhRect_t

Fonts chapter of the Photon Programmer's Guide