core: add CustomVectorSource for binary tile data delivery

[Vladyslav-Odobesku-Intellias]

Introduces CustomVectorSource — a new source type that lets applications deliver pre-encoded binary tile data (MVT) directly to the rendering pipeline, bypassing the GeoJSON encode/decode round-trip of CustomGeometrySource.

• Core C++ API with fetch/cancel callbacks and async setTileData/setTileError/invalidateTile
• Android/Kotlin platform binding using coroutines for ergonomic async tile fetching
• Actor-based concurrency with cooperative cancellation
• Reuses existing well-tested MVT infrastructure instead of introducing yet one more binary tile data format

Design Proposal

Included in this PR: design-proposals/2025-07-05-custom-vector-source.md

Motivation

Existing options for programmatic tile delivery have limitations:

• URL-based vector sources require HTTP
• CustomGeometrySource operates on GeoJSON (encode/decode overhead), uses bounding-box requests (unclear tile semantics), and manages its own threadpool (vs. Kotlin suspendible aka coroutines)

CustomVectorSource fills the gap for applications that generate tiles on-device, decode from proprietary archives, or stream over non-HTTP transports.

Here is the description of what problem we are solving by introducing such data source. Newer Google Maps SDK provides tile data through GRPC service. That service is launched along the app as a separate process and simply serves tiles through GRPC in its` own format that resembles vector tiles. We cannot request it to service tiles through GRPC + in the vector tiles format. So we need to adapt it. Proposed interface declares a simple interface for the tile data provider to implement.

interface CustomVectorTileProvider {
    suspend fun fetchTile(z: Int, x: Int, y: Int): TileData
}

It everything. Only says that this function is suspendable (coroutine) and under the hood it can be anything - some exotic HTTP tile service or as in our case some GRPC service. For us to now adapt such GRPC service to MapLibre is just about implementing CustomVectorTileProvider by doing a suspendable call to GRPC, which will naturally be suspended and then transform data from one binary format to vector tiles.

Check it yourself
This change also adds one entry to the test scenarios of the android demo app. It simply injects trivial CustomGeometrySource that provides cross tile data (2 lines that form a cross) and sets the style of those lines to be red.

AI Disclosure

AI assistance (Claude) was used for drafting the design proposal document and PR description. All code and architectural decisions are human-authored.

[sjg-wdw]

Thoughts @TimSylvester @alexcristici @adrian-cojocaru ?

[github-actions]

Bloaty Results 🐋

Compared to main

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.5%  +876Ki  +0.4%  +145Ki    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4377-compared-to-main.txt

Compared to d387090 (legacy)

    FILE SIZE        VM SIZE    
 --------------  -------------- 
   +55% +64.1Mi  +474% +28.3Mi    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4377-compared-to-legacy.txt

[github-actions]

Benchmark Results ⚡

Benchmark                                                          Time             CPU      Time Old      Time New       CPU Old       CPU New
-----------------------------------------------------------------------------------------------------------------------------------------------
OVERALL_GEOMEAN                                                 -0.0002         -0.0002             0             0             0             0

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/benchmark-results/pr-4377-compared-to-main.txt

[Vladyslav-Odobesku-Intellias]

@louwers I've removed mentions of GRPC.

• I've made design proposal to sound more generic.
  As for the reasoning and description of how did we come up needing such custom source I've instead put it into this pull request description so that it does not pollute the design doc.

[louwers]

@Vladyslav-Odobesku-Intellias

We will discuss this during the Technical Steering Comittee Meeting tomorrow, 7:30PM CEST.

Do you want to join? If so, please e-mail team@maplibre.org and I will send you an invite.

[louwers]

Hi @Vladyslav-Odobesku-Intellias could you merge in main? That should resolve the CI issue.

Also there is a merge conflict.

[github-actions]

Bloaty Results (iOS) 🐋

Compared to main

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +0.3% +51.1Ki  +0.3% +48.0Ki    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results-ios/pr-4377-compared-to-main.txt

[Vladyslav-Odobesku-Intellias]

Hi @Vladyslav-Odobesku-Intellias could you merge in main? That should resolve the CI issue.

Also there is a merge conflict.

done, all green