What does the “Compatible with Lumen Card Sharing” flag do, and when should it be used?
I see this flag available on Materials and Material Instances, but I can’t any documentation that explains it’s usage
2026-02-27_12-17-33.jpg(16.8 KB)
Steps to Reproduce
Open any Material
Search in the Details Panel for “Lumen”
Hi there!
Lumen card sharing was added in CL#40533274 added support for Lumen card sharing between instances. r.LumenScene.SurfaceCache.AllowCardSharing (on by default)
There are two types of sharing:
1) downsampling from self when a card lowers resolution,
2) copying or downsampling from another matching card.
Downsampling from self is enabled by default as it is a pretty safe optimization (0.03 ms reduction on average LumenSceneUpdate cost).
Sharing between different cards is disabled by default due to potential material attribute variation across instances. There is code to auto detect card sharing eligibility but the detection is very conservative. Using any of the following material nodes will disable sharing: PerInstanceRandom, PerInstanceCustomData, WorldPosition, and ActorPositionWS. Sharing can be force enabled via the “Compatible with Lumen Card Sharing” material flag. The flag can be overridden in material instances. To force enable card sharing for a component, all materials applied on the component need to have the flag set. Sharing is only supported between Nanite mesh instances currently.
In testing with card sharing enabled for all Nanite instances in the Witcher demo with matching meshes and materials (best case scenario, equivalent to having the flag set for all materials) gave another 0.07 ms average cost saving on top of the 0.03 ms from self downsampling. In the demo, materials on large mountain rocks and trees were definitely good (if not the best) candidates. Another thing worth noting is that auto detection didn’t help in the demo so we needed to enable the material flag to get savings. We enabled the flag aggressively but carefully to ensure there were no problems in the Lumen scene visualizer. The card pages are constantly refreshed in a LRU fashion (r.LumenScene.SurfaceCache.CardCaptureRefreshFraction) so even if cards get incorrect data from sharing, they will get cleaned up over time.
r.Lumen.Visualize 22 was added for visualizing card sharing Meshes with valid IDs are colorized with random colors derived from their IDs. If they have invalid IDs (i.e. sharing disabled), it shows them with darkened albedo.
If auto detection is not enabled (r.LumenScene.SurfaceCache.DetectCardSharingCompatibility 0), nothing will share cards except for those that are told to share explicitly via the Material flag.
Note there is one issue to be aware of:
The wrong emissive value may be used on Nanite objects with custom primitive data when Lumen card sharing is enabled.
Thank you so much [mention removed], that answers my question