PfRenderCtx(), PfRenderCx()

Render a string via a user callback function

Synopsis:

int PfRenderCtx( void *ctx,
                 const char *font, 
                 long adata,
                 long bdata,
                 const char *str,
                 int len,
                 int flags,
                 PhPoint_t const *pos,
                 PhRect_t const *clip, 
                 void (*func) (
                    void *, const PhPoint_t *pos,
                    const FontRender *));

int PfRenderCx( struct _Pf_ctrl *context,
                void *ctx,
                const char *font, 
                long adata,
                long bdata,
                const char *str,
                int len,
                int flags,
                PhPoint_t const *pos,
                PhRect_t const *clip, 
                void (*func) (
                   void *, const PhPoint_t *pos,
                   const FontRender *));

Arguments:

context

(PfRenderCx() only) A pointer to the font context to use, which you can get by calling PfAttach().

ctx

A context/data pointer that's passed to the user callback, func. This value must be nonzero; if you don't want to pass a context, set this argument to 1.

font

The base font, which you should create by calling PfGenerateFontName().

adata

The horizontal fractional point size, if you set PF_FRACTIONAL in the flags argument.

bdata

The vertical fractional point size, if you set PF_FRACTIONAL in the flags argument.

str

The string whose extent you want to calculate. The string is a UTF-8 multibyte one by default.

len

The length of the string, str, in bytes. If len is 0, the function uses strlen(str).

flags

Flags that affect the behavior of the function.

You can set up to one of the following to indicate the format of the string:

• PF_WIDE_CHARS -- the string is composed of 16-bit wide characters. If you set this flag, the function assumes that each character is represented by 2 bytes that conform to the ISO/IEC 10646-1 UCS-2 double-byte format.
• PF_WIDE_CHAR32 -- the string is composed of 32-bit wide characters. If you set this flag, the function assumes that each character is represented by 4 bytes that conform to the ISO/IEC 10646-1 UCS-4 four-byte format.

  ---

  Although this flag allows for 32-bit wide characters, the underlying font system currently supports only characters up to Unicode U+FFFE.

  ---

If you don't set either of the above, the function assumes that the string is composed of UTF-8 multibyte characters.

You can OR in:

• PF_FRACTIONAL -- use a fractional 16.16 point size. If you set this flag, use the adata argument to specify the horizontal fractional point size, and bdata to specify the vertical fractional point size.

pos

A pointer to a PhPoint_t structure that specifies the location at which to render the text.

clip

A pointer to a PhRect_t that specifies the clipping rectangle for the text. If clip is NULL, it's ignored. The font server performs coarse character clipping only.

func

A user callback function that's called to render the text. It's called with the desired pen location and the metrics of the bitmap. If the entire bitmap doesn't fit in the allocated memory, multiple calls to the font server and the user function can be made, advancing the pen as appropriate between calls.

Library:

ph

Description:

These functions render the given string via a user callback function. The difference between PfRenderCtx() and PfRenderCx() is that PfRenderCx() lets you specify the font context to use.

When a request to construct the bitmap is sent to the font server, the string bitmap is returned, for efficiency, in the shared-memory area created through the initial call to PfAttach().

Normally, only the graphics drivers use these functions, but they may be useful for application programs that have to obtain text bitmap data directly.

The generic design of these routines allows future expansion.

The FontRender metrics structure contains at least the following members:

PhPoint_t size

The bounding size of the bitmap, in pixels.

PhPoint_t offset

The offset of the bitmap (the upper-left of the extent).

int width

The width of the bitmap.

short bpl

The number of bytes per line.

short bpp

The number of bits per pixel (1 for normal output, 4 for anti-aliased).

unsigned char *bmptr

A pointer to the bitmap data (stored row-wise).

Returns:

0

Success.

-1

An error occurred; errno is set.

Classification:

Photon

See also:

PfAttach(), PfDetach(), PfGenerateFontName(), PfRenderText(), PfRenderWideText(), PhPoint_t, PhRect_t