GroundPrimitive - SuperMap3D Documentation

GroundPrimitive

new SuperMap3D.GroundPrimitive(options)

地面基元代表场景中覆盖在地形上的几何体。目前还不支持批处理多个几何体。

将几何体实例与Appearance结合在一起，Appearance描述了完整的阴影，包括Material和RenderState。粗略地说，几何体实例定义了结构和位置，而外观定义了视觉特征。将几何体和外观解耦后，我们就可以混合和匹配大部分几何体和外观，并独立添加新的几何体或外观。目前只支持PerInstanceColorAppearance。

为实现正确的渲染，该功能需要使用 EXT_frag_depth WebGL 扩展。对于不支持该扩展的硬件，在某些视角下会出现渲染伪像。

有效的几何体包括：CircleGeometry, CorridorGeometry, EllipseGeometry, PolygonGeometry, and RectangleGeometry。

Name Type Description

options

Object

optional 具有以下属性的对象:

Name	Type	Default	Description
`geometryInstances`	Array \| GeometryInstance		optional 要渲染的几何体实例。
`show`	Boolean	`true`	optional 确定是否显示该基元。
`vertexCacheOptimize`	Boolean	`false`	optional 为true时，几何顶点将针对前置和后置顶点着色器缓存进行优化。
`interleave`	Boolean	`false`	optional 为true时，几何顶点属性会交错显示，这可以略微提高呈现性能，但会增加加载时间。
`compressVertices`	Boolean	`true`	optional 为true时，几何顶点将被压缩，从而节省内存。
`releaseGeometryInstances`	Boolean	`true`	optional 为true时，基元不会保留对输入 geometryInstances 的引用，以节省内存。
`allowPicking`	Boolean	`true`	optional 为true时，每个几何体实例只能通过 `Scene#pick` 进行拾取。为false时，将保存 GPU 内存。
`asynchronous`	Boolean	`true`	optional 确定基元是异步创建还是阻塞创建，直到准备就绪。如果为 false，则必须先调用 initializeTerrainHeights()。
`debugShowBoundingVolume`	Boolean	`false`	optional 仅用于调试。确定是否显示该基元的命令包围球。
`debugShowShadowVolume`	Boolean	`false`	optional 仅用于调试。确定是否绘制基元中每个几何图形的阴影体积。必须在创建时为true，以便在释放几何体或选项之前创建体。releaseGeometryInstance必须为false。

Example:

// Example 1: Create primitive with a single instance
var rectangleInstance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.RectangleGeometry({
    rectangle : SuperMap3D.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0)
  }),
  id : 'rectangle',
  attributes : {
    color : new SuperMap3D.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
  }
});
scene.primitives.add(new SuperMap3D.GroundPrimitive({
  geometryInstances : rectangleInstance
}));

// Example 2: Batch instances
var color = new SuperMap3D.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5); // Both instances must have the same color.
var rectangleInstance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.RectangleGeometry({
    rectangle : SuperMap3D.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0)
  }),
  id : 'rectangle',
  attributes : {
    color : color
  }
});
var ellipseInstance = new SuperMap3D.GeometryInstance({
    geometry : new SuperMap3D.EllipseGeometry({
        center : SuperMap3D.Cartesian3.fromDegrees(-105.0, 40.0),
        semiMinorAxis : 300000.0,
        semiMajorAxis : 400000.0
    }),
    id : 'ellipse',
    attributes : {
        color : color
    }
});
scene.primitives.add(new SuperMap3D.GroundPrimitive({
  geometryInstances : [rectangleInstance, ellipseInstance]
}));

See:

Members

readonlyallowPicking : Boolean

为true时，每个几何体实例只能通过 Scene#pick 进行拾取。为false时，将保存 GPU 内存。

Default Value: true

readonlyasynchronous : Boolean

决定是否在网络 Worker 上创建和批处理几何体实例。

Default Value: true

readonlycompressVertices : Boolean

为true时，几何顶点将被压缩，从而节省内存。

Default Value: true

debugShowBoundingVolume : Boolean

该属性仅用于调试，不用于生产，也未优化。

为基元中的每个绘制命令绘制包围球。

Default Value: false

debugShowShadowVolume : Boolean

该属性仅用于调试，不用于生产，也未优化。

为基元中的每个几何体绘制阴影体。

Default Value: false

geometryInstances : Array|GeometryInstance

与此基元一起渲染的几何体实例。如果构建基元时 options.releaseGeometryInstances 为 true，则可能未定义。

在渲染基元后更改此属性不会产生任何影响。

由于使用了渲染技术，所有几何体实例的颜色必须相同。如果存在颜色不同的实例，第一次尝试渲染时将会抛出 DeveloperError。

Default Value: undefined

readonlyinterleave : Boolean

确定几何顶点属性是否交错，这样可以略微提高渲染性能。

Default Value: false

readonlyready : Boolean

确定基元是否已完成并准备好渲染。如果该属性为 true，则将在下一次调用 GroundPrimitive#update 时渲染该基元。

readonlyreadyPromise : Promise.<GroundPrimitive>

获取一个Promise，该Promise会在基元准备好渲染时解析。

readonlyreleaseGeometryInstances : Boolean

为true时，基元不会保留对输入 geometryInstances 的引用，以节省内存。

Default Value: true

show : Boolean

确定是否显示基元。这会影响基元中的所有几何体实例。

Default Value: true

readonlyvertexCacheOptimize : Boolean

为true时，几何顶点将针对前置和后置顶点着色器缓存进行优化。

Default Value: true

Methods

staticSuperMap3D.GroundPrimitive.initializeTerrainHeights() → Promise

Initializes the minimum and maximum terrain heights. This only needs to be called if you are creating the GroundPrimitive synchronously.

Returns:

A promise that will resolve once the terrain heights have been loaded.

staticSuperMap3D.GroundPrimitive.isSupported(scene) → Boolean

确定是否支持 GroundPrimitive 渲染。

Name	Type	Description
`scene`	Scene	场景。

Returns:

如果支持 GroundPrimitives，则返回 true；否则，返回 false

destroy() → undefined

销毁该对象持有的 WebGL 资源。销毁对象可以确定性地释放 WebGL 资源，而不是依赖垃圾回收器来销毁该对象。

一旦对象被销毁，就不应再使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。因此，请按照示例中的方法将返回值（undefined）赋值给对象。

Returns:

Throws:

DeveloperError : 该对象已被销毁，即 destroy() 被调用。

Example:

e = e && e.destroy();

See:

GroundPrimitive#isDestroyed

getGeometryInstanceAttributes(id) → Object

返回 GeometryInstance 的每个实例的可修改属性。

Name	Type	Description
`id`	Object	`GeometryInstance` 的 id。

Returns:

属性格式的类型数组，如果没有 id 的实例，则未定义。

Throws:

DeveloperError : 必须在调用 getGeometryInstanceAttributes 之前调用 update。

Example:

var attributes = primitive.getGeometryInstanceAttributes('an id');
attributes.color = SuperMap3D.ColorGeometryInstanceAttribute.toValue(SuperMap3D.Color.AQUA);
attributes.show = SuperMap3D.ShowGeometryInstanceAttribute.toValue(true);

isDestroyed() → Boolean

如果该对象已被销毁，则返回 true；否则返回 false。

如果该对象已被销毁，则不应使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。

Returns:

如果该对象已被销毁，则为 true；否则为 false

See:

GroundPrimitive#destroy

update()

在Viewer 或 Widget 渲染场景时调用，以获取渲染该基元所需的绘制指令。

请勿直接调用此函数。记录此函数只是为了列出场景渲染时可能传播的异常：

Throws:

DeveloperError : 所有几何体实例必须具有相同的 primitiveType。
DeveloperError : 外观和材质有统一的名称。
DeveloperError : 并非所有几何体实例都具有相同的颜色属性。