J3DVertexAccessor

java.lang.Object
- vona.j3d.J3DVertexAccessor

Direct Known Subclasses:

J3DVertexAccessor.J3DBufferVertexAccessor, J3DVertexAccessor.J3DCopyVertexAccessor, J3DVertexAccessor.J3DInterleavedBufferVertexAccessor, J3DVertexAccessor.J3DInterleavedVertexAccessor, J3DVertexAccessor.J3DRefVertexAccessor
```
public abstract class J3DVertexAccessor
extends java.lang.Object
```
Read/write vertices in a JOGLGeometry or a Java3D GeometryArray.

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

Random access is provided through the seek() and read() APIs, and sequential access is provided through the next() method. The one-argument seek(int) and read(int) methods address the valid vertex range, with the first valid vertex at index 0. The multi-argument seek(int, int, int, int) and read(int, int, int, int) methods address the entire vertex storage area, potentially allowing different indices for the vertex components for non-interleaved formats.

If the geometry is indexed, setIndirect(boolean) may be called to install an appropriate J3DIndexAccessor which will then be used to map vertex index indices to vertex indices. The semantics of seek(int), read(int), next(), and hasNext(...) are then changed to deal in the valid set of vertex index indices.

Sequential access starts from the first vertex after the last-accessed vertex, or from the first valid vertex if no accesses have been performed yet. Repeated sequential access will return each vertex in storage (index) order.

A vertex accessor is not ready until it has been reset(...) at least once with valid parameters. Normally an accessor of the correct type is acquired from the factory cons(...), which also performs an initial reset. It is not correct to do a relative read() immediately after reset; instead do an absolute read(...) or next() first.

Note that vertexCount, validVertexCount and initialIndex are cached at reset(...), and if any of these parameters changes in the underlying geometry it is the caller's responsibility to call reset(...) again.

The component data for the currently indexed vertex may be mutated and then written back via a call to write(). Writes are not internally synchronized with the Java3D threads; the caller is responsible for using a GeometryUpdater or other synchronization for mutating live or compiled geometries.

Note that data reads and writes will throw the appropriate exception if the underlying storage does not allow the operation.

Most operations return this to facilitate operation chaining.

TBD:
- multitextures
- vertex attributes
- byte color components
Copyright (C) 2008 Marsette A. Vona, III
Author:

Marsette A. Vona, III

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`J3DVertexAccessor.J3DBufferVertexAccessor` This impl handles NIO non-interleaved by-ref vertex storage.
`static class`	`J3DVertexAccessor.J3DCopyVertexAccessor` This impl handles by-copy vertex storage.
`static class`	`J3DVertexAccessor.J3DInterleavedBufferVertexAccessor` This impl handles NIO interleaved vertex storage, both for `JOGLGeometry` and `GeometryArray`.
`static class`	`J3DVertexAccessor.J3DInterleavedVertexAccessor` This impl handles non-NIO interleaved by-ref vertex storage.
`static class`	`J3DVertexAccessor.J3DRefVertexAccessor` This impl handles non-NIO and non-interleaved by-ref vertex storage.

Field Summary

Fields
Modifier and Type	Field and Description
`float[]`	`color` Current color, or null if none.
`static int`	`COLOR` index of `color` in `component`
`protected float[]`	`color3` storage for `color`
`protected float[]`	`color4` storage for `color`
`float[][]`	`component` array of refs to the individual component arrays
`protected int[]`	`componentIndex` access index for each component
`float[]`	`coord` current coords or null if none (order XYZ)
`static int`	`COORD` index of `coord` in `component`
`protected float[]`	`coord3` storage for `coord`
`private static java.lang.String`	`cvsid`
`protected javax.media.j3d.GeometryArray`	`ga` currently referenced `GeometryArray`, if any
`protected J3DIndexAccessor`	`indexAccessor` index accessor, iff using indirect indices
`int[]`	`initialIndex` first valid index for each component
`protected JOGLGeometry`	`jg` currently referenced `JOGLGeometry`, if any
`float[]`	`normal` current normal, or null if none (order XYZ)
`static int`	`NORMAL` index of `normal` in `component`
`protected float[]`	`normal3` storage for `normal`
`private static J3DVertexAccessor[]`	`protos` set of prototype implementations for `cons(...)`
`float[]`	`texCoord` Current texture coord, or null if none.
`static int`	`TEXCOORD` index of `texCoord` in `component`
`protected float[]`	`texCoord2` storage for `texCoord`
`protected float[]`	`texCoord3` storage for `texCoord`
`protected float[]`	`texCoord4` storage for `texCoord`
`int`	`validVertexCount` number of valid vertices
`int`	`vertexCount` size of vertex storage
`int`	`vertexIndex` current position relative to initial valid vertex

Constructor Summary

Constructors
Constructor and Description

J3DVertexAccessor()

Constructors
Constructor and Description
`J3DVertexAccessor()`

Method Summary

Methods
Modifier and Type	Method and Description
`J3DVertexAccessor`	`advance(int num)` `seek(int)` relative to `vertexIndex`
`abstract boolean`	`checkFormat(javax.media.j3d.GeometryArray ga)` Check if the class, storage type, and vertex format of ga is compatible with this accessor implementation.
`boolean`	`checkFormat(JOGLGeometry jg)` Similar to `checkFormat(GeometryArray)`.
`float`	`computeBoundingSphere(float[] center)` Compute the center and radius of a bounding sphere which encloses all valid vertices.
`static J3DVertexAccessor`	`cons(javax.media.j3d.GeometryArray ga, boolean... enableComponent)` Factory method to cons a new accessor of the appropriate type for the class, storage type, and vertex format of ga.
`static J3DVertexAccessor`	`cons(JOGLGeometry jg, boolean... enableComponent)` similar to `cons(GeometryArray, boolean...)`
`static J3DVertexAccessor[]`	`consAll()` covers `consAll(J3DVertexAccessor[])`, makes a new array
`static J3DVertexAccessor[]`	`consAll(J3DVertexAccessor[] impls)` Cons a new instance of each available implementation.
`static int`	`getNumImplementations()` get the number of available implementations
`boolean`	`hasNext()` covers `hasNext(int)` with num = 1
`boolean`	`hasNext(int num)` Check if the next num subsequent calls to `next()` will read vertices at or before the end of the valid vertex range.
`boolean`	`isIndirect()` check if using indirect indices
`abstract J3DVertexAccessor`	`newInstance()` make a new instance of this accessor implementation
`J3DVertexAccessor`	`next()` incr `componentIndex` and `vertexIndex`, `read(int)`
`abstract J3DVertexAccessor`	`read()` Access the vertex storage and read the enabled vertex components at `componentIndex`.
`J3DVertexAccessor`	`read(int index)` convenience cover `seek(int)`, `read()`
`J3DVertexAccessor`	`read(int coordIndex, int normalIndex, int colorIndex, int texCoordIndex)` convenience cover `seek(int, int, int, int)`, `read(int)`
`J3DVertexAccessor`	`reset()` reset internal indices but continue referencing current geometry
`J3DVertexAccessor`	`reset(javax.media.j3d.GeometryArray ga, boolean... enableComponent)` Reset this accessor so that the subsequent call to `next()` reads the first valid vertex in ga.
`J3DVertexAccessor`	`reset(JOGLGeometry jg, boolean... enableComponent)` similar to `reset(GeometryArray, boolean...)`
`protected J3DVertexAccessor`	`resetImpl(int vf, boolean... enableComponent)` Common impl of `reset(GeometryArray, boolean...)` and `reset(JOGLGeometry, boolean...)`.
`J3DVertexAccessor`	`scaleAll(float scale)` `scaleVertex(float)` all valid vertices.
`J3DVertexAccessor`	`scaleVertex(float scale)` Apply a uniform scale factor to the current `coord` and then `write()`.
`J3DVertexAccessor`	`seek(int index)` Reposition the internal pointer(s) so that the subsequent `read()` or `write()` will access vertex index relative to the first valid vertex.
`J3DVertexAccessor`	`seek(int coordIndex, int normalIndex, int colorIndex, int texCoordIndex)` Reposition the internal pointer(s) so that the subsequent call to `read()` or `write()` will access the indicated coord and normal components relative to the start of their respective storage.
`J3DVertexAccessor`	`seek(J3DIndexAccessor indexAccessor)` `seek(int, int, int, int)` to the pos of indexAccessor
`J3DVertexAccessor`	`setIndexAccessor(J3DIndexAccessor indexAccessor)` directly set the index accessor, making this vertex accessor indirect
`boolean`	`setIndirect(boolean indirect)` Set whether to use indirect indices, if available.
`abstract J3DVertexAccessor`	`write()` Access the vertex storage and write the enabled vertex components.

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
  - TEXCOORD
```
public static final int TEXCOORD
```
    index of texCoord in component
    
    See Also:
    Constant Field Values
  - COLOR
```
public static final int COLOR
```
    index of color in component
    
    See Also:
    Constant Field Values
  - NORMAL
```
public static final int NORMAL
```
    index of normal in component
    
    See Also:
    Constant Field Values
  - COORD
```
public static final int COORD
```
    index of coord in component
    
    See Also:
    Constant Field Values
  - vertexIndex
```
public int vertexIndex
```
    current position relative to initial valid vertex
  - vertexCount
```
public int vertexCount
```
    size of vertex storage
  - validVertexCount
```
public int validVertexCount
```
    number of valid vertices
  - initialIndex
```
public int[] initialIndex
```
    first valid index for each component
  - texCoord
```
public float[] texCoord
```
    Current texture coord, or null if none.
    
    If non-null, length [2-4] gives texture space dimension.
  - color
```
public float[] color
```
    Current color, or null if none.
    
    If non-null, length (3 or 4) gives number of color components, order RGB(A).
  - normal
```
public float[] normal
```
    current normal, or null if none (order XYZ)
  - coord
```
public float[] coord
```
    current coords or null if none (order XYZ)
  - component
```
public float[][] component
```
    array of refs to the individual component arrays
  - ga
```
protected javax.media.j3d.GeometryArray ga
```
    currently referenced GeometryArray, if any
  - jg
```
protected JOGLGeometry jg
```
    currently referenced JOGLGeometry, if any
  - componentIndex
```
protected int[] componentIndex
```
    access index for each component
  - indexAccessor
```
protected J3DIndexAccessor indexAccessor
```
    index accessor, iff using indirect indices
  - texCoord4
```
protected float[] texCoord4
```
    storage for texCoord
  - texCoord3
```
protected float[] texCoord3
```
    storage for texCoord
  - texCoord2
```
protected float[] texCoord2
```
    storage for texCoord
  - color4
```
protected float[] color4
```
    storage for color
  - color3
```
protected float[] color3
```
    storage for color
  - normal3
```
protected float[] normal3
```
    storage for normal
  - coord3
```
protected float[] coord3
```
    storage for coord
  - protos
```
private static final J3DVertexAccessor[] protos
```
    set of prototype implementations for cons(...)
- Constructor Detail
  - J3DVertexAccessor
```
public J3DVertexAccessor()
```
- Method Detail
  - getNumImplementations
```
public static int getNumImplementations()
```
    get the number of available implementations
  - consAll
```
public static J3DVertexAccessor[] consAll(J3DVertexAccessor[] 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 J3DVertexAccessor[] consAll()
```
    covers consAll(J3DVertexAccessor[]), makes a new array
  - cons
```
public static J3DVertexAccessor cons(javax.media.j3d.GeometryArray ga,
                     boolean... enableComponent)
```
    Factory method to cons a new accessor of the appropriate type for the class, storage type, and vertex format of ga.
    
    The returned accessor is newly consed and already reset(GeometryArray, boolean...) given the passed parameters. It may be re-used by further reset()s.
  - cons
```
public static J3DVertexAccessor cons(JOGLGeometry jg,
                     boolean... enableComponent)
```
    similar to cons(GeometryArray, boolean...)
  - reset
```
public J3DVertexAccessor reset(javax.media.j3d.GeometryArray ga,
                      boolean... enableComponent)
```
    Reset this accessor so that the subsequent call to next() reads the first valid vertex in ga.
    
    Parameters:
    ga - the geometry, or null to clear the previous internal reference
    enableComponent - list or array of booleans enabling access to vertex components, iff present in ga, in order texCoord, color, normal, coord. If less than four booleans are provided the latter ones are assumed true.
    
    Returns:
    a reference to this J3DVertexAccessor
    
    Throws:
    
    java.lang.IllegalArgumentException - if ga is non-null and fails checkFormat(javax.media.j3d.GeometryArray)
  - reset
```
public J3DVertexAccessor reset(JOGLGeometry jg,
                      boolean... enableComponent)
```
    similar to reset(GeometryArray, boolean...)
  - resetImpl
```
protected J3DVertexAccessor resetImpl(int vf,
                          boolean... enableComponent)
```
    Common impl of reset(GeometryArray, boolean...) and reset(JOGLGeometry, boolean...).
  - reset
```
public J3DVertexAccessor reset()
```
    reset internal indices but continue referencing current geometry
  - setIndirect
```
public boolean setIndirect(boolean indirect)
```
    Set whether to use indirect indices, if available.
    
    Indirect indices are available iff ga is an IndexedGeometryArray or jg has an index buffer. If available, indirect indices are activated by allocating indexAccessor. Subsequent seek(int), read(int), next(), and hasNext(...) calls will then indirect through indexAccessor.
    
    Returns:
    true iff indirect indices were requested and available
  - isIndirect
```
public boolean isIndirect()
```
    check if using indirect indices
  - setIndexAccessor
```
public J3DVertexAccessor setIndexAccessor(J3DIndexAccessor indexAccessor)
```
    directly set the index accessor, making this vertex accessor indirect
  - seek
```
public J3DVertexAccessor seek(int index)
```
    Reposition the internal pointer(s) so that the subsequent read() or write() will access vertex index relative to the first valid vertex.
    
    If using indirect indices then index is instead the index of the index of the vertex.
    
    Parameters:
    index - the index of the vertex (or vertex index) to access, with the first valid vertex (vertex index) at index 0 (may be outside the valid range)
  - advance
```
public J3DVertexAccessor advance(int num)
```
    seek(int) relative to vertexIndex
  - seek
```
public J3DVertexAccessor seek(int coordIndex,
                     int normalIndex,
                     int colorIndex,
                     int texCoordIndex)
```
    Reposition the internal pointer(s) so that the subsequent call to read() or write() will access the indicated coord and normal components relative to the start of their respective storage.
    
    vertexIndex is also updated based on coord.
  - seek
```
public J3DVertexAccessor seek(J3DIndexAccessor indexAccessor)
```
    seek(int, int, int, int) to the pos of indexAccessor
  - read
```
public J3DVertexAccessor read(int index)
```
    convenience cover seek(int), read()
  - read
```
public J3DVertexAccessor read(int coordIndex,
                     int normalIndex,
                     int colorIndex,
                     int texCoordIndex)
```
    convenience cover seek(int, int, int, int), read(int)
  - read
```
public abstract J3DVertexAccessor read()
```
    Access the vertex storage and read the enabled vertex components at componentIndex.
    
    Note: if the internal indices for the access are outside the legal bounds for the vertex storage then the underlying access method will throw an exception according to the storage type.
  - hasNext
```
public boolean hasNext(int num)
```
    Check if the next num subsequent calls to next() will read vertices at or before the end of the valid vertex range.
    
    Note that this can include an invalid vertex before the start of the valid range, if that is the current position of the accessor.
    
    If using indirect indices then this chains instead to J3DIndexAccessor.hasNext(int) on indexAccessor.
  - hasNext
```
public boolean hasNext()
```
    covers hasNext(int) with num = 1
  - next
```
public J3DVertexAccessor next()
```
    incr componentIndex and vertexIndex, read(int)
  - write
```
public abstract J3DVertexAccessor write()
```
    Access the vertex storage and write the enabled vertex components.
    
    Note: if the internal indices for the access are outside the legal bounds for the vertex storage then the underlying access method will throw an exception according to the storage type.
  - scaleVertex
```
public J3DVertexAccessor scaleVertex(float scale)
```
    Apply a uniform scale factor to the current coord and then write().
  - scaleAll
```
public J3DVertexAccessor scaleAll(float scale)
```
    scaleVertex(float) all valid vertices.
    
    The accessor is reset(javax.media.j3d.GeometryArray, boolean...) at the beginning of the computation, but not afterwards.
  - checkFormat
```
public abstract boolean checkFormat(javax.media.j3d.GeometryArray ga)
```
    Check if the class, storage type, and vertex format of ga is compatible with this accessor implementation.
  - checkFormat
```
public boolean checkFormat(JOGLGeometry jg)
```
    Similar to checkFormat(GeometryArray).
    
    Default impl returns false.
  - computeBoundingSphere
```
public float computeBoundingSphere(float[] center)
```
    Compute the center and radius of a bounding sphere which encloses all valid vertices.
    
    Implements the two-pass algorithm due to Ritter presented in [Akenine-Moller, Haines. "Real-Time Rendering," 2nd ed, 2002, p565].
    
    The accessor is reset(javax.media.j3d.GeometryArray, boolean...) at the beginning of the computation, but not afterwards.
    
    Parameters:
    center - the center point is written here on return (or NaN if there are zero valid vertices), not null
    
    Returns:
    the radius, negative if no vertices
    
    Throws:
    
    java.lang.IllegalStateException - if this J3DVertexAccessor does not read vertex coordinates
  - newInstance
```
public abstract J3DVertexAccessor newInstance()
```
    make a new instance of this accessor implementation

Class J3DVertexAccessor

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

cvsid

TEXCOORD

COLOR

NORMAL

COORD

vertexIndex

vertexCount

validVertexCount

initialIndex

texCoord

color

normal

coord

component

ga

jg

componentIndex

indexAccessor

texCoord4

texCoord3

texCoord2

color4

color3

normal3

coord3

protos

Constructor Detail

J3DVertexAccessor

Method Detail

getNumImplementations

consAll

consAll

cons

cons

reset

reset

resetImpl

reset

setIndirect

isIndirect

setIndexAccessor

seek

advance

seek

seek

read

read

read

hasNext

hasNext

next

write

scaleVertex

scaleAll

checkFormat

checkFormat

computeBoundingSphere

newInstance