1 // SPDX-License-Identifier: LGPL-2.1-or-later 2 // 3 // SPDX-FileCopyrightText: 2006-2008 Torsten Rahn <tackat@kde.org> 4 // SPDX-FileCopyrightText: 2007 Inge Wallin <ingwa@kde.org> 5 // SPDX-FileCopyrightText: 2009 Jens-Michael Hoffmann <jensmh@gmx.de> 6 // 7 8 #ifndef MARBLE_MARBLEMAP_H 9 #define MARBLE_MARBLEMAP_H 10 11 12 /** @file 13 * This file contains the headers for MarbleMap. 14 * 15 * @author Torsten Rahn <tackat@kde.org> 16 * @author Inge Wallin <inge@lysator.liu.se> 17 */ 18 19 20 #include "marble_export.h" 21 #include "GeoDataCoordinates.h" // In geodata/data/ 22 #include "GeoDataRelation.h" 23 24 // Qt 25 #include <QObject> 26 #include <QRegion> 27 28 class QFont; 29 class QString; 30 31 namespace Marble 32 { 33 34 // MarbleMap 35 class MarbleMapPrivate; 36 37 // Marble 38 class GeoDataLatLonAltBox; 39 class GeoDataFeature; 40 class MarbleModel; 41 class ViewportParams; 42 class GeoPainter; 43 class LayerInterface; 44 class RenderPlugin; 45 class RenderState; 46 class AbstractDataPlugin; 47 class AbstractDataPluginItem; 48 class AbstractFloatItem; 49 class TextureLayer; 50 class TileCoordsPyramid; 51 class GeoSceneTextureTileDataset; 52 class StyleBuilder; 53 54 /** 55 * @short A class that can paint a view of the earth. 56 * 57 * FIXME: Change this description when we are done. 58 * 59 * This class can paint a view of the earth or any other globe, 60 * depending on which dataset is used. It can be used to show the 61 * globe in a widget like MarbleWidget does, or on any other 62 * QPaintDevice. 63 * 64 * The projection and other view parameters that control how MarbleMap 65 * paints the map is given through the class ViewParams. If the 66 * programmer wants to allow the user to control the map, he/she has 67 * to provide a way for the user to interact with it. An example of 68 * this can be seen in the class MarbleWidgetInputHandler, that lets 69 * the user control a MarbleWidget that uses MarbleMap internally. 70 * 71 * The MarbleMap needs to be provided with a data model to 72 * work. This model is contained in the MarbleModel class. The widget 73 * can also construct its own model if none is given to the 74 * constructor. This data model contains 3 separate datatypes: 75 * <b>tiles</b> which provide the background, <b>vectors</b> which 76 * provide things like country borders and coastlines and 77 * <b>placemarks</b> which can show points of interest, such as 78 * cities, mountain tops or the poles. 79 * 80 * @see MarbleWidget 81 * @see MarbleModel 82 */ 83 84 class MARBLE_EXPORT MarbleMap : public QObject 85 { 86 Q_OBJECT 87 Q_CLASSINFO("D-Bus Interface", "org.kde.MarbleMap") 88 89 public: 90 91 friend class MarbleWidget; 92 93 /** 94 * @brief Construct a new MarbleMap. 95 * 96 * This constructor should be used when you will only use one 97 * MarbleMap. The widget will create its own MarbleModel when 98 * created. 99 */ 100 MarbleMap(); 101 102 /** 103 * @brief Construct a new MarbleMap. 104 * @param model the data model for the widget. 105 * 106 * This constructor should be used when you plan to use more than 107 * one MarbleMap for the same MarbleModel (not yet supported, 108 * but will be soon). 109 */ 110 explicit MarbleMap( MarbleModel *model ); 111 112 ~MarbleMap() override; 113 114 /** 115 * @brief Return the model that this view shows. 116 */ 117 MarbleModel *model() const; 118 119 // Accessors to internal objects; 120 ViewportParams *viewport(); 121 const ViewportParams *viewport() const; 122 123 /** 124 * @brief Get the Projection used for the map 125 * @return @c Spherical a Globe 126 * @return @c Equirectangular a flat map 127 * @return @c Mercator another flat map 128 */ 129 Projection projection() const; 130 131 /** 132 * @brief Get the ID of the current map theme 133 * To ensure that a unique identifier is being used the theme does NOT 134 * get represented by its name but the by relative location of the file 135 * that specifies the theme: 136 * 137 * Example: 138 * maptheme = "earth/bluemarble/bluemarble.dgml" 139 */ 140 QString mapThemeId() const; 141 142 void setMapQualityForViewContext( MapQuality qualityForViewContext, ViewContext viewContext ); 143 MapQuality mapQuality( ViewContext viewContext ) const; 144 145 /** 146 * @brief Return the current map quality. 147 */ 148 MapQuality mapQuality() const; 149 150 void setViewContext( ViewContext viewContext ); 151 ViewContext viewContext() const; 152 153 void setSize( int width, int height ); 154 void setSize( const QSize& size ); 155 QSize size() const; 156 int width() const; 157 int height() const; 158 159 /** 160 * @brief Return the radius of the globe in pixels. 161 */ 162 int radius() const; 163 164 int preferredRadiusCeil(int radius) const; 165 int preferredRadiusFloor(int radius) const; 166 167 int tileZoomLevel() const; 168 169 /** 170 * @brief return the minimum zoom value for the current map theme. 171 */ 172 int minimumZoom() const; 173 174 /** 175 * @brief return the minimum zoom value for the current map theme. 176 */ 177 int maximumZoom() const; 178 179 bool discreteZoom() const; 180 181 /** 182 * @brief Get the screen coordinates corresponding to geographical coordinates in the map. 183 * @param lon the lon coordinate of the requested pixel position 184 * @param lat the lat coordinate of the requested pixel position 185 * @param x the x coordinate of the pixel is returned through this parameter 186 * @param y the y coordinate of the pixel is returned through this parameter 187 * @return @c true if the geographical coordinates are visible on the screen 188 * @c false if the geographical coordinates are not visible on the screen 189 */ 190 bool screenCoordinates( qreal lon, qreal lat, 191 qreal& x, qreal& y ) const; 192 193 /** 194 * @brief Get the earth coordinates corresponding to a pixel in the map. 195 * @param x the x coordinate of the pixel 196 * @param y the y coordinate of the pixel 197 * @param lon the longitude angle is returned through this parameter 198 * @param lat the latitude angle is returned through this parameter 199 * @param unit the angle units 200 * @return @c true if the pixel (x, y) is within the globe 201 * @c false if the pixel (x, y) is outside the globe, i.e. in space. 202 */ 203 bool geoCoordinates( int x, int y, 204 qreal& lon, qreal& lat, 205 GeoDataCoordinates::Unit = GeoDataCoordinates::Degree ) const; 206 207 /** 208 * @brief Return the longitude of the center point. 209 * @return The longitude of the center point in degree. 210 */ 211 qreal centerLongitude() const; 212 213 /** 214 * @brief Return the latitude of the center point. 215 * @return The latitude of the center point in degree. 216 */ 217 qreal centerLatitude() const; 218 219 qreal heading() const; 220 221 /** 222 * @since 0.26.0 223 */ 224 bool hasFeatureAt(const QPoint&) const; 225 226 QVector<const GeoDataFeature *> whichFeatureAt( const QPoint& ) const; 227 228 /** 229 * @brief Return the property value by name. 230 * @return The property value (usually: visibility). 231 */ 232 bool propertyValue( const QString& name ) const; 233 234 /** 235 * @brief Return whether the overview map is visible. 236 * @return The overview map visibility. 237 */ 238 bool showOverviewMap() const; 239 240 /** 241 * @brief Return whether the scale bar is visible. 242 * @return The scale bar visibility. 243 */ 244 bool showScaleBar() const; 245 246 /** 247 * @brief Return whether the compass bar is visible. 248 * @return The compass visibility. 249 */ 250 bool showCompass() const; 251 252 /** 253 * @brief Return whether the cloud cover is visible. 254 * @return The cloud cover visibility. 255 */ 256 bool showClouds() const; 257 258 /** 259 * @brief Return whether the night shadow is visible. 260 * @return visibility of night shadow 261 */ 262 bool showSunShading() const; 263 264 /** 265 * @brief Return whether the city lights are shown instead of the night shadow. 266 * @return visibility of city lights 267 */ 268 bool showCityLights() const; 269 270 /** 271 * @brief Return whether the globe is locked to the sub solar point 272 * @return if globe is locked to sub solar point 273 */ 274 bool isLockedToSubSolarPoint() const; 275 276 /** 277 * @brief Return whether the sun icon is shown in the sub solar point. 278 * @return visibility of the sun icon in the sub solar point 279 */ 280 bool isSubSolarPointIconVisible() const; 281 282 /** 283 * @brief Return whether the atmospheric glow is visible. 284 * @return The cloud cover visibility. 285 */ 286 bool showAtmosphere() const; 287 288 /** 289 * @brief Return whether the crosshairs are visible. 290 * @return The crosshairs' visibility. 291 */ 292 bool showCrosshairs() const; 293 294 /** 295 * @brief Return whether the coordinate grid is visible. 296 * @return The coordinate grid visibility. 297 */ 298 bool showGrid() const; 299 300 /** 301 * @brief Return whether the place marks are visible. 302 * @return The place mark visibility. 303 */ 304 bool showPlaces() const; 305 306 /** 307 * @brief Return whether the city place marks are visible. 308 * @return The city place mark visibility. 309 */ 310 bool showCities() const; 311 312 /** 313 * @brief Return whether the terrain place marks are visible. 314 * @return The terrain place mark visibility. 315 */ 316 bool showTerrain() const; 317 318 /** 319 * @brief Return whether other places are visible. 320 * @return The visibility of other places. 321 */ 322 bool showOtherPlaces() const; 323 324 /** 325 * @brief Return whether the relief is visible. 326 * @return The relief visibility. 327 */ 328 bool showRelief() const; 329 330 /** 331 * @brief Return whether the ice layer is visible. 332 * @return The ice layer visibility. 333 */ 334 bool showIceLayer() const; 335 336 /** 337 * @brief Return whether the borders are visible. 338 * @return The border visibility. 339 */ 340 bool showBorders() const; 341 342 /** 343 * @brief Return whether the rivers are visible. 344 * @return The rivers' visibility. 345 */ 346 bool showRivers() const; 347 348 /** 349 * @brief Return whether the lakes are visible. 350 * @return The lakes' visibility. 351 */ 352 bool showLakes() const; 353 354 /** 355 * @brief Return whether the frame rate gets displayed. 356 * @return the frame rates visibility 357 */ 358 bool showFrameRate() const; 359 360 bool showBackground() const; 361 362 GeoDataRelation::RelationTypes visibleRelationTypes() const; 363 364 /** 365 * @brief Returns the limit in kilobytes of the volatile (in RAM) tile cache. 366 * @return the limit of volatile tile cache in kilobytes. 367 */ 368 quint64 volatileTileCacheLimit() const; 369 370 /** 371 * @brief Returns a list of all RenderPlugins in the model, this includes float items 372 * @return the list of RenderPlugins 373 */ 374 QList<RenderPlugin *> renderPlugins() const; 375 QList<AbstractFloatItem *> floatItems() const; 376 377 /** 378 * @brief Returns a list of all FloatItems in the model 379 * @return the list of the floatItems 380 */ 381 AbstractFloatItem * floatItem( const QString &nameId ) const; 382 383 /** 384 * @brief Returns a list of all DataPlugins on the layer 385 * @return the list of DataPlugins 386 */ 387 QList<AbstractDataPlugin *> dataPlugins() const; 388 389 /** 390 * @brief Returns all widgets of dataPlugins on the position curpos 391 */ 392 QList<AbstractDataPluginItem *> whichItemAt( const QPoint& curpos ) const; 393 394 AngleUnit defaultAngleUnit() const; 395 396 QFont defaultFont() const; 397 398 TextureLayer *textureLayer() const; 399 400 /** 401 * @brief Add a layer to be included in rendering. 402 */ 403 void addLayer( LayerInterface *layer ); 404 405 /** 406 * @brief Adds a texture sublayer 407 * @return Returns a key that identifies the texture sublayer 408 */ 409 QString addTextureLayer(GeoSceneTextureTileDataset *texture); 410 411 /** 412 * @brief Removes a texture sublayer 413 * @param key a key that was returned from corresponding addTextureLayer 414 */ 415 void removeTextureLayer(const QString &key); 416 417 /** 418 * @brief Remove a layer from being included in rendering. 419 */ 420 void removeLayer( LayerInterface *layer ); 421 422 RenderStatus renderStatus() const; 423 424 RenderState renderState() const; 425 426 /** 427 * @since 0.26.0 428 */ 429 const StyleBuilder* styleBuilder() const; 430 431 public Q_SLOTS: 432 433 /** 434 * @brief Paint the map using a give painter. 435 * @param painter The painter to use. 436 * @param dirtyRect the rectangle that actually needs repainting. 437 */ 438 void paint( GeoPainter &painter, const QRect &dirtyRect ); 439 440 /** 441 * @brief Set the radius of the globe in pixels. 442 * @param radius The new globe radius value in pixels. 443 */ 444 void setRadius( int radius ); 445 446 void setHeading( qreal heading ); 447 448 /** 449 * @brief Rotate the view by the two angles phi and theta. 450 * @param deltaLon an angle that specifies the change in terms of longitude 451 * @param deltaLat an angle that specifies the change in terms of latitude 452 * 453 * This function rotates the view by two angles, 454 * deltaLon ("theta") and deltaLat ("phi"). 455 * If we start at (0, 0), the result will be the exact equivalent 456 * of (lon, lat), otherwise the resulting angle will be the sum of 457 * the previous position and the two offsets. 458 */ 459 void rotateBy(qreal deltaLon, qreal deltaLat); 460 461 /** 462 * @brief Center the view on a geographical point 463 * @param lat an angle parallel to the latitude lines 464 * +90(N) - -90(S) 465 * @param lon an angle parallel to the longitude lines 466 * +180(W) - -180(E) 467 */ 468 void centerOn( const qreal lon, const qreal lat ); 469 470 /** 471 * @brief Set the latitude for the center point 472 * @param lat the new value for the latitude in degree 473 */ 474 void setCenterLatitude( qreal lat ); 475 476 /** 477 * @brief Set the longitude for the center point 478 * @param lon the new value for the longitude in degree 479 */ 480 void setCenterLongitude( qreal lon ); 481 482 /** 483 * @brief Set the Projection used for the map 484 * @param projection projection type (e.g. Spherical, Equirectangular, Mercator) 485 */ 486 void setProjection( Projection projection ); 487 488 /** 489 * @brief Set a new map theme 490 * @param maptheme The ID of the new maptheme. To ensure that a unique 491 * identifier is being used the theme does NOT get represented by its 492 * name but the by relative location of the file that specifies the theme: 493 * 494 * Example: 495 * maptheme = "earth/bluemarble/bluemarble.dgml" 496 */ 497 void setMapThemeId( const QString& maptheme ); 498 499 /** 500 * @brief Sets the value of a map theme property 501 * @param name name of the property 502 * @param value value of the property (usually: visibility) 503 * 504 * Later on we might add a "setPropertyType and a QVariant 505 * if needed. 506 */ 507 void setPropertyValue( const QString& name, bool value ); 508 509 /** 510 * @brief Set whether the overview map overlay is visible 511 * @param visible visibility of the overview map 512 */ 513 void setShowOverviewMap( bool visible ); 514 515 /** 516 * @brief Set whether the scale bar overlay is visible 517 * @param visible visibility of the scale bar 518 */ 519 void setShowScaleBar( bool visible ); 520 521 /** 522 * @brief Set whether the compass overlay is visible 523 * @param visible visibility of the compass 524 */ 525 void setShowCompass( bool visible ); 526 527 /** 528 * @brief Set whether the cloud cover is visible 529 * @param visible visibility of the cloud cover 530 */ 531 void setShowClouds( bool visible ); 532 533 /** 534 * @brief Set whether the night shadow is visible. 535 * @param visible visibility of shadow 536 */ 537 void setShowSunShading( bool visible ); 538 539 /** 540 * @brief Set whether city lights instead of night shadow are visible. 541 * @param visible visibility of city lights 542 */ 543 void setShowCityLights( bool visible ); 544 545 /** 546 * @brief Set the globe locked to the sub solar point 547 * @param visible if globe is locked to the sub solar point 548 */ 549 void setLockToSubSolarPoint( bool visible ); 550 551 /** 552 * @brief Set whether the sun icon is shown in the sub solar point 553 * @param visible if the sun icon is shown in the sub solar point 554 */ 555 void setSubSolarPointIconVisible( bool visible ); 556 557 /** 558 * @brief Set whether the is tile is visible 559 * NOTE: This is part of the transitional debug API 560 * and might be subject to changes until Marble 0.8 561 * @param visible visibility of the tile 562 */ 563 void setShowTileId( bool visible ); 564 565 /** 566 * @brief Set whether the atmospheric glow is visible 567 * @param visible visibility of the atmospheric glow 568 */ 569 void setShowAtmosphere( bool visible ); 570 571 /** 572 * @brief Set whether the crosshairs are visible 573 * @param visible visibility of the crosshairs 574 */ 575 void setShowCrosshairs( bool visible ); 576 577 /** 578 * @brief Set whether the coordinate grid overlay is visible 579 * @param visible visibility of the coordinate grid 580 */ 581 void setShowGrid( bool visible ); 582 583 /** 584 * @brief Set whether the place mark overlay is visible 585 * @param visible visibility of the place marks 586 */ 587 void setShowPlaces( bool visible ); 588 589 /** 590 * @brief Set whether the city place mark overlay is visible 591 * @param visible visibility of the city place marks 592 */ 593 void setShowCities( bool visible ); 594 595 /** 596 * @brief Set whether the terrain place mark overlay is visible 597 * @param visible visibility of the terrain place marks 598 */ 599 void setShowTerrain( bool visible ); 600 601 /** 602 * @brief Set whether the other places overlay is visible 603 * @param visible visibility of other places 604 */ 605 void setShowOtherPlaces( bool visible ); 606 607 /** 608 * @brief Set whether the relief is visible 609 * @param visible visibility of the relief 610 */ 611 void setShowRelief( bool visible ); 612 613 /** 614 * @brief Set whether the ice layer is visible 615 * @param visible visibility of the ice layer 616 */ 617 void setShowIceLayer( bool visible ); 618 619 /** 620 * @brief Set whether the borders visible 621 * @param visible visibility of the borders 622 */ 623 void setShowBorders( bool visible ); 624 625 /** 626 * @brief Set whether the rivers are visible 627 * @param visible visibility of the rivers 628 */ 629 void setShowRivers( bool visible ); 630 631 /** 632 * @brief Set whether the lakes are visible 633 * @param visible visibility of the lakes 634 */ 635 void setShowLakes( bool visible ); 636 637 /** 638 * @brief Set whether the frame rate gets shown 639 * @param visible visibility of the frame rate 640 */ 641 void setShowFrameRate( bool visible ); 642 643 void setShowRuntimeTrace( bool visible ); 644 645 bool showRuntimeTrace() const; 646 647 /** 648 * @brief Set whether to enter the debug mode for 649 * polygon node drawing 650 * @param visible visibility of the node debug mode 651 */ 652 void setShowDebugPolygons( bool visible); 653 654 bool showDebugPolygons() const; 655 656 /** 657 * @brief Set whether to enter the debug mode for 658 * visualizing batch rendering 659 * @param visible visibility of the batch rendering 660 */ 661 void setShowDebugBatchRender( bool visible); 662 663 bool showDebugBatchRender() const; 664 665 666 /** 667 * @brief Set whether to enter the debug mode for 668 * placemark drawing 669 * @param visible visibility of the node debug mode 670 */ 671 void setShowDebugPlacemarks(bool visible); 672 673 bool showDebugPlacemarks() const; 674 675 676 /** 677 * @brief Set whether to enter the debug mode for 678 * level tags 679 * @param visible visibility according to OSM level tags 680 */ 681 void setLevelTagDebugModeEnabled(bool visible); 682 683 bool levelTagDebugModeEnabled() const; 684 685 void setDebugLevelTag(int level); 686 687 int debugLevelTag() const; 688 689 690 void setShowBackground( bool visible ); 691 692 void setVisibleRelationTypes(GeoDataRelation::RelationTypes relationTypes); 693 694 /** 695 * @brief used to notify about the position of the mouse click 696 */ 697 void notifyMouseClick( int x, int y ); 698 699 void clearVolatileTileCache(); 700 /** 701 * @brief Set the limit of the volatile (in RAM) tile cache. 702 * @param kiloBytes The limit in kilobytes. 703 */ 704 void setVolatileTileCacheLimit( quint64 kiloBytes ); 705 706 void setDefaultAngleUnit( AngleUnit angleUnit ); 707 708 void setDefaultFont( const QFont& font ); 709 710 /** 711 * @brief Reload the currently displayed map by reloading texture tiles 712 * from the Internet. In the future this should be extended to all 713 * kinds of data which is used in the map. 714 */ 715 void reload(); 716 717 void downloadRegion( QVector<TileCoordsPyramid> const & ); 718 719 void highlightRouteRelation(qint64 osmId, bool enabled); 720 721 Q_SIGNALS: 722 void tileLevelChanged( int level ); 723 724 /** 725 * @brief Signal that the theme has changed 726 * @param theme Name of the new theme. 727 */ 728 void themeChanged( const QString& theme ); 729 730 void projectionChanged( Projection ); 731 732 void radiusChanged( int radius ); 733 734 void mouseMoveGeoPosition( const QString& geoPositionString); 735 736 void mouseClickGeoPosition( qreal lon, qreal lat, GeoDataCoordinates::Unit ); 737 738 void framesPerSecond( qreal fps ); 739 740 /** 741 * This signal is emitted when the repaint of the view was requested. 742 * If available with the @p dirtyRegion which is the region the view will change in. 743 * If dirtyRegion.isEmpty() returns true, the whole viewport has to be repainted. 744 */ 745 void repaintNeeded( const QRegion& dirtyRegion = QRegion() ); 746 747 /** 748 * This signal is emitted when the visible region of the map changes. This typically happens 749 * when the user moves the map around or zooms. 750 */ 751 void visibleLatLonAltBoxChanged( const GeoDataLatLonAltBox& visibleLatLonAltBox ); 752 753 /** 754 * @brief This signal is emit when the settings of a plugin changed. 755 */ 756 void pluginSettingsChanged(); 757 758 /** 759 * @brief Signal that a render item has been initialized 760 */ 761 void renderPluginInitialized( RenderPlugin *renderPlugin ); 762 763 /** 764 * @brief Emitted when the layer rendering status has changed 765 * @param status New render status 766 */ 767 void renderStatusChanged( RenderStatus status ); 768 769 void renderStateChanged( const RenderState &state ); 770 771 void highlightedPlacemarksChanged( qreal, qreal, GeoDataCoordinates::Unit ); 772 773 void viewContextChanged(ViewContext viewContext); 774 775 void visibleRelationTypesChanged(GeoDataRelation::RelationTypes relationTypes); 776 777 protected: 778 779 /** 780 * @brief Enables custom drawing onto the MarbleMap straight after 781 * @brief the globe and before all other layers have been rendered. 782 * @param painter 783 * 784 * @deprecated implement LayerInterface and add it using @p addLayer() 785 */ 786 virtual void customPaint( GeoPainter *painter ); 787 788 private: 789 Q_PRIVATE_SLOT( d, void updateMapTheme() ) 790 Q_PRIVATE_SLOT( d, void updateProperty( const QString &, bool ) ) 791 Q_PRIVATE_SLOT( d, void setDocument(QString) ) 792 Q_PRIVATE_SLOT( d, void updateTileLevel() ) 793 Q_PRIVATE_SLOT(d, void addPlugins()) 794 795 private: 796 Q_DISABLE_COPY( MarbleMap ) 797 MarbleMapPrivate * const d; 798 friend class MarbleMapPrivate; 799 800 class CustomPaintLayer; 801 friend class CustomPaintLayer; 802 }; 803 804 } 805 806 #endif 807