.\" @(#)PEXAnnotationText.3 1.4 95/03/24 SMI;
.so man3/pex.macs
.TH PEXAnnotationText 3 "May 1995" "Solaris PEXlib Reference Manual" ""
.SH NAME
PEXAnnotationText \- 3D Annotation Text Primitive
.SH SYNTAX
.HP
void PEXAnnotationText\^(\^Display *\fIdisplay\fP\^, XID \fIresource_id\fP\^, PEXOCRequestType \fIreq_type\fP\^, PEXCoord *\fIorigin\fP\^, PEXCoord *\fIoffset\fP\^, int \fIlength\fP\^, char *\fIstring\fP\^)
.SH PARAMETERS
.TP 1i
\fIdisplay\fP
A pointer to a display structure returned by a successful
.B XOpenDisplay
call.
.TP
\fIresource_id\fP
The resource identifier of the renderer or structure.
.TP
\fIreq_type\fP
The request type for the output command (
.B PEXOCRender,
.B PEXOCStore,
.B PEXOCRenderSingle
or
.B PEXOCStoreSingle
).
.TP
\fIorigin\fP
The origin of the text string.
.TP
\fIoffset\fP
The relative position of the text string from the origin.
.TP
\fIlength\fP
The number of bytes in the text string.
.TP
\fIstring\fP
A pointer to the text string.
.SH RETURNS
None
.SH DESCRIPTION
.\" indexing
.IX PEXAnnotationText
.IX "Annotation Text" PEXAnnotationText
.LP
This function creates an annotation text output primitive.
.LP
The first character set in the text font will be used.
.LP
The
.I origin
defines, in modeling coordinates, the position of the
first character in the text
.I string.
The
.I offset
specifies an offset from the
.I origin
in normalized projection coordinates.  The point where the text
.I string
is placed is called the annotation point.  The annotation point is
computed by adding the value of
.I offset
to the transformed
.I origin
point.  The z-component of the annotation point
specifies the x-y plane in normalized projection coordinate
space on which the annotation text
.I string
is placed.
.LP
Depending on the text attribute
source flag values, the text color, text precision,
character expansion, character spacing, and text font index attributes are
either obtained directly from
the current text attribute values or
from the entry in the text bundle
specified by the current text bundle index attribute.
The annotation text height, annotation text path,
annotation text alignment, annotation text up vector,
and annotation text style are also used to render the text
.I string.
.LP
The annotation text string's color is affected only by the
depth-cueing computation (the reflectance stage of the
rendering pipeline affects only surface primitives) and is mapped to a
device color.  The entire annotation text primitive is clipped
if the
.I origin
is clipped.  If the
.I origin
is not clipped, the
annotation text is clipped according to text clipping rules.
The connection line, if any, is clipped according to
polyline clipping rules, except that modeling clipping is
ignored.  The current set of polyline attributes is used to render the
connection line.
.SH DATA STRUCTURES
.LP
See
.B PEXlib.h.
.sp .5
.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 PEXSetATextHeight (3)
.BR PEXSetATextUpVector (3)
.BR PEXSetATextPath (3)
.BR PEXSetATextAlignment (3)
.BR PEXSetATextStyle (3)
.BR PEXSetTextBundleIndex (3)
.fi