agi.foundation.graphics

(agi.foundation.graphics-2025r1.jar)

Class PathPrimitive

java.lang.Object

agi.foundation.graphics.Primitive

agi.foundation.graphics.PathPrimitive

All Implemented Interfaces:

IDisposable, AutoCloseable, Iterable<PathPoint>

public final class PathPrimitive
extends Primitive
implements Iterable<PathPoint>, IDisposable

Renders a line to the 3D scene. Similar to the PolylinePrimitive; however, the PathPrimitive was designed for the efficient addition/removal of points to/from the front or back of the line.

See Also:

Path Primitive topic

Constructor Summary

Constructors

Constructor and Description
PathPrimitive() Initializes a default path primitive.
PathPrimitive(int capacity) Initializes a path primitive with the specified capacity.

Method Summary

Modifier and Type	Method and Description
void	addBack(PathPoint pathPoint) Add a PathPoint to the back of the line.
void	addFront(PathPoint pathPoint) Add a PathPoint to the front of the line.
void	addRangeToBack(Iterable<PathPoint> positions) Add the range of PathPoints to the back of the line.
void	addRangeToFront(Iterable<PathPoint> positions) Add the range of PathPoints to the front of the line.
PathPoint	back() Access the PathPoint at the back of the line.
void	clear() Removes all of the points.
protected void	dispose(boolean disposing)
protected void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
PathPoint	front() Access the PathPoint at the front of the line.
PathPoint	get(int index) Returns the point at the given zero-based index.
int	getCapacity() Returns the capacity that was set during object construction.
boolean	getCentralBodyClipped() Gets whether the polyline will be clipped by the central body.
Color	getColor() The path primitive does not support the Color property.
int	getCount() Returns the number of points.
boolean	getDisplayOutline() Gets whether an outline is rendered around the line.
static float	getMaximumWidthSupported() Gets the maximum width, in pixels, supported by the video card.
static float	getMinimumWidthSupported() Gets the minimum width, in pixels, supported by the video card.
float	getOutlineWidth() Gets the width, in pixels, of the outline around the line.
boolean	getPerItemPickingEnabled() Gets whether individual line indices will be included in the PickResults returned from the Scene's Pick method.
PolylineType	getPolylineType() Gets how the primitive interprets the positions.
float	getTranslucency() The path primitive does not support the Translucency property.
PathPrimitiveUpdatePolicy	getUpdatePolicy() Gets how the primitive will be updated based on the current animation time.
float	getWidth() Gets the line width, in pixels.
Iterator<PathPoint>	iterator() Returns an enumerator that iterates through the collection.
void	removeAllAfter(int index) Remove all points after index.
void	removeAllBefore(int index) Remove all points before index.
void	removeBack() Remove a PathPoint to the back of the line.
void	removeFront() Remove a PathPoint to the front of the line.
void	setCentralBodyClipped(boolean value) Sets whether the polyline will be clipped by the central body.
void	setColor(Color value) The path primitive does not support the Color property.
void	setDisplayOutline(boolean value) Sets whether an outline is rendered around the line.
void	setOutlineWidth(float value) Sets the width, in pixels, of the outline around the line.
void	setPerItemPickingEnabled(boolean value) Sets whether individual line indices will be included in the PickResults returned from the Scene's Pick method.
void	setPolylineType(PolylineType value) Sets how the primitive interprets the positions.
void	setTranslucency(float value) The path primitive does not support the Translucency property.
void	setUpdatePolicy(PathPrimitiveUpdatePolicy value) Sets how the primitive will be updated based on the current animation time.
void	setWidth(float value) Sets the line width, in pixels.

Methods inherited from class agi.foundation.graphics.Primitive

dispose, getAutomaticallyComputeBoundingSphere, getBoundingSphere, getDisplay, getDisplayCondition, getReferenceFrame, getTag, setAutomaticallyComputeBoundingSphere, setBoundingSphere, setDisplay, setDisplayCondition, setReferenceFrame, setTag

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface agi.foundation.compatibility.IDisposable

close, dispose

Constructor Detail

PathPrimitive

public PathPrimitive()

Initializes a default path primitive. This is equivalent to constructing a path primitive with an initial capacity of 16.

See Also:

PathPrimitive.PathPrimitive(int)

PathPrimitive

public PathPrimitive(int capacity)

Initializes a path primitive with the specified capacity.

After constructing the primitive, call a method such as AddFront or AddBack to provide it with positions.

The primitive's properties are initialized to the following values:

• agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere: true
• agi.foundation.graphics.primitive.BoundingSphere: BoundingSphere.MaximumRadiusBoundingSphere (get)
• agi.foundation.graphics.primitive.Display: true
• agi.foundation.graphics.primitive.DisplayCondition: null
• agi.foundation.graphics.primitive.ReferenceFrame: The earth's agi.foundation.celestial.earthcentralbody.FixedFrame
• MaximumWidthSupported: Video card dependent
• MinimumWidthSupported: Video card dependent
• agi.foundation.graphics.pathprimitive.DisplayOutline: false
• agi.foundation.graphics.pathprimitive.OutlineWidth: 1
• agi.foundation.graphics.pathprimitive.PerItemPickingEnabled: false
• agi.foundation.graphics.pathprimitive.PolylineType: LineStrip
• agi.foundation.graphics.pathprimitive.Width: 1

Once the primitive is constructed, it must be added to Primitives (get) before it will be rendered.

Parameters:

capacity - Sets the initial capacity for the buffer containing positions. Setting the capacity reserves memory so the addition of points is more efficient.

Throws:

ArgumentOutOfRangeException - capacity must be greater than or equal to 0.

See Also:

Path Primitive topic

Method Detail

finalize

protected void finalize()
                 throws Throwable

Description copied from class: java.lang.Object

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java™ virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Overrides:

finalize in class Object

Throws:

Throwable - the Exception raised by this method

See Also:

WeakReference, PhantomReference

dispose

protected void dispose(boolean disposing)

Overrides:

dispose in class Primitive

getColor

public Color getColor()

The path primitive does not support the Color property. Instead, use the Color (get) property on PathPoint.

Overrides:

getColor in class Primitive

Throws:

UnsupportedOperationException - Always thrown by the path primitive.

setColor

public void setColor(Color value)

The path primitive does not support the Color property. Instead, use the Color (get) property on PathPoint.

Overrides:

setColor in class Primitive

Throws:

UnsupportedOperationException - Always thrown by the path primitive.

getTranslucency

public float getTranslucency()

The path primitive does not support the Translucency property. Instead, use the Translucency (get) property on PathPoint.

Overrides:

getTranslucency in class Primitive

Throws:

UnsupportedOperationException - Always thrown by the path primitive.

setTranslucency

public void setTranslucency(float value)

The path primitive does not support the Translucency property. Instead, use the Translucency (get) property on PathPoint.

Overrides:

setTranslucency in class Primitive

Throws:

UnsupportedOperationException - Always thrown by the path primitive.

getCount

public final int getCount()

Returns the number of points.

Returns:

The number of points.

getCapacity

public final int getCapacity()

Returns the capacity that was set during object construction. The capacity is the amount of memory reserved for storing the points on the path. This will be automatically updated when adding/removing points.

Returns:

The capacity.

See Also:

PathPrimitive.PathPrimitive(int)

getUpdatePolicy

public PathPrimitiveUpdatePolicy getUpdatePolicy()

Gets how the primitive will be updated based on the current animation time.

See Also:

PathPrimitiveUpdatePolicy, Path Primitive topic

setUpdatePolicy

public void setUpdatePolicy(PathPrimitiveUpdatePolicy value)

Sets how the primitive will be updated based on the current animation time.

See Also:

PathPrimitiveUpdatePolicy, Path Primitive topic

getPolylineType

public PolylineType getPolylineType()

Gets how the primitive interprets the positions.

See Also:

Path Primitive topic

setPolylineType

public void setPolylineType(PolylineType value)

Sets how the primitive interprets the positions.

See Also:

Path Primitive topic

getWidth

public float getWidth()

Gets the line width, in pixels.

The width is defined in pixels so even if the camera moves very close or very far from the primitive, the width of the line on the screen does not change.

Throws:

ArgumentOutOfRangeException - Width is less than 0.

InsufficientVideoCardException - Width is outside of the range supported by the video card. To verify a width is supported, check MinimumWidthSupported and MaximumWidthSupported. Regardless of MinimumWidthSupported, a width of 0 is always allowed and effectively hides the primitive.

See Also:

MinimumWidthSupported, MaximumWidthSupported

setWidth

public void setWidth(float value)

Sets the line width, in pixels.

The width is defined in pixels so even if the camera moves very close or very far from the primitive, the width of the line on the screen does not change.

Throws:

ArgumentOutOfRangeException - Width is less than 0.

InsufficientVideoCardException - Width is outside of the range supported by the video card. To verify a width is supported, check MinimumWidthSupported and MaximumWidthSupported. Regardless of MinimumWidthSupported, a width of 0 is always allowed and effectively hides the primitive.

See Also:

MinimumWidthSupported, MaximumWidthSupported

getMinimumWidthSupported

public static final float getMinimumWidthSupported()

Gets the minimum width, in pixels, supported by the video card.

See Also:

Width

getMaximumWidthSupported

public static final float getMaximumWidthSupported()

Gets the maximum width, in pixels, supported by the video card.

See Also:

Width

getDisplayOutline

public final boolean getDisplayOutline()

Gets whether an outline is rendered around the line.

Outlines are rendered with the OutlineWidth property.

See Also:

OutlineWidth

setDisplayOutline

public final void setDisplayOutline(boolean value)

Sets whether an outline is rendered around the line.

Outlines are rendered with the OutlineWidth property.

See Also:

OutlineWidth

getOutlineWidth

public final float getOutlineWidth()

Gets the width, in pixels, of the outline around the line.

Similar to Width, the outline width is defined in pixels, so even if the camera moves very close or very far from the primitive, the outline width on the screen does not change.

The total line width, in pixels, including the Width and outline width is clamped to MaximumWidthSupported.

Throws:

ArgumentOutOfRangeException - OutlineWidth is less than 0.

InsufficientVideoCardException - OutlineWidth is outside of the range supported by the video card. To verify a width is supported, check MinimumWidthSupported and MaximumWidthSupported.

See Also:

Width, MinimumWidthSupported, MaximumWidthSupported

setOutlineWidth

public final void setOutlineWidth(float value)

Sets the width, in pixels, of the outline around the line.

Similar to Width, the outline width is defined in pixels, so even if the camera moves very close or very far from the primitive, the outline width on the screen does not change.

The total line width, in pixels, including the Width and outline width is clamped to MaximumWidthSupported.

Throws:

ArgumentOutOfRangeException - OutlineWidth is less than 0.

InsufficientVideoCardException - OutlineWidth is outside of the range supported by the video card. To verify a width is supported, check MinimumWidthSupported and MaximumWidthSupported.

See Also:

Width, MinimumWidthSupported, MaximumWidthSupported

getPerItemPickingEnabled

public final boolean getPerItemPickingEnabled()

Gets whether individual line indices will be included in the PickResults returned from the Scene's Pick method. Each line index that is picked will be returned as a BatchPrimitiveIndex.

See Also:

Picking topic

setPerItemPickingEnabled

public final void setPerItemPickingEnabled(boolean value)

Sets whether individual line indices will be included in the PickResults returned from the Scene's Pick method. Each line index that is picked will be returned as a BatchPrimitiveIndex.

See Also:

Picking topic

getCentralBodyClipped

public final boolean getCentralBodyClipped()

Gets whether the polyline will be clipped by the central body.

See Also:

Picking topic

setCentralBodyClipped

public final void setCentralBodyClipped(boolean value)

Sets whether the polyline will be clipped by the central body.

See Also:

Picking topic

get

public PathPoint get(int index)

Returns the point at the given zero-based index.

Throws:

ArgumentOutOfRangeException - index is out of range. It must be between 0 and Count - 1.

iterator

public Iterator<PathPoint> iterator()

Returns an enumerator that iterates through the collection.

Specified by:

iterator in interface Iterable<PathPoint>

Returns:

An enumerator that can be used to iterate through the collection.

addFront

public final void addFront(PathPoint pathPoint)

Add a PathPoint to the front of the line.

Parameters:

pathPoint - The point added to the front of the line.

See Also:

PathPrimitive.addBack(agi.foundation.graphics.PathPoint)

addRangeToFront

public final void addRangeToFront(Iterable<PathPoint> positions)

Add the range of PathPoints to the front of the line.

Parameters:

positions - The positions to add to the front of the path.

See Also:

PathPrimitive.addRangeToBack(java.lang.Iterable)

addBack

public final void addBack(PathPoint pathPoint)

Add a PathPoint to the back of the line.

Parameters:

pathPoint - The point added to the back of the line.

See Also:

PathPrimitive.addFront(agi.foundation.graphics.PathPoint)

addRangeToBack

public final void addRangeToBack(Iterable<PathPoint> positions)

Add the range of PathPoints to the back of the line.

Parameters:

positions - The positions to add to the back of the path.

See Also:

PathPrimitive.addRangeToFront(java.lang.Iterable)

removeFront

public final void removeFront()

Remove a PathPoint to the front of the line.

See Also:

PathPrimitive.removeBack()

removeAllBefore

public final void removeAllBefore(int index)

Remove all points before index.

Parameters:

index - The index at which to stop removing points.

Throws:

ArgumentOutOfRangeException - The index is less than 0 or greater than the size of the path.

See Also:

PathPrimitive.removeAllAfter(int)

removeBack

public final void removeBack()

Remove a PathPoint to the back of the line.

See Also:

PathPrimitive.removeFront()

removeAllAfter

public final void removeAllAfter(int index)

Remove all points after index.

Parameters:

index - The index at which any points after will be removed.

Throws:

ArgumentOutOfRangeException - The index is less than 0 or greater than the size of the path.

See Also:

PathPrimitive.removeAllBefore(int)

front

public final PathPoint front()

Access the PathPoint at the front of the line.

Returns:

The PathPoint at the front of the line.

Throws:

IllegalStateException - The path primitive does not contain any positions.

back

public final PathPoint back()

Access the PathPoint at the back of the line.

Returns:

The PathPoint at the back of the line.

Throws:

IllegalStateException - The path primitive does not contain any positions.

clear

public final void clear()

Removes all of the points.

Even though this method will remove all of the points, the memory reserved will not be altered.

See Also:

Capacity (get)