OpenRM - RM Library (rmpick.c)

## Index of OpenRM - RM Library

     RMpick * rmFramePick (RMpipe *renderPipe,
                           RMnode *subTree,
                           int xpick,
    	               int ypick)

     RMpipe *renderPipe - the pipe upon which rendering and picking will occur.

     RMnode *subTree- the subtree to be drawn, and picked.

     int xpick, ypick - integer values indicating an (x,y) window
        location.

rmFramePick() performs object picking. A single RMpick object is returned representing the object closest to the viewer at the pixel location (xpick, ypick) in the display window. To obtain a list of all objects that appear at (xpick, ypick), not just the frontmost, use rmFramePickList().

If no objects were picked, NULL is returned.

Some scene parameters will generate pick hits. These include 2D and 3D cameras. When the pick occurs at some (x,y) location that is not covered by any objects, a pick hit will be returned. In that case, the returned RMpick object's RMnode attribute will point to the RMnode that has a camera that generated the pick hit.

With the RMpick object returned by rmPickFrame or rmPickFrameList, use the routine rmPickedNode to obtain a handle to the RMnode that was picked; rmPickedPrimitive to obtain a handle to the RMprimitive that was picked; rmPickedNodeName() to obtain the (character string) name of the node that was picked; and rmPickedPrimitiveZval to obtain the NDC z-coordinate of the primitive that was picked.

June 2002: the RMpick object returned by rmFramePick should be deleted with rmPickDelete when it is no longer needed. (In versions of RM earlier than 1.4.2, a pointer to static memory was returned, and apps were prohibited from free'ing that memory. This has changed as of v1.4.2).

See the RM demo programs for example usage, particularly "trans2d.c", which performs picking in 2D, and "pickTest.c", which performs picking in 3D. The RM demo program "pickListTest.c" exercises rmFramePickList() in 3D.

librm library source file: rmpick.c

     int rmFramePickList (RMpipe *renderPipe,
                          RMnode *subTree,
                          int xpick,
    		      int ypick,
    		      RMpick **listReturn)

     RMpipe *renderPipe - the pipe upon which rendering and picking will occur.

     RMnode *subTree- the subtree to be drawn, and picked.

     int xpick, ypick - integer values indicating an (x,y) pixel
        coordinate within a window (input).

     RMpick **listReturn - a handle to an RMpick pointer (modified,
        return).

Performs a pick operation, returning a list of all objects encountered at the (x,y) pixel location in the render window through the parameter listReturn. The number of objects in that list is returned on the stack, or zero is returned if there were no objects picked.

The list of objects that is returned to the caller is sorted in ascending order of the z-coordinate of the picked object. Therefore, listReturn[0] contains information about the object closest to the viewer, and listReturn[nhits-1] contains info about the object farthest from the viewer.

The RMpick objects returned through listReturn should be freed when no longer needed by using rmPickListDelete().

librm library source file: rmpick.c

     RMenum rmPickDelete (RMpick *toDelete)

     RMpick *toDelete - a handle to a single or flat array of RMpick
        objects.

Use this routine to free resources associated with an RMpick object or flat array of RMpick objects.

When rmFramePick() and rmFramePickList() finish, each returns an RMpick * object (rmFramePick) or flat array of RMpick objects (rmFramePickList). When applications are finished with these RMpick objects, they should be deleted using rmPickDelete().

librm library source file: rmpick.c

     RMnode * rmPickedNode (const RMpick *toQuery)

     const RMpick *toQuery - a handle to an RMpick object (input).

Returns to the caller the RMnode handle contained within an RMpick object, or NULL upon failure.

The RMpick object returned from rmFramePick (or objects returned from rmFramePickList) can be queried to determine the node, primitive, node name or z-coordinate of the picked object.

librm library source file: rmpick.c

     int rmPickedPrimitive (const RMpick *toQuery)

     const RMpick *toQuery - a handle to an RMpick object (input).

The RMpick object returned from rmFramePick (or objects returned from rmFramePickList) can be queried to determine the node, primitive, node name or z-coordinate of the picked object.

This routine returns the index of the primitive that was picked. Combining the primitive index with the RMnode handle of the picked object allows applications to determine which primitive was picked.

Returns a non-negative integer upon success, or -1 upon failure.

librm library source file: rmpick.c

     char * rmPickedNodeName (const RMpick *toQuery)

     const RMpick *toQuery - a handle to an RMpick object (input).

Returns to the caller the node name of the RMnode handle contained within an RMpick object, or NULL upon failure.

The RMpick object returned from rmFramePick (or objects returned from rmFramePickList) can be queried to determine the node, primitive, node name or z-coordinate of the picked object.

This routine is functionally equivalent to first obtaining the RMnode handle using rmPickedNode() followed by rmNodeGetName().

librm library source file: rmpick.c

     float rmPickedPrimitiveZval (const RMpick *toQuery)

     const RMpick *toQuery - a handle to an RMpick object (input).

Returns to the caller the NDC z-coordinate of the RMprimitive at the (x,y) screen location where picking occured. A value of zero is returned upon error, when no picking occurred (RMpick NULL).

The RMpick object returned from rmFramePick (or objects returned from rmFramePickList) can be queried to determine the node, primitive, node name or z-coordinate of the picked object.

librm library source file: rmpick.c