gumbo.graphic.space
Interface SpaceMapper

All Superinterfaces:

Graphic

All Known Implementing Classes:

AbstractSpaceMapper, SwingSpaceMapper

public interface SpaceMapper

extends Graphic

A graphic object that provides a strategy for transforming (mapping) geometry from one space to another in a space tree. Implementations are encouraged to take advantage of native graphic capabilities.

Design note: Space transforms involve SpaceNode, TransformableGraphic, and specifically Point3, Vector3, and Matrix4. SpaceMapper is intended to embody all awareness of native graphics for space transformations, thereby freeing the other classes from such dependencies.

Version:

$Revision: 1.1 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Method Summary

Matrix4	getGraphicTransform(SpaceNode from, SpaceNode to, Matrix4 retVal) Returns a matrix that transforms geometry from one local space to another when the geometry is pre-multiplied by the matrix.
Point3	transformGraphic(Point3 point, SpaceNode from, SpaceNode to, Point3 retVal) Transforms a point from one local space to another.
Vector3	transformGraphic(Vector3 vector, SpaceNode from, SpaceNode to, Vector3 retVal) Transforms a vector from one local space to another.

Methods inherited from interface gumbo.graphic.Graphic

getGraphic

Method Detail

transformGraphic

public Point3 transformGraphic(Point3 point,
                               SpaceNode from,
                               SpaceNode to,
                               Point3 retVal)

Transforms a point from one local space to another. Consistent with the definition of a point, the point's W component is assumed to be one. For efficiency the transform may be cached.

Parameters:

point - Value of a point in the from space. Never null.

from - The source space. If null, the tree's absolute space.

to - The target space. If null, the tree's absolute space.

retVal - The return value object. The transformed point Never null.

Returns:

Reference to retVal. Never null.

Throws:

java.lang.IllegalArgumentException - The from and to nodes are not in the same tree.

transformGraphic

public Vector3 transformGraphic(Vector3 vector,
                                SpaceNode from,
                                SpaceNode to,
                                Vector3 retVal)

Transforms a vector from one local space to another. Consistent with the definition of a vector, the vector's W component is assumed to be zero (the transformation is invariant to translation). For efficiency the transform may be cached.

Parameters:

vector - Value of a vector in the from space. Never null.

from - The source space. If null, the tree's absolute space.

to - The target space. If null, the tree's absolute space.

retVal - The return value object. The transformed vector Never null.

Returns:

Reference to retVal. Never null.

Throws:

java.lang.IllegalArgumentException - The from and to nodes are not in the same tree.

getGraphicTransform

public Matrix4 getGraphicTransform(SpaceNode from,
                                   SpaceNode to,
                                   Matrix4 retVal)

Returns a matrix that transforms geometry from one local space to another when the geometry is pre-multiplied by the matrix. The transform is always newly computed (never stale). Where possible, for speed, use the point and vector transform methods instead of this method.

Parameters:

from - The source space. If null, the tree's absolute space.

to - The target space. If null, the tree's absolute space.

retVal - The return value object. The transform matrix. Never null.

Returns:

Reference to retVal. Never null.

Throws:

java.lang.IllegalArgumentException - The from and to nodes are not in the same tree.