GitLab

gltfpack: Implement support for KHR_materials_variants

To make sure that all variants can be used interchangeably we need to
make sure that whenever multiple materials can be used on a given mesh,
the quantization grid for these materials matches.

Since multiple meshes can use a single material as well, this means that
multiple materials can be bound by the same quantization rules even if
they are never used on the same mesh, for example:

	mesh 0: materials 0, 1
	mesh 1: materials 2, 3
	mesh 2: materials 0, 3

Here all 4 materials must use the same quantization settings even though
materials 1 & 2 never overlap; to make all 3 meshes render correctly we
need to use the common quantization for all 3 meshes for all 4
materials.

To make this work, we use union-find to find a single "canonical"
material for each source mesh & material; we use that slot to accumulate
UV bounds and then redistribute the resulting quantization parameters to
all relevant materials.

When a mesh uses multiple materials through the use of variants, we need
to make sure that the quantization parameters for UV for a given
material incorporate all meshes that refer to it, including variants.

In addition, when processing a mesh, we need to take all variant
requirements into account, so that e.g. if only one material needs a
second UV set, we still include it even if it's a variant.

This isn't quite correct in cases when materials are used in other
meshes as well, since we need to ensure that the quantization data is
the same across all materials.

Instead of merging materials across meshes, we find unique materials
first by going just through the material list, and then simply remap
mesh materials and variants.

This has a slightly different complexity - from O(meshes * materials) to
O(materials^2) - however, assuming each material is used by at least one
mesh in the source data, the resulting algorithm is still faster.

We were previously emitting the same material mapping for all primitives
in a batch.

This change implements basic support for material variants. Each mesh
now keeps track of a set of material mappings; mesh merging is limited
to cases when the variant set is the same, and all material variants are
preserved.

Since we don't correctly compute the UV bounds for variant materials,
this only works without quantization so far.

This adds support to KHR_materials_variants, stored as an array of
mapping pairs.

gltfpack: Add support for KHR_materials_volume

This extension is in draft but the specification is reasonably complete.
This change adds support for the extension as well as fixing a bug with
KHR_materials_specular writing.

This change is https://github.com/jkuhlmann/cgltf/pull/133 with an extra
float.h include to keep the code compiling.

gltfpack: Update KHR_materials_specular to match new draft

Instead of implementing separate queries for texture transform & texture
set, this change centralizes querying of material requirements in
analyzeMaterials and calls it once before mesh processing.

This allows us to also fold the image type classification into the same
function, which makes adding new material extensions less fragile, and
additionally fixes a corner cases where tangent information could be
removed from meshes that had clearcoat normal map without a regular
normal map.

image/basis and .basis aren't standard per glTF spec; when support for
using Basis encoding directly was removed, two conditions were missed
that are now redundant.

This change adjusts the implementation of KHR_materials_specular; the
last update to the specification split the single texture (RGB+A) into
two separate texture slots (RGB + A). This requires associated changes
to handle the case when these are separate.

The cgltf change is using this PR:
https://github.com/jkuhlmann/cgltf/pull/131

image/basis and .basis aren't standard per glTF spec; when support for
using Basis encoding directly was removed, two conditions were missed
that are now redundant.

indexgenerator: Implement support for triangle adjacency index buffers

This code is identical and self-sufficient so it's easy to extract.
Building the edge table is more specialized due to the need for storing
the opposite vertex, and the hasher along with other data is necessary
during lookup, so it's better to leave that duplicated for now.

Several algorithms that use geometry shaders to render data require
adjacency information; triangle-with-adjacency topology in various APIs
provides a way to supply 3 extra vertices per each triangle that
represent vertices opposite to each triangle's edge.

This data can then be used to compute silhouettes and perform other
types of local geometric processing.

This change implements the data preprocessing step that is similar to
the previous tessellation IB - but instead of storing vertices that
adjoin the triangle from the opposite side, we need to store
complementary / opposite vertices of adjacent triangles, which requires
a separate temporary table.

indexgenerator: Implement support for PN-AEN tessellation buffers

To render a mesh with normal/UV seams using hardware tessellation, the
PN-triangles method is not sufficient as it produces cracks on normal
discontinuities (position displacement based on normal is not consistent
along both sides of the seam), and displacement mapping uses slightly
different texture samples which results in cracks along UV seams.

In 2010, NVidia proposed a PN-AEN tessellation scheme that fixes the
problem around normal discontinuities by using opposite edge normals and
averaging the resulting control point data. In 2011, NVidia proposed a
further tweak on top of this technique that allows to select the
"dominant" edge by choosing the min. edge index out of the
current/adjacent edges, and using the UV data from that edge on the
patch edges to sample the displacement data. For corners, there can be
more than two wedges that have the same position, so you need to store
the dominant vertex for each patch corner as well.

As a result, generating a 12-vertex patch for each input triangle allows
to use the hardware tessellation engine to implement PN-AEN (using 9
vertices) and/or displacement mapping (using 3 more vertices) without
cracks.

This change implements the data preprocessing step for this algorithm as
meshopt_generateTessellationIndexBuffer; this index buffer can be
directly fed to the GPU along with the requisite hull/domain shaders.

For implementing the shader code, the following papers are recommended:

John McDonald, Mark Kilgard
Crack-Free Point-Normal Triangles using Adjacent Edge Normals. 2010

John McDonald
Tessellation on Any Budget. 2010

Bryan Dudash
My Tessellation Has Cracks! 2012

Add a note about meshopt_decoder.module.js when using Three.js

While in most cases we overallocate the hash tables as the number of
elements we supply is an upper bound that's never reached, it's possible
to create meshes that do reach that bound by having a power of two count
of vertices and have all vertices be unique.

To avoid catastrophic performance degradation of hash-based algorithms
on such meshes we make sure that we have ~20% of elements free, which
means that our expected chain length is reasonably short in all cases.

Note: this isn't motivated by a specific example, but is merely done as
a precaution.

gltfpack: Fix CI build for files with spaces

A recently introduced Box With Spaces isn't xargs-friendly.

Add reference to Debian and Ubuntu packages

gltfpack: Properly handle KHR_texture_transform extension

These are now unified in a single generic materialHasProperty function
so that we need to add new material extensions in fewer places.

When -noq is used we still may need to preserve KHR_texture_transform in
extensionsUsed if it was used in the source scene in one of the
materials.

Reflow some code examples to make them easier to read

This change corrects simplification examples following the updates to the interfaces and adds information about the resulting error.

clusterizer: Rework meshlet interface to use SoA results

This is valuable for consistency and in case the triangle data is read
in groups of 4 bytes.

Realistically the expected number of triangles for a 64-vertex meshlet
is under 100 (8x8 vertex grid => 7x7 quad grid => 98 triangles), but for
documentation purposes make sure we're staying under the limit
recommended by NVidia - triangle indices are allocated in 128 byte chunks
and 4 bytes are reserved for the count, so 124 is more optimal than 128.

This makes sure that our output is deterministic as it doesn't contain
uninitialized values.

This is a bit inconsistent with computeClusterBounds but makes more
sense in meshlet context where triangle_count is used instead of
index_count consistently.

Fixes MSVC type conversion and clang 'unused variable' warnings.