Package com.here.sdk.mapview

Class MapSurface

  • java.lang.Object
    • com.here.sdk.mapview.MapSurface
  • All Implemented Interfaces:
    MapViewBase
    public class MapSurface
extends java.lang.Object
implements MapViewBase
    Provides the ability to render a map into a provided rendering surface. This enables the possibility to render a map into external displays like Android Auto. If you want to use the map for a regular use case please use the MapView instead.

    • Constructor Detail

      • MapSurface

        public MapSurface()
        Creates a new instance.

      • MapSurface

        public MapSurface​(MapViewOptions options)
        Creates a new instance.
        Parameters:
        options - The options

      • MapSurface

        public MapSurface​(android.content.Context context)
        Creates a new instance.
        Parameters:
        context - The Application context

      • MapSurface

        public MapSurface​(android.content.Context context,
                  MapViewOptions options)
        Creates a new instance.
        Parameters:
        options - The options
        context - The Application context

    • Method Detail

      • isValid

        public boolean isValid()
        Returns whether this MapSurface is valid. An invalid MapSurface is non-functional. A MapSurface is considered valid only after setSurface(Context, Surface, int, int) and before destroy() is called. MapSurface is also invalidated when the SDKNativeEngine it is using is destroyed.
        Specified by:
        isValid in interface MapViewBase
        Returns:
        true if this MapSurface is valid, false otherwise.

      • destroy

        public void destroy()
        Destroys the map renderer and render surface, making this MapSurface invalid. Call this method only when the render surface will no longer be used. isValid() will return @{code false} after this is called. It can be made valid again by setting render surface using setSurface(Context, Surface, int, int).

      • setOnReadyListener

        public void setOnReadyListener​(MapView.OnReadyListener readyListener)
        Sets the OnReadyListener, which will be notified once MapView initialization has been finished. It is highly recommended to put code that accesses map view related functionality inside MapView.OnReadyListener.onMapViewReady() instead of directly in Activity's onResume().
        Parameters:
        readyListener - The listener to be registered, or null to unregister any previously register listener.

      • setSurface

        public void setSurface​(android.content.Context context,
                       android.view.Surface surface,
                       int width,
                       int height)
        Deprecated.

        Will be removed in v4.26.0. Please use attachSurface.

        Sets the surface on which the map will be rendered. This method needs to be called before any other methods in this class.
        Parameters:
        context - The Application context
        surface - The surface to render to.
        width - The width of the render surface in pixels.
        height - The height of the render surface in pixels.

      • attachSurface

        public void attachSurface​(android.content.Context context,
                          android.view.Surface surface,
                          int width,
                          int height)
        Sets the surface on which the map will be rendered. Throws exception if the surface cannot be used by HERESDK.
        Parameters:
        context - The Application context
        surface - The surface to render to.
        width - The width of the render surface in pixels.
        height - The height of the render surface in pixels.
        Throws:
        java.lang.NullPointerException - if surface is invalid and cannot be used.

      • setSurface

        @Deprecated
public void setSurface​(android.content.Context context,
                       android.view.Surface surface,
                       int width,
                       int height,
                       @NonNull
                       MapSurface.RenderListener renderListener)
        Deprecated.

        Will be removed in v4.26.0. Please use attachSurface.

        Sets the surface on which the map will be rendered. This method needs to be called before any other methods in this class. Note: This feature is in BETA state and thus there can be bugs and unexpected behavior. Related APIs may change for new releases without a deprecation process.
        Parameters:
        context - The Application context
        surface - The surface to render to.
        width - The width of the render surface in pixels.
        height - The height of the render surface in pixels.
        renderListener - A listener for render events. The listener will be released once destroySurface() gets called.

      • attachSurface

        public void attachSurface​(android.content.Context context,
                          android.view.Surface surface,
                          int width,
                          int height,
                          @NonNull
                          MapSurface.RenderListener renderListener)
        Sets the surface on which the map will be rendered. Throws exception if the surface cannot be used by HERESDK. Note: This feature is in BETA state and thus there can be bugs and unexpected behavior. Related APIs may change for new releases without a deprecation process.
        Parameters:
        context - The Application context
        surface - The surface to render to.
        width - The width of the render surface in pixels.
        height - The height of the render surface in pixels.
        renderListener - A listener for render events. The listener will be released once destroySurface() gets called.
        Throws:
        java.lang.NullPointerException - if surface is invalid and cannot be used.

      • destroySurface

        public void destroySurface()
        Destroys the rendering surface.

      • redraw

        public void redraw​(java.lang.Runnable redrawFinished)

        Redraws the map and reports back on completion.

        Parameters:
        redrawFinished -

        The runnable to be executed after completion.

      • pick

        public void pick​(@Nullable
                 MapScene.MapPickFilter filter,
                 @NonNull
                 Rectangle2D viewArea,
                 @NonNull
                 MapViewBase.MapPickCallback callback)

        Returns all map content located inside the specified pick area. Content to be picked is specified by a pick content filter. The pick area is defined by a rectangle in map view coordinates in pixels, relative to the map view's origin at (0, 0) which indicates the top-left corner of the map view.

        Specified by:
        pick in interface MapViewBase
        Parameters:
        filter -

        Filter for the map content to be picked. When a filter is not set all of the pickable content will be picked.

        viewArea -

        The rectangular pixel area of the view inside which map content will be picked. View area is relative to the map view's origin at (0, 0) at the top-left corner of the map view.

        callback -

        Callback to call with the result. This will be called on a main thread when pick operation completes.

      • geoToViewCoordinates

        @Nullable
public Point2D geoToViewCoordinates​(@NonNull
                                    GeoCoordinates geoCoordinates)
        Converts geographical coordinates to view coordinates (in pixels).

        If specified, altitude of the input coordinates is interpreted as altitude above sea level. If not specified, the input coordinates are interpreted as being on ground elevation. The above distinction is only relevant when 3D terrain feature is enabled.

        The resulting view coordinates might be outside of current viewport, i.e. result might contain values less than zero or greater than view's dimensions.

        If the render surface is not attached, it will return null.

        Specified by:
        geoToViewCoordinates in interface MapViewBase
        Parameters:
        geoCoordinates -

        Geographical coordinates to convert.

        Returns:

        The view coordinates of the specified geographical point or null if there is no render surface attached.

        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.
        See Also:
        MapView.OnReadyListener

      • addLifecycleListener

        public void addLifecycleListener​(@NonNull
                                 MapViewLifecycleListener lifecycleListener)

        Adds a MapViewLifecycleListener to this map view. Adding the same object multiple times has no effect.

        Specified by:
        addLifecycleListener in interface MapViewBase
        Parameters:
        lifecycleListener -

        An object to be notified of lifecycle events.

        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • removeLifecycleListener

        public void removeLifecycleListener​(@NonNull
                                    MapViewLifecycleListener lifecycleListener)

        Removes a MapViewLifecycleListener from this map view. Trying to remove an object that was not added or was removed before has no effect.

        Specified by:
        removeLifecycleListener in interface MapViewBase
        Parameters:
        lifecycleListener -

        An object to stop being notified of lifecycle events.

        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • onResume

        public void onResume()

        Call this method in the onResume() method of the lifecycle owner.

      • onPause

        public void onPause()

        Call this method in the onPause() method of the lifecycle owner.

      • viewToGeoCoordinates

        @Nullable
public GeoCoordinates viewToGeoCoordinates​(@NonNull
                                           Point2D viewCoordinates)
        Converts view coordinates to geographical coordinates.

        An optional altitude component of the resulting geographical coordinate is not set.

        If the view coordinates specify a point above a horizon, then the result is geographical coordinates of the point on a horizon below the specified view coordinates.

        The fog effect is ignored for the calculation, meaning that for the view point within the area covered by the fog, the result is geographical coordinates that would be displayed at the specified point if the fog effect was not applied.

        If the render surface is not attached, it will return null.

        Specified by:
        viewToGeoCoordinates in interface MapViewBase
        Parameters:
        viewCoordinates -

        Point inside the view to convert.

        Returns:

        The geographical coordinates under specified view point or null if there is no render surface attached.

        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.
        See Also:
        MapView.OnReadyListener

      • getGestures

        @NonNull
public Gestures getGestures()
        Returns the gestures control object. Please note that there is no gesture support for the MapSurface at this point.
        Specified by:
        getGestures in interface MapViewBase
        Returns:
        the Gestures control object
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getPixelScale

        public double getPixelScale()

        Gets the pixel scale factor used by this MapView. It is used to support screen resolution and size independence. This value is a derivative of the device's screen pixel density and is a direct analog of pixel density from DisplayMetrics. It can be used to translate between physical pixels and density independent pixels according to formula:

        dp = px / pixel_scale.

        Specified by:
        getPixelScale in interface MapViewBase
        Returns:
        current pixel scale factor, or 0.0 if MapView is not initialized
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getViewportSize

        public Size2D getViewportSize()
        Returns the viewport size of this MapView in physical pixels.
        Specified by:
        getViewportSize in interface MapViewBase
        Returns:
        The viewport size in physical pixels
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getFrameRate

        public int getFrameRate()
        Gets maximum render frame rate in frames per second. The default value is 60 frames per second.
        Specified by:
        getFrameRate in interface MapViewBase
        Returns:
        Actual maximal render frame rate
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • setFrameRate

        public void setFrameRate​(int value)
        Sets maximum render frame rate in frames per second.
        Specified by:
        setFrameRate in interface MapViewBase
        Parameters:
        value - Maximum render frame rate in frames per second. Setting to 0 disables automatic rendering for this view. Setting negative values has no effect.
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • takeScreenshot

        public void takeScreenshot​(MapView.TakeScreenshotCallback callback)
        Asynchronously retrieves screenshot of current map view
        Parameters:
        callback - Completion handler called when the screenshot is completed

      • setWatermarkLocation

        public void setWatermarkLocation​(@NonNull
                                 Anchor2D anchor,
                                 @NonNull
                                 Point2D offset)

        Sets the position of the HERE logo watermark within the map view. By default, the watermark is aligned to the bottom-right corner of the view: Anchor2D(1.0, 1.0) and Point2D(-watermarkSize.width / 2, -watermarkSize.height / 2). It is recommended to change the default position only if necessary to avoid overlapping UI elements. The watermark should always be fully visible within the view. The anchor point on the watermark is its center (width/2, height/2), around which it will be placed in the map view. For map views smaller than 250 dip in both width and height, the watermark will not be shown.

        Specified by:
        setWatermarkLocation in interface MapViewBase
        Parameters:
        anchor -

        Anchor point in normalized view coordinates [0, 1]. Map view's origin at (0, 0) indicates a top-left corner of the map view. Out of boundary anchor point values will be clamped to the [0, 1] range.

        offset -

        A horizontal and vertical offset (expressed in positive/negative pixel coordinates) that allows shifting the watermark from the anchor point position in one or the other direction. For the quadrant of values expressing visible part of the map view negative offset shifts the watermark to the direction of the origin, positive - away from it. For example, the offset of (-10, 5) will shift the watermark 10px to the left and 5px to the bottom. If specified offset will result in watermark being completely or partially out-of-view the offset will be adjusted internally so that watermark is fully visible. Offset is not being scaled when the map view size changes.

        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getWatermarkSize

        @NonNull
public Size2D getWatermarkSize()

        Returns the watermark size in physical pixels.

        Specified by:
        getWatermarkSize in interface MapViewBase
        Returns:

        Provides the size of the watermark in physical pixels.

        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • setShadowQuality

        public static void setShadowQuality​(ShadowQuality shadowQuality)
        Set desired shadow quality for all instances of MapSurface/MapView. The quality controls the size of the shadow maps and the cascade count. The default shadow quality is ShadowQuality.MEDIUM. MapSurfaces can request to render shadows by feature. Enabling shadows has a performance impact and should be considered only for devices with sufficient performance. Note: This feature is in beta state and thus there can be bugs and unexpected behavior.
        Parameters:
        shadowQuality - The shadow quality.
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getShadowQuality

        public static ShadowQuality getShadowQuality()
        Gets the currently set shadow quality. The default shadow quality is ShadowQuality.MEDIUM. Note: This feature is in beta state and thus there can be bugs and unexpected behavior.
        Returns:
        The currently set shadow quality.
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getCamera

        @NonNull
public MapCamera getCamera()
        Returns the camera control object for the map
        Specified by:
        getCamera in interface MapViewBase
        Returns:
        the MapCamera object for the map
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getMapScene

        @NonNull
public MapScene getMapScene()
        Gets the map scene associated with this map view. This can be used to request different map schemes to be displayed in the map view, and to add and remove map items from the map.
        Specified by:
        getMapScene in interface MapViewBase
        Returns:
        the MapScene associated with this map view.
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getMapContext

        @NonNull
public MapContext getMapContext()
        Gets the map context associated with this map view.
        Specified by:
        getMapContext in interface MapViewBase
        Returns:
        the MapContext associated with this map view.
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.

      • getHereMap

        @NonNull
public HereMap getHereMap()
        Gets the HereMap associated with this map view.
        Specified by:
        getHereMap in interface MapViewBase
        Returns:
        the HereMap associated with this map view.
        Throws:
        java.lang.IllegalStateException - if MapSurface object is not valid.