SceneView Class

Scene."> SceneView Class | ArcGISQtCpp
  • SceneView
  • class Esri::ArcGISRuntime::SceneView

    A user interface control that displays three-dimensional (3D) geographic content defined by a Scene. More...

    Header: #include <SceneView.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::GeoView
    Inherited By:

    Esri::ArcGISRuntime::SceneGraphicsView and Esri::ArcGISRuntime::SceneQuickView

    Public Functions

    virtual ~SceneView() override
    QColor ambientLightColor() const
    Esri::ArcGISRuntime::AnalysisOverlayListModel *analysisOverlays() const
    Esri::ArcGISRuntime::Scene *arcGISScene() const
    Esri::ArcGISRuntime::AtmosphereEffect atmosphereEffect() const
    Esri::ArcGISRuntime::CameraController *cameraController() const
    Esri::ArcGISRuntime::Camera currentViewpointCamera() const
    double fieldOfView() const
    double fieldOfViewDistortionRatio() const
    Esri::ArcGISRuntime::ImageOverlayListModel *imageOverlays() const
    bool isManualRendering() const
    Esri::ArcGISRuntime::LocationToScreenResult locationToScreen(const Esri::ArcGISRuntime::Point &scenePoint) const
    void renderFrame()
    Esri::ArcGISRuntime::Point screenToBaseSurface(double screenX, double screenY) const
    QFuture<Esri::ArcGISRuntime::Point> screenToLocationAsync(double screenX, double screenY)
    void setAmbientLightColor(const QColor &color)
    void setArcGISScene(Esri::ArcGISRuntime::Scene *scene)
    void setAtmosphereEffect(Esri::ArcGISRuntime::AtmosphereEffect atmosphereEffect)
    void setCameraController(Esri::ArcGISRuntime::CameraController *cameraController)
    void setFieldOfView(double angle)
    void setFieldOfViewAndDistortionRatio(double angle, double distortionRatio)
    void setFieldOfViewFromLensIntrinsics(double xFocalLength, double yFocalLength, double xPrincipal, double yPrincipal, double xImageSize, double yImageSize, Esri::ArcGISRuntime::DeviceOrientation deviceOrientation)
    virtual void setManualRendering(bool manualRendering)
    void setSpaceEffect(Esri::ArcGISRuntime::SpaceEffect spaceEffect)
    void setSunLighting(Esri::ArcGISRuntime::LightingMode lightingMode)
    void setSunTime(const QDateTime &sunTime)
    void setViewpointCameraAndWait(const Esri::ArcGISRuntime::Camera &camera)
    QFuture<bool> setViewpointCameraAsync(const Esri::ArcGISRuntime::Camera &camera)
    QFuture<bool> setViewpointCameraAsync(const Esri::ArcGISRuntime::Camera &camera, float duration)
    Esri::ArcGISRuntime::SpaceEffect spaceEffect() const
    Esri::ArcGISRuntime::LightingMode sunLighting() const
    QDateTime sunTime() const

    Static Public Members

    quint64 memoryLimit()
    void setMemoryLimit(quint64 memoryLimitBytes)

    Protected Functions

    SceneView(int width, int height)

    Detailed Description

    A SceneView is a user interface that displays Scene layers and graphics in 3D. It uses a camera to control the visible area (extent) of the Scene and supports user interactions such as pan, zoom, tilt, and rotate. A scene view also provides access to the underlying layer data in a scene.

    To display a Scene, add a SceneView control to your app and assign the scene to it. This loads the scene and its content, such as a Surface, Basemap and collection of operational layers, and displays this content on screen.

    User interactions such as pan, zoom, tilt, rotate, and identify or selection are supported in the SceneView using touch, mouse, keyboard or pen/pencil. If required, you can override keys, clicks, and gestures to provide a specific user experience.

    The visible area (Viewpoint) of a SceneView is defined by the position and orientation of a Camera. To determine the current visible area, call GeoView::currentViewpoint. Make sure that any user-initiated or programmatic navigation is complete before getting the current Viewpoint by calling GeoView::isNavigating.

    You can programmatically set the visible area by specifying a viewpoint. For example, to zoom to the Viewpoint specified by a camera, pass the Camera to the SceneView using one of its methods, such as setViewpointCameraAsync. The SceneView has a camera controller (cameraController) to manage the camera's movement and user interactions.

    In an MVC architecture, the SceneView represents the View tier. The Model tier is represented by the Scene object which can provide a collection of operational layers, a Basemap and a Surface. You can only set one Scene per SceneView, but you can swap the arcGISScene with another when the application is running.

    See Scene view for more information.

    See also Scene, GeoView, SceneGraphicsView, and SceneQuickView.

    Member Function Documentation

    [protected] SceneView::SceneView(int width, int height)

    Constructs a SceneView with a specified size.

    • width - The width in physical pixels.
    • height - The height in physical pixels.

    [override virtual] SceneView::~SceneView()

    Destructor.

    [since Esri::ArcGISRuntime 100.1] QColor SceneView::ambientLightColor() const

    Returns the color of the scene view's ambient light.

    The ambient light is visible if the sunLighting is set to LightingMode::Light or LightingMode::LightAndShadows.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also setAmbientLightColor().

    [since Esri::ArcGISRuntime 100.2] Esri::ArcGISRuntime::AnalysisOverlayListModel *SceneView::analysisOverlays() const

    Gets the list of analysis overlays that render the results of 3D visual analysis on the scene view.

    Dynamic 3D analyses, such as LineOfSight and Viewshed, generate visual results that are rendered on the scene view. To display the results, add the Analysis to a collection of AnalysisOverlay::analyses and then add the AnalysisOverlay to the collection of SceneView::analysisOverlays.

    Note that the SceneView::analysisOverlays collection can be empty but is never null. It's created for a specific SceneView so you can't reuse an AnalysisOverlay collection from another SceneView. Each AnalysisOverlay can only exist in one SceneView::analysisOverlays collection.

    This function was introduced in Esri::ArcGISRuntime 100.2.

    Esri::ArcGISRuntime::Scene *SceneView::arcGISScene() const

    Gets the scene that the SceneView is displaying.

    If you assign a Scene to a SceneView, the scene, its Surface, Basemap, and collection of operational layers automatically start to load. When loading completes, the layers and basemap are rendered over the Surface in the scene view.

    You can load a Scene into your app before you assign it to a SceneView. This is useful if you want to validate the content of a scene before you display it.

    See also setArcGISScene().

    Esri::ArcGISRuntime::AtmosphereEffect SceneView::atmosphereEffect() const

    Gets the effect applied to the scene's atmosphere.

    The default value is AtmosphereEffect::HorizonOnly

    See also setAtmosphereEffect().

    Esri::ArcGISRuntime::CameraController *SceneView::cameraController() const

    The camera controller manages the position, orientation, and movement of the camera for a SceneView.

    The controller handles user-interaction with the SceneView and updates the Camera. You can assign a CameraController with a specific navigation mode that is free roaming, following a moving target, fixed on a stationary target, or that supports AR transformation matrices. For more information, see CameraController.

    The default is GlobeCameraController.

    See also setCameraController().

    Esri::ArcGISRuntime::Camera SceneView::currentViewpointCamera() const

    Gets the camera that displays the current viewpoint.

    [since Esri::ArcGISRuntime 100.6] double SceneView::fieldOfView() const

    Returns the horizontal field of view of the scene view in degrees.

    The value of the field of view is influenced by the size and orientation of the device screen. A landscape orientation has a larger field of view value than a portrait orientation

    The default value is 45.0.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also setFieldOfView().

    [since Esri::ArcGISRuntime 100.6] double SceneView::fieldOfViewDistortionRatio() const

    Gets the ratio that indicates how much the vertical field of view is distorted.

    A distortion factor less than 1.0 causes the visuals to be stretched taller in comparison to their width. A distortion factor greater than 1.0 causes the visuals to be shrunk shorter in comparison to their width.

    The default value is 1.0.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    [since Esri::ArcGISRuntime 100.8] Esri::ArcGISRuntime::ImageOverlayListModel *SceneView::imageOverlays() const

    Returns a collection of overlays for displaying images in the scene view.

    An image overlay collection cannot belong to more that one SceneView. If the collection contains multiple image overlays, they display in the order in which they were added to the collection.

    So the first overlay in the collection (at index 0) displays at the bottom and each one that follows displays on top of the previous ones.

    If the SceneView also has a GraphicsOverlay, it displays on top of the ImageOverlay.

    This function was introduced in Esri::ArcGISRuntime 100.8.

    [since Esri::ArcGISRuntime 100.6] bool SceneView::isManualRendering() const

    Returns whether the SceneView is under manual rendering control.

    Note: manual rendering is only supported on iOS and Android platforms.

    This property determines whether the SceneView will use manual rendering updates rather than the using this API's internal rendering mechanism.

    When this property is true, you must call renderFrame for any updates to be drawn on the screen. Calling renderFrame isn't necessary when this property is false. The default value is false.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also renderFrame.

    Esri::ArcGISRuntime::LocationToScreenResult SceneView::locationToScreen(const Esri::ArcGISRuntime::Point &scenePoint) const

    Converts a location in map coordinates to a point in screen coordinates relative to the upper-left corner of the scene view.

    • scenePoint - A location defined within the spatial reference of the scene view.

    The screen coordinates are in device-independent pixels (DIP) relative to the upper-left corner of the scene view at position 0,0. The LocationToScreenResult indicates whether the screen coordinates are visible in the scene view. They can be invisible if they are on the other side of the globe, not in the Viewpoint, or are blocked by the base surface or elevation layer.

    To call this method, assign a scene to the scene view, ensure that it is loaded and the draw status is DrawStatus::Completed.

    [static, since Esri::ArcGISRuntime 100.3] quint64 SceneView::memoryLimit()

    Gets the total memory (in bytes) that a process can use for rendering scene data (Android only).

    Note, the default value is determined upon initialization of the first SceneView instance that is being created by the process. Before any SceneView instance has been created, zero is returned. For some use cases you might want to choose to set a custom limit. See setMemoryLimit for details.

    The default value is determined as follows:

    • If ActivityManager.getLargeMemoryClass() is greater than 1 gigabyte, then that value is used as the default value.
    • Otherwise, check whether 45% of total system memory android.app.ActivityManager.MemoryInfo.totalMem is less than 1 gigabyte. If so, then that value is used as the default value.
    • Otherwise, the default value is 1 gigabyte.

    This function was introduced in Esri::ArcGISRuntime 100.3.

    See also setMemoryLimit().

    [since Esri::ArcGISRuntime 100.6] void SceneView::renderFrame()

    Manually render the current frame.

    Note: manual rendering (along with this method) is only supported on iOS and Android platforms.

    This call will block the caller until the latest changes have been rendered to the screen.

    This method may be called from the main/GUI thread or a sub-thread. Do not mix calls from the main thread and a sub-thread to this method in the same application session.

    If calling this method from a timer event, be sure to stop the timer before shutting down the application.

    In certain situations you may be able to achieve better rendering performance by utilizing the single-threaded renderer. This is already the default setting on some platforms.

    // use the environment variable to use the "basic" rendering loop
    // for the Qt Quick Scene Graph
    qputenv("QSG_RENDER_LOOP", "basic");

    For more information, see here https://links.esri.com/qtquick-visualcanvas-scenegraph-rendering

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also isManualRendering.

    Esri::ArcGISRuntime::Point SceneView::screenToBaseSurface(double screenX, double screenY) const

    Returns the x/y location on the map that corresponds to the provided screen coordinates.

    Converts the specified screen coordinate, relative to the upper-left corner of the scene view, to a location on the base surface in map coordinates.

    • screenX - The x screen coordinate.
    • screenY - The y screen coordinate.

    The coordinate of the top left corner of the screen is 0,0.

    This method gets the x/y coordinates on the base surface that would be seen at the screen coordinates without regard for any features in the scene. Any features in the line of sight from the camera to the base surface are ignored. To convert this result into a 3D scene location, use the returned x/y coordinates with the z-value at that x/y location on the base surface.

    To call this method, assign a scene to the scene view, ensure that it is loaded and the draw status is DrawStatus::Completed.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::Point> SceneView::screenToLocationAsync(double screenX, double screenY)

    Asynchronously converts a screen coordinate relative to the upper-left corner of the scene view to a location in map coordinates.

    • screenX - The screen's x-coordinate to convert to map coordinate.
    • screenY - The screen's y-coordinate to convert to map coordinate.

    The coordinate of the top left corner of the screen is 0,0.

    This is a high performance calculation executed on the GPU using a triangular mesh. Note that elevation values are approximated, and as the distance between the camera and the surface increases, the precision of the elevation value decreases.

    To call this method, assign a scene to the scene view, ensure that it is loaded and the draw status is DrawStatus::Completed. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 100.1] void SceneView::setAmbientLightColor(const QColor &color)

    Sets the ambientLightColor to color.

    The ambientLightColor is the color of the scene view's ambient light.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also ambientLightColor.

    void SceneView::setArcGISScene(Esri::ArcGISRuntime::Scene *scene)

    Sets the scene associated with this SceneView.

    Setting a non-loaded scene to a view starts the load process of the scene so the scene can be displayed once loaded.

    • scene - The scene to associate with this sceneview.

    See also arcGISScene().

    void SceneView::setAtmosphereEffect(Esri::ArcGISRuntime::AtmosphereEffect atmosphereEffect)

    Sets the atmosphereEffect to atmosphereEffect.

    See also atmosphereEffect.

    void SceneView::setCameraController(Esri::ArcGISRuntime::CameraController *cameraController)

    Sets the sceneview's camera controller.

    The camera controller determines the camera interaction and navigation model.

    • cameraController - The Camera controller to set for the sceneview.

    The default is GlobeCameraController.

    See also cameraController().

    [since Esri::ArcGISRuntime 100.6] void SceneView::setFieldOfView(double angle)

    Sets the horizontal field of view of the scene view in degrees.

    The value of the field of view is influenced by the size and orientation of the device screen. A landscape orientation has a larger field of view value than a portrait orientation.

    This value must be between 0 and 120. If the value is outside the range, the field of view is not changed and an error "Invalid argument" is emitted.

    angle - The field of view on the scene view in degrees. This value must be greater than 0 and less than or equal to 120.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also fieldOfView().

    [since Esri::ArcGISRuntime 100.6] void SceneView::setFieldOfViewAndDistortionRatio(double angle, double distortionRatio)

    Sets the field of view on the scene view in degrees and determines how much the vertical field of view is distorted.

    A distortion ratio less than 1.0 will cause the visuals to be stretched taller in comparison to their width. A distortion ratio greater than 1.0 will cause the visuals to be shrunk shorter in comparison to their width. The default distortion ratio is 1.0.

    • angle - The field of view on the scene view in degrees. This value must be between 0 and 120.
    • distortionRatio - The field of view vertical distortion ratio. This value must be between 0.1 and 10.

    If the values are outside the range, the field of view and the field of view vertical distortion ratio are not changed and an error "Invalid argument" is emitted.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    [since Esri::ArcGISRuntime 100.6] void SceneView::setFieldOfViewFromLensIntrinsics(double xFocalLength, double yFocalLength, double xPrincipal, double yPrincipal, double xImageSize, double yImageSize, Esri::ArcGISRuntime::DeviceOrientation deviceOrientation)

    Sets the field of view of the scene view to the field of view of a camera lens using the lens characteristics.

    Allows for matching the field of view of the scene view to the field of view of a camera lens using the lens characteristics. All parameter values must be greater than 0.

    • xFocalLength - The pixel focal length along the x-axis. The units are in pixels. xFocal and yFocal should be identical for square pixels.
    • yFocalLength - The pixel focal length along the y-axis. The units are in pixels. xFocal and yFocal should be identical for square pixels.
    • xPrincipal - The distance along the x-axis between the principal point and the top-left corner of the image frame. The units are in pixels. This must also be less than xImageSize.
    • yPrincipal - The distance along the y-axis between the principal point and the top-left corner of the image frame. The units are in pixels. This must also be less than xImageSize.
    • xImageSize - The x value of the image size captured by the camera. The units are in pixels.
    • yImageSize - The y value of the image size captured by the camera. The units are in pixels.
    • deviceOrientation - Describes the orientation of the device.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    [virtual, since Esri::ArcGISRuntime 100.6] void SceneView::setManualRendering(bool manualRendering)

    Sets the SceneView rendering mode manualRendering.

    Note: manual rendering is only supported on iOS and Android platforms.

    When the SceneView is using manual rendering, you must call renderFrame on a regular interval for the view to update.

    Note: this can only be set once, and must be set as early as possible. This setting cannot be changed once rendering has started.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also isManualRendering() and renderFrame.

    [static, since Esri::ArcGISRuntime 100.3] void SceneView::setMemoryLimit(quint64 memoryLimitBytes)

    Sets the total memory (in bytes) that a process can use for rendering scene data to memoryLimitBytes (Android only).

    The memory limit is set by default and this should be sufficient for most use cases. For more details of how the default limit is determined see memoryLimit. For some use cases you might want to choose to override the default to increase or reduce the limit. In those cases, set this property before instantiating any SceneView objects. If you choose to override this limit, consider the device's recommended memory limits. You can get that value from ActivityManager.getLargeMemoryClass().

    This function was introduced in Esri::ArcGISRuntime 100.3.

    See also memoryLimit().

    [since Esri::ArcGISRuntime 100.6] void SceneView::setSpaceEffect(Esri::ArcGISRuntime::SpaceEffect spaceEffect)

    Sets the space effect for the scene view.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also spaceEffect().

    [since Esri::ArcGISRuntime 100.1] void SceneView::setSunLighting(Esri::ArcGISRuntime::LightingMode lightingMode)

    Sets the lighting mode for the sceneview.

    The lighting mode determines whether the Earth appears to be illuminated by the Sun, and whether to simulate shadows. For example, this can be used to control whether the shadows of terrain and 3D models are cast.

    • lightingMode - The lighting mode to set.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also sunLighting().

    [since Esri::ArcGISRuntime 100.1] void SceneView::setSunTime(const QDateTime &sunTime)

    Sets the Sun's position to simulate a specific time.

    The position of sunset, sunrise, and the night-time area of darkness are visible in the scene view as calculated from the SceneView::setSunTime value. These lighting effects are visible if you have set the SceneView::sunLighting modes of LightingMode::Light and LightingMode::LightAndShadows.

    The default value is Fri Sep 22 2000 12:00:00 GMT+0000.

    You can simulate the Sun's position relative to the Earth to be as it would at a specific date and time.

    The default time of the simulation is September 22, 2000 at noon GMT.

    • sunTime - The time to be used.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also sunTime().

    void SceneView::setViewpointCameraAndWait(const Esri::ArcGISRuntime::Camera &camera)

    Sets the Camera for the scene view synchronously. This call runs in the same thread as the caller and will block until it finishes.

    The Camera determines at what position and angle the scene is viewed.

    • camera - The Camera to set for the sceneview.

    [since Esri::ArcGISRuntime 200.2] QFuture<bool> SceneView::setViewpointCameraAsync(const Esri::ArcGISRuntime::Camera &camera)

    Changes the display to the new camera viewpoint asynchronously.

    • camera - The new camera information for the scene view.

    Use setViewpointCamera to set a viewpoint that animates over a specified duration. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<bool> SceneView::setViewpointCameraAsync(const Esri::ArcGISRuntime::Camera &camera, float duration)

    Animates the display to the viewpoint specified by the given camera using the specified duration to arrive.

    • camera - The new camera information for the scene view.
    • duration - The time for the transition animation to complete, in seconds.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 100.6] Esri::ArcGISRuntime::SpaceEffect SceneView::spaceEffect() const

    Gets the visual effect of outer space in the scene view.

    Determines whether outer space is black with stars or transparent in the scene view.

    The default value is SpaceEffect::Stars.

    This function was introduced in Esri::ArcGISRuntime 100.6.

    See also setSpaceEffect().

    [since Esri::ArcGISRuntime 100.1] Esri::ArcGISRuntime::LightingMode SceneView::sunLighting() const

    Returns the type of ambient sunlight and shadows in the scene view.

    LightingMode::Light and LightingMode::LightAndShadows display ambient light according to the specified SceneView::ambientLightColor.

    The default value is LightingMode::NoLight.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also setSunLighting().

    [since Esri::ArcGISRuntime 100.1] QDateTime SceneView::sunTime() const

    Returns the position of the sun in the scene view based on a specific date and time.

    The position of sunset, sunrise, and the night-time area of darkness are visible in the scene view as calculated from the sunTime value. These lighting effects are visible if you have set the sunLighting modes of LightingMode::Light and LightingMode::LightAndShadows. The default value is Fri Sep 22 2000 12:00:00 GMT+0000

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also setSunTime().

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.