Interface for asynchronous map retrieval.
- Note
- SW Release Applicability: These APIs are available in NVIDIA DRIVE Software releases.
The map provider is designed to service requests for map data per bounds or route query. This is required to enable "address to address" scenarios including dynamic routing.
The backend for map retrieval is abstracted away from the application. Initialization of the map provider instance should be the only implementation-specific method required.
To avoid runtime memory allocations, a pool of preallocated map objects is created at initialization time. Map requests are service using map objects acquired from this pool.
The map provider backend may also provide access to content layers representing map elements that are optional and/or memory-intensive. This constrasts directly with the core layer of the map that is fully loaded in-memory, i.e. lanes and road segments.
Supported content layer types initially include localization images and point clouds.
In the future, more complex heterogeneous objects such as wait conditions with features will be represented via content layers including cross-layer depedencies.
Content layers are accessed via the content slice interface, which uses a local layout as the key to asynchronously load and serve data-intensive content layers.
See ContentLayers.h for details on supported layer types and content slice methods.
|
DW_API_PUBLIC dwStatus | dwMapProvider_getContentLayer (dwConstMapsContentLayerHandle_t *layer, const char *layerId, dwConstMapsProviderHandle_t providerHandle) |
| Get content layer by identifier from the map provider. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_getContentLayers (dwMapsContentLayerBuffer *layers, dwConstMapsProviderHandle_t providerHandle) |
| Get all available content layers from the map provider. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_getCoverageBounds (dwMapsBounds *bounds, dwMapProviderHandle_t providerHandle) |
| Get the bounds of coverage for the map provider. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_initializeWithCacheFile (dwMapProviderHandle_t *providerHandle, const char *mapCacheFile, dwMapProviderParameters *params, dwContextHandle_t contextHandle) |
| Create a map provider backed by a map cache file in the local filesystem. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_initializeWithDirectory (dwMapProviderHandle_t *providerHandle, const char *mapDirectory, dwMapProviderParameters *params, dwContextHandle_t contextHandle) |
| Create a map provider backed by a map directory in the local filesystem. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_release (dwMapProviderHandle_t providerHandle) |
| Release map provider. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_releaseMap (dwConstMapHandle_t mapHandle, dwMapProviderHandle_t providerHandle) |
| Releases a requested map back to original map provider. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_requestMapForBounds (dwMapsRequestToken *requestToken, const dwMapsBounds *bounds, const dwMapsContentLayerBuffer *layers, dwMapProviderHandle_t providerHandle) |
| Requests a map covering a specified geographic bounds. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_requestMapForRoute (dwMapsRequestToken *requestToken, const dwMapsRoute *route, const dwMapsContentLayerBuffer *layers, dwMapProviderHandle_t providerHandle) |
| Requests a map covering a planned route. More...
|
|
DW_API_PUBLIC dwStatus | dwMapProvider_tryGetRequestedMap (dwConstMapHandle_t *mapHandle, dwMapsRequestToken requestToken, dwMapProviderHandle_t providerHandle) |
| Attempts to get a requested map with a request token. More...
|
|
◆ dwMapProviderParameters
struct dwMapProviderParameters |
Data Fields |
size_t |
numAllocatedMaps |
Number of maps to allocate for requests. |
size_t |
totalMapAllocationBytes |
Total memory available for requests. |
◆ dwMapsContentLayerBuffer
struct dwMapsContentLayerBuffer |
Data Fields |
dwConstMapsContentLayerHandle_t * |
buffer |
pointer to layers array |
size_t |
maxSize |
maximum number of layers that fit into the buffer |
size_t |
size |
current number of layers in the buffer |
◆ dwMapsRoute
Data Fields |
size_t |
waypointCount |
Number of waypoints in the planned route. |
dwMapsGeoPoint * |
waypoints |
Sequence of waypoints defining the planned route. |
◆ dwConstMapsContentLayerHandle_t
Forward declaration of content layer handle.
Definition at line 160 of file MapProvider.h.
◆ dwConstMapsProviderHandle_t
◆ dwMapProviderHandle_t
◆ dwMapsRequestToken
Token for retrieval of requested maps from the provider.
Definition at line 92 of file MapProvider.h.
◆ dwMapProvider_getContentLayer()
Get content layer by identifier from the map provider.
- Parameters
-
[out] | layer | Handle to the returned content layer |
[in] | layerId | Identifier for the desired layer |
[in] | providerHandle | Map provider handle |
- Returns
- DW_SUCCESS Layer with the provided ID was retrieved
DW_NOT_AVAILABLE Layer with the provided ID is not available
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_getContentLayers()
Get all available content layers from the map provider.
- Parameters
-
[out] | layers | Buffer to contain returned content layers |
[in] | providerHandle | Map provider handle |
- Returns
- DW_SUCCESS Layers were retrieved
DW_NOT_AVAILABLE No layers are available
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_getCoverageBounds()
Get the bounds of coverage for the map provider.
This indicates the "requestable region" per map provider implementation.
Map requests outside this region will always fail and the success of requests inside this bounds is not guaranteed. This method provides a "shortcut" to predict when it will not be possible for a map request to be fulfilled.
- Parameters
-
[out] | bounds | Bounds of the map provider coverage |
[in] | providerHandle | Map provider handle |
- Returns
- DW_SUCCESS bounds were retrieved
DW_NOT_AVAILABLE bounds could not be retrieved
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_initializeWithCacheFile()
Create a map provider backed by a map cache file in the local filesystem.
- Parameters
-
[in,out] | providerHandle | Pointer to provider handle to be initialized |
[in] | mapCacheFile | Cache file containing the map |
[in] | params | Parameters for map allocation |
[in] | contextHandle | Handle to DriveWorks SDK context |
- Returns
- DW_SUCCESS provider handle is successfully initialized
DW_INVALID_ARGUMENT mapCacheFile is nullptr
DW_FILE_NOT_FOUND mapCacheFile does not exist
DW_NOT_AVAILABLE mapCacheFile does not contain a valid map
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_initializeWithDirectory()
Create a map provider backed by a map directory in the local filesystem.
- Parameters
-
[in,out] | providerHandle | Pointer to provider handle to be initialized |
[in] | mapDirectory | Directory containing the map |
[in] | params | Parameters for map allocation |
[in] | contextHandle | Handle to DriveWorks SDK context |
- Returns
- DW_SUCCESS provider handle is successfully initialized
DW_INVALID_ARGUMENT mapDirectory is nullptr
DW_FILE_NOT_FOUND mapDirectory does not exist
DW_NOT_AVAILABLE mapDirectory does not contain a valid map
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_release()
Release map provider.
- Parameters
-
[in] | providerHandle | Map provider handle to be released |
- Returns
- DW_SUCCESS Successfully released map provider object and handle.
DW_INVALID_ARGUMENT providerHandle is nullptr.
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_releaseMap()
Releases a requested map back to original map provider.
- Parameters
-
[in] | mapHandle | Map handle to return. |
[in] | providerHandle | Original provider for the returned map. |
- Returns
- DW_SUCCESS Successfully released the map.
DW_FAILURE Map handle could not be released.
DW_BAD_CAST Could not successfully cast handle to map provider
◆ dwMapProvider_requestMapForBounds()
Requests a map covering a specified geographic bounds.
Bounds requests should be used when a planned route is not known at request time. The retrieved map may be used directly for route planning, but significant download and storage overhead may be expected for associated content layers.
- Parameters
-
[out] | requestToken | Token issued for the map request. |
[in] | bounds | Geographic bounds for the map request. |
[in] | layers | Layers to obtain for the request. If this is NULL no layers are requested. |
[in] | providerHandle | Provider for the map request. |
- Returns
- DW_SUCCESS Successfully issued a map request.
DW_INVALID_ARGUMENT bounds or requestToken are nullptr
DW_BAD_CAST Could not successfully cast handle to map provider
DW_BUFFER_FULL No preallocated maps are available for the request
DW_NOT_AVAILABLE Map coverage is not available for the requested bounds
◆ dwMapProvider_requestMapForRoute()
Requests a map covering a planned route.
Route requests may be used instead of bounds requests whenever a planned route is known at request time. This enables the system to efficiently get only the map data required to cover the planned route.
- Parameters
-
[out] | requestToken | Token issued for the request. |
[in] | route | Requested route for map coverage. |
[in] | layers | Layers to obtain for the request. If this is NULL no layers are requested. |
[in] | providerHandle | Provider for the map request. |
- Returns
- DW_SUCCESS Successfully issue a map request.
DW_INVALID_ARGUMENT Request token was invalid or previously used.
DW_BAD_CAST Could not successfully cast handle to map provider
DW_BUFFER_FULL No preallocated maps are available for the request
DW_NOT_AVAILABLE Map coverage is not available for the requested route
◆ dwMapProvider_tryGetRequestedMap()
Attempts to get a requested map with a request token.
- Parameters
-
[out] | mapHandle | Pointer to handle for requested map. |
[in] | requestToken | Token issued for the request. |
[in] | providerHandle | Provider for the map request. |
- Returns
- DW_SUCCESS Successfully obtained the requested map
DW_INVALID_ARGUMENT Request token was invalid or previously used
DW_NOT_READY Requested map is not yet available
DW_BAD_CAST Could not successfully cast handle to map provider