Detailed Description

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.

Data Structures
struct	dwMapProviderParameters
	Parameters for the provider determining preallocation. More...

struct	dwMapsContentLayerBuffer
	Caller-provided buffer for content layers. More...

struct	dwMapsRoute
	Defines a planned route for an ordered sequence of waypoints. More...

Typedefs
typedef struct dwMapsContentLayerObject const *	dwConstMapsContentLayerHandle_t
	Forward declaration of content layer handle. More...

typedef struct dwMapProviderObject const *	dwConstMapsProviderHandle_t

typedef struct dwMapProviderObject *	dwMapProviderHandle_t

typedef uint64_t	dwMapsRequestToken
	Token for retrieval of requested maps from the provider. More...

Functions
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...

Data Structure Documentation

◆ 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

struct dwMapsRoute

Data Fields
size_t	waypointCount	Number of waypoints in the planned route.
dwMapsGeoPoint *	waypoints	Sequence of waypoints defining the planned route.

Typedef Documentation

◆ dwConstMapsContentLayerHandle_t

typedef struct dwMapsContentLayerObject const* dwConstMapsContentLayerHandle_t

Forward declaration of content layer handle.

Definition at line 160 of file MapProvider.h.

◆ dwConstMapsProviderHandle_t

typedef struct dwMapProviderObject const* dwConstMapsProviderHandle_t

Definition at line 78 of file MapProvider.h.

◆ dwMapProviderHandle_t

typedef struct dwMapProviderObject* dwMapProviderHandle_t

Definition at line 77 of file MapProvider.h.

◆ dwMapsRequestToken

typedef uint64_t dwMapsRequestToken

Token for retrieval of requested maps from the provider.

Definition at line 92 of file MapProvider.h.

Function Documentation

◆ dwMapProvider_getContentLayer()

DW_API_PUBLIC dwStatus dwMapProvider_getContentLayer	(	dwConstMapsContentLayerHandle_t *	layer,
		const char *	layerId,
		dwConstMapsProviderHandle_t	providerHandle
	)

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()

DW_API_PUBLIC dwStatus dwMapProvider_getContentLayers	(	dwMapsContentLayerBuffer *	layers,
		dwConstMapsProviderHandle_t	providerHandle
	)

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()

DW_API_PUBLIC dwStatus dwMapProvider_getCoverageBounds	(	dwMapsBounds *	bounds,
		dwMapProviderHandle_t	providerHandle
	)

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()

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.

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()

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.

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()

DW_API_PUBLIC dwStatus dwMapProvider_release ( dwMapProviderHandle_t providerHandle )

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()

DW_API_PUBLIC dwStatus dwMapProvider_releaseMap	(	dwConstMapHandle_t	mapHandle,
		dwMapProviderHandle_t	providerHandle
	)

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()

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.

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()

DW_API_PUBLIC dwStatus dwMapProvider_requestMapForRoute	(	dwMapsRequestToken *	requestToken,
		const dwMapsRoute *	route,
		const dwMapsContentLayerBuffer *	layers,
		dwMapProviderHandle_t	providerHandle
	)

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()

DW_API_PUBLIC dwStatus dwMapProvider_tryGetRequestedMap	(	dwConstMapHandle_t *	mapHandle,
		dwMapsRequestToken	requestToken,
		dwMapProviderHandle_t	providerHandle
	)

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

Detailed Description

Data Structures

Typedefs

Functions

Data Structure Documentation

◆ dwMapProviderParameters

◆ dwMapsContentLayerBuffer

◆ dwMapsRoute

Typedef Documentation

◆ dwConstMapsContentLayerHandle_t

◆ dwConstMapsProviderHandle_t

◆ dwMapProviderHandle_t

◆ dwMapsRequestToken

Function Documentation

◆ dwMapProvider_getContentLayer()

◆ dwMapProvider_getContentLayers()

◆ dwMapProvider_getCoverageBounds()

◆ dwMapProvider_initializeWithCacheFile()

◆ dwMapProvider_initializeWithDirectory()

◆ dwMapProvider_release()

◆ dwMapProvider_releaseMap()

◆ dwMapProvider_requestMapForBounds()

◆ dwMapProvider_requestMapForRoute()

◆ dwMapProvider_tryGetRequestedMap()