Cesium API - GroundPrimitive 中文文档

new Cesium.GroundPrimitive(options)

GroundPrimitive（贴地图元），表示在场景Scene中覆盖在地形，或者3D Tiles上的图形。

图元（Primitive）将几何图形实例（geometry instances）和外观（Appearance）结合在一起，包括Material and RenderState。大致上几何图形实例定义了结构和位置，外观定义了视觉效果。

需要支持WEBGL_depth_texture扩展来使用除PerInstanceColorAppearance外，还具有不同perinstancecolor颜色或材质的几何实例。

纹理贴地图元是为概念模式而设计的，并不意味着精确地将纹理映射到地形。请使用SingleTileImageryProvider。

为了正确的渲染，这个特性需要EXT_frag_depth WebGL扩展。对于不支持此扩展的硬件，将在某些视角呈现渲染伪像。

支持的集合图形有 CircleGeometry，CorridorGeometry，EllipseGeometry，PolygonGeometry，和RectangleGeometry.

Name Type Description

options

Object

optional 具有下列属性的对象:

Name	Type	Default	Description
`geometryInstances`	Array \| GeometryInstance		optional 要渲染的几何图形实例.
`appearance`	Appearance		optional 几何图形的外观。当几何图形实例具有颜色属性时，默认为PerInstanceColorAppearance.
`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 确定图元是异步创建（true）还是阻塞直到准备就绪。
`classificationType`	ClassificationType	`ClassificationType.BOTH`	optional 确定是贴到地形上还是3DTiles上。
`debugShowBoundingVolume`	Boolean	`false`	optional 只是用来调试，是否显示图元的包围球。
`debugShowShadowVolume`	Boolean	`false`	optional 只是用来调试，确定是否绘制图元中每个几何图形的阴影体。在创建体之前，必须是`true`，几何图形被释放或options.releaseGeometryInstance必须是`false`。

示例：

// 例1: 使用单个实例创建图元
var rectangleInstance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0)
  }),
  id : 'rectangle',
  attributes : {
    color : new Cesium.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
  }
});
scene.primitives.add(new Cesium.GroundPrimitive({
  geometryInstances : rectangleInstance
}));
// 例2: 批量实例
var color = new Cesium.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5); //两个实例必须具有相同的颜色。
var rectangleInstance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0)
  }),
  id : 'rectangle',
  attributes : {
    color : color
  }
});
var ellipseInstance = new Cesium.GeometryInstance({
    geometry : new Cesium.EllipseGeometry({
        center : Cesium.Cartesian3.fromDegrees(-105.0, 40.0),
        semiMinorAxis : 300000.0,
        semiMajorAxis : 400000.0
    }),
    id : 'ellipse',
    attributes : {
        color : color
    }
});
scene.primitives.add(new Cesium.GroundPrimitive({
  geometryInstances : [rectangleInstance, ellipseInstance]
}));

参考：

成员变量

readonlyallowPicking : Boolean

Scene/GroundPrimitive.js 288

当true时, 每个几何体实例只能用Scene#pick来拾取。当false时, 节省GPU内存。

Default Value: true

appearance : Appearance

Scene/GroundPrimitive.js 136

用于给图元着色的Appearance. 每个几何实例都以相同的外观着色，有些外观，如PerInstanceColorAppearance允许赋予每个实例唯一的值。

Default Value: undefined

readonlyasynchronous : Boolean

Scene/GroundPrimitive.js 304

确定图元是异步创建（true）还是阻塞直到准备就绪。

Default Value: true

classificationType : ClassificationType

Scene/GroundPrimitive.js 165

确定是贴到地形上还是3DTiles上。

Default Value: ClassificationType.BOTH

readonlycompressVertices : Boolean

Scene/GroundPrimitive.js 320

当true时, 几何顶点被压缩，这将节省内存。

Default Value: true

debugShowBoundingVolume : Boolean

Scene/GroundPrimitive.js 176

只是用来调试，是否显示图元的包围球。

Default Value: false

debugShowShadowVolume : Boolean

Scene/GroundPrimitive.js 188

只是用来调试

为图元中的每个几何图形绘制阴影体积。

Default Value: false

readonlygeometryInstances : Array|GeometryInstance

Scene/GroundPrimitive.js 149

这个图元渲染的几何实例，它有可能为undefined（当构造图元时，如果options.releaseGeometryInstances属性为true）。

在图元被渲染后，更改此属性无效。

Default Value: undefined

readonlyinterleave : Boolean

Scene/GroundPrimitive.js 256

当true时, 几何顶点属性是交错的，这可以略微提高渲染性能，但增加了加载时间。

Default Value: false

readonlyready : Boolean

Scene/GroundPrimitive.js 334

确定图元是否完成并准备渲染。如果为true,将在下一次调用Primitive#update时渲染图元。

readonlyreadyPromise : Promise.<GroundPrimitive>

Scene/GroundPrimitive.js 346

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

readonlyreleaseGeometryInstances : Boolean

Scene/GroundPrimitive.js 272

当true时, 该图元不保留对输入geometryInstances的引用，以节省内存。

Default Value: true

show : Boolean

Scene/GroundPrimitive.js 157

图元是否显示，这将影响到所有的几何实例（geometryInstances）

Default Value: true

readonlyvertexCacheOptimize : Boolean

Scene/GroundPrimitive.js 240

当true时, 几何顶点被优化为前后顶点着色器缓存。

Default Value: true

内置方法

staticCesium.GroundPrimitive.initializeTerrainHeights() → Promise

Scene/GroundPrimitive.js 573

初始化最小和最大地形高度。只有在同步创建GroundPrimitive时才需要调用它。

返回值：

一个promise，一旦地形高度已加载将解析。

staticCesium.GroundPrimitive.isSupported(scene) → Boolean

Scene/GroundPrimitive.js 360

确定是否支持渲染GroundPrimitive。

Name	Type	Description
`scene`	Scene	The scene.

返回值：

如果支持返回true,不支持返回false。

staticCesium.GroundPrimitive.supportsMaterials(scene) → Boolean

Scene/GroundPrimitive.js 830

检查给定场景是否支持基本材质。 GroundPrimitives上的材质需要支持WEBGL_depth_texture扩展。

Name	Type	Description
`scene`	Scene	当前的场景。

返回值：

当前场景是否支持GroundPrimitives。

destroy()

Scene/GroundPrimitive.js 807

销毁此对象持有的WebGL资源。

一旦对象被销毁，它将不能在使用; 调用除isDestroyed之外的任何函数都会导致DeveloperError异常。因此，将返回值(undefined)赋给对象，如示例所示。

异常情况：

DeveloperError : 对象已经被销毁。

示例：

e = e && e.destroy();

参考：

GroundPrimitive#isDestroyed

getGeometryInstanceAttributes(id) → Object

Scene/GroundPrimitive.js 771

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

Name	Type	Description
`id`	*	`GeometryInstance`的id.

返回值：

以属性格式表示的类型化数组.

异常情况：

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

示例：

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

isDestroyed() → Boolean

Scene/GroundPrimitive.js 790

/** 如果该对象没被销毁，返回false。

如果该对象已经被销毁, 使用isDestroyed 会触发 DeveloperError 异常.

返回值：

false

参考：

GroundPrimitive#destroy

update()

Scene/GroundPrimitive.js 587

当Viewer或CesiumWidget渲染场景以获得渲染此图元所需的draw命令时调用。

不要直接调用这个函数。这被记录下来只是为了列出在场景渲染时可能出现的异常:

异常情况：

DeveloperError : 对于同步的GroundPrimitive，您必须调用GroundPrimitive. initializeterrainheights()并等待返回的promise解析。
DeveloperError : 所有实例几何图形必须具有相同的图元类型。
DeveloperError : 外观和材质有统一的名称。