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

GPPLD3 - Polyline Set 3 With Data

GPPLD3 (pflags, pdata, plflags, plwidth, pldata, vxflags, vxwidth, vxdata)

Purpose

Use GPPLD3 to insert a Polyline Set 3 With Data structure element into the open structure following the element pointer or to replace the element pointed at by the element pointer with a Polyline Set 3 With Data structure element depending on the current edit mode.

This structure element defines multiple three-dimensional polylines within one structure element. This is similar to the Disjoint Polyline 2 (GPDPL2) subroutine and the Disjoint Polyline 3 (GPDPL3) subroutine, except in its specification. When encountered during structure traversal, this element generates an unconnected sequence of polylines from the list of points specified.

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

  • Vertex colors.

    When rendering this primitive, if the primitive is not to be highlighted, then the graPHIGS API uses the specified vertex colors. If the current polyline shading method is 1=POLYLINE_SHADING_NONE (default), then the graPHIGS API uses the ith vertex color to color the ith line of the polyline. If the current polyline shading method is 2=POLYLINE_SHADING_COLOR , then the graPHIGS API interpolates the color along each line between the colors specified at the endpoints of the line. If your application does not specify the vertex color data in this primitive definition, then the graPHIGS API uses the current polyline color to render GPPLD3

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

    • 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 vertex colors 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.

    Polyline attributes are applied to this primitive.

    GPPLD3 is identified as GDP 1014.

    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

    0

    Number of polylines.

    4

    Count of vertex 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 Polylines -- fullword integer (>=0)

    Number of specified polylines. 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.

    plflags -- specified by user, fullword integer

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

    Value

    Corresponding Field

    0

    Number of vertices in each polyline. (There is no optional data currently defined. This field must be set to zero)

    plwidth -- specified by user, fullword integer

    Number of words between subsequent entries of the pldata parameter array (>=1)

    pldata -- specified by user, array of per polyline data

    Contains specific information about each polyline in the primitive. The length of this array is defined by the contents of the number of polylines field in the pdata parameter. The presence of optional fields is determined by the value of the plflags 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 each polyline. If the number is less than two, then no lines are generated. This field is required for each polyline.

    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.

    2

    Vertex colors are specified.

    16

    Vertex morphing vectors are specified.

    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 the sum of the number of vertices fields in the pldata 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 each vertex. This field is required.

    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.

    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.

    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
    351
    OPTIONAL DATA AVAILABILITY FLAG IS INVALID
    356
    NUMBER OF POLYLINES < 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

    GPLT
    Set Linetype
    GPLWSC
    Set Linewidth Scale Factor
    GPPLCD
    Set Polyline Color Direct
    GPPLCI
    Set Polyline Color Index
    GPPLET
    Set Polyline End Type
    GPPLI
    Set Polyline Index
    GPPLSM
    Set Polyline Shading Method
    GPTCO
    Set Transparency Coefficient
    GPVMF
    Set Vertex Morphing Factors

    RCP code

    201342211 (X'0C003D03')

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