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 this | Use |
|---|---|
| Move to an absolute position | SetCameraPosition() |
| Move relative to where the camera is pointing | MoveCameraRelativeToOrientation(), ScrollCamera() |
| Aim by angles | SetCameraOrientation() — yaw, pitch, roll |
| Aim at a place on the ground | SetCameraLookAtPoint() |
| Orbit a position | RotateCameraAroundWorldPoint() |
| Zoom | SetCameraScale(), SetCameraFieldOfView() |
| Fit a known extent | SetCameraWorldVisibleArea(), SetCameraScreenVisibleArea() |
| Find out what is in view | GetCameraFootprint(), 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()andSetCameraWorldVisibleArea()are rejected on a perspective-projection 3D camera withIMcErrors::VIEWPORT_MAP_TYPE_MISMATCH. A parallel-projection camera accepts both.SetCameraScale()andGetCameraScale()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::SUCCESSwithout 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.