Scene - Cesium Documentation

# Scene

#### new Scene(options)

  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 : true }, 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.

  `webgl.failIfMajorPerformanceCaveat` defaults to true, which ensures a context is not successfully created if the system has a major performance issue such as only supporting software rendering. The standard WebGL default is false, which is not appropriate for almost any Cesium app.

  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.

  Name | Type | Description
  --- | --- | ---

  `options`

  Object

  optional Object with the following properties:

  Name | Type | 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 | `new GeographicProjection()` | optional The map projection to use in 2D and Columbus View modes.
  `orderIndependentTranslucency` | Boolean | `true` | optional If true and the configuration supports it, use order independent translucency.
  `scene3DOnly` | Boolean | `false` | optional If true, optimizes memory use and performance for 3D mode but disables the ability to use 2D or Columbus View. *

  ##### Throws:

  - DeveloperError : options and options.canvas are required.

  ##### Example:

      // Create scene without anisotropic texture filtering
      var scene = new Cesium.Scene({
        canvas : canvas,
        contextOptions : {
          allowTextureFilterAnisotropic : false
        }
      });

  ##### See:

  - CesiumWidget
  - WebGLContextAttributes
  Source: Scene/Scene.js, line 183

### Members

#### backgroundColor :Color

  The background color, which is only visible if there is no sky box, i.e., `Scene#skyBox` is undefined.
  Default Value: ``Color.BLACK``

  ##### See:

  - Scene#skyBox
  Source: Scene/Scene.js, line 353

#### readonlycamera :Camera

  Gets the camera.
  Source: Scene/Scene.js, line 644

#### readonlycanvas :Element

  Gets the canvas element to which this scene is bound.
  Source: Scene/Scene.js, line 529

#### completeMorphOnUserInput :Boolean

  Determines whether or not to instantly complete the scene transition animation on user input.
  Default Value: `true`
  Source: Scene/Scene.js, line 286

#### 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.

  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 Cesium.BillboardCollection();
      scene.debugCommandFilter = function(command) {
          return command.owner === billboards;
      };

  Source: Scene/Scene.js, line 404

#### readonlydebugFrustumStatistics :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.

  Default Value: `undefined`
  Source: Scene/Scene.js, line 811

#### 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.

  Default Value: `false`
  Source: Scene/Scene.js, line 418

#### debugShowDepthFrustum :Number

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

  Indicates which frustum will have depth information displayed.

  Default Value: `1`
  Source: Scene/Scene.js, line 473

#### debugShowFramesPerSecond :Boolean

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

  Displays frames per second and time between frames.

  Default Value: `false`
  Source: Scene/Scene.js, line 449

#### 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.

  Default Value: `false`
  Source: Scene/Scene.js, line 435

#### debugShowGlobeDepth :Boolean

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

  Displays depth information for the indicated frustum.

  Default Value: `false`
  Source: Scene/Scene.js, line 461

#### readonlydrawingBufferHeight :Number

  The drawingBufferWidth of the underlying GL context.

  ##### See:

  - drawingBufferWidth
  Source: Scene/Scene.js, line 544

#### readonlydrawingBufferWidth :Number

  The drawingBufferHeight of the underlying GL context.

  ##### See:

  - drawingBufferHeight
  Source: Scene/Scene.js, line 559

#### farToNearRatio :Number

  The far-to-near ratio of the multi-frustum. The default is 1,000.0.
  Default Value: `1000.0`
  Source: Scene/Scene.js, line 375

#### fxaa :Boolean

  When `true`, enables Fast Approximate Anti-aliasing even when order independent translucency is unsupported.
  Default Value: `true`
  Source: Scene/Scene.js, line 482

#### globe :Globe

  Gets or sets the depth-test ellipsoid.
  Source: Scene/Scene.js, line 613

#### readonlyid :String

  Gets the unique identifier for this scene.
  Source: Scene/Scene.js, line 849

#### readonlyimageryLayers :ImageryLayerCollection

  Gets the collection of image layers that will be rendered on the globe.
  Source: Scene/Scene.js, line 717

#### readonlymapProjection :MapProjection

  Get the map projection to use in 2D and Columbus View modes.
  Default Value: `new GeographicProjection()`
  Source: Scene/Scene.js, line 673

#### readonlymaximumAliasedLineWidth :Number

  The maximum aliased line width, in pixels, supported by this WebGL implementation. It will be at least one.

  ##### See:

  - glGet with `ALIASED_LINE_WIDTH_RANGE`.
  Source: Scene/Scene.js, line 574

#### readonlymaximumCubeMapSize :Number

  The maximum length in pixels of one edge of a cube map, supported by this WebGL implementation. It will be at least 16.

  ##### See:

  - glGet with `GL_MAX_CUBE_MAP_TEXTURE_SIZE`.
  Source: Scene/Scene.js, line 589

#### mode :SceneMode

  Gets or sets the current mode of the scene.
  Default Value: ``SceneMode.SCENE3D``
  Source: Scene/Scene.js, line 861

#### moon :Moon

  The `Moon`
  Default Value: `undefined`
  Source: Scene/Scene.js, line 343

#### morphComplete :Event

  The event fired at the completion of a scene transition.
  Default Value: `Event()`
  Source: Scene/Scene.js, line 300

#### morphStart :Event

  The event fired at the beginning of a scene transition.
  Default Value: `Event()`
  Source: Scene/Scene.js, line 293

#### 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.
  Default Value: `1.0`
  Source: Scene/Scene.js, line 368

#### readonlyorderIndependentTranslucency :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.
  Source: Scene/Scene.js, line 837

#### readonlypostRender :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.
  Source: Scene/Scene.js, line 776

#### readonlypreRender :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.
  Source: Scene/Scene.js, line 762

#### readonlyprimitives :PrimitiveCollection

  Gets the collection of primitives.
  Source: Scene/Scene.js, line 631

#### readonlyrenderError :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.
  Source: Scene/Scene.js, line 748

#### 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.
  Default Value: `false`
  Source: Scene/Scene.js, line 277

#### readonlyscene3DOnly :Boolean

  Gets whether or not the scene is optimized for 3D only viewing.
  Source: Scene/Scene.js, line 823

#### readonlyscreenSpaceCameraController :ScreenSpaceCameraController

  Gets the controller for camera input handling.
  Source: Scene/Scene.js, line 658

#### skyAtmosphere :SkyAtmosphere

  The sky atmosphere drawn around the globe.
  Default Value: `undefined`
  Source: Scene/Scene.js, line 318

#### skyBox :SkyBox

  The `SkyBox` used to draw the stars.
  Default Value: `undefined`

  ##### See:

  - Scene#backgroundColor
  Source: Scene/Scene.js, line 310

#### sun :Sun

  The `Sun`.
  Default Value: `undefined`
  Source: Scene/Scene.js, line 326

#### sunBloom :Boolean

  Uses a bloom filter on the sun when enabled.
  Default Value: `true`
  Source: Scene/Scene.js, line 334

#### terrainProvider :TerrainProvider

  The terrain provider providing surface geometry for the globe.
  Source: Scene/Scene.js, line 729

### Methods

#### completeMorph()

  Instantly completes an active transition.
  Source: Scene/Scene.js, line 1999

#### 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.

  ##### Returns:

  ##### Throws:

  - DeveloperError : This object was destroyed, i.e., destroy() was called.

  ##### Example:

      scene = scene && scene.destroy();

  ##### See:

  - Scene#isDestroyed
  Source: Scene/Scene.js, line 2082

#### drillPick(windowPosition, limit) → 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).

  Name | Type | Description
  --- | --- | ---
  `windowPosition` | Cartesian2 | Window coordinates to perform picking on.
  `limit` | Number | optional If supplied, stop drilling after collecting this many picks.

  ##### Returns:

  Array of objects, each containing 1 picked primitives.

  ##### Throws:

  - DeveloperError : windowPosition is undefined.

  ##### Example:

      var pickedObjects = Cesium.Scene.drillPick(new Cesium.Cartesian2(100.0, 200.0));

  Source: Scene/Scene.js, line 1932

#### 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.

  ##### Returns:

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

  ##### See:

  - Scene#destroy
  Source: Scene/Scene.js, line 2061

#### morphTo2D(duration)

  Asynchronously transitions the scene to 2D.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `duration` | Number | `2.0` | optional The amount of time, in seconds, for transition animations to complete.

  Source: Scene/Scene.js, line 2007

#### morphTo3D(duration)

  Asynchronously transitions the scene to 3D.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `duration` | Number | `2.0` | optional The amount of time, in seconds, for transition animations to complete.

  Source: Scene/Scene.js, line 2039

#### morphToColumbusView(duration)

  Asynchronously transitions the scene to Columbus View.

  Name | Type | Default | Description
  --- | --- | --- | ---
  `duration` | Number | `2.0` | optional The amount of time, in seconds, for transition animations to complete.

  Source: Scene/Scene.js, line 2023

#### 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.

  Name | Type | Description
  --- | --- | ---
  `windowPosition` | Cartesian2 | Window coordinates to perform picking on.

  ##### Returns:

  Object containing the picked primitive.

  ##### Throws:

  - DeveloperError : windowPosition is undefined.
  Source: Scene/Scene.js, line 1806

#### pickPosition(windowPosition, result) → Cartesian3

  Returns the cartesian position reconstructed from the depth buffer and window position.

  Name | Type | Description
  --- | --- | ---
  `windowPosition` | Cartesian2 | Window coordinates to perform picking on.
  `result` | Cartesian3 | optional The object on which to restore the result.

  ##### Returns:

  The cartesian position.

  ##### Throws:

  - DeveloperError : Picking from the depth buffer is not supported. Check pickPositionSupported.
  - DeveloperError : 2D is not supported. An orthographic projection matrix is not invertible.
  Source: Scene/Scene.js, line 1859