vona.j3d

Class Widget

java.lang.Object

vona.j3d.Widget

Direct Known Subclasses:

AxesWidget, CurveWidget, FacetedWidget

@NotThreadSafe
public class Widget
extends java.lang.Object

Defines a set of geometries and their appearances.

The number of geometries is fixed at construction time.

Various subclasses in this package provide common geometric objects. Also the user may instantiate a Widget from a Shape3D, or can simply populate a raw Widget with geometries.

This class is not internally synchronized. Applications which allow access to a Widget from multiple threads need to implement their own synchronization.

Includes

• enabled enable/disable each geometry
• rx to set a local coordinate frame for all geometry
• a primitiveIterator for each JOGLGeometry or GeometryArray geometry (coords and normals, if available, only)
• a vertexAccessor for each geometry
• a boundingSphereCenter and boundingSphereRadius for each geometry
• a widgetLength which can be used as a scale reference
• an extra multiplicative alpha on top of any individual Appearance alphas
• updateDBGNormals(int, float), a facility to generate geometry that displays line segments along explicit vertex normals
• updateDBGSpheres(int), a facility to generate geometry that displays bounding spheres
• a lazily consed propertyMap

Copyright (C) 2008 Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:

Marsette (Marty) A. Vona, III

Field Summary

Fields

Modifier and Type	Field and Description
float	alpha Extra multiplicative alpha on top of any individual Appearance alphas.
javax.media.j3d.Appearance[]	appearance appearance for each geometry, null if none
boolean	autoSetBoundingSpheres Whether to automatically update geometry bounding spheres in subclasses that support such functionality.
float[][]	boundingSphereCenter bounding sphere ctr for each geom in native frame of this Widget
float[][]	boundingSphereCenterInView boundingSphereCenter in view frame, alloc if desired by calling ensureBoundingSpheresInView().
float[]	boundingSphereRadius Bounding sphere rad for each geom in native frame of this Widget
float[]	boundingSphereRadiusInView boundingSphereRadius in view frame, alloc if desired by calling ensureBoundingSpheresInView().
private static java.lang.String	cvsid
boolean	dbgEnabled whether debug spheres and normals are enabled if present
JOGLGeometry	dbgNormalsGeometry DBG normal geometry if non-null, see updateDBGNormals(int, float).
java.nio.FloatBuffer	dbgNormalsVertices vertex array for dbgNormalsGeometry, if non-null
JOGLGeometry	dbgSpheresGeometry dbg spheres geometry if non-null, see updateDBGSpheres(int)
java.nio.FloatBuffer	dbgSpheresVertices vertex array for dbgSpheresGeometry, if non-null
static float	DEF_DBG_NORMAL_LENGTH line segment length for dbg normal display
static float	DEF_WIDGET_LENGTH default widgetLength
boolean[]	enabled enable/disable flag for each geometry, default true
javax.media.j3d.Geometry[]	geometry the geometries, entries may be null
int	numGeometries number of geometries in this Widget
J3DPrimitiveIterator[]	primitiveIterator Primitive iterator for each geometry (colors and normals, if available, only).
protected java.util.Map<java.lang.String,java.lang.Object>	propertyMap the property map or null if none
RX	rx Transforms coordinates in the native frame of this Widget to a parent frame, or null (i.e.
J3DVertexAccessor[]	vertexAccessor Vertex accessor (contained in primitiveIterator) for each JOGLGeometry or GeometryArray geometry.
protected float	widgetLength current widget length

Constructor Summary

Constructors

Constructor and Description
Widget(int numGeometries) Creates a new Widget that will hold the specified number of geometries.
Widget(javax.media.j3d.Shape3D shape3D) Covers Widget(Shape3D, boolean, int, PrintStream), sets extractToJOGL, no error stream, extracts all vertex components.
Widget(javax.media.j3d.Shape3D shape3D, boolean extractToJOGL, int j3dFormatMask, java.io.PrintStream errorStream) Makes a new Widget by extracting all the GeometryArrays of shape3D and its Appearance, if any.
Widget(javax.media.j3d.Shape3D shape3D, int j3dFormatMask) Covers Widget(Shape3D, boolean, int, PrintStream), sets extractToJOGL, no error stream.
Widget(javax.media.j3d.Shape3D shape3D, int j3dFormatMask, java.io.PrintStream errorStream) covers Widget(Shape3D, boolean, int, PrintStream), sets extractToJOGL

Method Summary

Methods

Modifier and Type	Method and Description
static Widget	cons(java.lang.String type) Generic factory method to construct Widget subclass instances.
protected static int	countGeometryArrays(javax.media.j3d.Shape3D shape3D) count the number of GeometryArrays in shape3D
void	disableBoundingSphere(int index) disable the bounding sphere at index by setting its radius -1
void	disableBoundingSpheres() Disable all bounding spheres and turn off autoSetBoundingSpheres.
void	dump() dump(PrintStream) to System.out
void	dump(java.io.PrintStream s) dump widget details
void	enableDBGGeometry(boolean enable) Enable or disable debug spheres and normals.
void	enableGeometry(int index, boolean enable) set the enabled flag for geometry at index
void	ensureBoundingSpheresInView() Cons boundingSphereCenterInView and boundingSphereRadiusInView iff necessary.
javax.media.j3d.Appearance	getAppearance(int index) get a reference to the appearance at indicated index
float[]	getBoundingSphereCenter(int index) get a reference to boundingSphereCenter at index
float	getBoundingSphereRadius(int index) get the boundingSphereRadius at index
javax.media.j3d.Geometry	getGeometry(int index) get a reference to the geometry at indicated index
java.lang.Object	getProperty(java.lang.String key) get a property
static Widget	getWidget(javax.media.j3d.Geometry geometry) Convenience to get the Widget containing geometry by following the user data ref on geometry.
float	getWidgetAlpha() get alpha
boolean	hasBoundingSphere(int index) Check if the geometry at index has a non-negative boundingSphereRadius.
boolean	hasBoundingSphereInView(int index) Check if view-frame bounding spheres are allocated and that the geometry at index has a n-negative boundingSphereRadiusInView.
boolean	hasProperty(java.lang.String key) check existence of a property
int	indexOf(javax.media.j3d.Geometry geometry) Lookup the index of geometry in this Widget.
protected void	populateFrom(javax.media.j3d.Shape3D shape3D, boolean extractToJOGL, int j3dFormatMask, java.io.PrintStream errorStream) impl of Widget(Shape3D, boolean, int, PrintStream)
void	recomputeBoundingSphere(int index) Recompute boundingSphereCenter and boundingSphereRadius for geometry at index, using vertexAccessor at index, if present.
void	recomputeBoundingSpheres() recomputeBoundingSphere(int) for each geometry
void	removeDBGNormals() remove any debug normals
void	removeDBGSpheres() remove any debug spheres
int	removeGeometry(javax.media.j3d.Geometry geometry) Remove (null) indicated geometry, iff found.
javax.media.j3d.Geometry	removeGeometry(int index) Remove (null) geometry at indicated index.
java.lang.Object	removeProperty(java.lang.String key) remove a property
javax.media.j3d.Appearance	replaceAppearanceWithClone(int index) similar to replaceGeometryWithClone(int)
javax.media.j3d.Geometry	replaceGeometryWithClone(int index) Replace the indicated geometry with a clone of itself.
void	scaleWidget(float scale) Apply a scale factor in-place to this widget.
javax.media.j3d.Appearance	setAppearance(int index, javax.media.j3d.Appearance appearance) Set a the appearance at indicated index by ref.
void	setBoundingSphereCenter(int index, float... center) set boundingSphereCenter at index by copy
void	setBoundingSphereRadius(int index, float radius) set the boundingSphereRadius at index
javax.media.j3d.Geometry	setGeometry(int index, javax.media.j3d.Geometry geometry) Set the geometry at the specified index.
void	setGeometryAlpha(float alpha) convenience to setGeometryAlpha(int, float) on all geometries
void	setGeometryAlpha(int index, float alpha) set transparency alpha for a particular geometry
void	setGeometryAndAppearance(int index, javax.media.j3d.Geometry geometry, javax.media.j3d.Appearance appearance) setGeometry(int, javax.media.j3d.Geometry) and appearance at the specified index
java.lang.Object	setProperty(java.lang.String key, java.lang.Object value) covers setProperty(String, Object, boolean), replaces
java.lang.Object	setProperty(java.lang.String key, java.lang.Object value, boolean replace) Set a property.
void	setWidgetAlpha(float alpha) set alpha
void	setWidgetLength(float widgetLength) Set widgetLength, calls widgetLengthChanged() iff different.
void	trackWidgetLength(float... trackFactor) Subclasses may implement this to store factors that map widgetLength to their parameters.
void	updateAllDBGNormals() updateDBGNormals(int, float) for all geometry, creating them if they don't yet exist, using DEF_DBG_NORMAL_LENGTH.
void	updateAllDBGNormals(float normalLength) updateDBGNormals(int, float) for all geometry, creating them if they don't yet exist.
void	updateAllDBGSpheres() updateDBGSpheres(int) for all geometry
void	updateDBGNormals(int upToGeometry) updateDBGNormals(int, float) using DEF_DBG_NORMAL_LENGTH.
void	updateDBGNormals(int upToGeometry, float normalLength) Create or update the dbgNormalsGeometry which shows line segments for each normal in each geometry.
void	updateDBGSpheres(int upToGeometry) Create or update the dbgSpheresGeometry which shows the bounding spheres for each geometry.
void	updateExistingDBGNormals() updateDBGNormals(int, float) that already exist, using length of first existing one.
void	updateExistingDBGSpheres() updateDBGSpheres(int) only existing
protected void	widgetLengthChanged() called by setWidgetLength(float) after the length has changed

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

cvsid

private static final java.lang.String cvsid

See Also:

Constant Field Values

DEF_WIDGET_LENGTH

public static final float DEF_WIDGET_LENGTH

default widgetLength

See Also:

Constant Field Values

DEF_DBG_NORMAL_LENGTH

public static final float DEF_DBG_NORMAL_LENGTH

line segment length for dbg normal display

See Also:

Constant Field Values

numGeometries

public final int numGeometries

number of geometries in this Widget

geometry

public final javax.media.j3d.Geometry[] geometry

the geometries, entries may be null

appearance

public final javax.media.j3d.Appearance[] appearance

appearance for each geometry, null if none

enabled

public final boolean[] enabled

enable/disable flag for each geometry, default true

rx

public volatile RX rx

Transforms coordinates in the native frame of this Widget to a parent frame, or null (i.e. use identity).

alpha

public volatile float alpha

Extra multiplicative alpha on top of any individual Appearance alphas.

Ignored if outside the range [0, 1]. Otherwise, multiplies the original Appearance alpha for each geometry.

autoSetBoundingSpheres

public volatile boolean autoSetBoundingSpheres

Whether to automatically update geometry bounding spheres in subclasses that support such functionality.

primitiveIterator

public final J3DPrimitiveIterator[] primitiveIterator

Primitive iterator for each geometry (colors and normals, if available, only).

vertexAccessor

public final J3DVertexAccessor[] vertexAccessor

Vertex accessor (contained in primitiveIterator) for each JOGLGeometry or GeometryArray geometry.

boundingSphereCenter

public final float[][] boundingSphereCenter

bounding sphere ctr for each geom in native frame of this Widget

boundingSphereRadius

public final float[] boundingSphereRadius

Bounding sphere rad for each geom in native frame of this Widget

Convention: set negative to indicate that the corresp bounding sphere is not available.

boundingSphereCenterInView

public float[][] boundingSphereCenterInView

boundingSphereCenter in view frame, alloc if desired by calling ensureBoundingSpheresInView().

Note, if this is non-null then it must have length at least numGeometries, each entry must have length at least 3, and boundingSphereCenterInView must also be non-null.

boundingSphereRadiusInView

public float[] boundingSphereRadiusInView

boundingSphereRadius in view frame, alloc if desired by calling ensureBoundingSpheresInView().

Note, if this is non-null then it must have length at least numGeometries, and boundingSphereCenterInView must also be non-null.

widgetLength

protected float widgetLength

current widget length

dbgNormalsGeometry

public JOGLGeometry dbgNormalsGeometry

DBG normal geometry if non-null, see updateDBGNormals(int, float).

dbgNormalsVertices

public java.nio.FloatBuffer dbgNormalsVertices

vertex array for dbgNormalsGeometry, if non-null

dbgSpheresGeometry

public JOGLGeometry dbgSpheresGeometry

dbg spheres geometry if non-null, see updateDBGSpheres(int)

dbgSpheresVertices

public java.nio.FloatBuffer dbgSpheresVertices

vertex array for dbgSpheresGeometry, if non-null

dbgEnabled

public boolean dbgEnabled

whether debug spheres and normals are enabled if present

propertyMap

protected java.util.Map<java.lang.String,java.lang.Object> propertyMap

the property map or null if none

Constructor Detail

Widget

public Widget(int numGeometries)

Creates a new Widget that will hold the specified number of geometries.

All geometries are initially enabled and all boundingSphereRadius are initially negative.

Widget

public Widget(javax.media.j3d.Shape3D shape3D,
      boolean extractToJOGL,
      int j3dFormatMask,
      java.io.PrintStream errorStream)

Makes a new Widget by extracting all the GeometryArrays of shape3D and its Appearance, if any.

The extracted geometries, if any, and appearance, if any, are stored by ref. No ref is retained for the shape3D itself.

Bounding spheres are automatically computed for the extracted geometries.

Parameters:

extractToJOGL - if true then an attempt will be made to JOGLGeometry.extract(javax.media.j3d.GeometryArray, int, java.io.PrintStream) each GeometryArray geometry; when successful the resulting JOGLGeometry is saved, otherwise the original geometry is saved

j3dFormatMask - see JOGLGeometry.extract(GeometryArray, int, PrintStream)

errorStream - see JOGLGeometry.extract(GeometryArray, int, PrintStream)

Widget

public Widget(javax.media.j3d.Shape3D shape3D,
      int j3dFormatMask,
      java.io.PrintStream errorStream)

covers Widget(Shape3D, boolean, int, PrintStream), sets extractToJOGL

Widget

public Widget(javax.media.j3d.Shape3D shape3D,
      int j3dFormatMask)

Covers Widget(Shape3D, boolean, int, PrintStream), sets extractToJOGL, no error stream.

Widget

public Widget(javax.media.j3d.Shape3D shape3D)

Covers Widget(Shape3D, boolean, int, PrintStream), sets extractToJOGL, no error stream, extracts all vertex components.

Method Detail

cons

public static Widget cons(java.lang.String type)

Generic factory method to construct Widget subclass instances.

Parameters:

type - identifies a Widget sub-class, i.e. a class vona.j3d.<i>Type</i>Widget, where Type is type with the first character, if any, capitalized

Throws:

java.lang.IllegalArgumentException - if type does not identify a known Widget subclass with a no-arg constructor.

java.lang.IllegalStateException - if there was a problem instantiating the new Widget

countGeometryArrays

protected static int countGeometryArrays(javax.media.j3d.Shape3D shape3D)

count the number of GeometryArrays in shape3D

populateFrom

protected void populateFrom(javax.media.j3d.Shape3D shape3D,
                boolean extractToJOGL,
                int j3dFormatMask,
                java.io.PrintStream errorStream)

impl of Widget(Shape3D, boolean, int, PrintStream)

setGeometry

public javax.media.j3d.Geometry setGeometry(int index,
                                   javax.media.j3d.Geometry geometry)

Set the geometry at the specified index.

This also

• makes a new J3DPrimitiveIterator for geometry and stores it in primitiveIterator[index], iff geometry is a JOGLGeometry or a GeometryArray
• stores a reference to the J3DVertexAccessor of the primitive iterator in vertexAccessor[index]
• the boundingSphereCenter and boundingSphereRadius at index are not modified
• the user data field of geometry is set to reference this Widget iff it was null
• sets enabled[index] iff geometry not null

Parameters:

geometry - may be null

Returns:

the old value

getGeometry

public javax.media.j3d.Geometry getGeometry(int index)

get a reference to the geometry at indicated index

removeGeometry

public javax.media.j3d.Geometry removeGeometry(int index)

Remove (null) geometry at indicated index.

removeGeometry

public int removeGeometry(javax.media.j3d.Geometry geometry)

Remove (null) indicated geometry, iff found.

replaceGeometryWithClone

public javax.media.j3d.Geometry replaceGeometryWithClone(int index)

Replace the indicated geometry with a clone of itself.

Returns:

the original geometry instance

Throws:

java.lang.IllegalStateException - if the geometry is a JOGLGeometry for which clone is TBD

getWidget

public static Widget getWidget(javax.media.j3d.Geometry geometry)

Convenience to get the Widget containing geometry by following the user data ref on geometry.

Returns:

the Widget or null if the user data was not set to a Widget

indexOf

public int indexOf(javax.media.j3d.Geometry geometry)

Lookup the index of geometry in this Widget.

Returns:

the index or negative if not found

setAppearance

public javax.media.j3d.Appearance setAppearance(int index,
                                       javax.media.j3d.Appearance appearance)

Set a the appearance at indicated index by ref.

Returns:

the old value

getAppearance

public javax.media.j3d.Appearance getAppearance(int index)

get a reference to the appearance at indicated index

replaceAppearanceWithClone

public javax.media.j3d.Appearance replaceAppearanceWithClone(int index)

similar to replaceGeometryWithClone(int)

setGeometryAndAppearance

public void setGeometryAndAppearance(int index,
                            javax.media.j3d.Geometry geometry,
                            javax.media.j3d.Appearance appearance)

setGeometry(int, javax.media.j3d.Geometry) and appearance at the specified index

setGeometryAlpha

public void setGeometryAlpha(int index,
                    float alpha)

set transparency alpha for a particular geometry

setGeometryAlpha

public void setGeometryAlpha(float alpha)

convenience to setGeometryAlpha(int, float) on all geometries

setWidgetAlpha

public void setWidgetAlpha(float alpha)

set alpha

getWidgetAlpha

public float getWidgetAlpha()

get alpha

setBoundingSphereRadius

public void setBoundingSphereRadius(int index,
                           float radius)

set the boundingSphereRadius at index

getBoundingSphereRadius

public float getBoundingSphereRadius(int index)

get the boundingSphereRadius at index

setBoundingSphereCenter

public void setBoundingSphereCenter(int index,
                           float... center)

set boundingSphereCenter at index by copy

getBoundingSphereCenter

public float[] getBoundingSphereCenter(int index)

get a reference to boundingSphereCenter at index

disableBoundingSphere

public void disableBoundingSphere(int index)

disable the bounding sphere at index by setting its radius -1

disableBoundingSpheres

public void disableBoundingSpheres()

Disable all bounding spheres and turn off autoSetBoundingSpheres.

hasBoundingSphere

public boolean hasBoundingSphere(int index)

Check if the geometry at index has a non-negative boundingSphereRadius.

hasBoundingSphereInView

public boolean hasBoundingSphereInView(int index)

Check if view-frame bounding spheres are allocated and that the geometry at index has a n-negative boundingSphereRadiusInView.

ensureBoundingSpheresInView

public void ensureBoundingSpheresInView()

Cons boundingSphereCenterInView and boundingSphereRadiusInView iff necessary.

updateDBGNormals

public void updateDBGNormals(int upToGeometry,
                    float normalLength)

Create or update the dbgNormalsGeometry which shows line segments for each normal in each geometry.

Parameters:

upToGeometry - only make dbg normals for geometry up to this index, or negative to update already exisiting normals

normalLength - the length of the normal lines, non-positive to use DEF_DBG_NORMAL_LENGTH, NaN to use length of first existing normal, if any

updateAllDBGNormals

public void updateAllDBGNormals(float normalLength)

updateDBGNormals(int, float) for all geometry, creating them if they don't yet exist.

updateDBGNormals

public void updateDBGNormals(int upToGeometry)

updateDBGNormals(int, float) using DEF_DBG_NORMAL_LENGTH.

updateAllDBGNormals

public void updateAllDBGNormals()

updateDBGNormals(int, float) for all geometry, creating them if they don't yet exist, using DEF_DBG_NORMAL_LENGTH.

updateExistingDBGNormals

public void updateExistingDBGNormals()

updateDBGNormals(int, float) that already exist, using length of first existing one.

removeDBGNormals

public void removeDBGNormals()

remove any debug normals

updateDBGSpheres

public void updateDBGSpheres(int upToGeometry)

Create or update the dbgSpheresGeometry which shows the bounding spheres for each geometry.

Parameters:

upToGeometry - only make or update dbg spheres for geometry up to this index, or negative to only update already existing spheres, if any

updateAllDBGSpheres

public void updateAllDBGSpheres()

updateDBGSpheres(int) for all geometry

updateExistingDBGSpheres

public void updateExistingDBGSpheres()

updateDBGSpheres(int) only existing

removeDBGSpheres

public void removeDBGSpheres()

remove any debug spheres

enableDBGGeometry

public void enableDBGGeometry(boolean enable)

Enable or disable debug spheres and normals.

You still have to compute them by calling updateDBGNormals(int, float) and/or updateDBGSpheres(int) as desired.

enableGeometry

public void enableGeometry(int index,
                  boolean enable)

set the enabled flag for geometry at index

setProperty

public java.lang.Object setProperty(java.lang.String key,
                           java.lang.Object value,
                           boolean replace)

Set a property.

Parameters:

replace - whether to replace the value if the key is already present

Returns:

the prior value

setProperty

public java.lang.Object setProperty(java.lang.String key,
                           java.lang.Object value)

covers setProperty(String, Object, boolean), replaces

removeProperty

public java.lang.Object removeProperty(java.lang.String key)

remove a property

getProperty

public java.lang.Object getProperty(java.lang.String key)

get a property

hasProperty

public boolean hasProperty(java.lang.String key)

check existence of a property

setWidgetLength

public void setWidgetLength(float widgetLength)

Set widgetLength, calls widgetLengthChanged() iff different.

trackWidgetLength

public void trackWidgetLength(float... trackFactor)

Subclasses may implement this to store factors that map widgetLength to their parameters.

Default impl does nothing.

dump

public void dump(java.io.PrintStream s)

dump widget details

dump

public void dump()

dump(PrintStream) to System.out

widgetLengthChanged

protected void widgetLengthChanged()

called by setWidgetLength(float) after the length has changed

recomputeBoundingSphere

public void recomputeBoundingSphere(int index)

Recompute boundingSphereCenter and boundingSphereRadius for geometry at index, using vertexAccessor at index, if present.

This will change the state of the vertex accessor.

recomputeBoundingSpheres

public void recomputeBoundingSpheres()

recomputeBoundingSphere(int) for each geometry

scaleWidget

public void scaleWidget(float scale)

Apply a scale factor in-place to this widget.

Current impl only works if all geometry are JOGLGeometry.

Throws:

java.lang.IllegalStateException - if any geometry is not a JOGLGeometry