Primitive

new SuperMap3D.Primitive(options)

基元表示场景中的几何体。 几何体可以是单一的GeometryInstance（如下面的示例 1 所示），也可以是由多个实例组成的数组，即使这些几何体属于不同的几何体类型，如代码示例 2 所示的RectangleGeometry 和EllipsoidGeometry。

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

将多个实例合并为一个基元称为批处理，可显著提高静态数据的性能。实例可单独挑选；Scene#pick 返回其 GeometryInstance#id 。 使用每个实例的外观，如 PerInstanceColorAppearance，每个实例也可以拥有独特的颜色。

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

Name Type Description
options Object optional 具有以下属性的对象:
Name Type Default Description
geometryInstances Array.<GeometryInstance> | GeometryInstance optional 要渲染的几何实例-或单个几何实例。
appearance Appearance optional 用于渲染基元的外观。
show Boolean true optional 决定是否显示该基元。
modelMatrix Matrix4 Matrix4.IDENTITY optional 4x4 变换矩阵，用于将基元（所有几何体实例）从模型坐标变换到地理坐标。
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内存。
cull Boolean true optional 当为true时，渲染器截锥体和地平线会根据原语的边界体积来剔除它们的命令。如果手动剔除原语，则将其设置为false以获得较小的性能增益。
asynchronous Boolean true optional 决定基元是异步创建还是阻塞创建，直到准备就绪。
debugShowBoundingVolume Boolean false optional 仅用于调试。确定是否显示该基元的命令包围球。
shadows ShadowMode ShadowMode.DISABLED optional 确定该原型是投射还是接收来自各光源的阴影。
Examples:
// 1. Draw a translucent ellipse on the surface with a checkerboard pattern
var instance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.EllipseGeometry({
      center : SuperMap3D.Cartesian3.fromDegrees(-100.0, 20.0),
      semiMinorAxis : 500000.0,
      semiMajorAxis : 1000000.0,
      rotation : SuperMap3D.Math.PI_OVER_FOUR,
      vertexFormat : SuperMap3D.VertexFormat.POSITION_AND_ST
  }),
  id : 'object returned when this instance is picked and to get/set per-instance attributes'
});
scene.primitives.add(new SuperMap3D.Primitive({
  geometryInstances : instance,
  appearance : new SuperMap3D.EllipsoidSurfaceAppearance({
    material : SuperMap3D.Material.fromType('Checkerboard')
  })
}));
// 2. Draw different instances each with a unique color
var rectangleInstance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.RectangleGeometry({
    rectangle : SuperMap3D.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0),
    vertexFormat : SuperMap3D.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  id : 'rectangle',
  attributes : {
    color : new SuperMap3D.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
  }
});
var ellipsoidInstance = new SuperMap3D.GeometryInstance({
  geometry : new SuperMap3D.EllipsoidGeometry({
    radii : new SuperMap3D.Cartesian3(500000.0, 500000.0, 1000000.0),
    vertexFormat : SuperMap3D.VertexFormat.POSITION_AND_NORMAL
  }),
  modelMatrix : SuperMap3D.Matrix4.multiplyByTranslation(SuperMap3D.Transforms.eastNorthUpToFixedFrame(
    SuperMap3D.Cartesian3.fromDegrees(-95.59777, 40.03883)), new SuperMap3D.Cartesian3(0.0, 0.0, 500000.0), new SuperMap3D.Matrix4()),
  id : 'ellipsoid',
  attributes : {
    color : SuperMap3D.ColorGeometryInstanceAttribute.fromColor(SuperMap3D.Color.AQUA)
  }
});
scene.primitives.add(new SuperMap3D.Primitive({
  geometryInstances : [rectangleInstance, ellipsoidInstance],
  appearance : new SuperMap3D.PerInstanceColorAppearance()
}));
// 3. Create the geometry on the main thread.
scene.primitives.add(new SuperMap3D.Primitive({
  geometryInstances : new SuperMap3D.GeometryInstance({
      geometry : SuperMap3D.EllipsoidGeometry.createGeometry(new SuperMap3D.EllipsoidGeometry({
        radii : new SuperMap3D.Cartesian3(500000.0, 500000.0, 1000000.0),
        vertexFormat : SuperMap3D.VertexFormat.POSITION_AND_NORMAL
      })),
      modelMatrix : SuperMap3D.Matrix4.multiplyByTranslation(SuperMap3D.Transforms.eastNorthUpToFixedFrame(
        SuperMap3D.Cartesian3.fromDegrees(-95.59777, 40.03883)), new SuperMap3D.Cartesian3(0.0, 0.0, 500000.0), new SuperMap3D.Matrix4()),
      id : 'ellipsoid',
      attributes : {
        color : SuperMap3D.ColorGeometryInstanceAttribute.fromColor(SuperMap3D.Color.AQUA)
      }
  }),
  appearance : new SuperMap3D.PerInstanceColorAppearance()
}));
See:

Members

readonlyallowPicking : Boolean

当为true时，每个几何实例只能用Scene#pick来选择。当false时，节省GPU内存。
Default Value: true

appearance : Appearance

用于对该基元进行阴影处理的 Appearance。每个几何体都使用相同的外观进行着色。某些外观，如 PerInstanceColorAppearance 可以为每个实例赋予独特的属性。
Default Value: undefined

readonlyasynchronous : Boolean

确定是否要在web worker上创建和批处理几何体实例。
Default Value: true

readonlycompressVertices : Boolean

当为true时，几何顶点被压缩，这将节省内存。
Default Value: true

cull : Boolean

当为true时，渲染器截锥体和地平线会根据基元的边界体积来剔除它们的命令。如果手动剔除基元，则将其设置为false以获得较小的性能增益。
Default Value: true

debugShowBoundingVolume : Boolean

此属性仅用于调试;它不是用于生产的，也没有经过优化。

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

Default Value: false

depthFailAppearance : Appearance

当该基元未能通过深度测试时，Appearance用于遮蔽该基元。每个几何实例都有相同外观的阴影。有些外观，比如PerInstanceColorAppearance允许赋予每个实例独特的属性。

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

需要使用 EXT_frag_depth WebGL 扩展才能正常渲染。如果不支持该扩展，可能会出现伪像。

Default Value: undefined

geometryInstances : Array.<GeometryInstance>|GeometryInstance

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

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

Default Value: undefined

readonlyinterleave : Boolean

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

modelMatrix : Matrix4

将基元（所有几何体实例）从模型坐标转换为地理坐标的 4x4 变换矩阵。当该矩阵为同一矩阵时，基元将以地理坐标绘制，即WGS84 坐标。本地参照系可以通过提供不同的变换矩阵来使用，如 Transforms.eastNorthUpToFixedFrame 返回的矩阵。

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

Default Value: Matrix4.IDENTITY
Example:
var origin = SuperMap3D.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
p.modelMatrix = SuperMap3D.Transforms.eastNorthUpToFixedFrame(origin);

readonlyready : Boolean

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

readonlyreadyPromise : Promise.<Primitive>

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

readonlyreleaseGeometryInstances : Boolean

当为true时，基元不保留对输入的引用以节省内存。
Default Value: true

shadows : ShadowMode

确定此基元是否投射或接收来自每个光源的阴影。
Default Value: ShadowMode.DISABLED

show : Boolean

决定是否显示基底面。这会影响基元中的所有几何体实例。
Default Value: true

readonlyvertexCacheOptimize : Boolean

当为true时，几何顶点将针对顶点着色器前后瓦片进行优化。
Default Value: true

Methods

destroy() → undefined

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

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

Returns:
Throws:
Example:
e = e && e.destroy();
See:

getGeometryInstanceAttributes(id) → Object

Returns the modifiable per-instance attributes for a GeometryInstance.
Name Type Description
id Object The id of the GeometryInstance.
Returns:
The typed array in the attribute's format or undefined if the is no instance with id.
Throws:
  • DeveloperError : must call update before calling getGeometryInstanceAttributes.
Example:
var attributes = primitive.getGeometryInstanceAttributes('an id');
attributes.color = SuperMap3D.ColorGeometryInstanceAttribute.toValue(SuperMap3D.Color.AQUA);
attributes.show = SuperMap3D.ShowGeometryInstanceAttribute.toValue(true);
attributes.distanceDisplayCondition = SuperMap3D.DistanceDisplayConditionGeometryInstanceAttribute.toValue(100.0, 10000.0);

isDestroyed() → Boolean

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

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

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

setPolygonOffset(polyOffsetFactor, polyOffsetUnits)

设置primitive多边形偏移（目前仅支持面）。
Name Type Description
polyOffsetFactor Number 多边形的偏移常量。当值为正值时表示多边形朝屏幕外偏移，为负值时表示朝屏幕内测偏移
polyOffsetUnits Number 多边形缩放因子。多边形缩放因子和偏移常量共同决定了多边形对象在屏幕深度方向的偏移量，可用于解决多边形重叠时闪烁的问题。

update()

Called when Viewer or Widget render the scene to get the draw commands needed to render this primitive.

Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered:

Throws:
  • DeveloperError : All instance geometries must have the same primitiveType.
  • DeveloperError : Appearance and material have a uniform with the same name.
  • DeveloperError : Primitive.modelMatrix is only supported in 3D mode.
  • RuntimeError : Vertex texture fetch support is required to render primitives with per-instance attributes. The maximum number of vertex texture image units must be greater than zero.