IDLgrSurface Properties

IDLgrSurface 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 IDLgrSurface::GetProperty. Properties with the word “Yes” in the “Init” column of the property table can be set via IDLgrSurface::Init. Properties with the word “Yes” in the “Set” column in the property table can be set via IDLgrSurface::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

AMBIENT

ANTIALIAS

BOTTOM

CLIP_PLANES

COLOR

DATA

DATAX

DATAY

DATAZ

DEPTH_OFFSET

DEPTH_TEST_DISABLE

DEPTH_TEST_FUNCTION

DEPTH_WRITE_DISABLE

DIFFUSE

DOUBLE

EMISSION

EXTENDED_LEGO

HIDDEN_LINES

HIDE

LINESTYLE

MAX_VALUE

MIN_VALUE

PALETTE

PARENT

REGISTER_PROPERTIES

RESET_DATA

SHADE_RANGE

SHADER

SHADING

SHARE_DATA

SHININESS

SHOW_SKIRT

SKIRT

SPECULAR

STYLE

TEXTURE_COORD

TEXTURE_HIGHRES

TEXTURE_INTERP

TEXTURE_MAP

THICK

USE_TRIANGLES

VERT_COLORS

XCOORD_CONV

XRANGE

YCOORD_CONV

YRANGE

ZCOORD_CONV

ZERO_OPACITY_SKIP

ZRANGE

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

Set this property to a floating-point value in the range [0.0, 1.0] to specify the opacity of the surface. The default value of 1.0 causes IDL to draw the surface completely opaque. If the value of this property is less than 1.0, then the pixels of the surface are blended with the pixels already on the screen. The color of the surface 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. This also applies to the individual facets of the surface that IDL generates to represent the surface geometry. Since you do not have control over the rendering order of the facets that form the surface, there is little you can do to change the ordering so that the facets draw in a back-to-front order. Therefore, using this property to draw semi-transparent surfaces is not recommended unless the surface geometry and orientation is such that the surface can be viewed without self-overlapping areas.

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

When used with textures, the ALPHA_CHANNEL value controls the opacity of the polygon in the same manner as when not using a texture. If the texture contains alpha information, the effective alpha of each texel is the texel’s alpha multiplied by the polygon’s alpha value (ALPHA_CHANNEL property).

Note:

Property Type

Float-point value

Name String

Transparency

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

AMBIENT

Set this property to a three-element vector [red, green, blue] to specify the ambient reflective color of the object. The default is black or [0,0,0], which specifies that the value of the COLOR property determines the ambient reflective color of the object. Setting an ambient color other than black makes the object use that color for ambient reflectance. Ambient reflectance affects the overall color of the object and is most noticeable where the object is not directly lit by a light source. This property has no effect on devices using indexed color mode.

Property Type

COLOR

Name String

Ambient reflective color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

ANTIALIAS

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

Property Type

BOOLEAN

Name String

Anti-aliasing

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

BOTTOM

A scalar or three-element vector [red, green, blue] specifying the color used to draw the bottom of the surface. Set this property to a scalar to draw the bottom with the same color as the top. If set to a scalar, IDL returns the default value of -1 if the property is retrieved with GetProperty. Setting a bottom color is only supported when the destination device uses RGB color mode.

Property Type

COLOR

Name String

Bottom color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

CLIP_PLANES

A 4-by-N floating-point array 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

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

COLOR

The color to be used as the foreground color for this model. The color may be specified as a color lookup table index or as a three-element vector [red, green, blue]. The default is [0, 0, 0].

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

An array of any type that specifies the surface data. The array format is based upon the following:

The value of the DATA array represents the combination of the DATAX, DATAY, and DATAZ values defined using ::SetProperty. If DATAZ was set, and DATAX and DATAY were not, the DATA value returned includes the implied X and Y grid locations.

Property Type

Array of any type

Name String

not displayed

Get: Yes

Set: No

Init: No

Registered: No

DATAX

A floating-point vector or a two-dimensional array specifying the X coordinates of the surface grid. This property is stored as double precision floating point values if the property is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point.

Specifying this property is the same as specifying the optional X argument to the IDLgrSurface::Init method.

Property Type

Floating-point vector or array

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

DATAY

A floating-point vector or a two-dimensional array specifying the Y coordinates of the surface grid. This property is stored as double precision floating point values if the property is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point.

Specifying this property is the same as specifying the optional Y argument to the IDLgrSurface::Init method.

Property Type

Floating-point vector or array

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

DATAZ

A two-dimensional floating-point array to display as a surface. This property is stored as double precision floating point values if the property is of type DOUBLE or if the DOUBLE property is non-zero, otherwise it is stored as single precision floating point.

Specifying this property is the same as specifying the optional Z argument to the IDLgrSurface::Init method.

Property Type

Floating-point array

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

DEPTH_OFFSET

An integer value that specifies an offset in depth to be used when rendering filled primitives. This offset is applied along the viewing axis, with positive values moving the primitive away from the viewer.

The units are “Z-Buffer units,” where a value of 1 is used to specify a distance that corresponds to a single step in the device’s Z-Buffer.

Use DEPTH_OFFSET to always cause a filled primitive to be rendered slightly deeper than other primitives, independent of model transforms. This is useful for avoiding stitching artifacts caused by rendering lines or polygons on top of other polygons at the same depth.

Note: Use this feature to remove stitching artifacts and not as a means for “layering” complex scenes with multiple DEPTH_OFFSET values. It is safest to use only a DEPTH_OFFSET value of 0, the default, and one other non-zero value, such as 1. Many system-level graphics drivers are not consistent in their handling of DEPTH_OFFSET values, particularly when multiple non-zero values are used. This can lead to portability problems because a set of DEPTH_OFFSET values may produce better results on one machine than on another. Using IDL’s software renderer will help improve the cross-platform consistency of scenes that use DEPTH_OFFSET.

Note: DEPTH_OFFEST has no effect unless the value of the STYLE property is 2 or 6 (Filled or LegoFilled).

Property Type

INTEGER

Name String

Depth offset

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

DEPTH_TEST_DISABLE

An integer value that determines whether depth testing is disabled.

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.

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.

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

DIFFUSE

Set this property to a three-element vector [red, green, blue] to specify the diffuse reflectance color of the object. The default is black or [0,0,0], which specifies that the value of the COLOR property determines the diffuse reflective color of the object. Setting a diffuse color other than black makes the object use that color for diffuse reflectance. Diffuse reflectance is an important factor in determining the color of the object and is affected by the color and angle of the light sources in a scene. This property has no effect on devices using indexed color mode.

Property Type

COLOR

Name String

Diffuse reflective color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

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.

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

EMISSION

Set this property to a three-element vector [red, green, blue] to specify the emissive color of the object. The default is black or [0,0,0], which specifies that the object contributes no additional color in an emissive sense. Setting an emission color other than black makes the object appear as if it were emitting that color. This property is used to simulate light sources or other objects that emit light in a scene. This property has no effect on devices using indexed color mode.

Property Type

COLOR

Name String

Emissive color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

EXTENDED_LEGO

A Boolean value that determines whether to force the IDLgrSurface object to display the last row and column of data when lego display styles are selected.

Property Type

Boolean

Name String

Show last lego row/column

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

HIDDEN_LINES

A Boolean value that determines whether to draw point and wireframe surfaces using hidden line (point) removal. By default, hidden line removal is disabled.

Property Type

Boolean

Name String

Remove hidden lines

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

HIDE

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

Value

Property Sheet Value

Description

0

True

Draw graphic (the default)

1

False

Do no draw graphic

Property Type

ENUMLIST

Name String

Show

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

LINESTYLE

An integer value that indicates the line style to use to draw the surface lines. 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

MAX_VALUE

A double-precision floating-point value that determines the maximum value to be plotted. If this property is present, data values greater than the value of MAX_VALUE are treated as missing data and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

FLOAT

Name String

Maximum value

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

MIN_VALUE

A double-precision floating-point value that determines the minimum value to be plotted. If this property is present, data values less than the value of MIN_VALUE are treated as missing data and are not plotted. Note that the IEEE floating-point value NaN is also treated as missing data. IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

FLOAT

Name String

Minimum value

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 IDLgrSurface 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

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[XYZ] properties 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 a DATA[XYZ] property. .

Property Type

Boolean

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

SHADE_RANGE

A two-element integer array that specifies the range of pixel values (color indices) to use for shading. The first element is the color index for the darkest pixel. The second element is the color element for the brightest pixel. This value is ignored when the polygons are drawn to a graphics destination that uses the RGB color model.

Property Type

Integer array

Name String

not displayed

Get: Yes

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 surface 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 surface 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 if STYLE is set to 2 (Filled).

Value

Property Sheet Value

Description

0

Flat

The color has a constant intensity for each face of the surface, based on the normal vector (the default)

1

Gouraud

The colors are interpolated between vertices, and then along scanlines from each of the edge intensities

Gouraud shading may be slower than flat shading, but results in a smoother appearance.

Property Type

ENUMLIST

Name String

Fill 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 surface. A surface may only share data with another surface. 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 IDLgrSurface object is destroyed.

Property Type

Object reference

Name String

not displayed

Get: No

Set: Yes

Init: Yes

Registered: No

SHININESS

Set this property to a floating-point value between 0.0 and 128.0, inclusive. The default value is 25.0. Higher values of shininess concentrate specular highlights into smaller and brighter areas, while lower values will spread out specular highlights over a wider area and make them appear dimmer.

Property Type

FLOAT

Name String

Shininess

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

SHOW_SKIRT

A Boolean value that determines whether to enable skirt drawing. The default is to disable skirt drawing. .

Property Type

Boolean

Name String

Show skirt

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

SKIRT

A floating-point value that determines the Z value at which a skirt is to be defined around the array. The Z value is expressed in data units; the default is 0.0. If a skirt is defined, each point on the four edges of the surface is connected to a point on the skirt which has the given Z value, and the same X and Y values as the edge point. In addition, each point on the skirt is connected to its neighbor. The skirt value is ignored if skirt drawing is disabled (see SHOW_SKIRT above). IDL converts, maintains, and returns this data as double-precision floating-point.

Property Type

FLOAT

Name String

Skirt bottom height

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

SPECULAR

Set this property to a three-element vector [red, green, blue] to specify the color of the specular highlights of an object. The default is white or [255,255,255]. This property is used to simulate and control reflective highlights on an object. This property has no effect on devices using indexed color mode.

Property Type

COLOR

Name String

Specular highlight color

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

STYLE

An integer value or an enumerated list item that indicates the style to be used to draw the surface. Valid values are:

Value

Property Sheet Value

Description

0

Points

Points

1

Wire mesh

Wire mesh (the default)

2

Filled

Filled

3

RuledXZ

RuledXZ

4

RuledYZ

RuledYZ

5

Lego

Lego

6

Lego filled

Lego filled for outline or shaded and stacked histogram-style plots

Note: Stitching effects may appear when combining an unfilled style (STYLE=0, 1, 3, 4, or 5) and hidden lines (HIDDEN_LINES=1). In such a case, missing lines may be caused by depth buffer resolution, limited depth offset support of the graphics card, or invisible parts of a surface occluding line visibility.

Property Type

ENUMLIST

Name String

Surface style

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

TEXTURE_COORD

A 2-by-n floating-point array of texture map coordinate pairs that are internally mapped to surface vertex coordinates. The number of data points in the surface and the value of n in the 2-by-n array should be equal.

Each texture map coordinate pair is mapped to a surface vertex coordinate pair in array order. For example, with a 2-by-9 element array, texture map coordinates will be mapped to a 3-by-3 surface as follows:

Use this property in conjunction with the TEXTURE_MAP property to warp images over the surface. To stretch (or shrink) the texture map to cover the surface mesh completely, set TEXTURE_COORD to a scalar. By default, IDL stretches (or shrinks) the texture map to cover the surface mesh completely, and sets TEXTURE_COORD to a scalar (-1).

Texture coordinates are normalized. This means that the m x n image object specified via the TEXTURE_MAP property is mapped into the range [0.0, 0.0] to [1.0, 1.0]. As the texture coordinates run from 0.0 to 1.0 across a texture, a texture coordinate of [0.5, 0.5] at a vertex specifies that the image pixel at the exact center of the image is mapped to the surface at that vertex. If texture coordinates outside the range [0.0, 0.0] to [1.0, 1.0] are specified, the image object is tiled into the larger range.

For example, suppose the image object specified via TEXTURE_MAP is a 256 x 256 array, and we want to map the image into a surface two units on each side. To completely fill the 2 x 2 surface with a single copy of the image:

TEXTURE_COORD = [[0,0], [1,0], [0,1], [1,1]]

To fill the 2 x 2 surface with four tiled copies of the image:

TEXTURE_COORD = [[0,0], [2,0], [0,2], [2,2]]

Because of the way in which high-resolution textures require modified texture coordinates, if the TEXTURE_COORD property is used, TEXTURE_HIGHRES will be disabled.

Property Type

Floating-point array

Name String

not displayed

Get: Yes

Set: Yes

Init: Yes

Registered: No

TEXTURE_HIGHRES

An integer value or enumerated list item that determines the type of texture tiling, if any, that will be used to maintain the full pixel resolution of the original texture image.

Value

Property Sheet Value

Description

0

No tiling

If the texture map is larger than the maximum resolution supported by the 3-D hardware, the texture is scaled down to this resolution (the default).

1

LOD tiling

If the texture map is larger than the maximum resolution supported by the hardware, texture tiling is used to ensure no loss of data. As a large image could easily consume all available video memory, this mode employs texture Level of Detail (LoD). Rather than loading the entire image into the texture tiles at the full resolution, the image tiles are downsampled based on the level of zoom. If the entire image is visible the texture tiles will contain highly downsampled data from the image to conserve video memory. As a portion of the image is zoomed in on, progressively higher resolution image data is loaded into the visible tiles, until the maximum resolution is reached. The tiles that are not visible during zooming are not loaded with high resolution data.

This mode is recommended if IDL is running on modern 3-D hardware and resolution loss due to downscaling becomes problematic when TEXTURE_HIGHRES=0.

2

Tiling

If the texture map is larger than the maximum resolution supported by the hardware, texture tiling is used to ensure no loss of data. However, the highest resolution data is loaded into all tiles. LoD tiling is disabled. This mode should only be used if the video memory is sufficient for the image size.

Note: TEXTURE_HIGHRES is supported only when STYLE=2 (Filled).

Note: Because of the way in which high-resolution textures require modified texture coordinates, if you specify the TEXTURE_COORD property, high resolution textures (TEXTURE_HIGHRES) will be disabled.

Property Type

ENUMLIST

Name String

Texture hires

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

TEXTURE_INTERP

A Boolean value or enumerated list item that indicates whether bilinear sampling is to be used with texture mapping.

Value

Property Sheet Value

Description

0

Nearest neighbor

Surveys the value of the nearest pixel (the default)

1

Bilinear

Surveys the 4 closest pixels

Property Type

ENUMLIST

Name String

Texture interpolation

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

TEXTURE_MAP

An object reference to an instance of the IDLgrImage object class to be texture mapped onto the surface. If this property is omitted or set to a null object reference, no texture map is applied and the surface is filled with the color specified by the COLOR or VERT_COLORS property. If both TEXTURE_MAP and COLORS or VERT_COLORS properties exist, the color of the texture is modulated by the base color of the object. (This means that for the clearest display of the texture image, the COLOR property should be set equal to [255,255,255].) By default, the texture map will be stretched (or shrunk) to cover the surface mesh completely.

Setting TEXTURE_MAP to the object reference of an IDLgrImage that contains an alpha channel allows you to create a transparent IDLgrSurface object. If an alpha channel is present in the IDLgrImage object, IDL blends the texture using the blend function src = alpha and dst = 1 - alpha, which corresponds to a BLEND_FUNCTION of (3,4) as described for the IDLgrImage object.

If a texture is provided without texture coordinates, IDLgrSurface generates its own texture mapping coordinates to map the texture onto the surface without resampling artifacts, even if the provided texture image does not have dimensions that are an exact power of two. If texture coordinates are provided, the image is resampled to the nearest larger dimensions that are exact powers of two.

Note: Texture mapping is disabled when rendering to a destination object that uses Indexed color mode.

Note: Texture mapping is applied to all styles that are set by the STYLE property except Lego and LegoFilled.

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

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

Property Type

USERDEF

Name String

Texture map

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

THICK

A floating-point value between 0.0 and 10.0, specifying the line thickness to use to draw surface lines, 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

Line thickness

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

USE_TRIANGLES

A Boolean value or an enumerated list item that determines whether to force the IDLgrSurface object to use triangles instead of quads to draw the surface and skirt.

Value

Property Sheet Value

Description

0

Quads

Use quads to draw the surface and skirt (the default)

1

Triangles

Use triangles to draw the surface and skirt

 

Property Type

Boolean

Name String

Draw method

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

VERT_COLORS

A vector of colors to be used to specify the color of a surface 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 surface 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 surface polygon is the color of the first vertex of that surface polygon. 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.

Note: If the surface object is being rendered on a destination device that uses the Indexed color model, and the view that contains the surface also contains one or more light objects, the VERT_COLORS property is ignored and the SHADE_RANGE property is used instead.

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

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

ZERO_OPACITY_SKIP

A Boolean value that determines whether to gain finer control over the rendering of textured surface pixels (texels) by setting an opacity of 0 in the texture map. Texels with zero opacity do not affect the color of a screen pixel since they have no opacity. If this property is set to 1, any texels are “skipped” and not rendered at all. If this property is set to zero, the Z-buffer is updated for these pixels and the display image is not affected as noted above. By updating the Z-buffer without updating the display image, the surface can be used as a clipping surface for other graphics primitives drawn after the current graphics object. The default value for this property is 1.

Note: This property has no effect if no texture map is used or if the texture map in use does not contain an opacity channel.

Property Type

Boolean

Name String

Skip zero opacity

Get: Yes

Set: Yes

Init: Yes

Registered: Yes

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