ANNOTATION TEXT RELATIVE(3P) — SUNPHIGS LIBRARY

NAME

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

SYNOPSIS

C Syntax

void
pannotationtextrelative ( ref_pt, anno_offset, text )
Ppoint∗ref_pt;reference point
Ppoint∗anno_offset;annotation offset
Pchar∗text;annotation text string

FORTRAN Syntax

SUBROUTINE patr ( RPX, RPY, APX, APY, CHARS )
REALRPX, RPYreference point (MC)
REALAPX, APYannotation offset (NPC)
CHARACTER∗(∗)CHARS string of characters

FORTRAN Subset Syntax

SUBROUTINE patrs ( RPX, RPY, APX, APY, LSTR, CHARS )
REALRPX, RPYreference point (MC)
REALAPX, APYannotation offset (NPC)
INTEGERLSTRlength of string (in characters)
CHARACTER∗80CHARS string of characters

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

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

The ANNOTATION TEXT RELATIVE 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 primitives differ from TEXT primitives in that the reference point is specified in Modelling Coordinates (MC). The z coordinate is assumed to be 0. The characters are generated 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 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 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 element.

C Input Parameters

ref_ptA pointer to a Ppoint structure containing the x and y MC that locate the annotation text.

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

typedef struct {
Pfloat x; /∗ x coordinate ∗/
Pfloat y; /∗ y coordinate ∗/
} Ppoint;

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

FORTRAN Input Parameters

RPXThe x MC of the point locating the annotation text.

RPYThe y MC of the point locating the annotation text.

APXThe x offset in NPC locating the text string relative to RPX.

APYThe y offset in NPC locating the text string relative to RPY.

CHARS
A character array containing the string to be written into the display.

It is best to use substrings or constants and to use only the portion desired. Avoid use of the blank-padded portion. An example of a substring is LABEL(1:8), where label might be declared as CHARACTER∗256. An example of a character constant is abcdefg. Another way to achieve the same result is to null terminate the string, i.e., hello\0. Strings returned from SunPHIGS inquiry functions, however, will not be null terminated, even though they may have been specified that way.

Execution

When the structure is traversed, the ANNOTATION TEXT RELATIVE element draws the specified character string on the plane in the NPC System defined by the 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 TEXTCHARACTER 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 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 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, ∗)

Museum