javax.microedition.m3g
Class RayIntersection

java.lang.Object
  javax.microedition.m3g.RayIntersection

public class RayIntersection

extends java.lang.Object

A RayIntersection object is filled in by the pick methods in Group. RayIntersection stores a reference to the intersected Mesh or Sprite3D and information about the intersection point. RayIntersection is strictly a run-time object; it cannot be loaded from a file by Loader.

Constructor Summary

RayIntersection()
Constructs a new RayIntersection object with default values.

Method Summary

float	getDistance() Retrieves the distance from the pick ray origin to the intersection point.
Node	getIntersected() Retrieves the picked Mesh or Sprite3D object.
float	getNormalX() Retrieves the X component of the surface normal at the intersection point.
float	getNormalY() Retrieves the Y component of the surface normal at the intersection point.
float	getNormalZ() Retrieves the Z component of the surface normal at the intersection point.
void	getRay(float[] ray) Retrieves the origin (ox oy oz) and direction (dx dy dz) of the pick ray, in that order.
int	getSubmeshIndex() Retrieves the index of the submesh where the intersection point is located within the intersected Mesh.
float	getTextureS(int index) Retrieves the S texture coordinate at the intersection point on the picked Mesh or Sprite3D.
float	getTextureT(int index) Retrieves the T texture coordinate at the intersection point on the picked Mesh or Sprite3D.

Constructor Detail

RayIntersection

public RayIntersection()

Constructs a new RayIntersection object with default values. The default values are as follows:

• ray origin : (0 0 0)
• ray direction : (0 0 1)
• intersected node : null
• intersected submesh index : 0
• distance to intersection point : 0.0
• all texture coordinates : 0.0
• normal vector: (0 0 1)

Method Detail

getIntersected

public Node getIntersected()

Retrieves the picked Mesh or Sprite3D object. Other types of Nodes are not pickable and hence can not be returned by this method.

Returns:

the picked Mesh or Sprite3D object

getRay

public void getRay(float[] ray)

Retrieves the origin (ox oy oz) and direction (dx dy dz) of the pick ray, in that order. The ray origin and direction vector are specified in the coordinate system of the Group node where the pick method was called from. The returned direction vector is the same that is used to compute the distance measure from the pick point to the object in getDistance.

Note that if the application itself provides the pick ray origin and direction to the pick method, this method simply returns the same information; in particular, the direction vector is returned as is, not normalized. On the other hand, if the application uses the other pick method, where only a Camera and a point on the viewing plane are specified, the ray origin and direction would not otherwise be readily available.

This method together with getDistance enables the point of intersection to be computed conveniently, as shown in the example below.

Parameters:

ray - a float array to fill in with the pick ray origin and direction, in that order

Throws:

java.lang.NullPointerException - if ray is null

java.lang.IllegalArgumentException - if ray.length < 6

Example:

Computing the ray intersection point.

float x, y, z;                  // the intersection point
 float [] ray = new float[6];    // ray origin and direction
 RayIntersection ri = new RayIntersection();
  
 // Pick through the center of the viewport
  
 if (myGroup.pick(-1, 0.5f, 0.5f, myCamera, ri) == true)
 {
     ri.getRay(ray);
     x = ray[0] + ray[3] * ri.getDistance();
     y = ray[1] + ray[4] * ri.getDistance();
     z = ray[2] + ray[5] * ri.getDistance();
 }

getDistance

public float getDistance()

Retrieves the distance from the pick ray origin to the intersection point. The distance is normalized to the length of the given pick ray (1.0 = ray length). The length of the pick ray is defined as sqrt(dx² + dy² + dz²), where (dx dy dz) is the direction vector of the ray. The direction vector itself can be obtained using getRay.

The normalized distance is convenient, because it is independent of the transformations of the intersected Node and its ancestors, including any non-uniform scales and other non-length preserving transformations. The distance to the intersection point can be used for simple collision detection, for instance.

Returns:

normalized distance from the pick ray origin to the intersection point

getSubmeshIndex

public int getSubmeshIndex()

Retrieves the index of the submesh where the intersection point is located within the intersected Mesh. This allows the application to identify, for example, the texture image that is displayed at the intersection point. The submesh index is only applicable to Meshes; its value is always set to zero if the picked object is a Sprite3D.

Returns:

index of the intersected submesh (always 0 for sprites)

getTextureS

public float getTextureS(int index)

Retrieves the S texture coordinate at the intersection point on the picked Mesh or Sprite3D. For meshes, there can be between zero and N texture coordinates, where N is the number of texturing units supported by the implementation. If a texturing unit is disabled, the corresponding texture coordinates are undefined. For sprites, there is always exactly one pair of valid texture coordinates (at index zero); the rest of the coordinates are undefined.

If the picked object is a Mesh, the returned coordinates represent the texture coordinates after applying the texture transformation and projection, but before possible clamping. In the case of a Sprite3D, the returned coordinates are always between [0, 1], where (0, 0) is the upper left corner of the sprite image. Note that the sprite crop rectangle has no effect on the returned values.

Parameters:

index - index of the texturing unit to get the texture coordinate of

Returns:

the S texcoord of the specified texturing unit at the intersection point

Throws:

java.lang.IndexOutOfBoundsException - if index != [0, N] where N is the implementation specific maximum texturing unit index

getTextureT

public float getTextureT(int index)

Retrieves the T texture coordinate at the intersection point on the picked Mesh or Sprite3D. See getTextureS for more information.

Parameters:

index - index of the texturing unit to get the texture coordinate of

Returns:

the T texcoord of the specified texturing unit at the intersection point

Throws:

java.lang.IndexOutOfBoundsException - if index != [0, N] where N is the implementation specific maximum texturing unit index

getNormalX

public float getNormalX()

Retrieves the X component of the surface normal at the intersection point. The normal is specified in the coordinate system of the intersected Node, and is always unit length. If the picked object is a Sprite3D, the normal vector is always (0 0 1). If the object is a Mesh with no vertex normals, the returned normal is undefined.

Returns:

the X component of the surface normal at the intersection point

getNormalY

public float getNormalY()

Retrieves the Y component of the surface normal at the intersection point. See getNormalX for more information.

Returns:

the Y component of the surface normal at the intersection point

getNormalZ

public float getNormalZ()

Retrieves the Z component of the surface normal at the intersection point. See getNormalX for more information.

Returns:

the Z component of the surface normal at the intersection point