[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPQM3 - Quadrilateral Mesh 3

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.

  • Convexity flag.

    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.

  • Normals.

    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.

  • Colors.

    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.

  • Boundary flags.

    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.

  • 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 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 (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

    mflags -- 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 mdata parameter.

    Value

    Corresponding Field

    0

    Dimensions of vertex array

    2

    Convexity flag is specified.

    4

    Count of vertex morphing vectors is specified.

    8

    Count of data mapping data is specified.

    16

    Count of data morphing vectors is specified.

    mdata -- 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 mflags parameter. The fields must be specified in the order defined below and no space is allowed between those that are present.

    Dimensions of vertex array -- 2 fullword integers (>=0)

    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.

    Convexity flag -- Fullword integer

    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.

    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.

    qflags -- specified by user, fullword integer

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

    Value

    Corresponding Field

    0

    Null, qdata is not referenced.

    1

    Geometric normals.

    2

    Color.

    qwidth -- specified by user, fullword integer (>=0)

    Number of words between subsequent entries of the qdata parameter array. The minimum value for this parameter is dependent on the optional data that is specified.

    qdata -- specified by user, array of per quadrilateral data

    Contains specific information about each quadrilateral in the primitive. The length of this array is (row_dim minus 1) times (col_dim minus 1) where row_dim and col_dim are the vertex array dimensions as defined in mdata The entries of this array are stored in row major order. The presence of optional fields is determined by the value of the qflags 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 this quadrilateral. This field is optional.

    Color -- 3 short floating-point numbers (0.0<=component<=1.0)

    The three components of a color in the current color model as contained in the graPHIGS API state list. 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

    0

    Vertex coordinates are specified.

    1

    Vertex normals are specified.

    2

    Vertex colors are specified.

    4

    Boundary flags are specified.

    8

    Transparency coefficient is specified.

    16

    Vertex morphing vectors are specified.

    32

    Data mapping data is specified.

    64

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

    vxwidth -- specified by user, fullword integer (>=3)

    Number of words between subsequent data entries of the vxdata parameter array The minimum value for this parameter depends on the optional data that is specified.

    vxdata -- specified by user, array of vertex data

    Contains specific information about each vertex in the primitive. The length of the array is row_dim [default] col_dim, where row_dim and col_dim are the dimensions of the vertex array as specified in the mdata parameter. The entries are stored in row major order. 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 quadrilateral at the corresponding vertex. This field is optional.

    Color -- 3 short floating-point numbers (0.0<=component<=1.0)

    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 quadrilateral (1=NOT_AN_EDGE, 2=IS_AN_EDGE ) These flags allow control over which parts of the quadrilateral's boundary are to be treated as edges. 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, 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.

    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 dx1 , dy1 , dz1 , dx2 , dy2 , dz2 , ..., dxn , dyn , dzn . 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 x1 , x2 , x3 , ..., xn 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 d1 1, d1 2, d1 3, ..., d1 n, d2 1, d2 2, d2 3, ..., d2 n, ..., dm1 , dm2 , dm3 , ..., dmn

    The data morphing vectors d11 >, d12 >, d13 >, ..., d1n >, d21 >, d22 >, d23 >, ..., d2n >, ..., dm1 , dm2 , dm3 , ..., dmn 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')


    [ Previous | Next | Contents | Glossary | Home | Search ]