Skip to main content

Rendering and cameras

A viewport is what draws; a camera is what decides from where. This page covers the camera model, the three map types it can be in, and the specialized viewports that behave differently enough to be worth knowing about before you pick one.

For the render loop itself — Render(), HasPendingUpdates(), and which calls belong on the main thread — see Architecture and Threading and lifecycle. For the coordinate frames every camera method works in, see Coordinate systems.

The camera​

IMcMapCamera is a virtual observer above the terrain. Its frame is what the viewport shows, and everything you do to navigate a map is a camera operation:

To do thisUse
Move to an absolute positionSetCameraPosition()
Move relative to where the camera is pointingMoveCameraRelativeToOrientation(), ScrollCamera()
Aim by anglesSetCameraOrientation() — yaw, pitch, roll
Aim at a place on the groundSetCameraLookAtPoint()
Orbit a positionRotateCameraAroundWorldPoint()
ZoomSetCameraScale(), SetCameraFieldOfView()
Fit a known extentSetCameraWorldVisibleArea(), SetCameraScreenVisibleArea()
Find out what is in viewGetCameraFootprint(), GetCameraWorldVisibleArea(), IsInCameraWorldVisibleArea()

Cameras are not constructed directly and are not released by you: the viewport creates and owns them. The ownership rules are in Threading and lifecycle.

IMcMapViewport inherits IMcMapCamera and forwards every camera method to the active camera, so a single-camera application never has to touch a camera pointer — call the methods above on the viewport. A viewport can hold several cameras: create with CreateCamera(), switch with SetActiveCamera(), and remove with DestroyCamera(). AddCameraUpdateCallback() fires both when the active camera is updated and when the viewport's active camera is changed, which is the hook for keeping a coordinate readout or a linked view in step — note that a SetActiveCamera() switch triggers it just as movement does.

Camera scale is not map scale​

SetCameraScale() and GetCameraScale() work in world units per display pixel — meters of ground per pixel, for a metric coordinate system. Cartographic "map scale" is the ratio of a ground distance to a distance on the physical display, which is a different quantity.

To convert, use the physical height of a display pixel from IMcMapViewport::GetPixelPhysicalHeight():

  • map scale → camera scale: multiply the map scale by the pixel's physical height.
  • camera scale → map scale: divide the camera scale by the pixel's physical height.

Getting this backwards produces a map that is wrong by a constant factor on every display, which is easy to miss during development on one monitor.

2D, 3D and anchored images​

GetMapType() reports which of two map types a camera is in, and the difference is larger than it looks.

EMT_2D — a flat map viewed from directly above. Yaw is the only orientation angle that applies, and it is the map's rotation: RotateCameraAroundWorldPoint() uses yaw alone here, and SetCameraUpVector() applies the yaw of the up vector's horizontal projection as the rotation angle. So the navigation model is scrolling, zooming and rotation.

EMT_3D — a perspective or orthographic view of terrain with real elevation. All three angles apply. Which of the two projections you get depends on the field of view: a non-zero field of view gives a perspective projection, and zero gives a parallel (orthographic) one. That switch matters more than its size, because several camera methods behave differently on each. The two to know:

  • ScrollCamera() and SetCameraWorldVisibleArea() are rejected on a perspective-projection 3D camera with IMcErrors::VIEWPORT_MAP_TYPE_MISMATCH. A parallel-projection camera accepts both.
  • SetCameraScale() and GetCameraScale() work on both. They are not rejected on a perspective camera — it simply makes the world-point argument mandatory, since a perspective camera's scale is only meaningful at a stated point. For a parallel camera that argument is ignored.

Anchored images are the case worth flagging. An anchored image — "oriented imagery" — is a geographically anchored perspective sensor image, supplied with a camera model from the IMcImageCalc hierarchy that converts between image pixels and ground coordinates. It is an EMT_2D map, but in it the camera's position, look-at, visible-area and screen-conversion methods work in image coordinates rather than world coordinates: pixels of the source image, origin at its bottom-left, y growing upward. Scale is in original image pixels per viewport pixel. Code written for a regular 2D map will compile against an anchored-image map and produce nonsense, so check the map type before reusing navigation code across both.

Attachments​

SetCameraAttachment() binds the camera's position, and optionally its orientation or look-at point, to an object or item — the mechanism behind following a moving track. Two things to know:

  • While an attachment is active, most position and orientation setters are silently ignored. They return IMcErrors::SUCCESS without changing anything. The affected methods say so individually, but the failure mode is a camera that will not move and an API that reports success. Clear the attachment first.
  • If the call fails, the previous attachment has already been removed and is not restored.

On 2D maps the look-at attachment argument is ignored. The camera holds a reference to the attached objects for as long as the attachment exists.

Specialized viewports​

Two viewport types do something a plain viewport does not. Each derives from IMcMapViewport and is created by its own factory method rather than by configuring a regular viewport.

Heat map​

Interface for heat map viewport.

A heat map viewport accumulates user-supplied weighted points (see UpdateHeatMapPoints()) into per-pixel sum and (optionally) count buffers, and can present the normalized result as a picture covering the viewport.

Used for:

  • Creating it: CreateHeatMap(), whose parameters are read back with IsHeatMapAverageCalculatedPerPoint() and IsHeatMapPictureShown().
  • Feeding it: UpdateHeatMapPoints() with SHeatMapPoint values.
  • Reading values back: per pixel (GetHeatMapPixelNormalizedValue(), GetHeatMapPixelSumValue() and GetHeatMapPixelCountValue()), as whole buffers (GetHeatMapNormalizedBuffer(), GetHeatMapSumBuffer() and GetHeatMapCountBuffer()) and as the un-normalized range (GetHeatMapUnNormalizedMinMaxValue()).
  • Shaping the picture: SetHeatMapMinThresholdValues() and SetHeatMapMaxThresholdValues() decide how the accumulated values map to what is shown; SetHeatMapDrawPriority() and SetHeatMapVisibility() decide where and whether it is drawn.

Note: A heat map viewport is always a 2D map viewport (CreateHeatMap() fails if SCreateData::eMapType is not IMcMapCamera::EMT_2D).

See also: IMcMapViewport, IMcSpatialQueries::CastToHeatMapViewport()

— from Map/IMcHeatMapViewport.h

Vertical section​

Interface for vertical section map viewport.

This is a 2D viewport that shows a terrain vertical section passing through given route points: the section's x axis runs along the route and its y axis is the height. The heights come from the terrains, either calculated when the viewport is created or supplied by the application.

Used for:

  • Creating it: CreateSection() with the route points and, optionally, precomputed height points.
  • Changing the section: SetSectionRoutePoints() / GetSectionRoutePoints(), SetAxesRatio() / GetAxesRatio() for the vertical exaggeration, and SetSectionPolygonItem() / GetSectionPolygonItem() for the polygon item whose line and fill colors draw the section.
  • Relating the section to the map: SectionToWorld() and WorldToSection() convert between section and world coordinates, GetSectionHeightAtPoint() gives the section height at a distance along the route, and GetHeightLimits() the height range over an interval of it.

See also: IMcMapViewport, IMcSpatialQueries::CastToSectionMapViewport()

— from Map/IMcSectionMapViewport.h

The global map​

The global map is not a third viewport type. IMcMapViewport inherits IMcGlobalMap, so every viewport already carries these methods, and a viewport becomes an overview inset by being given local maps to represent rather than by being created differently.

Interface for the global map role of a viewport (inherited by IMcMapViewport).

A global map shows the footprints of the local map viewports registered in it and allows navigating those viewports by editing their footprints on the global map. Any regular 2D viewport created with an overlay manager can serve as one: RegisterLocalMap() refuses 3D, anchored-image and section viewports, and viewports without an overlay manager.

Used for:

  • Registering the viewports to represent: RegisterLocalMap(), UnRegisterLocalMap() and GetRegisteredLocalMaps(); SetActiveLocalMap() / GetActiveLocalMap() select the local map whose movements the global map follows while SetGlobalMapAutoCenterMode() is on.
  • The footprint drawing: SetLocalMapFootprintItem() / GetLocalMapFootprintItem() supply the line and icon items the footprints are drawn with, for one local map or as the default for all of them, and GetLocalMapFootprintScreenPositions() reports where a footprint lies on the global map's screen.
  • Interaction: OnMouseEvent() feeds the user's mouse events in (EMouseEvent) and reports the cursor to show (ECursorType) and whether a render is needed.

See also: IMcMapViewport

— from Map/IMcGlobalMap.h

The global map viewport itself has requirements, and they are easy to trip over because they are about how you created it rather than what you call on it. It must be a regular 2D viewport — RegisterLocalMap() returns IMcErrors::VIEWPORT_MAP_TYPE_MISMATCH on a 3D, anchored-image or section viewport — and it must have been created with an overlay manager, or the call returns IMcErrors::NO_OVERLAY_MANAGER. Neither can be fixed after creation.

Verified against MapCore 12.5.0

Written from Map/IMcMapCamera.h, Map/IMcMapViewport.h, Map/IMcHeatMapViewport.h, Map/IMcSectionMapViewport.h, Map/IMcGlobalMap.h