Add a vector layer
The base interface for vector layers, displaying their vector items as MapCore objects held in an overlay.
A vector layer displays its vector items as MapCore objects held in an overlay of the map device's overlay manager. The overlay is created when the layer's terrain is added to a viewport, so the layer becomes "initialized" only then (see IMcMapLayer::IsInitialized()); until then the state, draw-priority, brightness and collision-prevention setters only store the values and return IMcErrors::SUCCESS, and the matching getters return the stored values. It is inherited by IMcNativeVectorMapLayer (data converted to MapCore's format, in a directory or behind a URL), IMcRawVectorMapLayer (a GDAL/OGR data source read as is) and IMcNativeServerVectorMapLayer (MapCore's Map Layer Server); there is no web-service vector layer.
Used for:
- State: SetOverlayState() and GetOverlayState() for the whole overlay, SetVectorItemObjectState() and GetVectorItemObjectState() for one vector item's object (the state selects the versions of the objects' properties to be used).
- Draw priority: SetOverlayDrawPriority() and GetOverlayDrawPriority() (the overlay's priority relative to the objects' overlays); SetDrawPriorityConsistency() and GetDrawPriorityConsistency().
- Brightness: SetBrightness() and GetBrightness(), in all viewports or in one of them.
- Collision prevention: SetCollisionPrevention() and GetCollisionPrevention() (labels not hiding each other).
- Tolerance for point: SetToleranceForPoint() and GetToleranceForPoint().
- Layer parameters: IsLiteVectorLayer() and GetMinMaxSizeFactor().
- The vector data: GetGeometryType(), GetLayerAttributes() and GetLayerDataSources(); the item IDs with VectorItemIDToOriginalID() and VectorItemIDFromOriginalID(); the fields with GetNumFields(), GetFieldData() and GetValidFieldsPerDataSource(); the items with GetVectorItemsCount(), GetVectorItemPoints(), GetScanExtendedData(), the GetFieldUniqueValuesAsXxx() and GetVectorItemFieldValueAsXxx() families and Query().
- Extended geometry data: GetExtendedGeometryDataSize() and LoadExtendedGeometryDataToMemory().
- Everything a map layer does, as IMcMapLayer (through the member-less IMcVectorBasedMapLayer): visibility, coordinate system and bounding box, ID and user data, tiles and levels of detail, saving and loading, type and casting.
Note: The data-query methods GetVectorItemPoints(), GetScanExtendedData(), the GetFieldUniqueValuesAsXxx() and GetVectorItemFieldValueAsXxx() families and Query() accept an optional IMcMapLayer::IAsyncOperationCallback. MapCore never takes ownership of the callback: the caller must keep it alive until the result is delivered and destroy it afterwards. The callback is never invoked when the method itself returns an error. Its effect depends on the layer type:
- On a native-server layer (see IMcNativeServerVectorMapLayer) the callback is mandatory: the query is sent to the server, the method returns IMcErrors::SUCCESS once the request was issued, and the result and its status arrive later in the callback. Without a callback such a layer returns IMcErrors::SYNC_OPERATION_ON_NATIVE_SERVER_LAYER.
- On any other layer the query is always performed synchronously. When a callback is passed, the result and its status are reported through the callback, the output parameters are emptied and the method itself returns IMcErrors::SUCCESS. Without a callback the result is returned through the output parameters and its status is the method's return value.
— from Map/IMcVectorMapLayer.h
That first sentence is the one to hold on to. A vector layer is not drawn like a raster layer — it becomes objects in an overlay, which is why so much of its behaviour is expressed in the vocabulary of the overlay manager, and why its initialisation is different from every other layer's.
Initialisation is different here
A raster or elevation layer is initialised when its data has been read. A vector layer is initialised when its terrain has been added to a viewport, because that is when the overlay holding its objects is created.
Until then, the setters below — state, draw priority, brightness, collision prevention — do not
fail. They store the value and return IMcErrors::SUCCESS, the matching getters return what was
stored, and everything is applied when initialisation happens. So configuring a layer immediately
after creating it is legal and is usually what you want. What you cannot do early is query it: the
data methods need the loaded data and return IMcErrors::NOT_INITIALIZED.
Choose the interface
| Interface | Reads from | Create() takes |
|---|---|---|
IMcNativeVectorMapLayer | Data converted to MapCore's format, in a directory or behind a URL | a directory or URL |
IMcRawVectorMapLayer | A GDAL/OGR data source, unconverted | IMcRawVectorMapLayer::SParams |
IMcNativeServerVectorMapLayer | MapCore's Map Layer Server | a layer URL |
There is no web-service vector layer: WMS, WMTS and WCS serve pixels and coverages, not features.
Two variants cut across that table and both restrict what the rest of this page applies to:
- A 'lite' layer is a native layer converted that way. It holds no per-item MapCore object, so
per-item state cannot be overridden on it.
IsLiteVectorLayer()reports it. - A rasterized layer is a raw layer whose data source name begins with
MAPNIK:followed by the path of a styling sheet. It renders its data into raster tiles instead of into objects, and most of the interface is then either a no-op returning success with an empty result or returnsIMcErrors::NOT_IMPLEMENTED.IsRasterizedVectorLayer()reports it. It is also the only kind of raw vector layer that supports a local cache — asking for one on any other raw vector layer returnsIMcErrors::NOT_IMPLEMENTED.
Create the layer
Converted data
IMcNativeVectorMapLayer *pLayer = NULL;
IMcErrors::ECode eCode = IMcNativeVectorMapLayer::Create(&pLayer, "C:/maps/roads");
As elsewhere, strDirectory may be a URL and loading is then deferred.
Raw data
IMcRawVectorMapLayer::Create() opens the data source synchronously, so a successful return
means the layer is ready. IMcRawVectorMapLayer::SParams is the largest parameter struct in the
layer family; the fields divide into four groups.
What to read:
| Field | Notes |
|---|---|
strDataSource | A raw file (.shp, .mdb, …), an XML file, or a PostGIS layer. Required |
pSourceCoordinateSystem | Required unless the data source carries its own |
pClipRect | Optional clip, in the source's coordinate system, x and y only. NULL, all-zero or all-DBL_MAX means no clipping |
strLocaleStr | Locale for string handling; NULL or empty uses the current one |
A multi-layer data source opens only its first sub-layer unless you append a suffix to
strDataSource. To find out what is in one, call the static
IMcRawVectorMapLayer::GetDataSourceSubLayersProperties() before creating the layer — it opens and
closes the source itself and returns one SDataSourceSubLayerProperties per sub-layer with its
index, name, geometry, item count, and the strMultiGeometriesSuffix to append. It works for every
multi-layer format except XML, PG: (PostGIS) and SDE:.
How it is displayed:
| Field | Notes |
|---|---|
fMinScale, fMaxScale | Scale range. Considered only when fMinScale < fMaxScale; not relevant for XML sources |
strPointTextureFile | Texture for a point layer; also the default texture under internal styling |
dSimplificationTolerance | Line and polygon simplification in map units. Default 0, no simplification |
Performance — the four fields that decide whether a large layer is usable:
| Field | Default | Effect |
|---|---|---|
uMaxNumVerticesPerTile | 100000 | Above this, objects that fit a child tile move down into it. Higher favours zoom-in, lower favours zoom-out; UINT_MAX disables |
uMaxNumVisiblePointObjectsPerTile | 5000 | Point objects beyond this are hidden depending on scale; UINT_MAX disables |
uMinPixelSizeForObjectVisibility | 8 | Lines and polygons smaller than this in pixels are hidden depending on scale; 0 disables |
fOptimizationMinScale | 0 | Below this scale the two hiding optimisations are not applied at all. FLT_MAX disables them entirely |
Styling — covered next.
GetCreateParams() reads the parameters back along with the target coordinate system and tiling
scheme, as a shallow copy pointing at layer-owned memory.
From a Map Layer Server
IMcNativeServerVectorMapLayer::Create() takes a layer URL containing a /. This layer holds no
vector data of its own, which has a consequence you cannot design around: every data query must be
made asynchronously. See Query the data.
Styling
A converted layer carries its styling with it. A raw layer has to be told, through
SParams::eAutoStylingType:
| Value | What it does |
|---|---|
EAST_INTERNAL | Build MapCore schemes from the source's own styling. The default |
EAST_NONE | No automatic styling — MapCore's default schemes for the source's geometry |
EAST_S52 | MapCore's predefined styling for S52/S57 |
EAST_CUSTOM | Your own: a folder of styling XMLs and MapCore object schemes, named by strCustomStylingFolder |
None of this applies when strDataSource is an XML file, which already is a styling description.
EAST_INTERNAL is the interesting one, because it can consume external style sheets as well as the
source's own. SInternalStylingParams::strStylingFile accepts SLD (.sld), ArcGIS LYRX
(.lyrx), and MapLibre (.json); leave it NULL and the data source's internal styling is used,
which currently means KML and KMZ. Either way MapCore generates an XML file and a Schemes folder:
| Field | Notes |
|---|---|
strOutputFolder | Where to write them. NULL uses the data source's folder |
strOutputXMLFileName | Name of the generated XML. NULL derives it from the data source name |
eVersion | Compatibility of the generated schemes with older MapCore releases. Default IMcOverlayManager::ESVC_LATEST — no compatibility |
fMaxScaleFactor | Caps the overlay manager's scale factor for this layer. Default 1 |
pDefaultFont | Used where the styling defines no font. With an IMcLogFont it also supplies parameters the styling omits |
fTextMaxScale | Largest scale at which text is drawn. Default FLT_MAX |
That generation step is worth knowing about: styling a raw layer writes files next to your data
unless you point strOutputFolder somewhere else. GetStylingParams() reads the parameters back —
and returns NULL with success on a rasterized layer, which has none.
Adjust the appearance
These act on the layer's overlay, and all of them may be called before initialisation.
Draw priority. By default a vector layer draws above all raster layers and below the objects'
overlays, ordered among similar layers by its terrain's priority and its own.
SetOverlayDrawPriority(true, nPriority) moves it into the object overlays' ordering at the
priority you give. The two other priorities that interact with it are
IMcMapViewport::SetTerrainDrawPriority() and IMcMapTerrain::SetLayerParams().
SetDrawPriorityConsistency() makes symbolic items of equal priority in layers of equal priority
draw in a consistent order. It is off by default, and the header's own guidance is precise about the
trade-off: it can degrade performance when many items share a draw priority, and it is recommended
where there are many overlaps between same-priority items of significantly different colours.
Brightness. SetBrightness() takes −1 to 1: an offset added to every colour component, 0
unchanged, 1 white, −1 black. Per viewport or, with NULL, for all of them. Once the layer is
initialised, GetBrightness() derives its answer from the colour override actually in effect, so it
can differ from what you set if something changed the override meanwhile.
Collision prevention. SetCollisionPrevention() stops labels hiding one another. Off by default.
Size factors. GetMinMaxSizeFactor() reports the bounds set at conversion time (always 1 for a
raw layer). They clamp the factor applied by IMcOverlayManager::SetItemSizeFactors() when it is
called for vector items.
Object state
Vector items are objects, so they have object state — the mechanism that selects which version of
each property is used. Set it for the whole layer with SetOverlayState(), either as one sub-state
or as an array of them, per viewport or for all viewports.
When state is an array, the version used for a property is the one from the first sub-state that
defines it; when no sub-state defines it, the zero-state version is used. Passing NULL with a
count of 0 resets to the zero state, and repeating a sub-state in the array is an error
(IMcErrors::ID_ALREADY_EXISTS).
SetVectorItemObjectState() overrides that for one item by ID. The override is stored by the layer
and reapplied whenever the item's object is recreated. Setting it for all viewports removes any
per-viewport overrides of that item, and passing NULL for the array removes the override. It is
not available on a 'lite' layer, which has no per-item object to carry it —
IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYER.
Query the data
Five of the calls below take an optional IMcMapLayer::IAsyncOperationCallback, and only these
five: GetVectorItemPoints(), GetScanExtendedData(), Query(), and the
GetFieldUniqueValuesAs…() and GetVectorItemFieldValueAs…() families. Everything else on this page
is synchronous with no callback parameter at all.
For those five, the same call behaves differently depending on the layer:
- On a native-server layer the asynchronous callback is mandatory. The query goes to the
server, the method returns success once the request is issued, and the result arrives in the
callback. Without a callback you get
IMcErrors::SYNC_OPERATION_ON_NATIVE_SERVER_LAYER. - On any other layer the query is always synchronous. Without a callback the result comes back
through the output parameters and the return value is its status. With one, the result is
reported through the callback, the output parameters are left empty, and the method returns
IMcErrors::SUCCESSregardless.
MapCore never takes ownership of the callback: keep it alive until the result is delivered, then destroy it. It is never invoked if the method itself returns an error.
What is in the layer
GetVectorItemsCount() counts the items. GetGeometryType() reports the geometry, or
UnSupportedGeometry — with success — for a multi-source layer whose sources disagree, and for a
rasterized layer.
GetLayerDataSources() returns two parallel arrays, data-source names and IDs.
GetLayerAttributes() returns layer-level attribute names and values, which currently exist only
for .pc layers — do not confuse them with fields, which belong to items.
Fields
Fields are the per-item metadata. They exist on raw layers, and on native layers only if they were
converted with metadata; asking a native layer that was not gets
IMcErrors::ACTIVE_VECTOR_LAYER_NOT_FOUND.
GetNumFields() counts them across every data source and GetFieldData() gives one field's name
and EFieldType by index. On a multi-source layer, GetValidFieldsPerDataSource() narrows that to
the fields valid for one source, which you identify by one of its item IDs, its name
(case-insensitive) or its ID.
Reading values is typed rather than variant: GetVectorItemFieldValueAsInt(), …AsDouble(),
…AsString() and …AsWString() for one item's field, and GetFieldUniqueValuesAsInt(),
…AsDouble(), …AsString() and …AsWString() for every distinct value of a field — which is what
you want for building a filter UI. When these are delivered through the callback instead,
EVectorFieldReturnedType tells the callback which type it is holding.
Filtering
Query() takes an SQL WHERE clause over field values and returns the matching item IDs:
CMcDataArray<UINT64> auItemsID;
pLayer->Query("\"Road Class\" = 'motorway' OR Lanes > 3", &auItemsID);
Quote a field name containing spaces with ", and quote string values with '. Every data source
of the layer is queried and the results unified.
Geometry
GetVectorItemPoints() returns an item's points in world coordinates, as one array per part — more
than one only for a multi-line or multi-polygon. The layer must be initialised.
GetScanExtendedData() belongs with IMcSpatialQueries::ScanInGeometry(). A scan reports one
target per vector item, but an item can be a unification of several original ones: a
multi-geometry, a polygon with holes, or the line unification a 'lite' layer performs. This call
splits that target back into the original items, returning one SVectorItemFound each with the
range of the unified point array it covers.
IDs are composite on a multi-source layer. VectorItemIDToOriginalID() splits a MapCore item ID
into the source's own ID plus the data source's name and ID, and VectorItemIDFromOriginalID()
reverses it. On a single-source layer the two IDs are equal and the data-source ID is zero.
Speeding up geometry access on native layers
GetVectorItemPoints() and GetScanExtendedData() read a native layer's geometry from file on every
call. LoadExtendedGeometryDataToMemory() loads that file once and keeps it, and
GetExtendedGeometryDataSize() tells you what that will cost in bytes — check it first if memory is
tight. Both are no-ops returning success on any other layer type, and on a native layer converted
without geometry data. The size call is what opens the geometry file, so it is also the cheapest way
to find out whether the layer has any.
3D extrusion
IMcVector3DExtrusionMapLayer builds volumes from vector contours — buildings from footprints.
It derives from both IMcVectorBasedMapLayer and IMcStaticObjectsMapLayer, and it behaves far
more like the latter: its output is static objects, addressed by object ID, not vector items
addressed by item ID. It is documented with the other static-object layers in
Add static objects.
IMcVectorBasedMapLayer itself has no members. It exists so that
IMcMapLayer::CastToVectorBasedMapLayer() can identify "a layer built from vector data", covering
both the vector layers and the extrusion layers.
3D models
IMc3DModelMapLayer holds meshes converted from a 3D source rather than anything extruded from
vector geometry, so despite the visual similarity it shares no API with vector layers. See
Add static objects.
Error codes
| Code | Cause |
|---|---|
IMcErrors::NOT_INITIALIZED | The layer's terrain is not in a viewport yet, or its data has not loaded |
IMcErrors::NO_OVERLAY | Initialised, but the layer has no overlay |
IMcErrors::NO_OVERLAY_MANAGER | The overlay is not in an overlay manager |
IMcErrors::NOT_THE_SAME_OVERLAY_MANAGER | The viewport belongs to a different overlay manager |
IMcErrors::THE_PROPERTY_CANT_BE_SET_PER_VIEWPORT | A per-viewport state change would alter a property version an object defines for all viewports |
IMcErrors::SYNC_OPERATION_ON_NATIVE_SERVER_LAYER | A data query on a native-server layer without a callback |
IMcErrors::ACTIVE_VECTOR_LAYER_NOT_FOUND | The data source could not be opened, or a native layer was converted without metadata |
IMcErrors::NOT_SUPPORTED_FOR_THIS_LAYER | Per-item state on a 'lite' layer |
IMcErrors::NOT_IMPLEMENTED | A rasterized layer, an unsupported local cache, or a build without HTTP support |
IMcErrors::ID_NOT_FOUND | The item or data source was not found, or no geometry data is held for it |
IMcErrors::ID_ALREADY_EXISTS | A sub-state array repeats a sub-state |
IMcErrors::LOCALE_NOT_FOUND | strLocaleStr is not a locale the system supports (Windows only) |
IMcErrors::MAPLAYER_FILE_WITHOUT_COORDINATE_SYSTEM | The data source carries no coordinate system and none was supplied |
IMcErrors::COORDINATES_NOT_CONVERTED | The source's area could not be converted to the target coordinate system |
IMcErrors::CANNOT_ALLOC_BUFFER | The extended-geometry buffer could not be allocated |