agi.foundation.graphics

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

Class TriangleMeshPrimitive

java.lang.Object

agi.foundation.graphics.Primitive

agi.foundation.graphics.TriangleMeshPrimitive

All Implemented Interfaces:

IDisposable, AutoCloseable

public final class TriangleMeshPrimitive
extends Primitive
implements IDisposable

Renders a triangle mesh in the 3D scene. Examples of triangle meshes include polygons on the globe (e.g. states or countries), terrain and imagery extents, ellipses, and extrusions.

See Also:

Triangle Mesh Primitive topic, Surface Mesh Primitive topic

Constructor Summary

Constructors

Constructor and Description
TriangleMeshPrimitive() Initializes a default triangle mesh primitive.
TriangleMeshPrimitive(SetHint setHint) Initializes a triangle mesh 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.
Color	getBlendingColor() Gets the blending color.
BlendingEquation	getBlendingEquation() Gets or set the blending equation used when compositing a transparent triangle mesh.
boolean	getCentralBodyClipped() Gets whether individual points will be clipped by the central body.
CullFace	getCullFace() Gets whether front and/or back-facing triangles may be culled.
BlendingFunction	getDestinationBlendingFunction() Gets or set the blending function that is used to modify the destination color before the final blending operation occurs.
boolean	getLighting() Gets whether the primitive is lit.
boolean	getRenderBackThenFrontFaces() Gets whether the primitive is rendered in two passes to improve the visual quality for translucent, convex meshes.
SetHint	getSetHint() Gets the primitive's SetHint.
RendererShadeModel	getShadeModel() Gets the shading model for the mesh.
BlendingFunction	getSourceBlendingFunction() Gets or set the blending function that is used to modify the source color before the final blending operation occurs.
Texture2D	getTexture() Gets the texture to be drawn on the triangle mesh.
TextureFilter2D	getTextureFilter() Gets the filter used for the Texture associated with this triangle mesh.
WindingOrder	getTriangleWindingOrder() Gets the orientation of front-facing triangles.
boolean	getUseCustomBlendingParameters() Gets or set the boolean that defines if custom blending parameters will be used or if it will use the blending parameters set by the particular rendering pass.
boolean	getWireframe() Gets or sets whether the primitive is rendered in wireframe.
void	set(Iterable<Cartesian> positions, Iterable<Cartesian> normals, Iterable<Integer> indices) Defines the triangle mesh using an indexed triangle list specified by positions, normals, and indices.
void	set(Iterable<Cartesian> positions, Iterable<Cartesian> normals, Iterable<Integer> indices, TriangleMeshPrimitiveOptionalParameters optionalParameters) Defines the triangle mesh using an indexed triangle list specified by positions, normals, indices, and optionalParameters.
void	set(TriangulatorResult triangulator) Defines the triangle mesh using the specified triangulator.
void	setBlendingColor(Color value) Sets the blending color.
void	setBlendingEquation(BlendingEquation blendingEquation) Gets or set the blending equation used when compositing a transparent triangle mesh.
void	setCentralBodyClipped(boolean value) Sets whether individual points will be clipped by the central body.
void	setCullFace(CullFace value) Sets whether front and/or back-facing triangles may be culled.
void	setDestinationBlendingFunction(BlendingFunction blendingFunction) Gets or set the blending function that is used to modify the destination color before the final blending operation occurs.
void	setLighting(boolean value) Sets whether the primitive is lit.
void	setRenderBackThenFrontFaces(boolean value) Sets whether the primitive is rendered in two passes to improve the visual quality for translucent, convex meshes.
void	setShadeModel(RendererShadeModel shadeModel) Sets the shading model for the mesh.
void	setSourceBlendingFunction(BlendingFunction blendingFunction) Gets or set the blending function that is used to modify the source color before the final blending operation occurs.
void	setTexture(Texture2D texture) Sets the texture to be drawn on the triangle mesh.
void	setTextureFilter(TextureFilter2D filter) Sets the filter used for the Texture associated with this triangle mesh.
void	setTranslucency(float value) Sets the primitive's translucency.
void	setTriangleWindingOrder(WindingOrder value) Sets the orientation of front-facing triangles.
void	setUseCustomBlendingParameters(boolean useCustomBlendingParameters) Gets or set the boolean that defines if custom blending parameters will be used or if it will use the blending parameters set by the particular rendering pass.
void	setWireframe(boolean value) Gets or sets whether the primitive is rendered in wireframe.

Methods inherited from class agi.foundation.graphics.Primitive

dispose, getAutomaticallyComputeBoundingSphere, getBoundingSphere, getColor, getDisplay, getDisplayCondition, getReferenceFrame, getTag, getTranslucency, setAutomaticallyComputeBoundingSphere, setBoundingSphere, setColor, 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

TriangleMeshPrimitive

public TriangleMeshPrimitive()

Initializes a default triangle mesh primitive. This is equivalent to constructing a triangle mesh with a SetHint of Frequent.

See TriangleMeshPrimitive.TriangleMeshPrimitive(agi.foundation.graphics.SetHint) for a full discussion.

See Also:

TriangleMeshPrimitive.TriangleMeshPrimitive(agi.foundation.graphics.SetHint)

TriangleMeshPrimitive

public TriangleMeshPrimitive(SetHint setHint)

Initializes a triangle mesh primitive with the specified setHint .

After constructing the primitive, call TriangleMeshPrimitive.set(agi.foundation.geometry.discrete.TriangulatorResult) or TriangleMeshPrimitive.set(java.lang.Iterable,java.lang.Iterable,java.lang.Iterable) to provide it with a mesh for rendering.

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

• agi.foundation.graphics.primitive.AutomaticallyComputeBoundingSphere: true
• agi.foundation.graphics.primitive.BoundingSphere: BoundingSphere.MaximumRadiusBoundingSphere (get)
• agi.foundation.graphics.primitive.Color: Yellow
• 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
• agi.foundation.graphics.primitive.Translucency: 0.7f
• CullFace: Neither
• SetHint: setHint
• TriangleWindingOrder: CounterClockwise
• Wireframe: false
• RenderBackThenFrontFaces: false

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

Parameters:

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

Throws:

UnsupportedCaseException - setHint must be agi.foundation.graphics.SetHint#Infrequent or agi.foundation.graphics.SetHint#Frequent. agi.foundation.graphics.SetHint#Partial is not supported by this primitive.

See Also:

TriangleMeshPrimitive.set(agi.foundation.geometry.discrete.TriangulatorResult), TriangleMeshPrimitive.set(java.lang.Iterable,java.lang.Iterable,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

getWireframe

public final boolean getWireframe()

Gets or sets whether the primitive is rendered in wireframe. This is useful for debugging.

setWireframe

public final void setWireframe(boolean value)

Gets or sets whether the primitive is rendered in wireframe. This is useful for debugging.

getRenderBackThenFrontFaces

public final boolean getRenderBackThenFrontFaces()

Gets whether the primitive is rendered in two passes to improve the visual quality for translucent, convex meshes.

If the mesh represents a translucent, convex object, such as an open box or cone, it is recommended to set this property to true to eliminate artifacts when parts of the mesh overlap each other.

setRenderBackThenFrontFaces

public final void setRenderBackThenFrontFaces(boolean value)

Sets whether the primitive is rendered in two passes to improve the visual quality for translucent, convex meshes.

If the mesh represents a translucent, convex object, such as an open box or cone, it is recommended to set this property to true to eliminate artifacts when parts of the mesh overlap each other.

getLighting

public final boolean getLighting()

Gets whether the primitive is lit.

setLighting

public final void setLighting(boolean value)

Sets whether the primitive is lit.

getTriangleWindingOrder

public final WindingOrder getTriangleWindingOrder()

Gets the orientation of front-facing triangles. This is used in combination with CullFace for culling.

Throws:

UnsupportedCaseException - TriangleWindingOrder must be Clockwise or CounterClockwise.

See Also:

Backface Culling topic, CullFace

setTriangleWindingOrder

public final void setTriangleWindingOrder(WindingOrder value)

Sets the orientation of front-facing triangles. This is used in combination with CullFace for culling.

Throws:

UnsupportedCaseException - TriangleWindingOrder must be Clockwise or CounterClockwise.

See Also:

Backface Culling topic, CullFace

getCullFace

public final CullFace getCullFace()

Gets whether front and/or back-facing triangles may be culled. This is used in combination with TriangleWindingOrder for culling.

Throws:

UnsupportedCaseException - CullFace must be a valid enumeration value in CullFace.

See Also:

Backface Culling topic, TriangleWindingOrder

setCullFace

public final void setCullFace(CullFace value)

Sets whether front and/or back-facing triangles may be culled. This is used in combination with TriangleWindingOrder for culling.

Throws:

UnsupportedCaseException - CullFace must be a valid enumeration value in CullFace.

See Also:

Backface Culling topic, TriangleWindingOrder

getShadeModel

public final RendererShadeModel getShadeModel()

Gets the shading model for the mesh.

Throws:

UnsupportedCaseException - RendererShadeModel must be a valid enumeration value in RendererShadeModel

setShadeModel

public final void setShadeModel(RendererShadeModel shadeModel)

Sets the shading model for the mesh.

Throws:

UnsupportedCaseException - RendererShadeModel must be a valid enumeration value in RendererShadeModel

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.

getTexture

public Texture2D getTexture()

Gets the texture to be drawn on the triangle mesh. Textures can be obtained from SceneManager.Textures (get).

If a texture is added to a triangle mesh, the mesh must be set with TriangleMeshOptionalParameters that have texture coordinates.

Throws:

IllegalStateException - When TextureFilter is set to a mipmapping filter the new Texture must be mipmap capable.

See Also:

Texture2D, Texture2DFactory, TextureFilter2D

setTexture

public void setTexture(Texture2D texture)

Sets the texture to be drawn on the triangle mesh. Textures can be obtained from SceneManager.Textures (get).

If a texture is added to a triangle mesh, the mesh must be set with TriangleMeshOptionalParameters that have texture coordinates.

Throws:

IllegalStateException - When TextureFilter is set to a mipmapping filter the new Texture must be mipmap capable.

See Also:

Texture2D, Texture2DFactory, TextureFilter2D

getTextureFilter

public TextureFilter2D getTextureFilter()

Gets the filter used for the Texture associated with this triangle mesh.

Throws:

IllegalStateException - Cannot set the TextureFilter to a mipmapping filter if the currently set Texture is not mipmap capable.

See Also:

TextureFilter2D, Texture2DFactory

setTextureFilter

public void setTextureFilter(TextureFilter2D filter)

Sets the filter used for the Texture associated with this triangle mesh.

Throws:

IllegalStateException - Cannot set the TextureFilter to a mipmapping filter if the currently set Texture is not mipmap capable.

See Also:

TextureFilter2D, Texture2DFactory

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.

getUseCustomBlendingParameters

public final boolean getUseCustomBlendingParameters()

Gets or set the boolean that defines if custom blending parameters will be used or if it will use the blending parameters set by the particular rendering pass.

setUseCustomBlendingParameters

public final void setUseCustomBlendingParameters(boolean useCustomBlendingParameters)

Gets or set the boolean that defines if custom blending parameters will be used or if it will use the blending parameters set by the particular rendering pass.

getBlendingEquation

public final BlendingEquation getBlendingEquation()

Gets or set the blending equation used when compositing a transparent triangle mesh.

setBlendingEquation

public final void setBlendingEquation(BlendingEquation blendingEquation)

Gets or set the blending equation used when compositing a transparent triangle mesh.

getSourceBlendingFunction

public final BlendingFunction getSourceBlendingFunction()

Gets or set the blending function that is used to modify the source color before the final blending operation occurs.

setSourceBlendingFunction

public final void setSourceBlendingFunction(BlendingFunction blendingFunction)

Gets or set the blending function that is used to modify the source color before the final blending operation occurs.

getDestinationBlendingFunction

public final BlendingFunction getDestinationBlendingFunction()

Gets or set the blending function that is used to modify the destination color before the final blending operation occurs.

setDestinationBlendingFunction

public final void setDestinationBlendingFunction(BlendingFunction blendingFunction)

Gets or set the blending function that is used to modify the destination color before the final blending operation occurs.

getBlendingColor

public final Color getBlendingColor()

Gets the blending color.

setBlendingColor

public final void setBlendingColor(Color value)

Sets the blending color.

setTranslucency

public void setTranslucency(float value)

Description copied from class: Primitive

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

Overrides:

setTranslucency in class Primitive

set

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

Defines the triangle mesh using an indexed triangle list specified by positions, normals, and indices. The mesh is rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

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 the input. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses the input.

Parameters:

positions - Positions for the triangle mesh.

normals - Normals used for lighting the triangle mesh. There must be one normal for each position in positions.

indices - Indices into positions and normals. Every 3 indices represent 1 triangle.

Throws:

ArgumentNullException - positions, normals, or indices is null.

ArgumentException - The number of positions and number of normals must be the same.

ArgumentException - The number of indices must be divisible by 3.

CouldNotCreateVideoCardResourceException - Could not allocate video memory for the mesh.

See Also:

Triangle Mesh Primitive topic - Indexed Triangle Lists, Performance topic

set

public final void set(Iterable<Cartesian> positions,
                      Iterable<Cartesian> normals,
                      Iterable<Integer> indices,
                      TriangleMeshPrimitiveOptionalParameters optionalParameters)

Defines the triangle mesh using an indexed triangle list specified by positions, normals, indices, and optionalParameters. The mesh is rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

See TriangleMeshPrimitiveOptionalParameters for details on how to define 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 the input. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses the input.

Parameters:

positions - Positions for the triangle mesh.

normals - Normals used for lighting the triangle mesh. There must be one normal for each position in positions.

indices - Indices into positions and normals. Every 3 indices represent 1 triangle.

optionalParameters - Optional parameters corresponding to positions.

Throws:

ArgumentNullException - positions, normals, or indices is null.

ArgumentException - The number of positions and number of normals must be the same.

ArgumentException - The number of indices must be divisible by 3.

CouldNotCreateVideoCardResourceException - Could not allocate video memory for the mesh.

See Also:

Triangle Mesh Primitive topic - Indexed Triangle Lists, Performance topic

set

public final void set(TriangulatorResult triangulator)

Defines the triangle mesh using the specified triangulator. The mesh is rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.

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 the input. Otherwise, it is the caller's responsibility to update the primitive's BoundingSphere (get) to a sphere that encompasses the input.

Parameters:

triangulator - The triangulator used to define the triangle mesh.

Throws:

ArgumentNullException - triangulator is null.

CouldNotCreateVideoCardResourceException - Could not allocate video memory for the mesh.

See Also:

Triangle Mesh Primitive topic, Performance topic