Primitive

基本体表示Scene中的几何体。几何图形可以来自下面的示例1所示的单个GeometryInstance，也可以来自实例数组，即使几何图形来自不同的几何图形类型，如代码示例2中所示的RectangleGeometry和EllipsoidGeometry。

基本体将几何体实例与描述完整着色的Appearance结合起来，包括Material和RenderState。大致上，几何体实例定义结构和位置，外观定义视觉特征。分离几何体和外观允许我们混合和匹配大多数几何体和外观，并独立地添加新的几何体或外观。

将多个实例组合成一个原语称为批处理，显著提高了静态数据的性能。实例可以单独选取；Scene#pick返回其GeometryInstance#id。使用类似于PerInstanceColorAppearance的每个实例外观，每个实例也可以具有唯一的颜色。

Geometry可以在Web工作者或主线程上创建和批处理。前两个示例显示将使用几何图形的描述在Web工作者上创建的几何图形。第三个示例演示如何通过显式调用createGeometry方法在主线程上创建几何体。

new Primitive(options)

Parameters:

options (Object)

Name	Description
options.geometryInstances `(Array.<GeometryInstance> \| GeometryInstance)`	要渲染的几何体实例-或单个几何体实例。
options.appearance `Appearance`	用于呈现原语的外观。
options.depthFailAppearance `Appearance`	用于在深度测试失败时对该基元进行着色的外观。
options.show `Boolean` default `true`	确定是否显示此基元。
options.modelMatrix `Matrix4` default `Matrix4.IDENTITY`	将基本体（所有几何体实例）从模型转换为世界坐标的4x4转换矩阵。
options.vertexCacheOptimize `Boolean` default `false`	当`true`时，几何体顶点将针对顶点前和顶点后明暗器缓存进行优化。
options.interleave `Boolean` default `false`	当`true`时，几何顶点属性交错，这可以稍微提高渲染性能，但增加加载时间。
options.compressVertices `Boolean` default `true`	当`true`时，几何体顶点被压缩，这将节省内存。
options.releaseGeometryInstances `Boolean` default `true`	当`true`时，原语不保留对输入`geometryInstances`的引用以保存内存。
options.allowPicking `Boolean` default `true`	当`true`时，每个几何体实例只能使用`Scene#pick`进行选择。当`false`时，保存GPU内存。
options.cull `Boolean` default `true`	当`true`时，渲染器的平截体剔除和地平线根据其边界体积剔除基本体的命令。如果要手动剔除原语，请将其设置为`false`以获得较小的性能增益。
options.asynchronous `Boolean` default `true`	确定在准备就绪之前是异步创建基元还是阻止创建基元。
options.debugShowBoundingVolume `Boolean` default `false`	仅用于调试。确定是否显示此基元的命令的边界球。
options.shadows `ShadowMode` default `ShadowMode.DISABLED`	确定此基元是投射还是接收来自每个光源的阴影。

Examples

// 1. Draw a translucent ellipse on the surface with a checkerboard pattern
var instance = new bmgl.GeometryInstance({
  geometry : new bmgl.EllipseGeometry({
      center : bmgl.Cartesian3.fromDegrees(-100.0, 20.0),
      semiMinorAxis : 500000.0,
      semiMajorAxis : 1000000.0,
      rotation : bmgl.Math.PI_OVER_FOUR,
      vertexFormat : bmgl.VertexFormat.POSITION_AND_ST
  }),
  id : 'object returned when this instance is picked and to get/set per-instance attributes'
});
scene.primitives.add(new bmgl.Primitive({
  geometryInstances : instance,
  appearance : new bmgl.EllipsoidSurfaceAppearance({
    material : bmgl.Material.fromType('Checkerboard')
  })
}));

// 2. Draw different instances each with a unique color
var rectangleInstance = new bmgl.GeometryInstance({
  geometry : new bmgl.RectangleGeometry({
    rectangle : bmgl.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0),
    vertexFormat : bmgl.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  id : 'rectangle',
  attributes : {
    color : new bmgl.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
  }
});
var ellipsoidInstance = new bmgl.GeometryInstance({
  geometry : new bmgl.EllipsoidGeometry({
    radii : new bmgl.Cartesian3(500000.0, 500000.0, 1000000.0),
    vertexFormat : bmgl.VertexFormat.POSITION_AND_NORMAL
  }),
  modelMatrix : bmgl.Matrix4.multiplyByTranslation(bmgl.Transforms.eastNorthUpToFixedFrame(
    bmgl.Cartesian3.fromDegrees(-95.59777, 40.03883)), new bmgl.Cartesian3(0.0, 0.0, 500000.0), new bmgl.Matrix4()),
  id : 'ellipsoid',
  attributes : {
    color : bmgl.ColorGeometryInstanceAttribute.fromColor(bmgl.Color.AQUA)
  }
});
scene.primitives.add(new bmgl.Primitive({
  geometryInstances : [rectangleInstance, ellipsoidInstance],
  appearance : new bmgl.PerInstanceColorAppearance()
}));

// 3. Create the geometry on the main thread.
scene.primitives.add(new bmgl.Primitive({
  geometryInstances : new bmgl.GeometryInstance({
      geometry : bmgl.EllipsoidGeometry.createGeometry(new bmgl.EllipsoidGeometry({
        radii : new bmgl.Cartesian3(500000.0, 500000.0, 1000000.0),
        vertexFormat : bmgl.VertexFormat.POSITION_AND_NORMAL
      })),
      modelMatrix : bmgl.Matrix4.multiplyByTranslation(bmgl.Transforms.eastNorthUpToFixedFrame(
        bmgl.Cartesian3.fromDegrees(-95.59777, 40.03883)), new bmgl.Cartesian3(0.0, 0.0, 500000.0), new bmgl.Matrix4()),
      id : 'ellipsoid',
      attributes : {
        color : bmgl.ColorGeometryInstanceAttribute.fromColor(bmgl.Color.AQUA)
      }
  }),
  appearance : new bmgl.PerInstanceColorAppearance()
}));

See:

Members

(readonly) allowPicking : Boolean

当true时，每个几何体实例只能使用Scene#pick进行选择。当false时，保存GPU内存。*

Default Value: true

appearance : Appearance

Appearance用于对该原语进行着色。每个几何体实例都以相同的外观着色。一些外观，如PerInstanceColorAppearance允许为每个实例提供唯一的属性。

Default Value: undefined

(readonly) asynchronous : Boolean

确定是否将在Web工作者上创建和批处理几何体实例。

Default Value: true

(readonly) compressVertices : Boolean

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

Default Value: true

cull : Boolean

当true时，渲染器的平截体剔除和地平线根据其边界体积剔除基本体的命令。如果要手动剔除原语，请将其设置为false以获得较小的性能增益。

Default Value: true

debugShowBoundingVolume : Boolean

此属性仅用于调试；它既不用于生产，也不进行优化。

为基本体中的每个draw命令绘制边界球体。

Default Value: false

depthFailAppearance : Appearance

Appearance用于在深度测试失败时对该原语进行着色。每个几何体实例都以相同的外观着色。一些外观，如PerInstanceColorAppearance允许为每个实例提供唯一的属性。

当使用需要颜色属性的外观时，如PerInstanceColorAppearance，请为每个实例属性添加DepthFailColor。

需要ext}frag_depth webgl扩展以正确呈现。如果不支持扩展，则可能存在工件。

Default Value: undefined

(readonly) geometryInstances : (Array.<GeometryInstance>|GeometryInstance)

使用此基元渲染的几何体实例。在构造基元时，如果options.releaseGeometryInstances是true，则可能是undefined。

在呈现基元后更改此属性没有效果。

Default Value: undefined

(readonly) interleave : Boolean

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

Default Value: false

modelMatrix : Matrix4

将基本体（所有几何体实例）从模型转换为世界坐标的4x4转换矩阵。当这是一个单位矩阵时，原语以世界坐标绘制，即地球的wgs84坐标。本地参考帧可以通过提供不同的转换矩阵来使用，如Transforms.eastNorthUpToFixedFrame返回的转换矩阵。

此属性仅在3D模式下受支持。

Default Value: Matrix4.IDENTITY

Example:

var origin = bmgl.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
p.modelMatrix = bmgl.Transforms.eastNorthUpToFixedFrame(origin);

(readonly) ready : Boolean

确定基元是否已完成并准备好呈现。如果此属性为真，则下次调用Primitive#update时将呈现原语。

(readonly) readyPromise : Promise.<Primitive>

获取解决基元何时准备呈现的承诺。

(readonly) releaseGeometryInstances : Boolean

当true时，原语不保留对输入geometryInstances的引用以保存内存。

Default Value: true

shadows : ShadowMode

确定此基元是投射还是接收来自每个光源的阴影。

Default Value: ShadowMode.DISABLED

show : Boolean

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

Default Value: true

(readonly) vertexCacheOptimize : Boolean

当true时，几何体顶点将针对顶点前和顶点后明暗器缓存进行优化。

Default Value: true

Methods

destroy()

销毁此对象持有的WebGL资源。销毁对象允许确定地释放WebGL资源，而不是依赖垃圾收集器来销毁此对象。

一旦对象被破坏，就不应使用它；调用除isDestroyed以外的任何函数都将导致DeveloperError异常。因此，将返回值（undefined）赋给对象，如示例中所述。

Example

e = e && e.destroy();

Throws

DeveloperError : 此对象已被销毁，即调用destroy（）。

See:

Primitive#isDestroyed

getGeometryInstanceAttributes(id) → {Object}

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

Parameters:

id (*) GeometryInstance的ID。

Example

var attributes = primitive.getGeometryInstanceAttributes('an id');
attributes.color = bmgl.ColorGeometryInstanceAttribute.toValue(bmgl.Color.AQUA);
attributes.show = bmgl.ShowGeometryInstanceAttribute.toValue(true);
attributes.distanceDisplayCondition = bmgl.DistanceDisplayConditionGeometryInstanceAttribute.toValue(100.0, 10000.0);
attributes.offset = bmgl.OffsetGeometryInstanceAttribute.toValue(Cartesian3.IDENTITY);

Throws

DeveloperError : 必须在调用GetGeometryInstanceAttributes之前调用Update。

isDestroyed() → {Boolean}

如果此对象被破坏，则返回true；否则返回false。

如果此对象被破坏，则不应使用它；调用除isDestroyed以外的任何函数都将导致DeveloperError异常。

See:

Primitive#destroy

update()

当Viewer或BMWidget渲染场景以获取渲染此原语所需的绘制命令时调用。

不要直接调用此函数。这只是为了列出渲染场景时可能传播的异常：

Throws

DeveloperError : 所有实例几何必须具有相同的PrimitiveType。
DeveloperError : 外观和材料有一个统一的名称。
DeveloperError : Primitive.ModelMatrix仅在3D模式下受支持。
RuntimeError : 需要顶点纹理获取支持来渲染具有每个实例属性的基本体。顶点纹理图像单位的最大数目必须大于零。