J3DPrimitiveIterator

java.lang.Object
- vona.j3d.J3DPrimitiveIterator

Direct Known Subclasses:

J3DPrimitiveIterator.J3DStripIterator
```
public class J3DPrimitiveIterator
extends java.lang.Object
```
Read primitives in a JOGLGeometry or a Java3D GeometryArray.

Provides an abstraction layer above the numerous vertex formats and data storage options available in Java3D.

A primitive iterator is not ready until it has been reset(...) at least once with valid parameters. Normally an iterator of the correct type is acquired from the factory cons(...), which also performs an initial reset.

The first call to next() will load the enabled and present components of the first primitive into texCoord, color, normal, and coord (which are also referenced by component. Subsequent calls will load subsequent primitives until hasNext(int) returns false, at which point all primitives have been read.

The vertices of quad and triangle primitives are always presented in CCW order around the outside face of the primitive.

GL_POLYGON primitives are treated as triangle fans.

Most operations return this to facilitate operation chaining.

TBD
- test point geometries
- test GL_LINE_LOOP and GL_POLYGON
- test indexed geometry
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

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`J3DPrimitiveIterator.J3DLineStripIterator` This impl iterates line strips.
`static class`	`J3DPrimitiveIterator.J3DStripIterator` This is a base impl for stripped geometry.
`static class`	`J3DPrimitiveIterator.J3DTriangleFanIterator` This impl iterates triangle fans.
`static class`	`J3DPrimitiveIterator.J3DTriangleStripIterator` This impl iterates triangle strips.
`static class`	`J3DPrimitiveIterator.JOGLQuadStripIterator` This impl iterates quad strips.

Field Summary

Fields
Modifier and Type	Field and Description
`float[][]`	`color` Most recently read color per vertex, null if not reading this component, NaN if first vertex not yet read.
`float[][][]`	`component` References `texCoord`, `color`, `normal`, `coord`.
`float[][]`	`coord` Most recently read coordinates per vertex, null if not reading this component, NaN if first vertex not yet read.
`private static java.lang.String`	`cvsid`
`int`	`enabledVertexCount` Number of enabled vertices.
`protected javax.media.j3d.GeometryArray`	`ga` currently referenced `GeometryArray`, if any
`protected JOGLGeometry`	`jg` currently referenced `JOGLGeometry`, if any
`boolean`	`loop` whether to consider each strip a loop
`float[][]`	`normal` Most recently read normal per vertex, null if not reading this component, NaN if first vertex not yet read.
`int`	`numEnabledStrips` Number of enabled strips.
`int`	`numStrips` number of strips, or 0 if `ga` is not stripped
`protected float[]`	`pickB` workspace for `pickLine(float[], float[], float, int)`
`protected float[]`	`pickU` workspace for `pickLine(float[], float[], float, int)`
`int`	`prim` current primitive index
`int`	`primCount` total number of primitives
`int`	`primInStrip` current primitive index in current strip
`int`	`primsInStrip` number of prims in current strip
`private static J3DPrimitiveIterator[]`	`protos` set of prototype implementations for `cons(javax.media.j3d.GeometryArray, boolean...)`
`int`	`strip` current strip index
`float[][]`	`texCoord` Most recently read texture coordinates per vertex, null if not reading this component, NaN if first vertex not yet read.
`int`	`validVertexCount` number of valid vertices (or valid indices if `ga` is indexed)
`J3DVertexAccessor`	`vertexAccessor` current vertex accessor
`int`	`vertsInStrip` number of vertices in current strip
`int`	`vertsPerPrim` vertices per prim
`int`	`vertsPerStripPrim` vertices per strip prim

Constructor Summary

Constructors
Constructor and Description

J3DPrimitiveIterator()

Constructors
Constructor and Description
`J3DPrimitiveIterator()`

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`checkFormat(javax.media.j3d.GeometryArray ga)` Check if the class, storage type, and vertex format of ga is compatible with this implementation.
`boolean`	`checkFormat(JOGLGeometry jg)` similar to `checkFormat(GeometryArray)`
`static J3DPrimitiveIterator`	`cons(javax.media.j3d.GeometryArray ga, boolean... enableComponent)` Factory method to cons a new iterator of the appropriate type for the class, storage type, and vertex format of ga.
`static J3DPrimitiveIterator`	`cons(JOGLGeometry jg, boolean... enableComponent)` similar to `cons(GeometryArray, boolean...)`
`static J3DPrimitiveIterator[]`	`consAll()` covers `consAll(J3DPrimitiveIterator[])`, makes a new array
`static J3DPrimitiveIterator[]`	`consAll(J3DPrimitiveIterator[] impls)` Cons a new instance of each available implementation.
`protected void`	`copyFromAccessor(int v)` copy all components of vertex v with the accessor
`void`	`dump(java.io.PrintStream s)` dump current state
`static int`	`getNumImplementations()` get the number of available implementations
`java.lang.String`	`getPrimName()` get the name of the prim type based on `vertsPerPrim`
`java.lang.String`	`getPrimsName()` plural of `getPrimName()`
`boolean`	`hasNext()` covers `hasNext(int)` with num = 1
`boolean`	`hasNext(int num)` Check if the next num subsequent calls to `next()` will succeed.
`protected J3DPrimitiveIterator`	`newInstance()` make a new instance of this implementation
`J3DPrimitiveIterator`	`next()` read the next primitive
`float`	`pick(float[] pickStart, float[] pickExtent, float threshold, int cullFace)` Compute a pick intersection with the current primitive.
`float`	`pickLine(float[] pickStart, float[] pickExtent, float threshold, int cullFace)` `pick(float[], float[], float, int)` assuming that the primitive is a line segment.
`float`	`pickPoint(float[] pickStart, float[] pickExtent, float threshold, int cullFace)` `pick(float[], float[], float, int)` assuming that the primitive is a point.
`float`	`pickQuad(float[] pickStart, float[] pickExtent, float threshold, int cullFace)` `pick(float[], float[], float, int)` assuming that the primitive is a quad.
`float`	`pickTriangle(float[] pickStart, float[] pickExtent, float threshold, int cullFace)` `pick(float[], float[], float, int)` assuming that the primitive is a triangle.
`J3DPrimitiveIterator`	`reset()` reset internal indices but continue referencing current `ga`
`J3DPrimitiveIterator`	`reset(javax.media.j3d.GeometryArray ga, boolean... enableComponent)` Reset this iterator so that the subsequent call to `next()` reads the first primitive in ga.
`J3DPrimitiveIterator`	`reset(JOGLGeometry jg, boolean... enableComponent)` similar to `reset(GeometryArray, boolean...)`
`protected J3DPrimitiveIterator`	`resetImpl(boolean... enableComponent)` Common impl of `reset(GeometryArray, boolean...)` and `reset(JOGLGeometry, boolean...)`.
`protected void`	`swap(int v0, int v1)` swap all components of vertices v0 and v1

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
  - strip
```
public int strip
```
    current strip index
  - prim
```
public int prim
```
    current primitive index
  - primInStrip
```
public int primInStrip
```
    current primitive index in current strip
  - primsInStrip
```
public int primsInStrip
```
    number of prims in current strip
  - vertsInStrip
```
public int vertsInStrip
```
    number of vertices in current strip
  - vertsPerPrim
```
public int vertsPerPrim
```
    vertices per prim
  - vertsPerStripPrim
```
public int vertsPerStripPrim
```
    vertices per strip prim
  - numStrips
```
public int numStrips
```
    number of strips, or 0 if ga is not stripped
  - loop
```
public boolean loop
```
    whether to consider each strip a loop
  - numEnabledStrips
```
public int numEnabledStrips
```
    Number of enabled strips.
    
    This will be the same as numStrips except when iterating a JOGLGeometry that contains negative array counts.
  - validVertexCount
```
public int validVertexCount
```
    number of valid vertices (or valid indices if ga is indexed)
  - enabledVertexCount
```
public int enabledVertexCount
```
    Number of enabled vertices.
    
    This will be the same as validVertexCount except when iterating a JOGLGeometry that contains negative array counts.
  - primCount
```
public int primCount
```
    total number of primitives
  - texCoord
```
public float[][] texCoord
```
    Most recently read texture coordinates per vertex, null if not reading this component, NaN if first vertex not yet read.
    
    If non-null, length [2-4] gives texture space dimension.
  - color
```
public float[][] color
```
    Most recently read color per vertex, null if not reading this component, NaN if first vertex not yet read.
    
    If non-null, length (3 or 4) gives color space dimension.
  - normal
```
public float[][] normal
```
    Most recently read normal per vertex, null if not reading this component, NaN if first vertex not yet read.
  - coord
```
public float[][] coord
```
    Most recently read coordinates per vertex, null if not reading this component, NaN if first vertex not yet read.
  - component
```
public float[][][] component
```
    References texCoord, color, normal, coord.
  - ga
```
protected javax.media.j3d.GeometryArray ga
```
    currently referenced GeometryArray, if any
  - jg
```
protected JOGLGeometry jg
```
    currently referenced JOGLGeometry, if any
  - vertexAccessor
```
public J3DVertexAccessor vertexAccessor
```
    current vertex accessor
  - pickB
```
protected final float[] pickB
```
    workspace for pickLine(float[], float[], float, int)
  - pickU
```
protected final float[] pickU
```
    workspace for pickLine(float[], float[], float, int)
  - protos
```
private static final J3DPrimitiveIterator[] protos
```
    set of prototype implementations for cons(javax.media.j3d.GeometryArray, boolean...)
- Constructor Detail
  - J3DPrimitiveIterator
```
public J3DPrimitiveIterator()
```
- Method Detail
  - getNumImplementations
```
public static int getNumImplementations()
```
    get the number of available implementations
  - consAll
```
public static J3DPrimitiveIterator[] consAll(J3DPrimitiveIterator[] impls)
```
    Cons a new instance of each available implementation.
    
    Parameters:
    impls - if non-null and at least length getNumImplementations() the new instances are collected here, else a new array is consed
    
    Returns:
    an array whose first getNumImplementations() elements are set to instances of each available implementation
  - consAll
```
public static J3DPrimitiveIterator[] consAll()
```
    covers consAll(J3DPrimitiveIterator[]), makes a new array
  - cons
```
public static J3DPrimitiveIterator cons(javax.media.j3d.GeometryArray ga,
                        boolean... enableComponent)
```
    Factory method to cons a new iterator of the appropriate type for the class, storage type, and vertex format of ga.
    
    The returned iterator is newly consed and already reset(GeometryArray, boolean...) given the passed parameters. It may be re-used by further reset()s.
  - cons
```
public static J3DPrimitiveIterator cons(JOGLGeometry jg,
                        boolean... enableComponent)
```
    similar to cons(GeometryArray, boolean...)
  - reset
```
public J3DPrimitiveIterator reset(javax.media.j3d.GeometryArray ga,
                         boolean... enableComponent)
```
    Reset this iterator so that the subsequent call to next() reads the first primitive in ga.
    
    Parameters:
    ga - the geometry, or null to clear the previous internal reference
    enableComponent - see J3DVertexAccessor.reset(GeometryArray, boolean...)
    
    Returns:
    a reference to this J3DPrimitiveIterator
    
    Throws:
    
    java.lang.IllegalArgumentException - if ga is non-null and fails checkFormat(javax.media.j3d.GeometryArray)
  - reset
```
public J3DPrimitiveIterator reset(JOGLGeometry jg,
                         boolean... enableComponent)
```
    similar to reset(GeometryArray, boolean...)
  - resetImpl
```
protected J3DPrimitiveIterator resetImpl(boolean... enableComponent)
```
    Common impl of reset(GeometryArray, boolean...) and reset(JOGLGeometry, boolean...).
  - reset
```
public J3DPrimitiveIterator reset()
```
    reset internal indices but continue referencing current ga
  - hasNext
```
public boolean hasNext(int num)
```
    Check if the next num subsequent calls to next() will succeed.
  - hasNext
```
public boolean hasNext()
```
    covers hasNext(int) with num = 1
  - next
```
public J3DPrimitiveIterator next()
```
    read the next primitive
  - getPrimName
```
public java.lang.String getPrimName()
```
    get the name of the prim type based on vertsPerPrim
  - getPrimsName
```
public java.lang.String getPrimsName()
```
    plural of getPrimName()
  - dump
```
public void dump(java.io.PrintStream s)
```
    dump current state
  - pick
```
public float pick(float[] pickStart,
         float[] pickExtent,
         float threshold,
         int cullFace)
```
    Compute a pick intersection with the current primitive.
    
    A threshold is provided to compare the perpendicular distance from the pick segment to the primitive for lines and points. The threshold is ignored for all two-dimensional primitives.
    
    Parameters:
    pickStart - the start 3D coordinates of the pick segment in the same coordinate frame as the geometry of this iterator
    pickExtent - the 3D extension vector from pickStart of the pick segment in the same coordinate frame as the geometry of this iterator
    threshold - the pick threshold, or NaN for none, see above
    
    Returns:
    the signed coordinate of the intersection along the pick segment, normalized to the segment length, or NaN if no intersection
  - pickPoint
```
public float pickPoint(float[] pickStart,
              float[] pickExtent,
              float threshold,
              int cullFace)
```
    pick(float[], float[], float, int) assuming that the primitive is a point.
  - pickLine
```
public float pickLine(float[] pickStart,
             float[] pickExtent,
             float threshold,
             int cullFace)
```
    pick(float[], float[], float, int) assuming that the primitive is a line segment.
  - pickTriangle
```
public float pickTriangle(float[] pickStart,
                 float[] pickExtent,
                 float threshold,
                 int cullFace)
```
    pick(float[], float[], float, int) assuming that the primitive is a triangle.
  - pickQuad
```
public float pickQuad(float[] pickStart,
             float[] pickExtent,
             float threshold,
             int cullFace)
```
    pick(float[], float[], float, int) assuming that the primitive is a quad.
  - checkFormat
```
public boolean checkFormat(javax.media.j3d.GeometryArray ga)
```
    Check if the class, storage type, and vertex format of ga is compatible with this implementation.
  - checkFormat
```
public boolean checkFormat(JOGLGeometry jg)
```
    similar to checkFormat(GeometryArray)
  - newInstance
```
protected J3DPrimitiveIterator newInstance()
```
    make a new instance of this implementation
  - swap
```
protected void swap(int v0,
        int v1)
```
    swap all components of vertices v0 and v1
  - copyFromAccessor
```
protected void copyFromAccessor(int v)
```
    copy all components of vertex v with the accessor

Class J3DPrimitiveIterator

TBD

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

cvsid

strip

prim

primInStrip

primsInStrip

vertsInStrip

vertsPerPrim

vertsPerStripPrim

numStrips

loop

numEnabledStrips

validVertexCount

enabledVertexCount

primCount

texCoord

color

normal

coord

component

ga

jg

vertexAccessor

pickB

pickU

protos

Constructor Detail

J3DPrimitiveIterator

Method Detail

getNumImplementations

consAll

consAll

cons

cons

reset

reset

resetImpl

reset

hasNext

hasNext

next

getPrimName

getPrimsName

dump

pick

pickPoint

pickLine

pickTriangle

pickQuad

checkFormat

checkFormat

newInstance

swap

copyFromAccessor