Skip to content

feat: Add render hooks to Painter for external render passes#7099

Open
cavencj wants to merge 21 commits intomaplibre:mainfrom
dvt3d:main
Open

feat: Add render hooks to Painter for external render passes#7099
cavencj wants to merge 21 commits intomaplibre:mainfrom
dvt3d:main

Conversation

@cavencj
Copy link
Copy Markdown

@cavencj cavencj commented Feb 10, 2026

Some advanced integrations require executing external rendering logic at specific points in the render pipeline. While custom layers provide a flexible extension mechanism, they are rendered as part of the layer-based pipeline and cannot be inserted at arbitrary render pass boundaries.

This PR introduces a lightweight render hook mechanism to Painter that allows external rendering logic to be executed at well-defined points in the render pipeline, without modifying the existing layer system or render order.
The goal is to enable advanced integrations (e.g. external renderers, custom GPU passes, Three.js) while keeping the core render flow intact and easy to maintain.

What’s added

A small, synchronous render hook API on Painter

Four hook phases aligned with the existing render passes:

  • beforeOpaque

  • afterOpaque

  • beforeTranslucent

  • afterTranslucent

Hooks receive the active Painter instance and current RenderOptions

No existing rendering logic is changed; hooks are executed strictly in addition to the current pipeline.

@codecov
Copy link
Copy Markdown

codecov bot commented Feb 10, 2026

Codecov Report

❌ Patch coverage is 50.00000% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.58%. Comparing base (b814996) to head (6b29908).
⚠️ Report is 34 commits behind head on main.

Files with missing lines Patch % Lines
src/render/painter.ts 50.00% 8 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #7099      +/-   ##
==========================================
- Coverage   92.61%   92.58%   -0.03%     
==========================================
  Files         289      289              
  Lines       24010    24026      +16     
  Branches     5085     5087       +2     
==========================================
+ Hits        22237    22245       +8     
- Misses       1773     1781       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@cavencj cavencj changed the title ADD: Add render hooks to Painter for external render passes feat: Add render hooks to Painter for external render passes Feb 10, 2026
@HarelM
Copy link
Copy Markdown
Collaborator

HarelM commented Feb 10, 2026

Thanks for taking the time to open this PR!
painter in not really part of the public API, the Map class is usually where things are configured/registered.
I would also recommend adding an example of how to use these hooks in the examples folder. It would also help to get some more context on a problem that this solves that can't be solved otherwise, or the alternative is a lot more complicated.
Also some tests would be great to cover the new code.
I think the changes are minimal and powerful at the same time, which is good.
What will happen on contextlost event when I think the painter is destroyed? Should there be a warning printed to console like we do for custom layers?
Thanks!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants