NAME

ANNOTATION TEXT RELATIVE 3 − create structure element specifying 3D annotation text primitive

SYNOPSIS

C Syntax

void
panno_text_rel3 ( ref_pt, anno_offset, text )
Ppoint3∗ref_pt;reference point
Pvec3∗anno_offset;annotation offset
char∗text;annotation text string

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

The ANNOTATION TEXT RELATIVE 3 subroutine puts a structure element containing the full specification of a three-dimensional ANNOTATION TEXT RELATIVE 3 primitive into the currently open structure. 

The ANNOTATION TEXT RELATIVE 3 primitive is a character string.  The location of the string in the display is controlled by the reference point and annotation offset subroutine parameters.  ANNOTATION TEXT RELATIVE 3 primitives differ from TEXT 3 primitives in that the reference point is specified in Modelling Coordinates (MC), and the plane upon which the characters are generated will always be parallel to the display surface and in the Normalized Projection Coordinate (NPC) Space.  Aspects of the text display, such as the font, colour, spacing, height, and alignment, are controlled by the current values of the primitive attributes listed below. 

If the current edit mode is INSERT, the structure element created by the ANNOTATION TEXT RELATIVE 3 subroutine is inserted into the open structure after the element pointed to by the current element pointer. If the current edit mode is REPLACE, the new ANNOTATION TEXT RELATIVE 3 element replaces the element in the structure pointed to by the element pointer.  In either case, the element pointer is updated to point to the new ANNOTATION TEXT RELATIVE 3 element. 

C Input Parameters

ref_ptA pointer to a Ppoint3 structure containing the x, y, and z MC that locate the annotation text.  The Ppoint3 structure is defined in phigs.h as follows:

typedef struct  {
Pfloatx;      /∗ x coordinate ∗/
Pfloaty;      /∗ y coordinate ∗/
Pfloatz;      /∗ z coordinate ∗/
} Ppoint3;

anno_offset
A pointer to a Pvec3 structure containing the x, y, and z coordinates of the offset of the text string from the transformed reference point.  The annotation offset specifies an offset in NPC.  The Pvec3 structure is defined in phigs.h as follows:

typedef struct  {
Pfloatdelta_x;      /∗ x magnitude ∗/
Pfloatdelta_y;      /∗ y magnitude ∗/
Pfloatdelta_z;      /∗ z magnitude ∗/
} Pvec3;

textA pointer to the character string to be written into the display. 

Execution

When the structure is traversed, the ANNOTATION TEXT RELATIVE 3 element draws the specified character string on the plane in the NPC System defined by reference point and the annotation offset.  These parameters define a Text Local Coordinate (TLC) System in the NPC System.  The annotation offset added to the transformed reference point defines the origin of this TLC System.  The x and y axes of the TLC System are parallel to and have the same direction as the x and y axes of the NPC System. 

The precise position of the text is defined in relation to this plane by the current values of the text primitive attributes ANNOTATION TEXT CHARACTER UP VECTOR, ANNOTATION TEXT CHARACTER, BASE VECTOR, ANNOTATION TEXT PATH, and ANNOTATION TEXT ALIGNMENT.  The reference point is subject to the current transformations in the transformation pipeline from the MC System to the workstation display.  The text itself is only subject to the transformations in the transformation pipeline from the NPC System to the workstation display. 

Other aspects of the appearance of the text are controlled by the attributes TEXT FONT, TEXT PRECISION, ANNOTATION STYLE, ANNOTATION TEXT CHARACTER HEIGHT, ANNOTATION TEXT CHARACTER WIDTH, CHARACTER EXPANSION FACTOR, CHARACTER SPACING, and TEXT COLOUR INDEX. 

ANNOTATION TEXT CHARACTER WIDTH and ANNOTATION TEXT BASE VECTOR are implicit attributes derived from ANNOTATION TEXT CHARACTER HEIGHT and ANNOTATION TEXT UP VECTOR, respectively. 

Attributes Applied

The attributes listed below are used to display the ANNOTATION TEXT RELATIVE 3 primitive when the structure is traversed.  The Aspect Source Flags (ASFs) tell where to access the output display attributes.  These attributes can come directly from the traversal state list, or they can be accessed indirectly, using the appropriate index in the traversal state list and the corresponding bundled representation in the PHIGS workstation state list. 

text fonttext font ASF
text precisiontext precision ASF
character expansion factorcharacter expansion factor ASF
character spacingcharacter spacing ASF
text colourtext colour index ASF
annotation character height
annotation character up vector
annotation text path
annotation text alignment
annotation style
text index
depth cue index
name set

ERRORS

005Ignoring function, function requires state (PHOP, ∗, STOP, ∗)

SEE ALSO

TEXT 3 (3P)

September 02, 1992