Skip to content

opacitymap: Documentation and tweaks#1029

Merged
zeux merged 12 commits intomasterfrom
omm-exp
Mar 14, 2026
Merged

opacitymap: Documentation and tweaks#1029
zeux merged 12 commits intomasterfrom
omm-exp

Conversation

@zeux
Copy link
Owner

@zeux zeux commented Mar 13, 2026

  • Change levels[] type to unsigned char*; we only need ~4 bits of data and levels can never be negative
  • Compaction now preserves special indices so it can be called multiple times on the same data
  • Remove PreferredMip for now; it works fine but it complicates the interface somewhat and it can be non-trivial to use in some cases; we might add it back as is if there's demand for it but for now it seems easier to recommend fixed-mip downsampling as a quality-time tradeoff.
  • Add extensive header and manual documentation

This contribution is sponsored by Valve.

zeux added 11 commits March 11, 2026 21:31
Add meshopt_opacityMap* functions to experimental list
The comments should now be sufficient to use all of the functions; after
measure, the user is responsble for doing the micromap entry layout
whereas compact does it automatically, which is perhaps a little
confusing, but other alternatives seem worse.
Add opacity micromap documentation.
Fix a few typos and a few logical issues in the code samples.
Add a note about index/meshlet compression adjusting the corner order.

For meshlet compression, this might be revised in the future via changes
to `optimizeMeshlet`, but for now it's required to compress/decompress
these too.
Wrap code samples to avoid vertical scrolling.
Improve wording.
For subdivision levels of OMM entries, we only need a 0..12 range, and
we don't need any sentinel values; even if source triangles need to be
marked as invalid in the future, this can be done via special indices
instead of invalid levels in the OMM level list.
While measure doesn't generate any special indices, it's possible to use
compaction multiple times; for example, in some cases it might be
preferable to always compact within the mesh, and then compact a group
of meshes - which would previously fail because the input OMM indices
would be negative. We now support this transparently which makes
compaction idempotent.
While triangle-adaptive mips for rasterization work reasonably well, in
practice fixed mips are a better tool for reducing the time OMM data
takes to generate - because reducing the mip resolution globally also
saves most of the texture loading/decompression time too. At the same
time, it's not fully clear if rasterizing from mip data requires
adjusting the threshold.

We might add this function back in the future more or less as is, but
for now in the spirit of minimal viable functionality, the caller can
decide which mip to use when instead of meshopt having a preference.
Remove mentions of preferred mip and adjust the recommendation to use
mip 0 for 4-state OMMs or mips 1/2 for 2-state or if the input texture
is higher resolution.
@zeux zeux marked this pull request as ready for review March 14, 2026 15:37
0.75 is derived from the fact that edge length is ~1.5 sqrt(uvarea) for
equilateral triangles, but it was not obvious from the code.
@zeux zeux merged commit f6ab3ec into master Mar 14, 2026
13 checks passed
@zeux zeux deleted the omm-exp branch March 14, 2026 16:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant