agi.foundation.graphics

(agi.foundation.graphics-2024r3.jar)

Class Primitive

java.lang.Object

agi.foundation.graphics.Primitive

All Implemented Interfaces:

IDisposable, AutoCloseable

Direct Known Subclasses:

AxesPrimitive, CompositePrimitive, MarkerBatchPrimitive, ModelPrimitive, OrderedCompositePrimitive, PathPrimitive, PointBatchPrimitive, PolylinePrimitive, ProjectedRaster, SolidPrimitive, SurfaceMeshPrimitive, TextBatchPrimitive, TriangleMeshPrimitive, VectorPrimitive

public abstract class Primitive
extends Object
implements IDisposable

Primitives represent objects rendered in the 3D scene.

See Also:

Primitives topic

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Primitive()

Method Summary

Modifier and Type	Method and Description
void	dispose() Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
protected void	dispose(boolean disposing)
boolean	getAutomaticallyComputeBoundingSphere() Gets if the primitive's BoundingSphere is automatically computed.
BoundingSphere	getBoundingSphere() Gets the bounding sphere that encompasses the primitive.
Color	getColor() Gets the primitive's color.
boolean	getDisplay() Gets if the primitive should be rendered.
DisplayCondition	getDisplayCondition() Gets the display condition that determines if the primitive should be rendered.
ReferenceFrame	getReferenceFrame() Gets the reference frame this primitive is defined and rendered in.
Object	getTag() Gets custom data associated with this primitive.
float	getTranslucency() Gets the primitive's translucency.
void	setAutomaticallyComputeBoundingSphere(boolean value) Sets if the primitive's BoundingSphere is automatically computed.
void	setBoundingSphere(BoundingSphere value) Sets the bounding sphere that encompasses the primitive.
void	setColor(Color value) Sets the primitive's color.
void	setDisplay(boolean value) Sets if the primitive should be rendered.
void	setDisplayCondition(DisplayCondition value) Sets the display condition that determines if the primitive should be rendered.
void	setReferenceFrame(ReferenceFrame value) Sets the reference frame this primitive is defined and rendered in.
void	setTag(Object value) Sets custom data associated with this primitive.
void	setTranslucency(float value) Sets the primitive's translucency.

Methods inherited from class java.lang.Object

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

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

Primitive

protected Primitive()

Method Detail

dispose

public final void dispose()

Description copied from interface: IDisposable

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Specified by:

dispose in interface IDisposable

dispose

protected void dispose(boolean disposing)

getReferenceFrame

public ReferenceFrame getReferenceFrame()

Gets the reference frame this primitive is defined and rendered in.

Throws:

ArgumentNullException - ReferenceFrame is null.

IllegalStateException - Cannot modify ReferenceFrame once the primitive is added to the primitive manager or a composite primitive. Remove the primitive from the manager or composite before modifying ReferenceFrame.

setReferenceFrame

public void setReferenceFrame(ReferenceFrame value)

Sets the reference frame this primitive is defined and rendered in.

Throws:

ArgumentNullException - ReferenceFrame is null.

IllegalStateException - Cannot modify ReferenceFrame once the primitive is added to the primitive manager or a composite primitive. Remove the primitive from the manager or composite before modifying ReferenceFrame.

getBoundingSphere

public BoundingSphere getBoundingSphere()

Gets the bounding sphere that encompasses the primitive. The center is defined in the primitive's ReferenceFrame.

Throws:

IllegalStateException - Cannot manually set BoundingSphere when AutomaticallyComputeBoundingSphere is true. Set AutomaticallyComputeBoundingSphere to false first.

setBoundingSphere

public void setBoundingSphere(BoundingSphere value)

Sets the bounding sphere that encompasses the primitive. The center is defined in the primitive's ReferenceFrame.

Throws:

IllegalStateException - Cannot manually set BoundingSphere when AutomaticallyComputeBoundingSphere is true. Set AutomaticallyComputeBoundingSphere to false first.

getAutomaticallyComputeBoundingSphere

public boolean getAutomaticallyComputeBoundingSphere()

Gets if the primitive's BoundingSphere is automatically computed.

A primitive's BoundingSphere is used for visibility tests to improve rendering performance. When AutomaticallyComputeBoundingSphere is true, the sphere is automatically computed when a primitive's geometry or position is modified due to a Set or SetPartial call. Otherwise, it is the caller's responsibility to set the primitive's BoundingSphere.

A user may set this property to false in cases when they can determine a BoundingSphere that encompasses everywhere a dynamic primitive may move to. This can improve performance by eliminating the overhead associated with re-computing the bounding sphere and updating the primitive manager's spatial data structures.

setAutomaticallyComputeBoundingSphere

public void setAutomaticallyComputeBoundingSphere(boolean value)

Sets if the primitive's BoundingSphere is automatically computed.

A primitive's BoundingSphere is used for visibility tests to improve rendering performance. When AutomaticallyComputeBoundingSphere is true, the sphere is automatically computed when a primitive's geometry or position is modified due to a Set or SetPartial call. Otherwise, it is the caller's responsibility to set the primitive's BoundingSphere.

A user may set this property to false in cases when they can determine a BoundingSphere that encompasses everywhere a dynamic primitive may move to. This can improve performance by eliminating the overhead associated with re-computing the bounding sphere and updating the primitive manager's spatial data structures.

getDisplayCondition

public DisplayCondition getDisplayCondition()

Gets the display condition that determines if the primitive should be rendered. Both this and Display must evaluate to true for the primitive to be rendered.

When DisplayCondition is null, no display condition is evaluated before the primitive is rendered.

See Also:

Display Conditions topic, DisplayCondition, Display

setDisplayCondition

public void setDisplayCondition(DisplayCondition value)

Sets the display condition that determines if the primitive should be rendered. Both this and Display must evaluate to true for the primitive to be rendered.

When DisplayCondition is null, no display condition is evaluated before the primitive is rendered.

See Also:

Display Conditions topic, DisplayCondition, Display

getDisplay

public boolean getDisplay()

Gets if the primitive should be rendered. Both this and DisplayCondition must evaluate to true for the primitive to be rendered.

A primitive must be added to the PrimitiveManager before it is rendered. Once in the manager, setting this property to false is more efficient than removing the primitive from the manager. Although, it is recommended to remove the primitive from the manager if the primitive will be hidden for a long period of time.

For more control over when a primitive is rendered, see DisplayCondition.

See Also:

PrimitiveManager, DisplayCondition

setDisplay

public void setDisplay(boolean value)

Sets if the primitive should be rendered. Both this and DisplayCondition must evaluate to true for the primitive to be rendered.

A primitive must be added to the PrimitiveManager before it is rendered. Once in the manager, setting this property to false is more efficient than removing the primitive from the manager. Although, it is recommended to remove the primitive from the manager if the primitive will be hidden for a long period of time.

For more control over when a primitive is rendered, see DisplayCondition.

See Also:

PrimitiveManager, DisplayCondition

getColor

public Color getColor()

Gets the primitive's color.

setColor

public void setColor(Color value)

Sets the primitive's color.

getTranslucency

public float getTranslucency()

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

Throws:

ArgumentOutOfRangeException - Translucency must be between 0 and 1.

setTranslucency

public void setTranslucency(float value)

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

Throws:

ArgumentOutOfRangeException - Translucency must be between 0 and 1.

getTag

public Object getTag()

Gets custom data associated with this primitive.

This property is commonly used in conjunction with picking. Custom data that needs to be retrieved or modified when this primitive is picked is assigned to this property. When the primitive is picked, this property is used to access the custom data.

See Also:

Picking topic

setTag

public void setTag(Object value)

Sets custom data associated with this primitive.

This property is commonly used in conjunction with picking. Custom data that needs to be retrieved or modified when this primitive is picked is assigned to this property. When the primitive is picked, this property is used to access the custom data.

See Also:

Picking topic