Map-wide memory usage hints

LuciadCPillar exposes configurable suggestions on how much CPU and GPU memory it should use at most. This can prevent the application from using more memory than is available on the system, possibly resulting in a crash. If you experience such behavior, try reducing both CPU and GPU memory from the default values. Alternatively, if memory is abundant, pushing those values higher can improve caching efficiency.

By default, these limits are 500 MB for CPU memory and 2000 MB for GPU memory (VRAM). You can provide your own limits when creating your mapcreating your mapcreating your map.

Program: Customizing the memory usage hints
auto map = Map::newBuilder()
               .maxMemoryUsageHint(2000, 4000) // 2000 MB CPU, 4000 MB GPU
               .build();
var map = Map.NewBuilder()
    .MaxMemoryUsageHint(2000, 4000) // 2000 MB CPU, 4000 MB GPU
    .Build();
var map = Map.newBuilder()
    .maxMemoryUsageHint(2000, 4000) // 2000 MB CPU, 4000 MB GPU
    .build();

These hints only apply to internal data managed by the map, not to any user data present in the rest of the application.

Load balancing mechanism

LuciadCPillar employs a load balancing mechanism to try and stay below the suggested limits.

  • The memory budget is distributed over the layers in your map.

  • The distribution happens automatically and continuously.

  • The distribution can be uneven, so layers that use more data are assigned a bigger portion of the memory budget.

  • Each layer attempts to restrict its memory usage to its allocated portion.

    • Layers start by removing cached data to reach the limit.

    • If they’re still over budget, some layers will reduce their quality or amount of data loaded. If they do so, they will log this clearly.

Optimizing memory usage on constrained hardware

It may be necessary to lower LuciadCPillar’s memory usage hints below the default to better reflect a device’s capabilities. To get the most out of a tighter memory budget, you can also fine-tune the settings below. These settings allow you to choose where the resources are allocated, based on what matters most for your use case: