Usage guidelines

_|

This page covers recommended usage guidelines for the Maps SDK for C++. Following these practices helps ensure code reliability and prevents common integration pitfalls.

Working with images

Images in the SDK are represented as abstract objects, not directly drawable on the UI. The relevant classes are Image, AbstractGeometryImage, LaneImage, SignpostImage, and RoadInfoImage.

These classes provide the following methods and getters:

• getUid: Returns the unique ID of the image. If two images are the same, then they have the same UID. This allows the user to optimize UI redraws and trigger an update only when the image changes.
• isValid: Returns whether the image data is valid. If invalid, both getRenderableImageBytes and getRenderableImage return null.
• exportAs: Returns a DataBuffer containing the binary representation of the image in the requested format. A specialized method (exportAs) also supports exporting directly to a file path.

Plain images

The Image class corresponds to plain (typically non-vector) images. These images have a recommended size and aspect ratio but can be resized to any dimension in order to be drawn (with possible loss of quality).

An Image can be instantiated in the following ways:

• Via the constructor that accepts a DataBuffer with image data and format.
• Using one of the predefined IDs from the images::Core enum.
• By providing a path to an image file on disk (e.g., .jpg, .png, .bmp).

Special images

The AbstractGeometryImage, LaneImage, SignpostImage, and RoadInfoImage classes correspond to vector images generated by the SDK based on internal data. They provide customizable options for rendering. They do not have a default size or aspect ratio.

The LaneImage, SignpostImage, and RoadInfoImage classes might be best displayed at a particular aspect ratio depending on the image content. To render the images at a suitable size, provide a IBitmap implementation accordingly. Rendering will always be done at the size specified by the user (the resulting image might be distorted).

The particularities of each image type are presented in the table below:

Class	Size and aspect ratio	Customizable render options	Instantiable by the user
Image	Usually fixed and retrievable via the getSize and getAspectRatio getters.	Not available	Yes, via the provided constructors. It can be also provided by the SDK.
AbstractGeometryImage	Generated by the SDK. Size and aspect ratio not retrievable.	Yes, via AbstractGeometryImageRenderSettings	No. Can only be provided by the SDK.
LaneImage	Generated by the SDK. Size and aspect ratio not retrievable.	Yes, via LaneImageRenderSettings	No. Can only be provided by the SDK.
SignpostImage	Generated by the SDK. Size and aspect ratio not retrievable.	Yes, via SignpostImageRenderSettings	No. Can only be provided by the SDK.
RoadInfoImage	Generated by the SDK. Size and aspect ratio not retrievable.	Background color customizable via Rgba	No. Can only be provided by the SDK.

Do not extend the classes provided by the SDK

The SDK is designed to deliver all necessary functionalities in an intuitive and straightforward manner. Avoid extending any of the Maps SDK for C++ classes. Use the callback methods provided by the SDK for seamless integration.

Check the error code

Many methods return error codes that indicate the outcome of the operation. Ensure that all failure cases are handled appropriately to maintain code robustness and prevent unexpected behavior.

The gem::error namespace defines the possible values corresponding to the outcome of an operation. The following values indicate successful outcomes:

• gem::KNoError: The operation completed successfully.
• gem::error::KReducedResult: The operation completed successfully, but only a subset of the results was returned.
• gem::error::KScheduled: The operation has been scheduled for execution at a later time.

Other SDK methods might result in failure in certain cases (if the system runs out of memory for example), even if they don't return a error value. In this cases, the error code can be obtained via the GET_GEM_API_ERROR() macro. After each operation the error code can be consulted in the following way:

// Any SDK call...
int error = GET_GEM_API_ERROR();
if (error == gem::KNoError) GEM_INFO_LOG("The last operation succeeded.");
else GEM_INFO_LOG("The last operation failed with error: %d", error);

warning

Make sure to check the error code using the GET_GEM_API_ERROR() macro immediately after the operation completes. Delaying this check could result in other SDK operations being executed, which might overwrite the error code.

Units of measurement

The SDK primarily uses SI units for measurements, including:

• Meter (distance).
• Second (time).
• Kilogram (mass).
• Meters per second (speed).
• Watts for power (consumption).

The length value and measurement unit used in TTS (text-to-speech) instructions, such as "After 150 meters, bear left," are determined by the unit system configured through the SdkSettings().setUnitSystem setter.

warning

In certain cases, other units of measurement are used as they are better suited. For instance, the height, length and width fields of the TruckProfile class are measured in centimeters. These exceptions are clearly indicated in the API reference.

Provide SDK logs when reporting issues

Native level logs

There are also logs at the native code level (C++). These logs events can be intercepted using an own implementation of IApiCallLogger. The logs granularity can be configured using by overriding onGetLogLevel method.

In order to add a new entry to the native logs, use the Debug().log method. Check GEM_INFO_LOG macro on how to call it.

Only the logs with a level equal to or higher than the configured level will be delivered.

Please provide native logs when reporting issues.

warning

The logs may contain sensitive information, so review them before sharing publicly.

Other useful information

When submitting a bug report, include the following to help with diagnosis:

• A clear, concise description of the issue.
• Steps to reproduce, including a minimal code sample where possible.
• Expected versus actual behavior.
• Screenshots or videos, if applicable.
• SDK version in use.
• Platform details (OS, version, device model).
• Console logs captured during the issue.
• Geographical location, if relevant (e.g., for routing, navigation, or search issues).
• Any other context that may assist in resolving the problem.

Additionally, ensure you are running the latest SDK version, as newer releases often include bug fixes and performance improvements.

Legal requirements

Certain features, such as police and speed camera reports, may be restricted or prohibited by law in some jurisdictions. Ensure that the safety overlay and the corresponding entries in socialReports overlay are disabled where applicable. Additionally, restrict the availability of the SocialOverlay features based on local regulations.

The Magic Lane Maps SDK for C++ utilizes data from OpenStreetMap. Ensure proper attribution in accordance with the OpenStreetMap license.

Any use or display of Wikipedia content must include appropriate attribution as outlined in the Reusers' rights and obligations section of Wikipedia's copyright guidelines.