GroundPrimitive

new Cesium.GroundPrimitive(options)
Scene/GroundPrimitive.js 111

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。
Example:
// 例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]
}));
See:

Members

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

Methods

staticCesium.GroundPrimitive.initializeTerrainHeights() → Promise
Scene/GroundPrimitive.js 573

初始化最小和最大地形高度。只有在同步创建GroundPrimitive时才需要调用它。
Returns:
一个promise，一旦地形高度已加载将解析。

staticCesium.GroundPrimitive.isSupported(scene) → Boolean
Scene/GroundPrimitive.js 360

确定是否支持渲染GroundPrimitive。
Name Type Description
scene Scene The scene.
Returns:
如果支持返回true,不支持返回false。

staticCesium.GroundPrimitive.supportsMaterials(scene) → Boolean
Scene/GroundPrimitive.js 830

检查给定场景是否支持基本材质。 GroundPrimitives上的材质需要支持WEBGL_depth_texture扩展。
Name Type Description
scene Scene 当前的场景。
Returns:
当前场景是否支持GroundPrimitives。

destroy()
Scene/GroundPrimitive.js 807

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

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

getGeometryInstanceAttributes(id) → Object
Scene/GroundPrimitive.js 771

返回 GeometryInstance 的每个实例的可修改属性。
Name Type Description
id * GeometryInstance的id.
Returns:
以属性格式表示的类型化数组.
Throws:
  • DeveloperError : 必须在调用getGeometryInstanceAttributes之前调用update。
Example:
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 异常.
Returns:
false
See:

update()
Scene/GroundPrimitive.js 587

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

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

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