agi.foundation.graphics

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

Class TextBatchPrimitive

java.lang.Object

agi.foundation.graphics.Primitive

agi.foundation.graphics.TextBatchPrimitive

All Implemented Interfaces:

IDisposable, AutoCloseable

public final class TextBatchPrimitive
extends Primitive
implements IDisposable

Renders one or more strings in the 3D scene.

For best performance, avoid creating lots of batches with only a few strings each. See the Batching Performance topic.

See Also:

Text Batch Primitive topic, Performance topic, TextBatchPrimitiveOptionalParameters

Constructor Summary

Constructors

Constructor and Description
TextBatchPrimitive(GraphicsFont font) Initializes a marker batch primitive with the specified font.
TextBatchPrimitive(GraphicsFont font, SetHint setHint) Initializes a marker batch primitive with the specified font and setHint.
TextBatchPrimitive(GraphicsFont font, SetHint setHint, boolean renderInScreenSpace) Initializes a text batch primitive with the specified font and setHint, optimized for 2d screen space rendering.

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	getAlignToPixel() Gets whether the screen space position of each string is aligned to a pixel.
double	getBoundingSphereScale() Gets or sets the scale applied to the radius of this primitive's bounding sphere.
Color	getColor() Gets the color that affects every string in the batch.
DistanceDisplayCondition	getDistanceDisplayConditionPerString() Gets a DistanceDisplayCondition that is evaluated per string in the text batch during rendering.
GraphicsFont	getFont() Gets the font used to render the text batch.
Color	getOutlineColor() Gets the text's outline color.
float	getOutlineTranslucency() Gets the text's outline translucency.
boolean	getPerItemPickingEnabled() Gets whether individual text indices will be included in the PickResults returned from the Scene's Pick method.
boolean	getRenderInScreenSpace() Gets whether the primitive is positioned and rendered in screen space coordinates.
SetHint	getSetHint() Gets the primitive's SetHint.
TextureFilter2D	getTextureFilter() Gets the filter used to filter the texture-based Font.
float	getTranslucency() Gets the translucency that affects every string in the batch.
void	set(Iterable<Cartesian> positions, Iterable<String> text) Defines the positions and text of strings in a text batch.
void	set(Iterable<Cartesian> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters) Defines the positions, text, and optional parameters of strings in a text batch.
void	set(Iterable<Cartesian> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters, RenderPassHint renderPassHint) Defines the positions, text, and optional parameters of strings in a text batch.
void	setAlignToPixel(boolean value) Sets whether the screen space position of each string is aligned to a pixel.
void	setBoundingSphereScale(double value) Gets or sets the scale applied to the radius of this primitive's bounding sphere.
void	setCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text) For convenience.
void	setCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters) For convenience.
void	setCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters, RenderPassHint renderPassHint) For convenience.
void	setColor(Color value) Sets the color that affects every string in the batch.
void	setDistanceDisplayConditionPerString(DistanceDisplayCondition value) Sets a DistanceDisplayCondition that is evaluated per string in the text batch during rendering.
void	setOutlineColor(Color value) Sets the text's outline color.
void	setOutlineTranslucency(float value) Sets the text's outline translucency.
void	setPartial(Iterable<Cartesian> positions, Iterable<String> text, Iterable<Integer> indices) Updates a subset of positions and/or text in a text batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<String> text, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint) Updates a subset of positions and/or text in a text batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters, Iterable<Integer> indices) Updates a subset of positions, text, and/or optional per-string parameters in a text batch.
void	setPartial(Iterable<Cartesian> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint, RenderPassHint renderPassHint) Updates a subset of positions, text, and/or optional per-string parameters in a text batch.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text, Iterable<Integer> indices) For convenience.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint) For convenience.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters, Iterable<Integer> indices) For convenience.
void	setPartialCartographic(CentralBody centralBody, Iterable<Cartographic> positions, Iterable<String> text, TextBatchPrimitiveOptionalParameters optionalParameters, Iterable<Integer> indices, IndicesOrderHint indicesOrderHint, RenderPassHint renderPassHint) For convenience.
void	setPerItemPickingEnabled(boolean value) Sets whether individual text indices will be included in the PickResults returned from the Scene's Pick method.
void	setRenderInScreenSpace(boolean renderInScreenSpace) Sets whether the primitive is positioned and rendered in screen space coordinates.
void	setTextureFilter(TextureFilter2D filter) Sets the filter used to filter the texture-based Font.
void	setTranslucency(float value) Sets the translucency that affects every string 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

TextBatchPrimitive

public TextBatchPrimitive(GraphicsFont font)

Initializes a marker batch primitive with the specified font. This is equivalent to constructing a text batch with the specified font and a SetHint of Frequent.

See TextBatchPrimitive.TextBatchPrimitive(agi.foundation.graphics.GraphicsFont,agi.foundation.graphics.SetHint) for a full discussion.

Parameters:

font - The font used to render text in the text batch.

See Also:

TextBatchPrimitive.TextBatchPrimitive(agi.foundation.graphics.GraphicsFont,agi.foundation.graphics.SetHint)

TextBatchPrimitive

public TextBatchPrimitive(GraphicsFont font,
                          SetHint setHint)

Initializes a marker batch primitive with the specified font and setHint.

After constructing the primitive, call a method such as TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable) or TextBatchPrimitive.setCartographic(agi.foundation.celestial.CentralBody,java.lang.Iterable,java.lang.Iterable) to provide it with text.

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: White
• 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
• AlignToPixel: true
• BoundingSphereScale: 1
• DistanceDisplayConditionPerString: null
• Font: font
• OutlineColor: Blue
• OutlineTranslucency: 0
• SetHint: setHint
• TextureFilter: NearestClampToEdge

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.

font - The font used to render text in the text batch.

Throws:

ArgumentNullException - font is null.

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

TextBatchPrimitive

public TextBatchPrimitive(GraphicsFont font,
                          SetHint setHint,
                          boolean renderInScreenSpace)

Initializes a text batch primitive with the specified font and setHint, optimized for 2d screen space rendering.

After constructing the primitive, call a method such as TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable) or TextBatchPrimitive.setCartographic(agi.foundation.celestial.CentralBody,java.lang.Iterable,java.lang.Iterable) to provide it with text.

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: White
• 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
• AlignToPixel: true
• BoundingSphereScale: 1
• DistanceDisplayConditionPerString: null
• Font: font
• OutlineColor: Blue
• OutlineTranslucency: 0
• SetHint: setHint
• TextureFilter: NearestClampToEdge

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.

font - The font used to render text in the text batch.

Throws:

ArgumentNullException - font is null.

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

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 string in the batch.

If per-string color and translucency were specified with TextBatchPrimitiveOptionalParameters.SetColors, the per-batch color is ignored.

Overrides:

getColor in class Primitive

Throws:

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

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters), TextBatchPrimitiveOptionalParameters.SetColors

setColor

public void setColor(Color value)

Sets the color that affects every string in the batch.

If per-string color and translucency were specified with TextBatchPrimitiveOptionalParameters.SetColors, the per-batch color is ignored.

Overrides:

setColor in class Primitive

Throws:

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

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters), TextBatchPrimitiveOptionalParameters.SetColors

getTranslucency

public float getTranslucency()

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

If per-string color and translucency were specified with TextBatchPrimitiveOptionalParameters.SetColors, the per-batch 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-string colors and translucency using a method such as a TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters) Each string has a color and translucency, therefore the primitive's Translucency is ignored.

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters), TextBatchPrimitiveOptionalParameters.SetColors

setTranslucency

public void setTranslucency(float value)

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

If per-string color and translucency were specified with TextBatchPrimitiveOptionalParameters.SetColors, the per-batch 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-string colors and translucency using a method such as a TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters) Each string has a color and translucency, therefore the primitive's Translucency is ignored.

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters), TextBatchPrimitiveOptionalParameters.SetColors

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.

getBoundingSphereScale

public final double getBoundingSphereScale()

Gets or sets the scale applied to the radius of this primitive's bounding sphere.

BoundingSphereScale is only used when AutomaticallyComputeBoundingSphere (get) is true.

A BoundingSphereScale greater than 1 is commonly used to enlarge the primitive's BoundingSphere (get) so the primitive is conservatively culled. This is useful for primitives defined in screen-space such as the marker batch and text batch.

Throws:

IllegalStateException - Cannot set BoundingSphereScale when AutomaticallyComputeBoundingSphere (get) is true. Set AutomaticallyComputeBoundingSphere (get) to false first.

ArgumentOutOfRangeException - BoundingSphereScale must be greater than or equal to zero.

See Also:

AutomaticallyComputeBoundingSphere (get), BoundingSphere (get)

setBoundingSphereScale

public final void setBoundingSphereScale(double value)

Gets or sets the scale applied to the radius of this primitive's bounding sphere.

BoundingSphereScale is only used when AutomaticallyComputeBoundingSphere (get) is true.

A BoundingSphereScale greater than 1 is commonly used to enlarge the primitive's BoundingSphere (get) so the primitive is conservatively culled. This is useful for primitives defined in screen-space such as the marker batch and text batch.

Throws:

IllegalStateException - Cannot set BoundingSphereScale when AutomaticallyComputeBoundingSphere (get) is true. Set AutomaticallyComputeBoundingSphere (get) to false first.

ArgumentOutOfRangeException - BoundingSphereScale must be greater than or equal to zero.

See Also:

AutomaticallyComputeBoundingSphere (get), BoundingSphere (get)

getFont

public final GraphicsFont getFont()

Gets the font used to render the text batch.

getOutlineColor

public final Color getOutlineColor()

Gets the text's outline color.

Throws:

IllegalStateException - Font was not created with an outline.

setOutlineColor

public final void setOutlineColor(Color value)

Sets the text's outline color.

Throws:

IllegalStateException - Font was not created with an outline.

getOutlineTranslucency

public final float getOutlineTranslucency()

Gets the text's outline translucency. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.

Throws:

ArgumentOutOfRangeException - Translucency must be between 0 and 1.

IllegalStateException - Font was not created with an outline.

setOutlineTranslucency

public final void setOutlineTranslucency(float value)

Sets the text's outline translucency. Translucency is between 0 and 1, where 0 is opaque and 1 is transparent.

Throws:

ArgumentOutOfRangeException - Translucency must be between 0 and 1.

IllegalStateException - Font was not created with an outline.

getAlignToPixel

public final boolean getAlignToPixel()

Gets whether the screen space position of each string is aligned to a pixel.

setAlignToPixel

public final void setAlignToPixel(boolean value)

Sets whether the screen space position of each string is aligned to a pixel.

getRenderInScreenSpace

public final boolean getRenderInScreenSpace()

Gets whether the primitive is positioned and rendered in screen space coordinates.

setRenderInScreenSpace

public final void setRenderInScreenSpace(boolean renderInScreenSpace)

Sets whether the primitive is positioned and rendered in screen space coordinates.

getDistanceDisplayConditionPerString

public final DistanceDisplayCondition getDistanceDisplayConditionPerString()

Gets a DistanceDisplayCondition that is evaluated per string in the text batch during rendering. This is different than agi.foundation.graphics.primitive.DisplayCondition, which is evaluated once for the entire text batch. When DistanceDisplayConditionPerString is null, no per string 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 string in the batch before a marker is rendered.

setDistanceDisplayConditionPerString

public final void setDistanceDisplayConditionPerString(DistanceDisplayCondition value)

Sets a DistanceDisplayCondition that is evaluated per string in the text batch during rendering. This is different than agi.foundation.graphics.primitive.DisplayCondition, which is evaluated once for the entire text batch. When DistanceDisplayConditionPerString is null, no per string 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 string in the batch before a marker is rendered.

getPerItemPickingEnabled

public final boolean getPerItemPickingEnabled()

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

See Also:

Picking topic

setPerItemPickingEnabled

public final void setPerItemPickingEnabled(boolean value)

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

See Also:

Picking topic

getTextureFilter

public final TextureFilter2D getTextureFilter()

Gets the filter used to filter the texture-based Font.

See Also:

Font

setTextureFilter

public final void setTextureFilter(TextureFilter2D filter)

Sets the filter used to filter the texture-based Font.

See Also:

Font

set

public final void set(Iterable<Cartesian> positions,
                      Iterable<String> text)

Defines the positions and text of strings in a text batch. The strings are rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

This call overwrites the primitive's previous strings. To update a subset of string, use TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable)

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 strings in the text batch.

text - The text for strings in the text batch. Each element in this collection corresponds to an element in positions.

Throws:

ArgumentNullException - positions or text is null.

ArgumentException - positions and text must contain the same number of elements.

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

See Also:

Text Batch Primitive topic, Performance topic, TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable)

set

public final void set(Iterable<Cartesian> positions,
                      Iterable<String> text,
                      TextBatchPrimitiveOptionalParameters optionalParameters)

Defines the positions, text, and optional parameters of strings in a text batch. The strings are rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

This call overwrites the primitive's previous strings. To update a subset of string, use TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable)

See TextBatchPrimitiveOptionalParameters for details on how to define per-batch and per-string parameters.

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 strings in the text batch.

text - The text for strings in the text batch. Each element in this collection corresponds to an element in positions.

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as positions.

Throws:

ArgumentNullException - positions or text is null.

ArgumentException - positions and text must contain the same number of elements.

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

See Also:

Text Batch Primitive topic, Performance topic, TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable)

set

public final void set(Iterable<Cartesian> positions,
                      Iterable<String> text,
                      TextBatchPrimitiveOptionalParameters optionalParameters,
                      RenderPassHint renderPassHint)

Defines the positions, text, and optional parameters of strings in a text batch. The strings 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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters) with just positions, text, and optionalParameters. When a more specific renderPassHint is used, this method can be more efficient.

See TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters) for a full discussion.

Parameters:

positions - The new positions for strings in the text batch.

text - The text for strings in the text batch. Each element in this collection corresponds to an element in positions.

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as positions.

renderPassHint - An optimization hint indicating the RenderPass implied by per-strings colors defined in optionalParameters.

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters)

setCartographic

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

For convenience. Defines the positions and text of strings in a text 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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable).

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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable) for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - The new positions for strings in the text batch.

text - The text for strings in the text batch. Each element in this collection corresponds to an element in positions.

Throws:

ArgumentNullException - centralBody is null.

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

See Also:

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

setCartographic

public final void setCartographic(CentralBody centralBody,
                                  Iterable<Cartographic> positions,
                                  Iterable<String> text,
                                  TextBatchPrimitiveOptionalParameters optionalParameters)

For convenience. Defines the positions, text, and optional parameters of strings in a text 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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable).

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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters) for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - The new positions for strings in the text batch.

text - The text for strings in the text batch. Each element in this collection corresponds to an element in positions.

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as positions.

Throws:

ArgumentNullException - centralBody is null.

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

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters)

setCartographic

public final void setCartographic(CentralBody centralBody,
                                  Iterable<Cartographic> positions,
                                  Iterable<String> text,
                                  TextBatchPrimitiveOptionalParameters optionalParameters,
                                  RenderPassHint renderPassHint)

For convenience. Defines the positions, text, and optional parameters of strings in a text 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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable).

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 TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,agi.foundation.graphics.advanced.RenderPassHint) for a full discussion.

Parameters:

centralBody - The central body the positions are defined on.

positions - The new positions for strings in the text batch.

text - The text for strings in the text batch. Each element in this collection corresponds to an element in positions.

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as positions.

renderPassHint - An optimization hint indicating the RenderPass implied by per-strings colors defined in optionalParameters.

Throws:

ArgumentNullException - centralBody is null.

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

See Also:

TextBatchPrimitive.set(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,agi.foundation.graphics.advanced.RenderPassHint)

setPartial

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

Updates a subset of positions and/or text in a text 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 text batch.

text - A collection of new text used to update a subset of text in the text 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 and text are null. Or indices is null.

ArgumentException - if non-null, positions and text must contain the same number of elements.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartial

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

Updates a subset of positions and/or text in a text 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 text batch.

text - A collection of new text used to update a subset of text in the text 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 and text are null. Or indices is null.

ArgumentException - if non-null, positions and text must contain the same number of elements.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartial

public final void setPartial(Iterable<Cartesian> positions,
                             Iterable<String> text,
                             TextBatchPrimitiveOptionalParameters optionalParameters,
                             Iterable<Integer> indices)

Updates a subset of positions, text, and/or optional per-string parameters in a text 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 text batch.

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

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as 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 text are null. Or indices is null.

ArgumentException - Every specified collection from positions, text, and optionalParameters 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<String> text,
                             TextBatchPrimitiveOptionalParameters optionalParameters,
                             Iterable<Integer> indices,
                             IndicesOrderHint indicesOrderHint,
                             RenderPassHint renderPassHint)

Updates a subset of positions, text, and/or optional per-string parameters in a text 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 text batch.

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

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as 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 per-marker colors defined in optionalParameters.

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 text are null. Or indices is null.

ArgumentException - Every specified collection from positions, text, and optionalParameters must have the same number of elements.

See Also:

Dynamic Updates topic, Set Hint Performance topic

setPartialCartographic

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

For convenience. Updates a subset of positions and/or text in a text 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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable).

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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable) 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 text batch.

text - A collection of new text used to update a subset of text in the text 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:

TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable)

setPartialCartographic

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

For convenience. Updates a subset of positions and/or text in a text 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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.advanced.IndicesOrderHint).

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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.advanced.IndicesOrderHint) 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 text batch.

text - A collection of new text used to update a subset of text in the text 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:

TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.advanced.IndicesOrderHint)

setPartialCartographic

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

For convenience. Updates a subset of positions, text, and/or per-string parameters in a text 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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,java.lang.Iterable).

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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,java.lang.Iterable) 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 text batch.

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

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as 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:

TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,java.lang.Iterable)

setPartialCartographic

public final void setPartialCartographic(CentralBody centralBody,
                                         Iterable<Cartographic> positions,
                                         Iterable<String> text,
                                         TextBatchPrimitiveOptionalParameters optionalParameters,
                                         Iterable<Integer> indices,
                                         IndicesOrderHint indicesOrderHint,
                                         RenderPassHint renderPassHint)

For convenience. Updates a subset of positions, text, and/or per-string parameters in a text 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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,java.lang.Iterable,agi.foundation.graphics.advanced.IndicesOrderHint,agi.foundation.graphics.advanced.RenderPassHint).

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 TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,java.lang.Iterable,agi.foundation.graphics.advanced.IndicesOrderHint,agi.foundation.graphics.advanced.RenderPassHint) 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 text batch.

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

optionalParameters - Optional per-batch parameters or per-string parameters corresponding to positions. Each per-string parameter must have the same number of elements as 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 per-marker colors defined in optionalParameters.

Throws:

ArgumentNullException - centralBody is null.

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

See Also:

TextBatchPrimitive.setPartial(java.lang.Iterable,java.lang.Iterable,agi.foundation.graphics.TextBatchPrimitiveOptionalParameters,java.lang.Iterable,agi.foundation.graphics.advanced.IndicesOrderHint,agi.foundation.graphics.advanced.RenderPassHint)