IDLgrBuffer::PickData

IDLgrBuffer::PickData

Syntax | Arguments | Keywords | Version History

The IDLgrBuffer::PickData function method maps a point in the two-dimensional device space of the buffer to a point in the three-dimensional data space of an object tree. The resulting 3-D data space coordinates are returned in a user-specified variable. The PickData function returns one if the specified location in the buffer's device space "hits" a graphic object, or zero otherwise.

Note

The PickData method relies on the contents of the depth buffer at the time it is called to compute and return its results. Be sure that the depth buffer contents are appropriate for getting the expected results from PickData. For example, you may use the DEPTH_WRITE_DISABLE property of an object to prevent an object from modifying the depth buffer as it is drawn. This prevents the object from affecting the result returned by the PickData method.

Syntax

Result = Obj->[IDLgrBuffer::]PickData( View, Object, Location, XYZLocation [, DIMENSIONS=[width,height]][, PATH=objref(s)] [, PICK_STATUS=variable])

Return Value

Returns one if the specified location in the buffer's device space "hits" a graphic object, or zero otherwise.

Arguments

View

The object reference of an IDLgrView object that contains the object being picked.

Object

The object reference of a model or atomic graphic object from which the data space coordinates are being requested.

Note

Even though you can specify any object for this argument, the location that is returned may not lie on this object. If another object is in front of the specified object then the returned location lies on the object in front. However, the coordinate system used is that of the object specified by this argument.

Location

A two-element vector [x, y] specifying the location in the buffer's device space of the point to pick data from.

XYZLocation

A named variable that will contain the three-dimensional double-precision floating-point data space coordinates of the picked point. Note that the value returned in this variable is a location, not a data value.

Note

If the atomic graphic object specified as the target has been transformed using either the LOCATION or DIMENSIONS properties (this is only possible with IDLgrAxis, IDLgrImage, and IDLgrText objects), these transformations will not be included in the data coordinates returned by the PickData function. This means that you may need to re-apply the transformation accomplished by specifying LOCATION or DIMENSIONS once you have retrieved the data coordinates with PickData. This situation does not occur if you transform the axis, text, or image object using the [XYZ]COORD_CONV properties.

Keywords

DIMENSIONS

Set this keyword to a two-element array [w, h] to specify data picking should occur for all device locations that fall within a pick box of these dimensions. The pick box will be centered about the coordinates [x, y] specified in the Location argument, and will occupy the rectangle defined by:

(x-(w/2), y-(h/2)) - (x+(w/2), y+(h/2))

By default, the pick box covers a single pixel. The array returned via the XYZLocation argument will have dimensions [3, w, h].

PATH

Set this keyword to a single object reference or a vector of object references. This keyword specifies the path in the graphics hierarchy to map the device position to a data space coordinate. Each path object reference specified with this keyword must contain an alias. The data space coordinate is computed for the version of the object falling within that path. If this keyword is not set, the PARENT properties determine the path from the current object to the top of the graphics hierarchy and no alias paths are pursued.

Note

For more information on aliases, refer to the ALIAS keyword in IDLgrModel::Add.

PICK_STATUS

Set this keyword to a named variable that will contain "hit" information for each pixel in the pick box. If the DIMENSIONS keyword is not set, the PICK_STATUS will be a scalar value exactly matching the Result of the method call. If the DIMENSIONS keyword is set, the PICK_STATUS variable will be an array matching the dimensions of the pick box. Each value in the PICK_STATUS array corresponds to a pixel in the pick box, and will be set to one of the following values:


Value	Description
-1	The pixel falls outside of the window's viewport.
0	No graphic object is "hit" at that pixel location.
1	A graphic object is "hit" at that pixel location.

Version History

Introduced: 5.0

PICK_STATUS keyword added: 5.6