.\" @(#)PEXText.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXText 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXText - 3D Text Primitive
.SH SYNTAX
.HP
void PEXText\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, PEXOCRequestType \fIreq_type\fP\^, PEXCoord *\fIorigin\fP\^, PEXVector *\fIvector1\fP\^, PEXVector *\fIvector2\fP\^, int \fIlength\fP\^, char *\fIstring\fP\^)
.SH PARAMETERS
.IP \fIdisplay\fP 1i
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.IP \fIresource_id\fP 1i
The resource identifier of the renderer or structure.
.IP \fIreq_type\fP 1i
The request type for the output command (
.B PEXOCRender,
.B PEXOCStore,
.B PEXOCRenderSingle
or
.B PEXOCStoreSingle
).
.IP \fIorigin\fP 1i
The origin of the text string.
.IP \fIvector1\fP 1i
A vector defining the positive x-direction of the text local coordinate system.
.IP \fIvector2\fP 1i
A vector defining the positive y-direction of the text local coordinate system.
.IP \fIlength\fP 1i
The number of bytes in the text string.
.IP \fIstring\fP 1i
A pointer to the text string.
.SH RETURNS
.LP
None
.SH DESCRIPTION
.\" indexing
.IX PEXText
.LP
This function creates a text output primitive.
.LP
The first character set in the text font will be used.
.LP
The text string is located on a plane defined by
its position and direction vectors.  The
.I origin
defines the position, in
model coordinates,
at which to render the text
.I string.
The two direction vectors define the
positive x- and y-directions of the text local coordinate system.
If the two vectors are parallel or if one of the vectors has zero
length, the vector values <1,0,0> and <0,1,0> are used.
.LP
During rendering, the string's position is
transformed to a position in device coordinates.  The string's
color is only affected by depth-cueing
and is mapped to a device color.  The text
.I string
is clipped depending
on the current text precision attribute.  If the text precision is
.B PEXStringPrecision,
clipping is done in an implementation-dependent fashion.
If the text precision is
.B PEXCharPrecision,
clipping is done on at least a character-by-character basis.
If the text precision is
.B PEXStrokePrecision,
clipping is performed at the clipping boundaries for each character.
.LP
Depending on the text ASF values, the text color, text precision,
character expansion, character spacing, and text font attributes are
obtained either directly from the current text attribute values or
from the entry in the text bundle
specified by the current text bundle index attribute.
The current character height, text path, text alignment attributes
and character up vector are also used to render the text
.I string.
The directions specified by the character up vector and text path
are relative to the text local coordinate system.
.SH DATA STRUCTURES
.LP
See
.B PEXlib.h.
.sp
.SH ERRORS
.TP
.SB BadPEXRenderer
The specified renderer resource identifier is invalid.
.TP
.SB BadPEXStructure
The specified structure resource identifier is invalid.
.SH SEE ALSO
.LP
.nf
.BR PEXSetTextFontIndex (3)
.BR PEXSetTextPrecision (3)
.BR PEXSetCharExpansion (3)
.BR PEXSetCharSpacing (3)
.BR PEXSetTextColorIndex (3)
.BR PEXSetTextColor (3)
.BR PEXSetCharHeight (3)
.BR PEXSetCharUpVector (3)
.BR PEXSetTextPath (3)
.BR PEXSetTextAlignment (3)
.BR PEXSetTextBundleIndex (3)
.fi