IDLgrPolyline objects have the following properties in addition to properties inherited from any superclasses. Properties with the word “Yes” in the “Get” column of the property table can be retrieved via IDLgrPolyline::GetProperty. Properties with the word “Yes” in the “Init” column of the property table can be set via IDLgrPolyline::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLgrPolyline::SetProperty.

Note: For a discussion of the property description tables shown below, see Modifying Object Property Descriptions.

Objects of this class have the following properties.

ALL

ALPHA_CHANNEL

ANTIALIAS

 

CLIP_PLANES

COLOR

DATA

DEPTH_TEST_DISABLE

DEPTH_TEST_FUNCTION

DEPTH_WRITE_DISABLE

DOUBLE

HIDE

LABEL_NOGAPS

LABEL_OBJECTS

LABEL_OFFSETS

LABEL_POLYLINES

LABEL_USE_VERTEX_COLOR

LINESTYLE

PALETTE

PARENT

POLYLINES

REGISTER_PROPERTIES

RESET_DATA

SHADER

SHADING

SHARE_DATA

SYMBOL

THICK

USE_LABEL_COLOR

USE_LABEL_ORIENTATION

USE_TEXT_ALIGNMENTS

VERT_COLORS

XCOORD_CONV

XRANGE

YCOORD_CONV

YRANGE

ZCOORD_CONV

 

In addition, objects of this class inherit:

ALL

An anonymous structure containing the values of all of the properties associated with the state of this object. State information about the object includes things like color, range, tick direction, etc., but not image, vertex, or connectivity data, or user values.

Note: The fields of this structure may change in subsequent releases of IDL.

Property Type

Structure

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

ALPHA_CHANNEL

A floating-point value in the range [0.0, 1.0] to specify the opacity of the polyline. The default value of 1.0 causes IDL to draw the line completely opaque. If the value of this property is less than 1.0, then the pixels of the polyline are blended with the pixels already on the screen, where the color of the polyline is multiplied by the alpha value and the pixels already on the screen are multiplied by 1.0-alpha.

Because an object can only be blended with objects already drawn on the screen, the drawing order of the objects must be considered carefully in order to obtain the desired results. Note that since a single polyline object may contain many polylines, or because a line may draw in back or in front of itself, the ordering of the polylines within the object (POLYLINES property) must be considered as well.

This property has no effect on devices using indexed color mode.

If 3-channel (RGB) VERT_COLORS are supplied, then the value of this property is used for the alpha at each vertex to draw the line. If 4-channel (RGBA) VERT_COLORS are supplied, then the alpha from each vertex color is used for the alpha at each vertex to draw the line.

When a polyline is drawn with symbols, the symbol’s color and alpha values are always used to draw the symbols unless VERT_COLORS are supplied. If the VERT_COLORS are RGB, then the alpha value of the symbol is used to draw the symbol. If the VERT_COLORS are RGBA, then the alpha from the vertex color is used to draw the symbol.

When used with labels, the value of this property is used as the alpha channel value for a label if its corresponding value in the USE_LABEL_COLOR property is zero and the value of LABEL_USE_VERTEX_COLOR is zero.

If a label’s corresponding value in the USE_LABEL_COLOR property is zero and the LABEL_USE_VERTEX_COLOR property is non-zero, then the label is drawn with the alpha value from its corresponding vertex color, if the alpha values are included in the vertex colors. If the vertex colors do not include alpha values, the value of this property is used as the alpha value for the label.

If a label’s corresponding value in the USE_LABEL_COLOR property is non-zero, then the value of the label object’s ALPHA_CHANNEL property is used to draw the label. In other words, USE_LABEL_COLOR also implies using the label object’s alpha as well as its color.

Property Type

Float-point value

Name String

Transparency

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

ANTIALIAS

A Boolean value that indicates whether anti-aliasing should be used when drawing the lines. The default is 0, which disables anti-aliasing.

Property Type

BOOLEAN

Name String

Anti-aliasing

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

CLIP_PLANES

A 4-by-N floating-point array of dimensions that specifies the coefficients of the clipping planes to be applied to this object. The four coefficients for each clipping plane are of the form [A, B, C, D], where Ax + By + Cz + D = 0. Portions of this object that fall in the half space Ax + By + Cz + D > 0 will be clipped. By default, the value of this property is a scalar (-1) indicating that no clipping planes are to be applied.

Note: The clipping planes specified via this property are applied in addition to the near and far clipping planes associated with the IDLgrView in which this object appears.

Note: Clipping planes are applied in the data space of this object (prior to the application of any x, y, or z coordinate conversion).

Note: To determine the maximum number of clipping planes supported by the device, use the MAX_NUM_CLIP_PLANES property of the GetDeviceInfo method for the IDLgrBuffer, IDLgrClipboard, IDLgrWindow, and IDLgrVRML objects.

Property Type

Floating-point array

Name String

 

Get: Yes

Set: Yes

Init: Yes

Registered: No

COLOR

A color index or a three-element vector [red, green, blue] specifying the color used to draw polylines. The default color is [0, 0, 0] (black). This property is ignored if the VERT_COLORS property is provided.

In a property sheet, this property appears as a color property.

Property Type

COLOR

Name String

Color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

DATA

A 2-by-n or a 3-by-n floating-point array which defines, respectively, the 2-D or 3‑D vertex data. This property is converted to double-precision floating-point values if the DOUBLE property is set. Otherwise, it is converted to single-precision floating-point.

Specifying this property is the same as specifying the optional X, Y, and Z arguments to the IDLgrPolyline::Init method.

Property Type

Floating-point array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DEPTH_TEST_DISABLE

An integer value that determines whether depth testing is disabled.

  • Set this property to 0 (the default) to inherit the value set by the parent model or view. The parent view always enables depth testing. A model may also enable or disable depth testing.
  • Set this property to 1 to explicitly disable depth buffer testing while drawing this object.
  • Set this property to 2 to explicitly enable depth testing for this object.

Disabling depth testing allows an object to draw itself “on top” of other objects already on the screen, even if the object is located behind them.

Note: Disabling depth testing also disables depth buffer writing. When disabling depth testing, the DEPTH_TEST_FUNCTION and DEPTH_WRITE_DISABLE properties are effectively ignored.

This property is registered as an enumerated list, but it is hidden by default.

Property Type

ENUMLIST

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DEPTH_TEST_FUNCTION

An integer value that determines the depth test function. Set this property to 0 (the default) to inherit the value set by the parent model or view. The parent view always sets a depth test function of LESS. A model may also set a depth test function value. The graphics device compares the object’s depth at a particular pixel location with the depth stored in the depth buffer at that same pixel location. If the comparison test passes, the object’s pixel is drawn at that location on the screen and the depth buffer is updated (if depth writing is enabled).

Set this property to any of the following values to use the desired function while rendering this object.

  • 0 = INHERIT - use value from parent model or view.
  • 1 = NEVER - never passes.
  • 2 = LESS - passes if the object’s depth is less than the depth buffer’s value.
  • 3 = EQUAL - passes if the object’s depth is equal to the depth buffer’s value.
  • 4 = LESS OR EQUAL - passes if the object’s depth is less than or equal to the depth buffer’s value.
  • 5 = GREATER - passes if the object’s depth is greater than or equal to the depth buffer’s value.
  • 6 = NOT EQUAL - passes if the object’s depth is not equal to the depth buffer’s value.
  • 7 = GREATER OR EQUAL - passes if the object’s depth is greater than or equal to the depth buffer’s value.
  • 8 = ALWAYS - always passes

Less means closer to the viewer.

This property is registered as an enumerated list, but it is hidden by default.

Property Type

ENUMLIST

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DEPTH_WRITE_DISABLE

An integer value that determines whether depth writing is disabled.

  • Set this property to 0 (the default) to inherit the value set by the parent model or view. The parent view always enables depth writing. A model may also enable or disable depth writing.
  • Set this property to 1 to explicitly disable depth buffer writing while rendering this object.
  • Set this property to 2 to explicitly enable depth writing for this object.

Disabling depth writing allows an object to be overdrawn by other objects, even if the object is located in front of them.

Note: If depth testing (see DEPTH_TEST_DISABLE property) is disabled, depth writing is also automatically disabled.

This property is registered as an enumerated list, but it is hidden by default.

Property Type

ENUMLIST

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

DOUBLE

A Boolean value that indicates whether data provided by any of the input arguments will be stored in this object as using double-precision floating-point format.

  • Set this property equal to 1 to convert input data to double-precision floating-point format.
  • Set this property equal to 0 to convert input data to single-precision floating-point format.
  • If you do not specify a value for this property, no data type conversion will be performed, and the data will be stored with its original precision.

Setting this property may be desirable if the data consists of large integers that cannot be accurately represented in single-precision floating-point arithmetic. This property is also automatically set to 1 if any of the input arguments are stored using a variable of type DOUBLE.

Property Type

Boolean

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

HIDE

A Boolean value or enumerated list item indicating whether this object should be drawn:

Value

Property Sheet Value

Description

0

True

Draw graphic (the default)

1

False

Do not draw graphic

 

Property Type

ENUMLIST

Name String

Show

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

LABEL_NOGAPS

An integer vector of values indicating whether gaps should be computed for the corresponding label. A zero value indicates that a gap will be computed for the labels; a non-zero value indicates that no gap will be computed for the label. If the number of labels exceeds the number of elements in this vector, the LABEL_NOGAPS values will be repeated cyclically. By default, gaps are computed for all labels (so that the polyline does not pass through the label).

Property Type

Integer vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

LABEL_OBJECTS

An object reference (or vector of object references) to specify the labels to be drawn along the polyline path(s). The objects specified via this property must inherit from one of the following classes:

  • IDLgrSymbol
  • IDLgrText

If a single object is provided, and it is an IDLgrText object, each of its strings will correspond to a label. If a vector of objects is used, any IDLgrText objects should have only a single string; each object will correspond to a label.

If one or more IDLgrText objects are provided, the LOCATION property of the provided text object(s) may be overwritten; position is determined according to the values provided via the LABEL_OFFSETS property. The labels will have the same color as the corresponding polyline (see the COLOR property) unless the USE_LABEL_COLOR property is specified. The orientation of the label objects USE_LABEL_ORIENTATION property is specified. The horizontal and vertical alignment for any text labels will each default to 0.5 (i.e., centered) unless the USE_TEXT_ALIGNMENTS property is specified.

Note: The objects provided via this property will not be destroyed automatically when this IDLgrPolyline is destroyed.

Property Type

Object reference

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

LABEL_OFFSETS

A scalar or vector of floating-point offsets, [t0, t1, …], that indicate the parametric offsets along the length of each polyline (specified via the LABEL_POLYLINES property) at which each label (as specified via the LABEL_OBJECTS property) would be positioned. If LABEL_OFFSETS is set to a scalar less than zero, then the offsets will be automatically computed to be evenly distributed along the length of the polyline. If a scalar value greater than or equal to zero is provided, it is used for all labels. If a vector is provided, the number of offsets must match the number of labels provided via LABEL_OBJECTS. By default, this property is set to the scalar, -1, indicating that the label offsets will be automatically computed.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

LABEL_POLYLINES

An integer or integer vector of polyline indices, [P0, P1, …], that indicate which polylines are to be labeled. Pi corresponds to the ith polyline specified via the POLYLINES property. This property is intended to be used in conjunction with the LABEL_OBJECTS property. If a scalar is provided, all labels will be drawn along the single indicated polyline. If a vector is provided, the number of polyline indices must match the number of labels provided via LABEL_OBJECTS.

By default, this property is set to the scalar, 0, indicating that only the first polyline will be labeled.

Note: If a given polyline has more than one label, then the corresponding polyline index may appear more than once in the LABEL_POLYLINES vector.

Property Type

Integer or integer vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

LABEL_USE_VERTEX_COLOR

An integer value that indicates whether labels should be colored according to the vertex coloring (if the VERT_COLORS property is set).

  • A non-zero value = labels should be colored according to the vertex coloring
  • Zero (the default) = the label will be drawn using the color specified via the COLOR property of the polyline object (unless the USE_LABEL_COLOR property is set).

Property Type

Integer

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

LINESTYLE

An integer or array value that indicates the line style to be used to draw the polyline. The value can be either an integer value specifying a pre-defined line style, or a two-element vector specifying a stippling pattern.

To use a pre-defined line style, set this property equal to one of the following integer values:

0

Solid line (the default)

1

Dotted

2

Dashed

3

Dash dot

4

Dash dot dot dot

5

Long dash

6

No line drawn

To define your own stippling pattern, specify a two-element vector [repeat, bitmask], where repeat indicates the number of times consecutive runs of 1’s or 0’s in the bitmask should be repeated. (That is, if three consecutive 0’s appear in the bitmask and the value of repeat is 2, then the line that is drawn will have six consecutive bits turned off.) The value of repeat must be in the range 1 ≤ repeat ≤ 255.

The bitmask indicates which pixels are drawn and which are not along the length of the line. Bitmask is most conveniently specified as a 16-bit hexadecimal value.

For example, LINESTYLE = [2, 'F0F0'X] describes a dashed line (8 bits on, 8 bits off, 8 bits on, 8 bits off).

In a property sheet, this property appears as follows:

Property Type

Linestyle

Name String

Line style

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

PALETTE

An object reference to a palette object (an instance of the IDLgrPalette object class) that defines the color palette of this object. This property is only used if the destination device is using the RGB color model. If so, and a color value for the object is specified as a color index value, the palette set by this property is used to translate the color to RGB space. If the PALETTE property on this object is not set, the destination object PALETTE property is used (which defaults to a grayscale ramp).

Note: Objects specified via this property are not automatically cleaned up when the IDLgrPolyline object is destroyed.

This property is registered as a user-defined property, but it is hidden by default.

Property Type

USERDEF

Name String

Color palette

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

PARENT

An object reference to the object that contains this object.

Property Type

Object reference

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

POLYLINES

An integer array of one or more polyline descriptions. IDL converts and stores this array as 32-bit signed integers. Set this property to a scalar to remove a polyline description array from the object, returning it to its initial empty state. When this property does not contain an array of polyline descriptions, IDL draws a single polyline using the vertices in the order they appear in the vertex list (see the DATA property).

A polyline description is an integer or long word array of the form: [n, i0, i1, ..., in-1], where n is the number of vertices that define the polyline, and i0..in-1 are indices into the X, Y, and Z arguments that represent the vertices of the polyline(s). To ignore an entry in the POLYLINES array, set the vertex count, n, and all associated indices to 0. To end the drawing list, even if additional array space is available, set n to -1. If this property is not specified, a single connected polyline will be generated from the X, Y, and Z arguments.

Note: Setting the POLYLINES property to a scalar value will reset the property to its initial, undefined state.

Note: The connectivity array described by POLYLINES allows an individual object to contain more than one polyline. Vertex, normal and color information can be shared by the multiple polylines. Consequently, the polyline object can represent an entire mesh and compute reasonable normal estimates in most cases.

Property Type

Integer array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

REGISTER_PROPERTIES

A Boolean value that determines whether to register properties available for this object. If this property is set, all properties marked in this properties section as “Registered: Yes” will be registered for display in a property sheet. This property is useful mainly when creating iTools. By default, no properties are registered.

Property Type

Boolean

Name String

not displayed

Get: No

Set: No

Init: Yes

Registered: No

RESET_DATA

A Boolean value that determines whether to treat the data provided via one of the DATA property as a new data set unique to this object, rather than overwriting data that is shared by other objects. There is no reason to use this property if the object on which the property is being set does not currently share data with another object (that is, if the SHARE_DATA property is not in use). This property has no effect if no new data is provided via the DATA property.

Property Type

Boolean

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

SHADER

An object reference to an IDLgrShader object (or an object containing IDLgrShader as a superclass). When there is suitable graphics card hardware support, the polyline is rendered using the GLSL shader program (executed on the graphics card) instead of using fixed OpenGL properties when initially drawn. (If a suitable graphics card is not present, IDL ignores the shader object when the scene is drawn.) A single IDLgrShader object may be associated with additional polyline objects or other graphic objects that have the SHADER property.

Property Type

Object reference

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

SHADING

An integer value or enumerated list item representing the type of shading to use:

Value

Property Sheet Value

Description

0

Flat

The color of the second vertex in a line segment is used to define the color for the entire line segment. The color has a constant intensity based upon the normal vector (the default).

1

Gouraud

The colors along each line are interpolated between vertex colors

 

Property Type

ENUMLIST

Name String

Shading

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

SHARE_DATA

An object reference to an object whose data is to be shared by this polyline. A polyline may only share data with a polygon object or another polyline. The SHARE_DATA property is intended for use when data values are not set via an argument to the object’s Init method or by setting the object’s DATA property.

Note: Objects specified via this property are not automatically cleaned up when the IDLgrPolyline object is destroyed.

Property Type

Object reference

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

SYMBOL

An object reference vector containing one or more instances of the IDLgrSymbol object class to indicate the plotting symbols to be used at each vertex of the polyline. If there are more vertices than elements in SYMBOL, the elements of the SYMBOL vector are cyclically repeated. By default, no symbols are drawn. To remove symbols from a polyline, set SYMBOL to a scalar.

Note: Objects specified via this property are not automatically cleaned up when the IDLgrPolyline object is destroyed.

Property Type

Object reference vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

THICK

A floating-point value between 0.0 and 10.0, specifying the line thickness to be used to draw the polyline, in points. A thickness of 0 displays a thin hairline on the chosen device. Out-of-range values are quietly clamped to the allowed range. The default is 1.0 points.

In a property sheet, this property appears as follows:

Property Type

Thickness

Name String

Thickness

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

USE_LABEL_COLOR

An integer vector of values to indicate whether the COLOR property value for the corresponding label object is to be used to draw that label. If the number of labels exceeds the number of elements in this vector, the USE_LABEL_COLOR values will be repeated cyclically. By default, this value is zero, indicating that the COLOR property of each label object will be ignored, and the COLOR property for the polyline object will be used instead.

Property Type

Integer vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

USE_LABEL_ORIENTATION

An integer vector of values to indicate whether the orientation of the corresponding label object is to be used to draw that label. For IDLgrText objects, this refers to the BASELINE and UPDIR property values. For IDLgrSymbol objects, this refers to the default (un-rotated) orientation of the symbol. If the number of labels exceeds the number of elements in this vector, the USE_LABEL_ORIENTATION values will be repeated cyclically. By default, USE_LABEL_ORIENTATION is zero, indicating that the orientation will be automatically computed so that the baseline is parallel to the polyline, and the updir is perpendicular to the polyline.

Property Type

Integer vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

USE_TEXT_ALIGNMENTS

A Boolean value that indicates whether, for any IDLgrText labels (as specified via the LABEL_OBJECTS property), the ALIGNMENT and VERTICAL_ALIGNMENT property values for the given IDLgrText object(s) are to be used to draw those labels. By default, this value is zero, indicating that the ALIGNMENT and VERTICAL_ALIGNMENT properties of the IDLgrText object(s) will be overwritten with default values (0.5 for each, indicating centered labels).

Property Type

Boolean

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

VERT_COLORS

A vector of colors to be used to specify the color of the line segment between each vertex. The vector may be of the form [n] where each entry is a color index, or of the form [3,n] where each 3-element row is an RGB color, or of the form [4,n] where each 4-element row is an RGBA color. To remove vertex colors after they have been set, set VERT_COLORS to a scalar.

If VERT_COLORS is not specified, the entire polyline is drawn in the single color provided by the COLOR property, which is the default action.

If SHADING is set to 0 (Flat, the default) the color of a line segment is the color of the second vertex of that line segment. Color is interpolated between vertices if SHADING is set to 1 (Gouraud).

If there are more vertices than elements in VERT_COLORS, the elements of VERT_COLORS are cyclically repeated.

When VERT_COLORS is used with symbols, the vertex colors and vertex alpha override any colors and alpha specified by the symbol object or any colors and alpha specified by graphic atoms contained in a user-defined symbol.

When VERT_COLORS is used with labels, the application of the color and alpha of the labels is controlled by the USE_LABEL_COLOR and LABEL_USE_VERTEX_COLOR properties.

Property Type

USERDEF

Name String

Vertex colors

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

XCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert X coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedX = s0 + s1 * DataX

Recommended values are:

[(-Xmin)/(Xmax-Xmin), 1/(Xmax-Xmin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

XRANGE

A two-element floating-point vector of the form [xmin, xmax] that specifies the range of x data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

YCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert Y coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedY = s0 + s1 * DataY

Recommended values are:

[(-Ymin)/(Ymax-Ymin), 1/(Ymax-Ymin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

YRANGE

A two-element floating-point vector of the form [ymin, ymax] that specifies the range of y data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

ZCOORD_CONV

A floating-point vector, [s0, s1], of scaling factors used to convert Z coordinates from data units to normalized units. The formula for the conversion is as follows:

NormalizedZ = s0 + s1 * DataZ

Recommended values are:

[(-Zmin)/(Zmax-Zmin), 1/(Zmax-Zmin)]

The default is [0.0, 1.0]. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

ZRANGE

A two-element floating-point vector of the form [zmin, zmax] that specifies the range of z data coordinates covered by the graphic object. IDL maintains and returns this property in double-precision floating-point.

Property Type

Floating-point vector

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No