agi.foundation.graphics

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

Class PointBatchPrimitive

java.lang.Object

agi.foundation.graphics.Primitive

agi.foundation.graphics.PointBatchPrimitive

All Implemented Interfaces:

IDisposable, AutoCloseable

public final class PointBatchPrimitive
extends Primitive
implements IDisposable

Renders one or more points in the 3D scene. Each point in the batch has a unique position and an optional color. All points in the batch share the same pixel size. For best performance, avoid creating lots of batches with only a few points each. See the Batching Performance topic.

See Also:

Point Batch Primitive topic, Performance topic

Constructor Summary

Constructors

Constructor and Description
PointBatchPrimitive() Initializes a default point batch primitive.
PointBatchPrimitive(SetHint setHint) Initializes a new instance of a point batch primitive with the specified SetHint.

Method Summary

Modifier and Type	Method and Description
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.
boolean	getCentralBodyClipped() Gets whether individual points will be clipped by the central body.
Color	getColor() Gets the color that affects every point in the batch.
boolean	getDisplayOutline() Gets whether an outline is rendered around each point in the batch.
DistanceDisplayCondition	getDistanceDisplayConditionPerPoint() Gets a DistanceDisplayCondition that is evaluated per point in the point batch during rendering.
static float	getMaximumPixelSizeSupported() Gets the maximum pixel size supported by the video card.
static float	getMinimumPixelSizeSupported() Gets the minimum pixel size supported by the video card.
Color	getOutlineColor() Gets the outline's color.
float	getOutlineTranslucency() Gets the translucency of the outline.
float	getOutlineWidth() Gets the size, in pixels, of the outline around each point in the batch.
boolean	getPerItemPickingEnabled() Gets whether individual point indices will be included in the PickResults returned from the Scene's Pick method.
float	getPixelSize() Gets the size, in pixels, of each point in the point batch.
SetHint	getSetHint() Gets the primitive's SetHint.
float	getTranslucency() Gets the translucency that affects every point in the batch.
void	set(Iterable<Cartesian> positions) Defines the positions of points in a point batch.
void	set(Iterable<Cartesian> positions, Iterable<Color> colors) Defines the positions and colors of points in a point batch.
void	set(Iterable<Cartesian> positions, Iterable<Color> colors, RenderPassHint renderPassHint) Defines the positions and colors of points in a point batch.
void	setCartographic(CentralBody centralBody, Iterable<Cartographic> positions) For convenience.
void	setCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<Color> colors) For convenience.
void	setCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<Color> colors, RenderPassHint renderPassHint) For convenience.
void	setCentralBodyClipped(boolean value) Sets whether individual points will be clipped by the central body.
void	setColor(Color value) Sets the color that affects every point in the batch.
void	setDisplayOutline(boolean value) Sets whether an outline is rendered around each point in the batch.
void	setDistanceDisplayConditionPerPoint(DistanceDisplayCondition value) Sets a DistanceDisplayCondition that is evaluated per point in the point batch during rendering.
void	setOutlineColor(Color value) Sets the outline's color.
void	setOutlineTranslucency(float value) Sets the translucency of the outline.
void	setOutlineWidth(float value) Sets the size, in pixels, of the outline around each point in the batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<Color> colors, Iterable<Integer> indices) Updates a subset of positions and/or colors in a point batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<Color> colors, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint, RenderPassHint renderPassHint) Updates a subset of positions and/or colors in a point batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<Integer> indices) Updates a subset of positions in a point batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint) Updates a subset of positions in a point batch.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<Color> colors, Iterable<Integer> indices) For convenience.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<Color> colors, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint, RenderPassHint renderPassHint) For convenience.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<Integer> indices) For convenience.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint) For convenience.
void	setPerItemPickingEnabled(boolean value) Sets whether individual point indices will be included in the PickResults returned from the Scene's Pick method.
void	setPixelSize(float value) Sets the size, in pixels, of each point in the point batch.
void	setTranslucency(float value) Sets the translucency that affects every point in the batch.

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 agi.foundation.compatibility.IDisposable

close, dispose

Constructor Detail

PointBatchPrimitive

public PointBatchPrimitive()

Initializes a default point batch primitive. This is equivalent to constructing a point batch with a agi.foundation.graphics.pointbatchprimitive.SetHint of Frequent.

See Also:

PointBatchPrimitive.PointBatchPrimitive(agi.foundation.graphics.SetHint)

PointBatchPrimitive

public PointBatchPrimitive(SetHint setHint)

Initializes a new instance of a point batch primitive with the specified SetHint.

After constructing the primitive, call a method such as Set or SetCartographic to provide it with points.

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

• agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere: true
• agi.foundation.graphics.primitive.BoundingSphere: BoundingSphere.MaximumRadiusBoundingSphere (get)
• Color: Blue
• 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
• Translucency: 0
• DistanceDisplayConditionPerPoint: null
• MaximumPixelSizeSupported: Video card dependent
• MinimumPixelSizeSupported: Video card dependent
• PixelSize: 2
• SetHint: setHint

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

Parameters:

setHint - The expected usage for Set and SetPartial methods. See the Set Hint topic for more information on selecting an appropriate value.

Throws:

UnsupportedCaseException - setHint must be a valid enumeration value in SetHint.

See Also:

Performance topic, PointBatchPrimitive.set(java.lang.Iterable)

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()

Gets the color that affects every point in the batch.

If per-position color and translucency were specified using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable), the primitive's Color is ignored.

Overrides:

getColor in class Primitive

Throws:

IllegalStateException - Cannot access Color when the primitive was defined with per-position colors and translucency using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable). Each position has a color and translucency, therefore the primitive's Color is ignored.

See Also:

PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable)

setColor

public void setColor(Color value)

Sets the color that affects every point in the batch.

If per-position color and translucency were specified using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable), the primitive's Color is ignored.

Overrides:

setColor in class Primitive

Throws:

IllegalStateException - Cannot access Color when the primitive was defined with per-position colors and translucency using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable). Each position has a color and translucency, therefore the primitive's Color is ignored.

See Also:

PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable)

getTranslucency

public float getTranslucency()

Gets the translucency that affects every point in the batch. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.

If per-position color and translucency were specified using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable), the primitive's Translucency is ignored.

Overrides:

getTranslucency in class Primitive

Throws:

ArgumentOutOfRangeException - Translucency must be between 0 and 1.

IllegalStateException - Cannot access Translucency when the primitive was defined with per-position colors and translucency using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable). Each position has a color and translucency, therefore the primitive's Translucency is ignored.

See Also:

PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable)

setTranslucency

public void setTranslucency(float value)

Sets the translucency that affects every point in the batch. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.

If per-position color and translucency were specified using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable), the primitive's Translucency is ignored.

Overrides:

setTranslucency in class Primitive

Throws:

ArgumentOutOfRangeException - Translucency must be between 0 and 1.

IllegalStateException - Cannot access Translucency when the primitive was defined with per-position colors and translucency using a method such as PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable). Each position has a color and translucency, therefore the primitive's Translucency is ignored.

See Also:

PointBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable)

getDisplayOutline

public final boolean getDisplayOutline()

Gets whether an outline is rendered around each point in the batch.

Outlines are rendered with the OutlineColor, OutlineTranslucency, and OutlineWidth properties.

See Also:

OutlineColor, OutlineTranslucency, OutlineWidth

setDisplayOutline

public final void setDisplayOutline(boolean value)

Sets whether an outline is rendered around each point in the batch.

Outlines are rendered with the OutlineColor, OutlineTranslucency, and OutlineWidth properties.

See Also:

OutlineColor, OutlineTranslucency, OutlineWidth

getOutlineColor

public final Color getOutlineColor()

Gets the outline's color.

See Also:

OutlineTranslucency

setOutlineColor

public final void setOutlineColor(Color value)

Sets the outline's color.

See Also:

OutlineTranslucency

getOutlineTranslucency

public final float getOutlineTranslucency()

Gets the translucency of the outline. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.

Throws:

ArgumentOutOfRangeException - The translucency must be between 0 and 1.

See Also:

OutlineColor

setOutlineTranslucency

public final void setOutlineTranslucency(float value)

Sets the translucency of the outline. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.

Throws:

ArgumentOutOfRangeException - The translucency must be between 0 and 1.

See Also:

OutlineColor

getOutlineWidth

public final float getOutlineWidth()

Gets the size, in pixels, of the outline around each point in the batch.

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

The total pixel size of a point, including the PixelSize and outline width is clamped to MaximumPixelSizeSupported.

Throws:

ArgumentOutOfRangeException - OutlineWidth is less than 0.

InsufficientVideoCardException - OutlineWidth is outside of the range supported by the video card. To verify a pixel size is supported, check MinimumPixelSizeSupported and MaximumPixelSizeSupported.

See Also:

PixelSize, MinimumPixelSizeSupported, MaximumPixelSizeSupported

setOutlineWidth

public final void setOutlineWidth(float value)

Sets the size, in pixels, of the outline around each point in the batch.

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

The total pixel size of a point, including the PixelSize and outline width is clamped to MaximumPixelSizeSupported.

Throws:

ArgumentOutOfRangeException - OutlineWidth is less than 0.

InsufficientVideoCardException - OutlineWidth is outside of the range supported by the video card. To verify a pixel size is supported, check MinimumPixelSizeSupported and MaximumPixelSizeSupported.

See Also:

PixelSize, MinimumPixelSizeSupported, MaximumPixelSizeSupported

getPixelSize

public final float getPixelSize()

Gets the size, in pixels, of each point in the point batch.

The size is defined in pixels so even if the camera moves very close or very far from a point batch, the size of each point on the screen does not change.

Throws:

ArgumentOutOfRangeException - PixelSize is less than 0.

InsufficientVideoCardException - PixelSize is outside of the range supported by the video card. To verify a pixel size is supported, check MinimumPixelSizeSupported and MaximumPixelSizeSupported. Regardless of MinimumPixelSizeSupported, a pixel size of 0 is always allowed and effectively hides the primitive.

See Also:

MinimumPixelSizeSupported, MaximumPixelSizeSupported

setPixelSize

public final void setPixelSize(float value)

Sets the size, in pixels, of each point in the point batch.

The size is defined in pixels so even if the camera moves very close or very far from a point batch, the size of each point on the screen does not change.

Throws:

ArgumentOutOfRangeException - PixelSize is less than 0.

InsufficientVideoCardException - PixelSize is outside of the range supported by the video card. To verify a pixel size is supported, check MinimumPixelSizeSupported and MaximumPixelSizeSupported. Regardless of MinimumPixelSizeSupported, a pixel size of 0 is always allowed and effectively hides the primitive.

See Also:

MinimumPixelSizeSupported, MaximumPixelSizeSupported

getMinimumPixelSizeSupported

public static final float getMinimumPixelSizeSupported()

Gets the minimum pixel size supported by the video card.

See Also:

PixelSize

getMaximumPixelSizeSupported

public static final float getMaximumPixelSizeSupported()

Gets the maximum pixel size supported by the video card.

See Also:

PixelSize

getDistanceDisplayConditionPerPoint

public final DistanceDisplayCondition getDistanceDisplayConditionPerPoint()

Gets a DistanceDisplayCondition that is evaluated per point in the point batch during rendering. This is different than agi.foundation.graphics.primitive.DisplayCondition, which is evaluated once for the entire point batch. When DistanceDisplayConditionPerPoint is null, no per point display condition is evaluated.

During rendering, first the primitive's agi.foundation.graphics.primitive.DisplayCondition is evaluated. If it succeeds, this distance display condition is evaluated for each point in the batch before a point is rendered.

setDistanceDisplayConditionPerPoint

public final void setDistanceDisplayConditionPerPoint(DistanceDisplayCondition value)

Sets a DistanceDisplayCondition that is evaluated per point in the point batch during rendering. This is different than agi.foundation.graphics.primitive.DisplayCondition, which is evaluated once for the entire point batch. When DistanceDisplayConditionPerPoint is null, no per point display condition is evaluated.

During rendering, first the primitive's agi.foundation.graphics.primitive.DisplayCondition is evaluated. If it succeeds, this distance display condition is evaluated for each point in the batch before a point is rendered.

getSetHint

public final SetHint getSetHint()

Gets the primitive's SetHint. See the Set Hint topic for more information on selecting an appropriate value to construct the primitive with.

getPerItemPickingEnabled

public final boolean getPerItemPickingEnabled()

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

See Also:

Picking topic

setPerItemPickingEnabled

public final void setPerItemPickingEnabled(boolean value)

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

See Also:

Picking topic

getCentralBodyClipped

public final boolean getCentralBodyClipped()

Gets whether individual points will be clipped by the central body.

setCentralBodyClipped

public final void setCentralBodyClipped(boolean value)

Sets whether individual points will be clipped by the central body.

set

public final void set(Iterable<Cartesian> positions)

Defines the positions of points in a point batch. The points are rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

This call overwrites the primitive's previous positions and per-position colors. To update a subset of positions, use SetPartial.

Each point is rendered with the same color and translucency, which is defined by the primitive's agi.foundation.graphics.primitive.Color and agi.foundation.graphics.primitive.Translucency properties.

If this method is called frequently, it is recommended to construct the primitive with agi.foundation.graphics.SetHint#Frequent, which is the default. If this method will be called only once or infrequently, construct the primitive with agi.foundation.graphics.SetHint#Infrequent. See the Set Hint topic for more information.

If the primitive's AutomaticallyComputeBoundingSphere (get) property is true, the primitive's BoundingSphere (get) is computed based on positions. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses all the positions.

Parameters:

positions - The new positions for the point batch.

Throws:

ArgumentNullException - positions is null.

CouldNotCreateVideoCardResourceException - Could not allocate video memory for positions.

See Also:

Point Batch Primitive topic, Performance topic, SetPartial

set

public final void set(Iterable<Cartesian> positions,
                      Iterable<Color> colors)

Defines the positions and colors of points in a point batch. The points are rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

This call overwrites the primitive's previous positions and per-position colors. To update a subset of positions and colors, use SetPartial.

Each color in colors corresponds to a position in positions with the same location. For example, the first color in colors is applied to the first position in positions. These colors override the primitive's agi.foundation.graphics.pointbatchprimitive.Color and agi.foundation.graphics.pointbatchprimitive.Translucency properties. Accessing these properties will result in an IllegalStateException.

To create translucent points, use the Color's alpha component. An alpha of 0 is completely transparent and an alpha of 255 is completely opaque.

If this method is called frequently, it is recommended to construct the primitive with agi.foundation.graphics.SetHint#Frequent, which is the default. If this method will be called only once or infrequently, construct the primitive with agi.foundation.graphics.SetHint#Infrequent. See the Set Hint topic for more information.

If the primitive's AutomaticallyComputeBoundingSphere (get) property is true, the primitive's BoundingSphere (get) is computed based on positions. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses all the positions.

Parameters:

positions - The new positions for the point batch.

colors - The new colors for the point batch. There must be one color for each position in positions.

Throws:

ArgumentNullException - positions or colors is null.

ArgumentException - positions and colors must have the same number of elements.

CouldNotCreateVideoCardResourceException - Could not allocate video memory for positions and colors.

See Also:

Point Batch Primitive topic, Performance topic, SetPartial

set

public final void set(Iterable<Cartesian> positions,
                      Iterable<Color> colors,
                      RenderPassHint renderPassHint)

Defines the positions and colors of points in a point batch. The points are rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame. renderPassHint is provided for efficiency.

Calling this method with a renderPassHint of Unknown is equivalent to calling Set with just positions and colors. When a more specific renderPassHint is used, this method can be more efficient.

See Set for a full discussion.

Parameters:

positions - The new positions for the point batch.

colors - The new colors for the point batch. There must be one color for each position in positions.

renderPassHint - An optimization hint indicating the RenderPass implied by colors.

See Also:

Set

setCartographic

public final void setCartographic(CentralBody centralBody,
                                  Iterable<Cartographic> positions)

For convenience. Defines the positions of points in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. This is equivalent to converting each position in positions to Cartesian and calling Set.

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See Set for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - The new positions for the point batch.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

Set

setCartographic

public final void setCartographic(CentralBody centralBody,
                                  Iterable<Cartographic> positions,
                                  Iterable<Color> colors)

For convenience. Defines the positions and colors of points in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. This is equivalent to converting each position in positions to Cartesian and calling Set.

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See Set for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - The new positions for the point batch.

colors - The new colors for the point batch. There must be one color for each position in positions.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

Set

setCartographic

public final void setCartographic(CentralBody centralBody,
                                  Iterable<Cartographic> positions,
                                  Iterable<Color> colors,
                                  RenderPassHint renderPassHint)

For convenience. Defines the positions and colors of points in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. renderPassHint is provided for efficiency. This is equivalent to converting each position in positions to Cartesian and calling Set.

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See Set for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - The new positions for the point batch.

colors - The new colors for the point batch. There must be one color for each position in positions.

renderPassHint - An optimization hint indicating the RenderPass implied by colors.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

Set

setPartial

public final void setPartial(Iterable<Cartesian> positions,
                             Iterable<Integer> indices)

Updates a subset of positions in a point batch.

To call SetPartial, the primitive must be constructed with agi.foundation.graphics.SetHint#Partial so the primitive builds the data structures necessary for partial updates. See the Set Hint topic for more information on selecting an appropriate value.

If the primitive's AutomaticallyComputeBoundingSphere (get) property is true, the primitive's BoundingSphere (get) is computed based the primitive's unmodified positions and the updated positions from the positions collection. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses all the positions in the primitive.

Parameters:

positions - A collection of new positions used to update a subset of positions in the point batch.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

Throws:

IllegalStateException - The primitive's SetHint property is not agi.foundation.graphics.SetHint#Partial. Construct the primitive using agi.foundation.graphics.SetHint#Partial to order to call this method.

IllegalStateException - Cannot call this method until the primitive is first defined with Set. It is not possible to partially update an empty primitive.

ArgumentNullException - positions or indices is null.

ArgumentException - positions and indices must have the same number of elements.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartial

public final void setPartial(Iterable<Cartesian> positions,
                             Iterable<Integer> indices,
                             IndicesOrderHint indicesOrderHint)

Updates a subset of positions in a point batch.

To call SetPartial, the primitive must be constructed with agi.foundation.graphics.SetHint#Partial so the primitive builds the data structures necessary for partial updates. See the Set Hint topic for more information on selecting an appropriate value.

If the primitive's AutomaticallyComputeBoundingSphere (get) property is true, the primitive's BoundingSphere (get) is computed based the primitive's unmodified positions and the updated positions from the positions collection. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses all the positions in the primitive.

Parameters:

positions - A collection of new positions used to update a subset of positions in the point batch.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

indicesOrderHint - An optimization hint indicating how indices are sorted.

Throws:

IllegalStateException - The primitive's SetHint property is not agi.foundation.graphics.SetHint#Partial. Construct the primitive using agi.foundation.graphics.SetHint#Partial to order to call this method.

IllegalStateException - Cannot call this method until the primitive is first defined with Set. It is not possible to partially update an empty primitive.

ArgumentNullException - positions or indices is null.

ArgumentException - positions and indices must have the same number of elements.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartial

public final void setPartial(Iterable<Cartesian> positions,
                             Iterable<Color> colors,
                             Iterable<Integer> indices)

Updates a subset of positions and/or colors in a point batch.

To call SetPartial, the primitive must be constructed with agi.foundation.graphics.SetHint#Partial so the primitive builds the data structures necessary for partial updates. See the Set Hint topic for more information on selecting an appropriate value.

If the primitive's AutomaticallyComputeBoundingSphere (get) property is true, the primitive's BoundingSphere (get) is computed based the primitive's unmodified positions and the updated positions from the positions collection. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses all the positions in the primitive.

Parameters:

positions - A collection of new positions used to update a subset of positions in the point batch.

colors - A collection of new colors used to update a subset of colors in the point batch. There must be one color for each position in positions.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

Throws:

IllegalStateException - The primitive's SetHint property is not agi.foundation.graphics.SetHint#Partial. Construct the primitive using agi.foundation.graphics.SetHint#Partial to order to call this method.

IllegalStateException - Cannot call this method until the primitive is first defined with Set. It is not possible to partially update an empty primitive.

ArgumentNullException - positions and colors are null. Or indices is null.

ArgumentException - positions, colors, and indices must have the same number of elements.

ArgumentException - A collection of colors was provided, but the primitive didn't have per-position colors defined with Set.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartial

public final void setPartial(Iterable<Cartesian> positions,
                             Iterable<Color> colors,
                             Iterable<Integer> indices,
                             IndicesOrderHint indicesOrderHint,
                             RenderPassHint renderPassHint)

Updates a subset of positions and/or colors in a point batch.

To call SetPartial, the primitive must be constructed with agi.foundation.graphics.SetHint#Partial so the primitive builds the data structures necessary for partial updates. See the Set Hint topic for more information on selecting an appropriate value.

If the primitive's AutomaticallyComputeBoundingSphere (get) property is true, the primitive's BoundingSphere (get) is computed based the primitive's unmodified positions and the updated positions from the positions collection. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses all the positions in the primitive.

Parameters:

positions - A collection of new positions used to update a subset of positions in the point batch.

colors - A collection of new colors used to update a subset of colors in the point batch. There must be one color for each position in positions.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

indicesOrderHint - An optimization hint indicating how indices are sorted.

renderPassHint - An optimization hint indicating the RenderPass implied by colors.

Throws:

IllegalStateException - The primitive's SetHint property is not agi.foundation.graphics.SetHint#Partial. Construct the primitive using agi.foundation.graphics.SetHint#Partial to order to call this method.

IllegalStateException - Cannot call this method until the primitive is first defined with Set. It is not possible to partially update an empty primitive.

ArgumentNullException - positions and colors are null. Or indices is null.

ArgumentException - positions, colors, and indices must have the same number of elements.

ArgumentException - A collection of colors was provided, but the primitive didn't have per-position colors defined with Set.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartialCartographic

public final void setPartialCartographic(CentralBody centralBody,
                                         Iterable<Cartographic> positions,
                                         Iterable<Integer> indices)

For convenience. Updates a subset of positions in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. This is equivalent to converting each position in positions to Cartesian and calling SetPartial

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See SetPartial for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - A collection of new positions used to update a subset of positions in the point batch.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

SetPartial

setPartialCartographic

public final void setPartialCartographic(CentralBody centralBody,
                                         Iterable<Cartographic> positions,
                                         Iterable<Integer> indices,
                                         IndicesOrderHint indicesOrderHint)

For convenience. Updates a subset of positions in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. This is equivalent to converting each position in positions to Cartesian and calling SetPartial

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See SetPartial for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - A collection of new positions used to update a subset of positions in the point batch.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

indicesOrderHint - An optimization hint indicating how indices are sorted.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

SetPartial

setPartialCartographic

public final void setPartialCartographic(CentralBody centralBody,
                                         Iterable<Cartographic> positions,
                                         Iterable<Color> colors,
                                         Iterable<Integer> indices)

For convenience. Updates a subset of positions and/or colors in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. This is equivalent to converting each position in positions to Cartesian and calling SetPartial

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See SetPartial for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - A collection of new positions used to update a subset of positions in the point batch.

colors - A collection of new colors used to update a subset of colors in the point batch. There must be one color for each position in positions.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

SetPartial

setPartialCartographic

public final void setPartialCartographic(CentralBody centralBody,
                                         Iterable<Cartographic> positions,
                                         Iterable<Color> colors,
                                         Iterable<Integer> indices,
                                         IndicesOrderHint indicesOrderHint,
                                         RenderPassHint renderPassHint)

For convenience. Updates a subset of positions and/or colors in a point batch using Cartographic positions. Longitude and latitude are in radians, and altitude is in meters. This is equivalent to converting each position in positions to Cartesian and calling SetPartial

centralBody is used to convert positions to Cartesian. The primitive's ReferenceFrame (get) must be equal to the centralBody fixed frame. If the primitive's ReferenceFrame (get) is changed after calling this method, the Cartesian positions stored by the primitive are not modified and are unlikely to represent the original Cartographic positions provided to this method.

See SetPartial for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - A collection of new positions used to update a subset of positions in the point batch.

colors - A collection of new colors used to update a subset of colors in the point batch. There must be one color for each position in positions.

indices - A collection of zero-based indices that map a corresponding position in positions to a position already in the primitive. For example, if a primitive is first given 5 positions with a call to Set, positions 1 and 3 can be modified with SetPartial by passing in positions containing two new positions and an indices collection with two elements, e.g. [1, 3]. The first position in positions will modify the position at index 1 in the primitive and the second will modify the position at index 3.

indicesOrderHint - An optimization hint indicating how indices are sorted.

renderPassHint - An optimization hint indicating the RenderPass implied by colors.

Throws:

ArgumentNullException - centralBody is null.

IllegalStateException - The primitive's ReferenceFrame (get) is not equal to centralBody fixed frame.

See Also:

SetPartial