Scene

虚拟场景中所有3D图形对象和状态的容器。 通常，场景不是直接创建的。 而是由BMWidget隐式创建。

contextOptions参数详细信息：

默认值为： { webgl : { alpha : false, depth : true, stencil : false, antialias : true, premultipliedAlpha : true, preserveDrawingBuffer : false, failIfMajorPerformanceCaveat : false }, allowTextureFilterAnisotropic : true }

webgl属性对应于用于创建的WebGLContextAttributes对象 WebGL上下文。

webgl.alpha的默认值为false，与标准的WebGL默认值为true相比，可以提高性能。 如果应用程序需要使用alpha混合在其他HTML元素上方合成，请将webgl.alpha设置为true。

其他webgl属性与WebGLContextAttributes的WebGL默认值匹配。

allowTextureFilterAnisotropic的默认值为true，当支持WebGL扩展时，它将启用各向异性纹理过滤。 将其设置为false将提高性能，但会损害视觉质量，尤其是对于地平线视图。

new Scene(options)
Parameters:
options (Object)
Name Description
options.canvas
Canvas
要为其创建场景的HTML画布元素。
options.contextOptions
Object
上下文和WebGL创建属性。详见上文。
options.creditContainer
Element
显示学分的HTML元素。
options.creditViewport
Element
显示信用弹出窗口的HTML元素。如果未指定，则视区将作为画布的同级添加。
options.mapProjection
MapProjection
default new GeographicProjection() 		要在二维和哥伦布视图模式中使用的地图投影。
options.orderIndependentTranslucency
Boolean
default true 		如果为true，并且配置支持它，则使用与顺序无关的半透明。
options.scene3DOnly
Boolean
default false 		如果为真，则优化3D模式的内存使用和性能，但禁用使用二维或哥伦布视图的功能。
options.terrainExaggeration
Number
default 1.0 		用于放大地形的标量。请注意，地形放大不会修改任何其他基本体，因为它们是相对于椭球体定位的。
options.shadows
Boolean
default false 		确定阴影是否由太阳投射。
options.mapMode2D
MapMode2D
default MapMode2D.INFINITE_SCROLL 		确定二维地图是可旋转的还是可以沿水平方向无限滚动。
options.requestRenderMode
Boolean
default false 		如果为“真”，则仅在场景中的更改决定需要时才会渲染帧。启用可以提高应用程序的性能，但需要使用Scene#requestRender在此模式下显式呈现新帧。在许多情况下，在对API其他部分中的场景进行更改之后，这是必需的。
options.maximumRenderTimeChange
Number
default 0.0 		如果requestrendermode为true，则此值定义请求呈现之前允许的模拟时间的最大更改。
Example
// Create scene without anisotropic texture filtering
var scene = new bmgl.Scene({
  canvas : canvas,
  contextOptions : {
    allowTextureFilterAnisotropic : false
  }
});
Throws
See:

Members

backgroundColor : Color

背景色，只有在没有天空框时才可见，即Scene#skyBox未定义。
Default Value: Color.BLACK
See:

(readonly) camera : Camera

获取或设置照相机。

(readonly) canvas : Canvas

获取此场景绑定到的画布元素。

(readonly) clampToHeightSupported : Boolean

如果支持Scene#clampToHeight和Scene#clampToHeightMostDetailed函数，则返回true。
See:

completeMorphOnUserInput : Boolean

确定是否在用户输入时立即完成场景转换动画。
Default Value: true

debugCommandFilter : function

此属性仅用于调试；不用于生产。

确定执行哪些命令的函数。如下面的示例所示，函数接收命令的owner作为参数，并返回一个布尔值，指示是否应执行命令。

默认为undefined，表示执行所有命令。

Default Value: undefined
Example:
// Do not execute any commands.
scene.debugCommandFilter = function(command) {
    return false;
};

// Execute only the billboard's commands.  That is, only draw the billboard.
var billboards = new bmgl.BillboardCollection();
scene.debugCommandFilter = function(command) {
    return command.owner === billboards;
};

(readonly) debugFrustumStatistics : Object

此属性仅用于调试；不用于生产。

当Scene.debugShowFrustums为true时，这包含属性，统计每个截锥执行的命令数。totalCommands是执行的命令总数，忽略重叠。commandsInFrustums是一个具有重复执行命令次数的数组，例如，有多少命令与两个或三个截锥重叠。

Default Value: undefined

debugShowCommands : Boolean

此属性仅用于调试；不用于生产。

当true时，命令随机着色。这对于性能分析很有用，可以查看场景或模型的哪些部分是命令密集的，并且可以从批处理中受益。

Default Value: false

debugShowDepthFrustum : Number

此属性仅用于调试；不用于生产。

表示哪个截锥将显示深度信息。

Default Value: 1

debugShowFramesPerSecond : Boolean

此属性仅用于调试；不用于生产。

显示每秒帧数和帧之间的时间。

Default Value: false

debugShowFrustumPlanes : Boolean

此属性仅用于调试；不用于生产。

当true时，绘制轮廓以显示相机截锥的边界

Default Value: false

debugShowFrustums : Boolean

此属性仅用于调试；不用于生产。

当true时，命令将根据它们重叠的截锥体进行着色。最近截锥体中的命令为红色，下一个最近截锥体中的命令为绿色，最远截锥体中的命令为蓝色。如果一个命令与多个截锥重叠，则组合颜色组件，例如，与前两个截锥重叠的命令为黄色。

Default Value: false

debugShowGlobeDepth : Boolean

此属性仅用于调试；不用于生产。

显示所示截锥的深度信息。

Default Value: false

(readonly) drawingBufferHeight : Number

基础GL上下文的DrawingBufferHeight。
See:

(readonly) drawingBufferWidth : Number

基础GL上下文的DrawingBufferHeight。
See:

eyeSeparation : Number

与纸板或WebVR一起使用的眼睛间隔距离（米）。

farToNearRatio : Number

多截锥在使用普通深度缓冲器时的远近比。

该值用于为多个截锥体的每个截锥体创建近、远值。仅当Scene#logarithmicDepthBuffer为false时使用。当logarithmicDepthBuffer为true时，使用Scene#logarithmicDepthFarToNearRatio。

Default Value: 1000.0

focalLength : Number

用于硬纸板或WebVR时的焦距。

fog : Fog

将大气与远离相机的几何体混合以获得地平线视图。允许通过渲染较少的几何图形和调度较少的地形请求来提高性能。

gamma : Number

用于伽玛校正的值。这仅在使用高动态范围渲染时使用。
Default Value: 2.2

globe : Globe

获取或设置深度测试椭球体。

(readonly) groundPrimitives : PrimitiveCollection

获取基本体的集合。

highDynamicRange : Boolean

是否使用高动态范围渲染。
Default Value: true

highDynamicRangeSupported : Boolean

是否支持高动态范围渲染。
Default Value: true

(readonly) id : String

获取此场景的唯一标识符。

(readonly) imageryLayers : ImageryLayerCollection

获取将在地球仪上呈现的图像层的集合。

imagerySplitPosition : Number

获取或设置图像拆分器在视区中的位置。有效值介于0.0和1.0之间。

invertClassification : Boolean

当false时，3D瓦片将正常呈现。当true时，分类的3D瓦片几何体将正常呈现，而非分类的3D瓦片几何体将以乘以Scene#invertClassificationColor的颜色呈现。
Default Value: false

invertClassificationColor : Color

当Scene#invertClassification为true时，未分类的3D瓦片几何体的突出显示颜色。

当颜色的alpha小于1.0时，3D瓦片的未分类部分将无法与3D瓦片的分类位置正确混合。

{

此外，当颜色的alpha小于1.0时，必须支持WebGL{深度{纹理和扩展{深度WebGL扩展。

Default Value: Color.WHITE

(readonly) invertClassificationSupported : Boolean

如果支持Scene#invertClassification，则返回true。
See:

(readonly) lastRenderTime : JulianDate

获取上次呈现场景时的模拟时间。如果尚未渲染场景，则返回未定义。

logarithmicDepthBuffer : Boolean

是否使用对数深度缓冲区。启用此选项将允许在多个截锥中减少截锥，从而提高性能。此属性依赖于支持的FragmentDepth。

logarithmicDepthFarToNearRatio : Number

使用对数深度缓冲器时多截锥的远近比。

该值用于为多个截锥体的每个截锥体创建近、远值。仅当Scene#logarithmicDepthBuffer为true时使用。当logarithmicDepthBuffer为false时，使用Scene#farToNearRatio。

Default Value: 1e9

mapMode2D : MapMode2D

确定二维地图是可旋转的还是可以沿水平方向无限滚动。

(readonly) mapProjection : MapProjection

获取要在二维和哥伦布视图模式中使用的地图投影。
Default Value: new GeographicProjection()

(readonly) maximumAliasedLineWidth : Number

此WebGL实现支持的最大混叠线条宽度（以像素为单位）。它至少是一个。
See:
  • glGet with ALIASED_LINE_WIDTH_RANGE.

(readonly) maximumCubeMapSize : Number

此WebGL实现支持的多维数据集映射的一条边的最大长度（以像素为单位）。至少16岁。
See:
  • glGet with GL_MAX_CUBE_MAP_TEXTURE_SIZE.

maximumRenderTimeChange : Number

如果Scene#requestRenderMode为true，则此值定义请求渲染之前允许的模拟时间的最大更改。值越小，渲染的帧数越多，值越大，渲染的帧数越少。如果undefined，对模拟时间的更改将永远不会请求渲染。此值会影响场景中更改（如照明、实体属性更新和动画）的渲染速率。
Default Value: 0.5
See:

minimumDisableDepthTestDistance : Number

从相机到禁止对广告牌、标签和点进行深度测试的距离，例如，防止对地形进行剪切。当设置为零时，应始终应用深度测试。当小于零时，不得进行深度测试。设置公告牌、标签或点的DisableDepthTestDistance属性将覆盖此值。
Default Value: 0.0

mode : SceneMode

获取或设置场景的当前模式。
Default Value: SceneMode.SCENE3D

moon : Moon

Moon
Default Value: undefined

morphComplete : Event

在完成场景转换时触发的事件。
Default Value: Event()

morphStart : Event

在场景转换开始时触发的事件。
Default Value: Event()

morphTime : Number

当前在二维/哥伦布视图和三维之间的变形过渡时间，0.0表示二维或哥伦布视图，1.0表示三维。
Default Value: 1.0

nearToFarDistance2D : Number

确定二维中多锈体的每个截锥的均匀深度大小（以米为单位）。如果靠近表面的原始体或模型显示Z形战斗，则减小此值将消除伪影，但会降低性能。另一方面，增加该值将提高性能，但可能导致靠近曲面的基本体之间发生Z-冲突。
Default Value: 1.75e6

(readonly) orderIndependentTranslucency : Boolean

获取场景是否启用了顺序独立半透明。请注意，这只反映了最初的构建选项，还有其他因素可能会阻止OIT在给定的系统配置上运行。

(readonly) pickPositionSupported : Boolean

如果支持Scene#pickPosition函数，则返回true。
See:

pickTranslucentDepth : Boolean

当true时，启用使用深度缓冲区拾取半透明几何体。请注意，Scene#useDepthPicking也必须为真，才能使其工作。

渲染必须在拾取之间调用。
启用时性能会降低。有额外的绘图调用来写入半透明几何体的深度。

Default Value: false
Example:
// picking the position of a translucent primitive
viewer.screenSpaceEventHandler.setInputAction(function onLeftClick(movement) {
     var pickedFeature = viewer.scene.pick(movement.position);
     if (!bmgl.defined(pickedFeature)) {
         // nothing picked
         return;
     }
     viewer.scene.render();
     var worldPosition = viewer.scene.pickPosition(movement.position);
}, bmgl.ScreenSpaceEventType.LEFT_CLICK);

postProcessStages : PostProcessStageCollection

应用于最终渲染的后期处理效果。

(readonly) postRender : Event

获取将在呈现场景后立即引发的事件。事件的订阅服务器接收场景实例作为第一个参数，当前时间作为第二个参数。
See:

(readonly) postUpdate : Event

获取将在场景更新后和渲染场景之前立即引发的事件。事件的订阅服务器接收场景实例作为第一个参数，当前时间作为第二个参数。
See:

(readonly) preRender : Event

获取将在场景更新后立即在场景呈现前引发的事件。事件的订阅服务器接收场景实例作为第一个参数，当前时间作为第二个参数。
See:

(readonly) preUpdate : Event

获取将在更新或呈现场景之前引发的事件。事件的订阅服务器接收场景实例作为第一个参数，当前时间作为第二个参数。
See:

(readonly) primitives : PrimitiveCollection

获取基元的集合。

(readonly) renderError : Event

获取在render函数中引发错误时将引发的事件。场景实例和抛出的错误是传递给事件处理程序的唯一两个参数。默认情况下，在引发此事件后不会重新引发错误，但可以通过设置rethrowRenderErrors属性来更改错误。

requestRenderMode : Boolean

当true时，仅当场景中的更改决定需要时才会渲染帧。启用可以提高应用程序的性能，但需要使用Scene#requestRender在此模式下显式呈现新帧。在许多情况下，在对API其他部分中的场景进行更改之后，这是必需的。
Default Value: false
See:

rethrowRenderErrors : Boolean

在render中发生的异常始终被捕获，以便引发renderError事件。如果此属性为true，则在引发事件后重新引发错误。如果此属性为假，则在引发事件后，render函数将正常返回。
Default Value: false

(readonly) sampleHeightSupported : Boolean

如果支持Scene#sampleHeight和Scene#sampleHeightMostDetailed函数，则返回true。
See:

(readonly) scene3DOnly : Boolean

获取该场景是否优化为仅用于三维查看。

(readonly) screenSpaceCameraController : ScreenSpaceCameraController

获取用于处理相机输入的控制器。

shadowMap : ShadowMap

场景中的阴影图。启用后，模型、基本体和球体可以投射和接收阴影。默认情况下，阴影贴图的光源是太阳。

skyAtmosphere : SkyAtmosphere

天空的大气吸引了全世界。
Default Value: undefined

skyBox : SkyBox

SkyBox用于绘制星星。
Default Value: undefined
See:

specularEnvironmentMaps : String

KTX文件的URL，其中包含用于PBR模型基于图像的照明的镜面环境贴图和卷积mipmap。

(readonly) specularEnvironmentMapsSupported : Boolean

如果支持镜面环境贴图，则返回true。
See:

sphericalHarmonicCoefficients : Array.<Cartesian3>

基于图像的PBR模型光照的球面谐波系数。

sun : Sun

Sun
Default Value: undefined

sunBloom : Boolean

启用时在太阳上使用“布卢姆”过滤器。
Default Value: true

sunColor : Cartesian3

获取或设置太阳发出的光的颜色。
Default Value: Cartesian3(1.8, 1.85, 2.0)

terrainExaggeration : Number

获取用于放大地形的标量。

terrainProvider : TerrainProvider

地形提供者为地球仪提供表面几何图形。

(readonly) terrainProviderChanged : Event

获取在地形提供程序更改时引发的事件

useDepthPicking : Boolean

当true时，使用深度缓冲区启用拾取。
Default Value: true

useWebVR : Boolean

当true时，将场景分割为两个具有左右眼立体视图的视区。用于纸板和网络虚拟现实。
Default Value: false

Methods

cartesianToCanvasCoordinates(position, result) → {Cartesian2}
将笛卡尔坐标中的位置转换为画布坐标。这通常用于将HTML元素放置在与场景中的对象相同的屏幕位置。
Parameters:
position (Cartesian3) 笛卡尔坐标中的位置。
result (Cartesian2) 返回转换为画布坐标的输入位置的可选对象。
Example
// Output the canvas position of longitude/latitude (0, 0) every time the mouse moves.
var scene = widget.scene;
var ellipsoid = scene.globe.ellipsoid;
var position = bmgl.Cartesian3.fromDegrees(0.0, 0.0);
var handler = new bmgl.ScreenSpaceEventHandler(scene.canvas);
handler.setInputAction(function(movement) {
    console.log(scene.cartesianToCanvasCoordinates(position));
}, bmgl.ScreenSpaceEventType.MOUSE_MOVE);
clampToHeight(cartesian, objectsToExclude, width, result) → {Cartesian3}
沿大地测量面法向将给定的笛卡尔坐标位置钳制到场景几何体。返回夹紧位置，如果没有要夹紧的场景几何图形，则返回undefined。可用于将对象夹持到场景中的球体、三维平铺或基本体上。

此功能仅限于当前视图中呈现的球形瓦片和三维瓦片。钳制到所有其他基本体，而不管它们的可见性如何。

Parameters:
cartesian (Cartesian3) 笛卡尔位置。
objectsToExclude (Array.<Object>) 基本体、实体或三维平铺特征的列表，不夹在其中。
width (Number) (default 0.1) 交叉口体积的宽度（米）。
result (Cartesian3) 返回夹紧位置的可选对象。
Example
// Clamp an entity to the underlying scene geometry
var position = entity.position.getValue(bmgl.JulianDate.now());
entity.position = viewer.scene.clampToHeight(position);
Throws
  • DeveloperError : ClampToHeight仅在3D模式下受支持。
  • DeveloperError : ClampToHeight需要深度纹理支持。检查支架高度。
See:
clampToHeightMostDetailed(cartesians, objectsToExclude, width) → {Promise.<Array.<Cartesian3>>}
使用场景中三维平铺的最大细节级别，启动异步Scene#clampToHeight查询Cartesian3位置数组。返回在查询完成时解决的承诺。每个位置都在适当的位置进行了修改。如果由于在该位置无法对几何图形进行采样而无法夹紧某个位置，或者发生其他错误，则阵列中的元素将设置为“未定义”。
Parameters:
cartesians (Array.<Cartesian3>) 要用夹持位置更新的笛卡尔位置。
objectsToExclude (Array.<Object>) 基本体、实体或三维平铺特征的列表，不夹在其中。
width (Number) (default 0.1) 交叉口体积的宽度（米）。
Example
var cartesians = [
    entities[0].position.getValue(bmgl.JulianDate.now()),
    entities[1].position.getValue(bmgl.JulianDate.now())
];
var promise = viewer.scene.clampToHeightMostDetailed(cartesians);
promise.then(function(updatedCartesians) {
    entities[0].position = updatedCartesians[0];
    entities[1].position = updatedCartesians[1];
}
Throws
  • DeveloperError : ClampToHeightMostDetailed仅在3D模式下受支持。
  • DeveloperError : ClamptoHeightMostDetailed需要深度纹理支持。检查支架高度。
See:
completeMorph()
立即完成活动转换。
destroy()
销毁此对象持有的WebGL资源。销毁对象允许确定地释放WebGL资源，而不是依赖垃圾收集器来销毁此对象。

一旦对象被破坏，就不应使用它；调用除isDestroyed以外的任何函数都将导致DeveloperError异常。因此，将返回值（undefined）赋给对象，如示例中所述。
Example
scene = scene && scene.destroy();
Throws
See:
drillPick(windowPosition, limit, width, height) → {Array.<Object>}
返回特定窗口坐标位置上所有基元的对象列表，每个对象都包含“primitive”属性。还可以根据基本体的类型设置其他属性，并可用于进一步标识拾取的对象。列表中的基本体按它们在场景中的视觉顺序（前后）排序。
Parameters:
windowPosition (Cartesian2) 要执行领料的窗口坐标。
limit (Number) 如果提供，在收集了这么多镐后停止钻孔。
width (Number) (default 3) 拾取矩形的宽度。
height (Number) (default 3) 拾取矩形的高度。
Example
var pickedObjects = scene.drillPick(new bmgl.Cartesian2(100.0, 200.0));
Throws
See:
getCompressedTextureFormatSupported(format) → {boolean}
确定是否支持压缩纹理格式。
Parameters:
format (String) 纹理格式。可以是格式名或WebGL扩展名，例如S3TC或WebGL_compressed_texture_S3TC。
isDestroyed() → {Boolean}
如果此对象被破坏，则返回true；否则返回false。

如果此对象被破坏，则不应使用它；调用除isDestroyed以外的任何函数将导致DeveloperError异常。
See:
morphTo2D(duration)
异步将场景转换为二维。
Parameters:
duration (Number) (default 2.0) 过渡动画完成所需的时间量（秒）。
morphTo3D(duration)
异步将场景转换为3D。
Parameters:
duration (Number) (default 2.0) 过渡动画完成所需的时间量（秒）。
morphToColumbusView(duration)
异步将场景转换为Columbus视图。
Parameters:
duration (Number) (default 2.0) 过渡动画完成所需的时间量（秒）。
pick(windowPosition, width, height) → {Object}
返回一个具有“primitive”属性的对象，该属性包含场景中特定窗口坐标处的第一个（顶部）primitive；如果该位置上没有任何内容，则返回未定义的。其他属性可能会根据基本体的类型进行设置，并可用于进一步标识拾取的对象。

当拾取3D Tiles-Tileset的功能时，pick返回BM3DTileFeature对象。

Parameters:
windowPosition (Cartesian2) 要执行领料的窗口坐标。
width (Number) (default 3) 拾取矩形的宽度。
height (Number) (default 3) 拾取矩形的高度。
Example
// On mouse over, color the feature yellow.
handler.setInputAction(function(movement) {
    var feature = scene.pick(movement.endPosition);
    if (feature instanceof bmgl.BM3DTileFeature) {
        feature.color = bmgl.Color.YELLOW;
    }
}, bmgl.ScreenSpaceEventType.MOUSE_MOVE);
pickPosition(windowPosition, result) → {Cartesian3}
返回从深度缓冲区和窗口位置重建的笛卡尔位置。

从二维深度缓冲区重建的位置可能与三维和哥伦布视图重建的位置略有不同。这是由于透视投影和正交投影的深度值分布不同造成的。

设置Scene#pickTranslucentDepth至true以包括半透明基本体的深度；否则，这基本上是通过半透明基本体选取的。

Parameters:
windowPosition (Cartesian2) 要执行领料的窗口坐标。
result (Cartesian3) 要在其上还原结果的对象。
Throws
  • DeveloperError : 不支持从深度缓冲区选取。检查支持的选择位置。
requestRender()
当Scene#requestRenderMode设置为true时，请求新的渲染帧。渲染速率不会超过BMWidget#targetFrameRate。
See:
sampleHeight(position, objectsToExclude, width) → {Number}
返回给定制图位置处的场景几何体高度，如果没有要采样的场景几何体，则返回undefined。输入位置的高度被忽略。可用于将对象夹持到场景中的球体、三维平铺或基本体上。

此函数仅对当前视图中渲染的球形瓦片和三维瓦片的高度进行采样。从所有其他基本体采样高度，而不考虑它们的可见性。

Parameters:
position (Cartographic) 要从中采样高度的地图位置。
objectsToExclude (Array.<Object>) 不从中采样高度的基本体、实体或三维平铺特征列表。
width (Number) (default 0.1) 交叉口体积的宽度（米）。
Example
var position = new bmgl.Cartographic(-1.31968, 0.698874);
var height = viewer.scene.sampleHeight(position);
console.log(height);
Throws
  • DeveloperError : 只有在3D模式下才支持sampleheight。
  • DeveloperError : 样品瓶需要深度纹理支持。检查支持的样本权重。
See:
sampleHeightMostDetailed(positions, objectsToExclude, width) → {Promise.<Array.<Number>>}
使用场景中三维平铺的最大细节级别，启动异步Scene#sampleHeight查询Cartographic位置数组。输入位置的高度将被忽略。返回在查询完成时解决的承诺。每个点的高度都会在适当的位置进行修改。如果由于无法在该位置对几何图形进行采样而无法确定高度，或发生其他错误，则高度设置为“未定义”。
Parameters:
positions (Array.<Cartographic>) 要用采样高度更新的地图位置。
objectsToExclude (Array.<Object>) 不从中采样高度的基本体、实体或三维平铺特征列表。
width (Number) (default 0.1) 交叉口体积的宽度（米）。
Example
var positions = [
    new bmgl.Cartographic(-1.31968, 0.69887),
    new bmgl.Cartographic(-1.10489, 0.83923)
];
var promise = viewer.scene.sampleHeightMostDetailed(positions);
promise.then(function(updatedPosition) {
    // positions[0].height and positions[1].height have been updated.
    // updatedPositions is just a reference to positions.
}
Throws
  • DeveloperError : 只有在3D模式下才支持sampleheight mostdetailed。
  • DeveloperError : sampleHeightmostDetailed需要深度纹理支持。检查支持的样本权重。
See: