Package com.here.sdk.mapview

Class MapSurface

java.lang.Object
com.here.sdk.mapview.MapSurface
All Implemented Interfaces:
MapViewBase
public class MapSurface extends 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 Details

    • 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 Details

    • 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:
      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:
      NullPointerException - if surface is invalid and cannot be used.

    • destroySurface

      public void destroySurface()
      Destroys the rendering surface.

    • redraw

      public void redraw(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:
      IllegalStateException - if MapSurface object is not valid.
      See Also:

    • 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:
      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:
      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:
      IllegalStateException - if MapSurface object is not valid.
      See Also:

    • 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:
      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:
      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:
      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:
      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:
      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:
      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:
      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:
      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:
      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:
      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:
      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:
      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:
      IllegalStateException - if MapSurface object is not valid.