Primitive

基本體表示Scene中的幾何體。幾何圖形可以來自下面的示例1所示的單個GeometryInstance，也可以來自實例數(shù)組，即使幾何圖形來自不同的幾何圖形類型，如代碼示例2中所示的RectangleGeometry和EllipsoidGeometry。

基本體將幾何體實例與描述完整著色的Appearance結(jié)合起來，包括Material和RenderState。大致上，幾何體實例定義結(jié)構(gòu)和位置，外觀定義視覺特征。分離幾何體和外觀允許我們混合和匹配大多數(shù)幾何體和外觀，并獨(dú)立地添加新的幾何體或外觀。

將多個實例組合成一個原語稱為批處理，顯著提高了靜態(tài)數(shù)據(jù)的性能。實例可以單獨(dú)選取；Scene#pick返回其GeometryInstance#id。使用類似于PerInstanceColorAppearance的每個實例外觀，每個實例也可以具有唯一的顏色。

Geometry可以在Web工作者或主線程上創(chuàng)建和批處理。前兩個示例顯示將使用幾何圖形的描述在Web工作者上創(chuàng)建的幾何圖形。第三個示例演示如何通過顯式調(diào)用createGeometry方法在主線程上創(chuàng)建幾何體。

new Primitive(options)

Parameters:

options (Object)

Name	Description
options.geometryInstances `(Array.<GeometryInstance> \| GeometryInstance)`	要渲染的幾何體實例-或單個幾何體實例。
options.appearance `Appearance`	用于呈現(xiàn)原語的外觀。
options.depthFailAppearance `Appearance`	用于在深度測試失敗時對該基元進(jìn)行著色的外觀。
options.show `Boolean` default `true`	確定是否顯示此基元。
options.modelMatrix `Matrix4` default `Matrix4.IDENTITY`	將基本體（所有幾何體實例）從模型轉(zhuǎn)換為世界坐標(biāo)的4x4轉(zhuǎn)換矩陣。
options.vertexCacheOptimize `Boolean` default `false`	當(dāng)`true`時，幾何體頂點將針對頂點前和頂點后明暗器緩存進(jìn)行優(yōu)化。
options.interleave `Boolean` default `false`	當(dāng)`true`時，幾何頂點屬性交錯，這可以稍微提高渲染性能，但增加加載時間。
options.compressVertices `Boolean` default `true`	當(dāng)`true`時，幾何體頂點被壓縮，這將節(jié)省內(nèi)存。
options.releaseGeometryInstances `Boolean` default `true`	當(dāng)`true`時，原語不保留對輸入`geometryInstances`的引用以保存內(nèi)存。
options.allowPicking `Boolean` default `true`	當(dāng)`true`時，每個幾何體實例只能使用`Scene#pick`進(jìn)行選擇。當(dāng)`false`時，保存GPU內(nèi)存。
options.cull `Boolean` default `true`	當(dāng)`true`時，渲染器的平截體剔除和地平線根據(jù)其邊界體積剔除基本體的命令。如果要手動剔除原語，請將其設(shè)置為`false`以獲得較小的性能增益。
options.asynchronous `Boolean` default `true`	確定在準(zhǔn)備就緒之前是異步創(chuàng)建基元還是阻止創(chuàng)建基元。
options.debugShowBoundingVolume `Boolean` default `false`	僅用于調(diào)試。確定是否顯示此基元的命令的邊界球。
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

當(dāng)true時，每個幾何體實例只能使用Scene#pick進(jìn)行選擇。當(dāng)false時，保存GPU內(nèi)存。*

Default Value: true

appearance : Appearance

Appearance用于對該原語進(jìn)行著色。每個幾何體實例都以相同的外觀著色。一些外觀，如PerInstanceColorAppearance允許為每個實例提供唯一的屬性。

Default Value: undefined

(readonly) asynchronous : Boolean

確定是否將在Web工作者上創(chuàng)建和批處理幾何體實例。

Default Value: true

(readonly) compressVertices : Boolean

當(dāng)true時，幾何體頂點被壓縮，這將節(jié)省內(nèi)存。

Default Value: true

cull : Boolean

當(dāng)true時，渲染器的平截體剔除和地平線根據(jù)其邊界體積剔除基本體的命令。如果要手動剔除原語，請將其設(shè)置為false以獲得較小的性能增益。

Default Value: true

debugShowBoundingVolume : Boolean

此屬性僅用于調(diào)試；它既不用于生產(chǎn)，也不進(jìn)行優(yōu)化。

為基本體中的每個draw命令繪制邊界球體。

Default Value: false

depthFailAppearance : Appearance

Appearance用于在深度測試失敗時對該原語進(jìn)行著色。每個幾何體實例都以相同的外觀著色。一些外觀，如PerInstanceColorAppearance允許為每個實例提供唯一的屬性。

當(dāng)使用需要顏色屬性的外觀時，如PerInstanceColorAppearance，請為每個實例屬性添加DepthFailColor。

需要ext}frag_depth webgl擴(kuò)展以正確呈現(xiàn)。如果不支持?jǐn)U展，則可能存在工件。

Default Value: undefined

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

使用此基元渲染的幾何體實例。在構(gòu)造基元時，如果options.releaseGeometryInstances是true，則可能是undefined。

在呈現(xiàn)基元后更改此屬性沒有效果。

Default Value: undefined

(readonly) interleave : Boolean

確定幾何體頂點屬性是否交錯，這可以稍微提高渲染性能。

Default Value: false

modelMatrix : Matrix4

將基本體（所有幾何體實例）從模型轉(zhuǎn)換為世界坐標(biāo)的4x4轉(zhuǎn)換矩陣。當(dāng)這是一個單位矩陣時，原語以世界坐標(biāo)繪制，即地球的wgs84坐標(biāo)。本地參考幀可以通過提供不同的轉(zhuǎn)換矩陣來使用，如Transforms.eastNorthUpToFixedFrame返回的轉(zhuǎn)換矩陣。

此屬性僅在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

確定基元是否已完成并準(zhǔn)備好呈現(xiàn)。如果此屬性為真，則下次調(diào)用Primitive#update時將呈現(xiàn)原語。

(readonly) readyPromise : Promise.<Primitive>

獲取解決基元何時準(zhǔn)備呈現(xiàn)的承諾。

(readonly) releaseGeometryInstances : Boolean

當(dāng)true時，原語不保留對輸入geometryInstances的引用以保存內(nèi)存。

Default Value: true

shadows : ShadowMode

確定此基元是投射還是接收來自每個光源的陰影。

Default Value: ShadowMode.DISABLED

show : Boolean

確定是否顯示基元。這會影響基本體中的所有幾何體實例。

Default Value: true

(readonly) vertexCacheOptimize : Boolean

當(dāng)true時，幾何體頂點將針對頂點前和頂點后明暗器緩存進(jìn)行優(yōu)化。

Default Value: true

Methods

destroy()

銷毀此對象持有的WebGL資源。銷毀對象允許確定地釋放WebGL資源，而不是依賴?yán)占鱽礓N毀此對象。

一旦對象被破壞，就不應(yīng)使用它；調(diào)用除isDestroyed以外的任何函數(shù)都將導(dǎo)致DeveloperError異常。因此，將返回值（undefined）賦給對象，如示例中所述。

Example

e = e && e.destroy();

Throws

DeveloperError : 此對象已被銷毀，即調(diào)用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 : 必須在調(diào)用GetGeometryInstanceAttributes之前調(diào)用Update。

isDestroyed() → {Boolean}

如果此對象被破壞，則返回true；否則返回false。

如果此對象被破壞，則不應(yīng)使用它；調(diào)用除isDestroyed以外的任何函數(shù)都將導(dǎo)致DeveloperError異常。

See:

Primitive#destroy

update()

當(dāng)Viewer或BMWidget渲染場景以獲取渲染此原語所需的繪制命令時調(diào)用。

不要直接調(diào)用此函數(shù)。這只是為了列出渲染場景時可能傳播的異常：

Throws

DeveloperError : 所有實例幾何必須具有相同的PrimitiveType。
DeveloperError : 外觀和材料有一個統(tǒng)一的名稱。
DeveloperError : Primitive.ModelMatrix僅在3D模式下受支持。
RuntimeError : 需要頂點紋理獲取支持來渲染具有每個實例屬性的基本體。頂點紋理圖像單位的最大數(shù)目必須大于零。