TEXT 3(3P) — SUNPHIGS LIBRARY

NAME

TEXT 3 − create structure element specifying 3D text primitive

SYNOPSIS

C Syntax

void
ptext3 ( text_pt, dir, text )
Ppoint3∗text_pt;text point
Pvector3dir[2];direction vectors
Pchar∗text;text string

FORTRAN Syntax

SUBROUTINE ptx3 ( PX, PY, PZ, TDX, TDY, TDZ, CHARS )
REALPX, PY, PZtext point (MC)
REALTDX(2), TDY(2), TDZ(2) text direction vectors (MC)
CHARACTER∗(∗)CHARS string of characters

FORTRAN Subset Syntax

SUBROUTINE ptx3s ( PX, PY, PZ, TDX, TDY, TDZ, LSTR, CHARS )
REALPX, PY, PZtext point (MC)
REALTDX(2), TDY(2), TDZ(2) text direction vectors (MC)
INTEGERLSTRlength of string (in characters)
CHARACTER∗80CHARS string of characters

Required PHIGS Operating States

(PHOP, ∗, STOP, ∗)

DESCRIPTION

Purpose

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

The TEXT 3 primitive is a character string. The location and orientation of the string in the display is controlled by the text point and direction vectors subroutine parameters, specified in Modelling Coordinates. Other 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 TEXT 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 TEXT 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 TEXT 3 element.

C Input Parameters

text_pt
A pointer to a Ppoint3 structure which specifies the x, y, and z coordinates that locate the text string. The Ppoint3 structure is defined in phigs.h as follows:

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

dirAn array of two Pvector3 structures containing direction vectors. The Pvector3 structure is defined in phigs.h as follows:

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

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

FORTRAN Input Parameters

PXThe x coordinate of the point locating the text string.

PYThe y coordinate of the point locating the text string.

PZThe z coordinate of the point locating the text string.

TDXAn array giving the x coordinates of two text direction vectors.

TDYAn array giving the y coordinates of two text direction vectors.

TDZAn array giving the z coordinates of two text direction vectors.

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

It is best to use substrings or constants, to use only the portion desired and 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 TEXT 3 element draws the specified character string on the plane in the Modelling Coordinate System defined by text point and the two direction vectors. These parameters define a Text Local Coordinate System in the Modelling Coordinate System. The text point parameter defines the origin of this Text Local Coordinate System, the first direction vector defines the positive x-axis, and the second direction vector defines the positive y-axis. Only the directions, not the lengths, of these vectors are relevant.

The precise position of the text is defined in relation to this plane by the current values of the text primitive attributes CHARACTER UP VECTOR, TEXT PATH, and TEXT ALIGNMENT. The text primitive is subject to the current transformations in the transformation pipeline from the Modelling Coordinate System to the workstation display.

Other aspects of the appearance of the text are controlled by the attributes TEXT FONT, TEXT PRECISION, CHARACTER HEIGHT, CHARACTER WIDTH, CHARACTER EXPANSION FACTOR, CHARACTER SPACING, TEXT COLOUR INDEX and CHARACTER SETS. The CHARACTER SETS attribute is controlled by the “set character sets” GENERALIZED STRUCTURE ELEMENT.

Attributes Applied

The attributes listed below are used to display the TEXT 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 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
character height
character up vector
text path
text alignment
text index
depth cue index
name set

ERRORS

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

Museum