Class: Scene

Scene

new Scene(optionsopt)

The container for all 3D graphical objects and state in a Cesium virtual scene. Generally, a scene is not created directly; instead, it is implicitly created by CesiumWidget.

contextOptions parameter details:

The default values are: { webgl : { alpha : false, depth : true, stencil : false, antialias : true, premultipliedAlpha : true, preserveDrawingBuffer : false, failIfMajorPerformanceCaveat : false }, allowTextureFilterAnisotropic : true }

The webgl property corresponds to the WebGLContextAttributes object used to create the WebGL context.

webgl.alpha defaults to false, which can improve performance compared to the standard WebGL default of true. If an application needs to composite Cesium above other HTML elements using alpha-blending, set webgl.alpha to true.

The other webgl properties match the WebGL defaults for WebGLContextAttributes.

allowTextureFilterAnisotropic defaults to true, which enables anisotropic texture filtering when the WebGL extension is supported. Setting this to false will improve performance, but hurt visual quality, especially for horizon views.

Parameters:
Name Type Attributes Description
options Object <optional>
 Object with the following properties:
Properties
Name Type Attributes Default Description
canvas Canvas The HTML canvas element to create the scene for.
contextOptions Object <optional>
 Context and WebGL creation properties. See details above.
creditContainer Element <optional>
 The HTML element in which the credits will be displayed.
mapProjection MapProjection <optional>
 new GeographicProjection() The map projection to use in 2D and Columbus View modes.
orderIndependentTranslucency Boolean <optional>
 true If true and the configuration supports it, use order independent translucency.
scene3DOnly Boolean <optional>
 false If true, optimizes memory use and performance for 3D mode but disables the ability to use 2D or Columbus View.
terrainExaggeration Number <optional>
 1.0 A scalar used to exaggerate the terrain. Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
shadows Boolean <optional>
 false Determines if shadows are cast by the sun.
mapMode2D MapMode2D <optional>
 MapMode2D.INFINITE_SCROLL Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
Source:
See:
Throws:
options and options.canvas are required.
Type
DeveloperError
Example
// Create scene without anisotropic texture filtering
var scene = new Cesium.Scene({
  canvas : canvas,
  contextOptions : {
    allowTextureFilterAnisotropic : false
  }
});

Members

backgroundColor :Color

The background color, which is only visible if there is no sky box, i.e., Scene#skyBox is undefined.
Type:
Default Value:
Source:
See:

(readonly) camera :Camera

Gets the camera.
Type:
Source:

(readonly) canvas :Canvas

Gets the canvas element to which this scene is bound.
Type:
  • Canvas
Source:

completeMorphOnUserInput :Boolean

Determines whether or not to instantly complete the scene transition animation on user input.
Type:
  • Boolean
Default Value:
  • true
Source:

debugCommandFilter :function

This property is for debugging only; it is not for production use.

A function that determines what commands are executed. As shown in the examples below, the function receives the command's owner as an argument, and returns a boolean indicating if the command should be executed.

The default is undefined, indicating that all commands are executed.

Type:
  • function
Default Value:
  • undefined
Source:
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 Cesium.BillboardCollection();
scene.debugCommandFilter = function(command) {
    return command.owner === billboards;
};

(readonly) debugFrustumStatistics :Object

This property is for debugging only; it is not for production use.

When Scene.debugShowFrustums is true, this contains properties with statistics about the number of command execute per frustum. totalCommands is the total number of commands executed, ignoring overlap. commandsInFrustums is an array with the number of times commands are executed redundantly, e.g., how many commands overlap two or three frustums.

Type:
  • Object
Default Value:
  • undefined
Source:

debugShowCommands :Boolean

This property is for debugging only; it is not for production use.

When true, commands are randomly shaded. This is useful for performance analysis to see what parts of a scene or model are command-dense and could benefit from batching.

Type:
  • Boolean
Default Value:
  • false
Source:

debugShowDepthFrustum :Number

This property is for debugging only; it is not for production use.

Indicates which frustum will have depth information displayed.

Type:
  • Number
Default Value:
  • 1
Source:

debugShowFramesPerSecond :Boolean

This property is for debugging only; it is not for production use.

Displays frames per second and time between frames.

Type:
  • Boolean
Default Value:
  • false
Source:

debugShowFrustums :Boolean

This property is for debugging only; it is not for production use.

When true, commands are shaded based on the frustums they overlap. Commands in the closest frustum are tinted red, commands in the next closest are green, and commands in the farthest frustum are blue. If a command overlaps more than one frustum, the color components are combined, e.g., a command overlapping the first two frustums is tinted yellow.

Type:
  • Boolean
Default Value:
  • false
Source:

debugShowGlobeDepth :Boolean

This property is for debugging only; it is not for production use.

Displays depth information for the indicated frustum.

Type:
  • Boolean
Default Value:
  • false
Source:

(readonly) drawingBufferHeight :Number

The drawingBufferWidth of the underlying GL context.
Type:
  • Number
Source:
See:

(readonly) drawingBufferWidth :Number

The drawingBufferHeight of the underlying GL context.
Type:
  • Number
Source:
See:

farToNearRatio :Number

The far-to-near ratio of the multi-frustum. The default is 1,000.0.
Type:
  • Number
Default Value:
  • 1000.0
Source:

fog :Fog

Blends the atmosphere to geometry far from the camera for horizon views. Allows for additional performance improvements by rendering less geometry and dispatching less terrain requests.
Type:
Source:

fxaa :Boolean

When true, enables Fast Approximate Anti-aliasing even when order independent translucency is unsupported.
Type:
  • Boolean
Default Value:
  • true
Source:

globe :Globe

Gets or sets the depth-test ellipsoid.
Type:
Source:

(readonly) groundPrimitives :PrimitiveCollection

Gets the collection of ground primitives.
Type:
Source:

(readonly) id :String

Gets the unique identifier for this scene.
Type:
  • String
Source:

(readonly) imageryLayers :ImageryLayerCollection

Gets the collection of image layers that will be rendered on the globe.
Type:
Source:

mapMode2D :Boolean

Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
Type:
  • Boolean
Source:

(readonly) mapProjection :MapProjection

Get the map projection to use in 2D and Columbus View modes.
Type:
Default Value:
  • new GeographicProjection()
Source:

(readonly) maximumAliasedLineWidth :Number

The maximum aliased line width, in pixels, supported by this WebGL implementation. It will be at least one.
Type:
  • Number
Source:
See:
  • glGet with ALIASED_LINE_WIDTH_RANGE.

(readonly) maximumCubeMapSize :Number

The maximum length in pixels of one edge of a cube map, supported by this WebGL implementation. It will be at least 16.
Type:
  • Number
Source:
See:
  • glGet with GL_MAX_CUBE_MAP_TEXTURE_SIZE.

mode :SceneMode

Gets or sets the current mode of the scene.
Type:
  • SceneMode
Default Value:
  • SceneMode.SCENE3D
Source:

moon :Moon

The Moon
Type:
Default Value:
  • undefined
Source:

morphComplete :Event

The event fired at the completion of a scene transition.
Type:
Default Value:
  • Event()
Source:

morphStart :Event

The event fired at the beginning of a scene transition.
Type:
Default Value:
  • Event()
Source:

morphTime :Number

The current morph transition time between 2D/Columbus View and 3D, with 0.0 being 2D or Columbus View and 1.0 being 3D.
Type:
  • Number
Default Value:
  • 1.0
Source:

nearToFarDistance2D :Number

Determines the uniform depth size in meters of each frustum of the multifrustum in 2D. If a primitive or model close to the surface shows z-fighting, decreasing this will eliminate the artifact, but decrease performance. On the other hand, increasing this will increase performance but may cause z-fighting among primitives close to thesurface.
Type:
  • Number
Default Value:
  • 1.75e6
Source:

(readonly) orderIndependentTranslucency :Boolean

Gets whether or not the scene has order independent translucency enabled. Note that this only reflects the original construction option, and there are other factors that could prevent OIT from functioning on a given system configuration.
Type:
  • Boolean
Source:

(readonly) pickPositionSupported :Boolean

Returns true if the pickPosition function is supported.
Type:
  • Boolean
Source:

(readonly) postRender :Event

Gets the event that will be raised at the end of each call to render. Subscribers to the event receive the Scene instance as the first parameter and the current time as the second parameter.
Type:
Source:

(readonly) preRender :Event

Gets the event that will be raised at the start of each call to render. Subscribers to the event receive the Scene instance as the first parameter and the current time as the second parameter.
Type:
Source:

(readonly) primitives :PrimitiveCollection

Gets the collection of primitives.
Type:
Source:

(readonly) renderError :Event

Gets the event that will be raised when an error is thrown inside the render function. The Scene instance and the thrown error are the only two parameters passed to the event handler. By default, errors are not rethrown after this event is raised, but that can be changed by setting the rethrowRenderErrors property.
Type:
Source:

rethrowRenderErrors :Boolean

Exceptions occurring in render are always caught in order to raise the renderError event. If this property is true, the error is rethrown after the event is raised. If this property is false, the render function returns normally after raising the event.
Type:
  • Boolean
Default Value:
  • false
Source:

(readonly) scene3DOnly :Boolean

Gets whether or not the scene is optimized for 3D only viewing.
Type:
  • Boolean
Source:

(readonly) screenSpaceCameraController :ScreenSpaceCameraController

Gets the controller for camera input handling.
Type:
Source:

shadowMap :ShadowMap

The shadow map in the scene. When enabled, models, primitives, and the globe may cast and receive shadows. By default the light source of the shadow map is the sun.
Type:
Source:

skyAtmosphere :SkyAtmosphere

The sky atmosphere drawn around the globe.
Type:
Default Value:
  • undefined
Source:

skyBox :SkyBox

The SkyBox used to draw the stars.
Type:
Default Value:
  • undefined
Source:
See:

sun :Sun

The Sun.
Type:
Default Value:
  • undefined
Source:

sunBloom :Boolean

Uses a bloom filter on the sun when enabled.
Type:
  • Boolean
Default Value:
  • true
Source:

terrainExaggeration :Number

Gets the scalar used to exaggerate the terrain.
Type:
  • Number
Source:

terrainProvider :TerrainProvider

The terrain provider providing surface geometry for the globe.
Type:
Source:

(readonly) terrainProviderChanged :Event

Gets an event that's raised when the terrain provider is changed
Type:
Source:

useDepthPicking :Boolean

When true, enables picking using the depth buffer.
Type:
  • Boolean
Default Value:
  • true
Source:

useWebVR :Boolean

When true, splits the scene into two viewports with steroscopic views for the left and right eyes. Used for cardboard and WebVR.
Type:
  • Boolean
Default Value:
  • false
Source:

Methods

completeMorph()

Instantly completes an active transition.
Source:

destroy() → {undefined}

Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this object.

Once an object is destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception. Therefore, assign the return value (undefined) to the object as done in the example.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
Type
undefined
Example
scene = scene && scene.destroy();

drillPick(windowPosition, limitopt) → {Array.<Object>}

Returns a list of objects, each containing a `primitive` property, for all primitives at a particular window coordinate position. Other properties may also be set depending on the type of primitive. The primitives in the list are ordered by their visual order in the scene (front to back).
Parameters:
Name Type Attributes Description
windowPosition Cartesian2 Window coordinates to perform picking on.
limit Number <optional>
 If supplied, stop drilling after collecting this many picks.
Source:
Throws:
windowPosition is undefined.
Type
DeveloperError
Returns:
Array of objects, each containing 1 picked primitives.
Type
Array.<Object>
Example
var pickedObjects = scene.drillPick(new Cesium.Cartesian2(100.0, 200.0));

isDestroyed() → {Boolean}

Returns true if this object was destroyed; otherwise, false.

If this object was destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception.
Source:
See:
Returns:
true if this object was destroyed; otherwise, false.
Type
Boolean

morphTo2D(durationopt)

Asynchronously transitions the scene to 2D.
Parameters:
Name Type Attributes Default Description
duration Number <optional>
 2.0 The amount of time, in seconds, for transition animations to complete.
Source:

morphTo3D(durationopt)

Asynchronously transitions the scene to 3D.
Parameters:
Name Type Attributes Default Description
duration Number <optional>
 2.0 The amount of time, in seconds, for transition animations to complete.
Source:

morphToColumbusView(durationopt)

Asynchronously transitions the scene to Columbus View.
Parameters:
Name Type Attributes Default Description
duration Number <optional>
 2.0 The amount of time, in seconds, for transition animations to complete.
Source:

pick(windowPosition) → {Object}

Returns an object with a `primitive` property that contains the first (top) primitive in the scene at a particular window coordinate or undefined if nothing is at the location. Other properties may potentially be set depending on the type of primitive.
Parameters:
Name Type Description
windowPosition Cartesian2 Window coordinates to perform picking on.
Source:
Throws:
windowPosition is undefined.
Type
DeveloperError
Returns:
Object containing the picked primitive.
Type
Object

pickPosition(windowPosition, resultopt) → {Cartesian3}

Returns the cartesian position reconstructed from the depth buffer and window position.
Parameters:
Name Type Attributes Description
windowPosition Cartesian2 Window coordinates to perform picking on.
result Cartesian3 <optional>
 The object on which to restore the result.
Source:
Throws:
  • Picking from the depth buffer is not supported. Check pickPositionSupported.
    Type
    DeveloperError
  • 2D is not supported. An orthographic projection matrix is not invertible.
    Type
    DeveloperError
Returns:
The cartesian position.
Type
Cartesian3