graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPTS3 - Triangle Strip 3

GPTS3 (pflags, pdata, tflags, twidth, tdata, vxflags, vxwidth, vxdata)

Purpose

Use GPTS3 to insert a Triangle Strip 3 structure element into the open structure following the element pointer or to replace the element pointed at by the element pointer with a Triangle Strip 3 structure element depending on the current edit mode.

When encountered during structure traversal, this element generates n - 2 triangles from n vertices. Each triangle is generated by vertices k, k + 1, k + 2 Your application can specify optional data to further control the rendering of this primitive. The optional data consists of:

Normals.

You can specify a geometric normal for each triangle and/or a normal for each vertex. The normals are used in the lighting process to produce more realistic effects.

Vertex colors.

You can specify color for each vertex. If the current color source attribute indicates using the color defined in the primitive, and the primitive is not to be highlighted, then the graPHIGS API uses the specified color. The colors are used in the lighting process to produce more realistic effects.

Boundary flags.

The edges of this primitive consist of the line segments forming the boundary of each triangle in the strip. You may specify boundary flags to identify the boundaries that are to be rendered as edges. (More boundary flags are specified than are actually used; the unused boundary flags are ignored.) Whether the edges between triangles are drawn once or twice is workstation dependent.

Transparency coefficients.

You can specify a transparency coefficient per vertex. The graPHIGS API uses these values when producing transparency effects for the rendered primitive.

Vertex morphing vectors.

You can supply vertex morphing vectors per vertex. The graPHIGS API combines these vectors with the vertices and vertex morphing scale factors (GPVMF) to create new vertex coordinate values for the rendered primitive.

Data mapping data.

You can specify data mapping data per vertex. The graPHIGS API uses these values to determine the colors of the rendered primitive.

Data morphing vectors.

You can specify data morphing vectors per vertex. The graPHIGS API combines these vectors with the data morphing scale factors (GPDMF) and (GPBDMF) and the vertex data mapping values to create new data mapping data values for the rendered primitive.

See The graPHIGS Programming Interface: Understanding Concepts for a more complete explanation of how the graPHIGS API uses the various optional data values.

Note:

This note applies ONLY to applications which will be run on the High Performance 3D Color Graphics Processor (8 or 24 bit). Use of any optional data other than the vertex normals, triangle normals, vertex colors, and boundary flags may cause unpredictable results (including locking the display) on this graphics processor. If only the High Performance 3D Color Graphics Processor is used, you should include only the supported optional data values. If your application must support multiple graphics processors INCLUDING this particular processor, the Inquire Workstation Description (GPQWDT) subroutine must be used to determine the functions that each workstation supports. See also the workstation description in The graPHIGS Programming Interface: Technical Reference for the High Performance 3D Color Graphics Processor.

When rendering this primitive, if the current edge flag attribute is set to 2=ON and the current line type is not set to 1=SOLID_LINE , then the results are unpredictable due to the potential double drawing of some edges on some workstations.

The graPHIGS API ignores triangle strips with less than three vertices.

Polygon attributes are applied to this primitive.

GPTS3 is identified as GDP 1029.

Note:

Not all GDPs are supported on all workstations. Use the Inquire List of Generalized Drawing Primitives (GPQGD) subroutine to determine the GDPs supported by an opened workstation. See also the workstation description in The graPHIGS Programming Interface: Technical Reference

Parameters

pflags -- specified by user, fullword integer

Shows what optional data is specified for the primitive. The value specified should be the sum of the following values based on the fields that are included in the pdata parameter.

Value

Corresponding Field

Number of vertices

Count of vertex morphing vectors is specified.

Count of data mapping data is specified.

Count of data morphing vectors is specified.

pdata -- specified by user, array of primitive data

Contains specific information about the entire primitive. The presence of optional fields is determined by the value of the pflags parameter. The fields must be specified in the order defined below and no space is allowed between those that are present.

Number of Vertices -- fullword integer (>=0)

Number of vertices in the triangle strip. This field is required.

Vertex Morphing Vector Count -- fullword integer (>=0)

The number of vertex morphing vectors specified at each vertex. The number of fullwords of vertex morphing vector data added to the other fullwords of vertex data specified per vertex cannot exceed 255 fullwords. This field is optional.

Data Mapping Data Count -- fullword integer (>=0)

The number of data mapping values specified at each vertex. The number of data mapping values added to the other fullwords of vertex data specified per vertex cannot exceed 255 fullwords. This field is optional.

Data Morphing Vector Count -- fullword integer (>=0)

The number of data morphing vectors specified at each vertex. The number of fullwords of data morphing vector data added to the other fullwords of vertex data specified per vertex cannot exceed 255 fullwords. This field is optional.

tflags -- specified by user, fullword integer

Shows what optional data is specified for each triangle. The value specified should be the sum of the following values based on the fields that are included in the tdata parameter.

Value

Corresponding Field

Null, tdata is not referenced.

Geometric Normals.

twidth -- specified by user, fullword integer

Number of words between subsequent entries of the tdata parameter array (>=0)

tdata -- specified by user, array of per triangle data

Contains specific information about each triangle in the primitive. The length of this array is defined by the contents of the number of vertices -2. The presence of optional fields is determined by the value of the tflags parameter. The fields must be specified in the order defined below and no space is allowed between those that are present.

Geometric Normal -- 3 short floating-point numbers (MC)

Geometric normal to be used in processing the triangle. This field is optional.

vxflags -- specified by user, fullword integer

Shows what optional data is specified for each vertex. The value specified should be the sum of the following values based on the fields that are specified in the vxdata parameter.

Value

Meaning

Vertex coordinates are specified.

Vertex normals are specified.

Vertex colors are specified.

Boundary flags are specified.

Transparency coefficient is specified.

Vertex morphing vectors are specified.

Data mapping data is specified.

Data morphing vectors are specified (valid only if date mapping data is specified also).

vxwidth -- specified by user, fullword integer

Number of words between subsequent entries of the vxdata parameter array (>=3)

vxdata -- specified by user, array of vertex data

Contains specific information about each vertex in the primitive. The length of this array is equal to number of vertices field in the pdata parameter. The presence of optional fields is determined by the value of the vxflags parameter. The fields must be specified in the order defined below and no space is allowed between those that are present.

Coordinates -- 3 short floating-point numbers (MC)

x, y, and z coordinates of a vertex. This field is required.

Normal -- 3 short floating-point numbers (MC)

The three components of a vector that is to be used as the normal of the polygon at the corresponding vertex. This field is optional.

Color -- 3 short floating-point numbers

The three components of a color in the current color model as contained in the graPHIGS API state list. This field is optional.

Boundary Flags -- 2 fullword integers

Specifies whether the corresponding boundary is to be treated as an edge of the polygon (1=NOT_AN_EDGE, 2=IS_AN_EDGE ) The edge attributes are only applied to boundary segments that have a boundary flag set to a value of 2=IS_AN_EDGE

Each vertex v(i) has two boundary flags which specify whether the boundary from the specified vertex to an adjacent vertex is to be drawn as an edge. The first boundary flag applies to the boundary from vertex v(i) to vertex v(i+1) and the second boundary flag applies to the boundary from vertex v(i) to vertex v(i+2), where 1<=i<=number_of_vertices As there are more boundary flags than edges, unused boundary flags are ignored. This field is optional.

Transparency Coefficient -- short floating-point number (0.0 <= transparency coefficient <=1.0)

The transparency coefficient value used when performing transparency processing. A value of 0.0 is fully opaque; a value of 1.0 is fully transparent. This field is optional.

Vertex Morphing Vectors -- array of short floating-point numbers.

The vertex morphing vectors dx₁ , dy₁ , dz₁ , dx₂ , dy₂ , dz₂ , ..., dx_n , dy_n , dz_n . The number, n, of vectors in this array is specified in the pdata parameter as the vertex morphing vector count. The array must be the same length for every vertex. This field is optional.

Data Mapping Data -- array of short floating-point numbers.

The data mapping data values x₁ , x₂ , x₃ , ..., x_n The number, n, of values in this array is specified in the pdata parameter as the data mapping data count. The array must be the same length for every vertex. This field is optional.

Data Morphing Vectors -- array of short floating-point numbers.

The data morphing vectors d₁₁ >, d₁₂ >, d₁₃ >, ..., d_1n >, d₂₁ >, d₂₂ >, d₂₃ >, ..., d_2n >, ..., d_m1 , d_m2 , d_m3 , ..., d_mn The number, n, is specified in the pdata parameter as the data mapping data count, and the number, m is specified in the pdata parameter as the data morphing vector count. The array must be the same length for every vertex. This field is optional.

Error Codes

5: FUNCTION REQUIRES STATE STOP OR NROP (NOT STCL)
96: COLOR PARAMETER OUT OF RANGE FOR CURRENT COLOR MODEL
100: NUMBER OF POINTS < ZERO
115: TRANSPARENT COEFFICIENT IS INVALID
349: NORMAL VECTOR HAS ZERO LENGTH
351: OPTIONAL DATA AVAILABILITY FLAG IS INVALID
352: BOUNDARY FLAG IS INVALID
509: DATA LENGTH VALUE < ZERO OR REQUIRED LENGTH
557: WIDTH PARAMETER < MINIMUM ALLOWED
636: FULLWORDS OF VERTEX DATA EXCEEDS MAXIMUM OF 255

Related Subroutines

GPBDMF: Set Back Data Morphing Factors
GPBDMI: Set Back Data Mapping Index
GPBICD: Set Back Interior Color Direct
GPBICI: Set Back Interior Color Index
GPBISM: Set Back Interior Shading Method
GPBSCD: Set Back Specular Color Direct
GPBSCI: Set Back Specular Color Index
GPBSPR: Set Back Surface Properties
GPBTCO: Set Back Transparency Coefficient
GPDMF: Set Data Morphing Factors
GPDMI: Set Data Mapping Index
GPECD: Set Edge Color Direct
GPECI: Set Edge Color Index
GPEI: Set Edge Index
GPELT: Set Edge Linetype
GPESC: Set Edge Scale Factor
GPFDMO: Set Face Distinguish Mode
GPICD: Set Interior Color Direct
GPICI: Set Interior Color Index
GPII: Set Interior Index
GPIS: Set Interior Style
GPISI: Set Interior Style Index
GPISM: Set Interior Shading Method
GPPGC: Set Polygon Culling
GPSCD: Set Specular Color Direct
GPSCI: Set Specular Color Index
GPSPR: Set Surface Properties
GPTCO: Set Transparency Coefficient
GPVMF: Set Vertex Morphing Factors

RCP code

201343745 (X'0C004301')