SurfaceMeshPrimitive

java.lang.Object
- agi.foundation.graphics.Primitive
- - agi.foundation.graphics.SurfaceMeshPrimitive

All Implemented Interfaces:

IDisposable, AutoCloseable
```
public final class SurfaceMeshPrimitive
extends Primitive
implements IDisposable
```
A triangle mesh primitive for meshes on the surface that need to conform to terrain.

See Also:

Surface Mesh Primitive topic, Triangle Mesh Primitive topic

Constructor Summary

Constructors
Constructor and Description
`SurfaceMeshPrimitive()` Initializes a default surface mesh primitive.
`SurfaceMeshPrimitive(SetHint setHint)` Initializes a surface mesh primitive with the specified `setHint`.
`SurfaceMeshPrimitive(SetHint setHint, SurfaceMeshRenderingMethod renderingMethod)` Initializes a surface mesh primitive with the specified `setHint` and `renderingMethod`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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 surface mesh.
`BlendingFunction`	`getDestinationBlendingFunction()` Gets or set the blending function that is used to modify the destination color before the final blending operation occurs.
`SurfaceMeshRenderingMethod`	`getRenderingMethod()` Gets the rendering method used to render the mesh.
`SetHint`	`getSetHint()` Gets the primitive's `SetHint`.
`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 applied to this primitive when rendering.
`TextureFilter2D`	`getTextureFilter()` Gets the filter used when a `Texture` is applied to this primitive.
`TextureMatrix`	`getTextureMatrix()` Gets the matrix used to transform texture coordinates when a `Texture` is applied to this primitive.
`boolean`	`getTransparentTextureBorder()` Gets or set the boolean that defines if the color obtained from texture coordinates beyond the texture border should be considered transparent or not.
`WindingOrder`	`getTriangleWindingOrder()` Gets the orientation of front-facing triangles in the mesh.
`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(SurfaceTriangulatorResult surfaceTriangulator)` Defines the surface mesh using the specified `surfaceTriangulator`.
`void`	`setBlendingColor(Color value)` Sets the blending color.
`void`	`setBlendingEquation(BlendingEquation blendingEquation)` Gets or set the blending equation used when compositing a transparent surface mesh.
`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`	`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 value)` Sets the texture applied to this primitive when rendering.
`void`	`setTextureFilter(TextureFilter2D filter)` Sets the filter used when a `Texture` is applied to this primitive.
`void`	`setTextureMatrix(TextureMatrix matrix)` Sets the matrix used to transform texture coordinates when a `Texture` is applied to this primitive.
`void`	`setTransparentTextureBorder(boolean transparentTextureBorder)` Gets or set the boolean that defines if the color obtained from texture coordinates beyond the texture border should be considered transparent or not.
`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.
`void`	`setWithoutTexturing(SurfaceTriangulatorResult surfaceTriangulator)` Defines the surface mesh using the specified `surfaceTriangulator`.
`static boolean`	`supported()` Determines whether or not the video card supports the surface mesh primitive.
`static boolean`	`supported(SurfaceMeshRenderingMethod renderingMethod)` Determines whether or not the video card supports the surface mesh primitive with the given `renderingMethod`.

Methods inherited from class agi.foundation.graphics.Primitive
dispose, getAutomaticallyComputeBoundingSphere, getBoundingSphere, getColor, getDisplay, getDisplayCondition, getReferenceFrame, getTag, getTranslucency, setAutomaticallyComputeBoundingSphere, setBoundingSphere, setColor, setDisplay, setDisplayCondition, setReferenceFrame, setTag, setTranslucency

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
  - SurfaceMeshPrimitive
```
public SurfaceMeshPrimitive()
```
    Initializes a default surface mesh primitive. This is equivalent to constructing a surface mesh with a SetHint of Frequent and a SurfaceMeshRenderingMethod of Automatic.
    See SurfaceMeshPrimitive.SurfaceMeshPrimitive(agi.foundation.graphics.SetHint,agi.foundation.graphics.advanced.SurfaceMeshRenderingMethod) for a full discussion.
    
    See Also:
    
    SurfaceMeshPrimitive.SurfaceMeshPrimitive(agi.foundation.graphics.SetHint,agi.foundation.graphics.advanced.SurfaceMeshRenderingMethod)
  - SurfaceMeshPrimitive
```
public SurfaceMeshPrimitive(SetHint setHint)
```
    Initializes a surface mesh primitive with the specified setHint. This is equivalent to constructing a surface mesh with the specified setHint and a SurfaceMeshRenderingMethod of Automatic.
    See SurfaceMeshPrimitive.SurfaceMeshPrimitive(agi.foundation.graphics.SetHint,agi.foundation.graphics.advanced.SurfaceMeshRenderingMethod) for a full discussion.
    
    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:
    
    SurfaceMeshPrimitive.SurfaceMeshPrimitive(agi.foundation.graphics.SetHint,agi.foundation.graphics.advanced.SurfaceMeshRenderingMethod)
  - SurfaceMeshPrimitive
```
public SurfaceMeshPrimitive(SetHint setHint,
                            SurfaceMeshRenderingMethod renderingMethod)
```
    Initializes a surface mesh primitive with the specified setHint and renderingMethod.
    After constructing the primitive, call Set 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: 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
    - agi.foundation.graphics.primitive.Translucency: 0.5f
    - RenderingMethod: renderingMethod
    - SetHint: setHint
    - Texture: null
    - TextureFilter: LinearClampToEdge (get)
    - TextureMatrix: Identity
    - TriangleWindingOrder: CounterClockwise
    - Wireframe: 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.
    
    renderingMethod - The method used to render the primitive.
    
    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.
    
    UnsupportedCaseException - renderingMethod must be a valid value in SurfaceMeshRenderingMethod.
    
    InsufficientVideoCardException - The surface mesh is not supported by this video card. Check SurfaceMeshPrimitive.supported() to determine if the surface mesh is supported.
    
    See Also:
    
    Set, SurfaceMeshPrimitive.supported()
- 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
  - getTexture
```
public final Texture2D getTexture()
```
    Gets the texture applied to this primitive when rendering.
    When a Texture is defined, it is modulated with the primitive's agi.foundation.graphics.primitive.Color. In order to show just the texture color, make sure agi.foundation.graphics.primitive.Color is White.
    
    By default, the texture is aligned north and encompasses the bounding extent of the surface mesh. Use TextureMatrix to scale, translate, and/or rotate the texture.
    
    The texture will not show up correctly if SetWithoutTexturing is used to define the surface mesh. When a texturing is desired, always use Set instead of SetWithoutTexturing.
    
    If rendering performance is poor when a texture is applied to the surface mesh, it is likely that the texturing is occurring in software instead of hardware. If you experience this, try updating your video card drivers.
    
    Throws:
    
    IllegalStateException - When TextureFilter is set to a mipmapping filter the new Texture must be mipmap capable.
    
    See Also:
    
    TextureMatrix, TextureFilter, Set, SetWithoutTexturing, Texture2DFactory, TextureFilter2D
  - setTexture
```
public final void setTexture(Texture2D value)
```
    Sets the texture applied to this primitive when rendering.
    When a Texture is defined, it is modulated with the primitive's agi.foundation.graphics.primitive.Color. In order to show just the texture color, make sure agi.foundation.graphics.primitive.Color is White.
    
    By default, the texture is aligned north and encompasses the bounding extent of the surface mesh. Use TextureMatrix to scale, translate, and/or rotate the texture.
    
    The texture will not show up correctly if SetWithoutTexturing is used to define the surface mesh. When a texturing is desired, always use Set instead of SetWithoutTexturing.
    
    If rendering performance is poor when a texture is applied to the surface mesh, it is likely that the texturing is occurring in software instead of hardware. If you experience this, try updating your video card drivers.
    
    Throws:
    
    IllegalStateException - When TextureFilter is set to a mipmapping filter the new Texture must be mipmap capable.
    
    See Also:
    
    TextureMatrix, TextureFilter, Set, SetWithoutTexturing, Texture2DFactory, TextureFilter2D
  - 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.
  - getTriangleWindingOrder
```
public final WindingOrder getTriangleWindingOrder()
```
    Gets the orientation of front-facing triangles in the mesh.
  - 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.
  - getRenderingMethod
```
public final SurfaceMeshRenderingMethod getRenderingMethod()
```
    Gets the rendering method used to render the mesh.
  - getTextureFilter
```
public final TextureFilter2D getTextureFilter()
```
    Gets the filter used when a Texture is applied to this primitive.
    
    Throws:
    
    IllegalStateException - Cannot set the TextureFilter to a mipmapping filter if the currently set Texture is not mipmap capable.
    
    See Also:
    
    Texture, Texture2DFactory
  - setTextureFilter
```
public final void setTextureFilter(TextureFilter2D filter)
```
    Sets the filter used when a Texture is applied to this primitive.
    
    Throws:
    
    IllegalStateException - Cannot set the TextureFilter to a mipmapping filter if the currently set Texture is not mipmap capable.
    
    See Also:
    
    Texture, Texture2DFactory
  - getTextureMatrix
```
public final TextureMatrix getTextureMatrix()
```
    Gets the matrix used to transform texture coordinates when a Texture is applied to this primitive.
    Performing transformations with the TextureMatrix over time can create effects such as water movement. See the Surface Mesh Primitive topic, Texture Matrix section for more information on using the TextureMatrix.
    
    See Also:
    
    Surface Mesh Primitive topic - Texture Matrix, Texture
  - setTextureMatrix
```
public final void setTextureMatrix(TextureMatrix matrix)
```
    Sets the matrix used to transform texture coordinates when a Texture is applied to this primitive.
    Performing transformations with the TextureMatrix over time can create effects such as water movement. See the Surface Mesh Primitive topic, Texture Matrix section for more information on using the TextureMatrix.
    
    See Also:
    
    Surface Mesh Primitive topic - Texture Matrix, Texture
  - getTransparentTextureBorder
```
public final boolean getTransparentTextureBorder()
```
    Gets or set the boolean that defines if the color obtained from texture coordinates beyond the texture border should be considered transparent or not. This is typically used in conjunction with the a TextureMatrix.
  - setTransparentTextureBorder
```
public final void setTransparentTextureBorder(boolean transparentTextureBorder)
```
    Gets or set the boolean that defines if the color obtained from texture coordinates beyond the texture border should be considered transparent or not. This is typically used in conjunction with the a TextureMatrix.
  - 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 surface mesh.
  - setBlendingEquation
```
public final void setBlendingEquation(BlendingEquation blendingEquation)
```
    Gets or set the blending equation used when compositing a transparent surface 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.
  - set
```
public final void set(SurfaceTriangulatorResult surfaceTriangulator)
```
    Defines the surface mesh using the specified surfaceTriangulator. 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:
    
    surfaceTriangulator - The surface triangulator used to define the surface mesh.
    
    Throws:
    
    ArgumentNullException - surfaceTriangulator is null.
    
    CouldNotCreateVideoCardResourceException - Could not allocate video memory for the mesh.
    
    CouldNotCreateVideoCardResourceException - Could not compile or link the required shaders. This may indicate that the video driver needs to be updated.
    
    See Also:
    
    Performance topic, SetWithoutTexturing
  - setWithoutTexturing
```
public final void setWithoutTexturing(SurfaceTriangulatorResult surfaceTriangulator)
```
    Defines the surface mesh using the specified surfaceTriangulator. The mesh is rendered in the primitive's agi.foundation.graphics.primitive.ReferenceFrame.
    Calling this method is more efficient than calling Set but the surface mesh will not render textures when this is used instead of Set. Therefore, only use SetWithoutTexturing when the surface mesh's Texture will only ever be null.
    
    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:
    
    surfaceTriangulator - The surface triangulator used to define the surface mesh.
    
    Throws:
    
    ArgumentNullException - surfaceTriangulator is null.
    
    CouldNotCreateVideoCardResourceException - Could not allocate video memory for the mesh.
    
    CouldNotCreateVideoCardResourceException - Could not compile or link the required shaders. This may indicate that the video driver needs to be updated.
    
    See Also:
    
    Performance topic, Set, Texture
  - supported
```
public static final boolean supported(SurfaceMeshRenderingMethod renderingMethod)
```
    Determines whether or not the video card supports the surface mesh primitive with the given renderingMethod.
    
    Parameters:
    
    renderingMethod - The rendering method to check support for.
    
    Returns:
    
    true if the video card supports the surface mesh primitive using the given renderingMethod; otherwise, false.
    
    Throws:
    
    UnsupportedCaseException - renderingMethod must be a valid value in SurfaceMeshRenderingMethod.
    
    See Also:
    
    System Requirements topic
  - supported
```
public static final boolean supported()
```
    Determines whether or not the video card supports the surface mesh primitive. This is equivalent to calling SurfaceMeshPrimitive.supported(agi.foundation.graphics.advanced.SurfaceMeshRenderingMethod) with Automatic.
    
    Returns:
    
    true if the video card supports the surface mesh primitive; otherwise, false.
    
    See Also:
    
    System Requirements topic, SurfaceMeshPrimitive.supported(agi.foundation.graphics.advanced.SurfaceMeshRenderingMethod)

Class SurfaceMeshPrimitive

Constructor Summary

Method Summary

Methods inherited from class agi.foundation.graphics.Primitive

Methods inherited from class java.lang.Object

Methods inherited from interface agi.foundation.compatibility.IDisposable

Constructor Detail

SurfaceMeshPrimitive

SurfaceMeshPrimitive

Method Detail

finalize

dispose

getTexture

setTexture

getWireframe

setWireframe

getTriangleWindingOrder

getSetHint

getRenderingMethod

getTextureFilter

setTextureFilter

getTextureMatrix

setTextureMatrix

getTransparentTextureBorder

setTransparentTextureBorder

getUseCustomBlendingParameters

setUseCustomBlendingParameters

getBlendingEquation

setBlendingEquation

getSourceBlendingFunction

setSourceBlendingFunction

getDestinationBlendingFunction

setDestinationBlendingFunction

getBlendingColor

setBlendingColor

set

setWithoutTexturing

supported

supported