GPQM3
(mflags,
mdata,
qflags,
qwidth,
qdata,
vxflags,
vxwidth,
vxdata) |

**Purpose**

Use
**GPQM3** to insert a Quadrilateral Mesh 3
structure element into the open structure following the
element pointer, or to replace the element pointed at by the
element pointer with a Quadrilateral Mesh 3 structure
element, depending on the current edit mode.

When encountered during structure traversal, this element
generates an array of
(M minus 1) (N minus 1)
quadrilaterals from a two-dimensional array of
M N vertices.
Each quadrilateral is generated by four neighboring
points in the vertex array, vertices
*v(i, j)*,
v(i + 1, j),
v(i + 1, j + 1),
and
v(i, j + 1), where 1<=
*i*<=
*M* and 1<=
*j*<= *N*
Each quadrilateral is a facet of the primitive.
For more information on quardrilaterals, see
The graPHIGS Programming Interface: Understanding Concepts

Your application can specify optional data to further control the rendering of this primitive.

The convexity flag indicates that the application determined the convexity of the quadrilateral mesh primitive. Therefore, the system rendering code does not have to determine the convexity every time the primitive is rendered.

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

You can specify color for each quadrilateral and/or each vertex. When rendering this primitive, if the primitive is to be highlighted, then the graPHIGS API uses the highlight color instead. The colors are used in the lighting process to produce more realistic effects.

The edges of this primitive consist of line segments
forming the boundary of each quadrilateral in the mesh.
Use boundary flags to identify the boundaries that you want
rendered as edges.
More boundary flags are specified than actually used,
but the graPHIGS API ignores the unused boundary flags.
If there are no boundary flags specified, then all
boundaries are rendered as edges.
If the edge flag is set to `2=ON`
and the 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.

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

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.

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

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: **

Use of any optional data other than the convexity flag, vertex normals, quadrilateral normals, quadrilateral colors, 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 iple graphics processors INCLUDING this particular processor, the Inquire Workstation Description (This note applies ONLY to applications which will be run on the High Performance 3D Color Graphics Processor (8 or 24 bit).GPQWDT) subroutinemust 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 the vertices of a quadrilateral are not coplanar, then the method of rendering the quadrilateral is workstation dependent.

During structure traversal, the graPHIGS API ignores quadrilateral meshes with less than two vertices in either direction, i.e., there is no visual effect.

Polygon attributes are applied to this primitive.

**GPQM3** is identified as GDP 1031.

**Note: **

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

**Parameters**

The dimensions of the vertex array.
The first value (*row_dim*) defines the
number of vertices in a row of the array.
The second value (*col_dim*) defines the
number of vertices in a column of the array.
The number of quadrilaterals generated in each
dimension is one less than its corresponding
vertex array dimension.
This field is required.

This data indicates that your application determined the
convexity of the mesh
(`0=CONCAVE, 1=CONVEX`
)
If any individual quadrilateral is concave, then set the flag to
`0=CONCAVE`
Set the flag to `1=CONVEX`
only if
all the quadrilaterals are convex.
This allows the workstation to optimize processing
of the primitive. This field is optional.

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.

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.

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.

Each vertex *v(i, j)* has two boundary flags which
specify whether the graPHIGS API draws the boundary from the
specified vertex to an adjacent vertex.
The first boundary flag applies to the boundary from
vertex *v(i, j)* to vertex *v(i + 1, j)*
and the second boundary flag applies to the boundary
from vertex *v(i, j)* to vertex
*v(i, j + 1)*, where 1<= *i*<=
*col_dim* and 1<= *j*<= *row_dim*
There are more vertices than boundary flags, but the graPHIGS API
ignores the unused boundary flags.
This field is optional.

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.

The vertex morphing vectors
dx_{1}
, dy_{1}
, dz_{1}
, dx_{2}
, dy_{2}
,
dz_{2}
, ..., 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.

The data mapping data values
x_{1}
, x_{2}
, x_{3}
, ..., 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.

The data morphing vectors
d_{1}
1, d_{1}
2, d_{1}
3, ..., d_{1}
n,
d_{2}
1, d_{2}
2, d_{2}
3, ..., d_{2}
n, ...,
d_{m1}
, d_{m2}
, d_{m3}
, ..., d_{mn}

The data morphing vectors
d_{11}
>, d_{12}
>, d_{13}
>, ..., d_{1n}
>,
d_{21}
>, d_{22}
>, d_{23}
>, ..., 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
**115**- TRANSPARENT COEFFICIENT IS INVALID
**349**- NORMAL VECTOR HAS ZERO LENGTH
**351**- OPTIONAL DATA AVAILABILITY FLAG IS INVALID
**352**- BOUNDARY FLAG IS INVALID
**357**- DIMENSION OF VERTEX ARRAY < ZERO
**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**

201343747 (X'0C004303')