Skip to content

feat!: support enableBufferObjects and add requiredGeometryCapabilities - #293

Merged
nmfisher merged 18 commits into
developfrom
fix/editable-vertex-buffer-updates
Aug 26, 2026
Merged

feat!: support enableBufferObjects and add requiredGeometryCapabilities#293
nmfisher merged 18 commits into
developfrom
fix/editable-vertex-buffer-updates

Conversation

@nmfisher

@nmfisher nmfisher commented Aug 26, 2026

Copy link
Copy Markdown
Owner

A Filament VertexBuffer uses either:

  • Direct attribute-stream (slot) storage via VertexBuffer::setBufferAt, or
  • a separate BufferObject enabled via VertexBuffer::Builder::enableBufferObjects() and attached with VertexBuffer::setBufferObjectAt, allowing streams to be shared or swapped without rebuilding the vertex buffer.

The storage model is fixed when the vertex buffer is created, but Filament currently provides no API for querying it afterward.

This PR therefore exposes BufferObject and VertexBufferBuilder.enableBufferObjects() for low-level procedural geometry. Thermion records the storage model when a buffer is created or exposed through an asset, and reports it through VertexBuffer.storageMode.

This PR also replaces VertexBufferMode with geometry requirements. Callers describe the geometry properties they require rather than selecting a particular reconstruction strategy:

  final asset = await viewer.loadGltf(
    path,
    requiredGeometryCapabilities: const {
      SceneAssetGeometryCapability.writableVertices,
      SceneAssetGeometryCapability.preservedTopology,
    },
  );

  final actualCapabilities = asset.geometryCapabilities;
  final canUseFlatShading = asset.supportsFlatShading;

The available geometry capabilities are:

  • writableVertices: vertex streams can be updated through VertexBuffer.setBufferAt
  • accessibleGeometryBuffers: Thermion exposes reusable vertex and index buffers
  • preservedTopology: source vertex order and triangle indices are preserved
  • barycentrics: triangle-corner barycentric coordinates are available
  • uniqueTriangleCorners: every triangle corner has a distinct vertex

The loader resolves requirements as follows:

  • An empty set retains gltfio’s original geometry and makes no additional geometry guarantees.
  • writableVertices, preservedTopology, or accessibleGeometryBuffers alone selects a topology-preserving, directly writable representation.
  • barycentrics or uniqueTriangleCorners selects an unwelded, BufferObject-backed representation.
  • accessibleGeometryBuffers can also be combined with unwelded requirements because both reconstructed representations expose their geometry buffers.
  • writableVertices or preservedTopology cannot be combined with barycentrics or uniqueTriangleCorners.
  • The loader may provide a compatible superset of the requested capabilities.
  • Loading fails if the requested capabilities cannot be provided consistently across the asset’s applicable primitives.

Flat shading is intentionally not a geometry capability. It is a rendering operation supported by the unwelded representation and can be queried independently through ThermionAsset.supportsFlatShading. .

The resulting public responsibilities are distinct:

  • SceneAssetGeometryCapability describes required and guaranteed geometry properties.
  • ThermionAsset.supportsFlatShading reports support for the flat-shading operation.
  • VertexBuffer.storageMode describes how an individual buffer is populated or updated: direct, bufferObjects, or unknown.
  • Geometry reconstruction and the choice of internal representation remain loader implementation details.

@nmfisher nmfisher changed the title fix: make editable glTF vertex buffers writable feat!: support enableBufferObjects and add requiredGeometryCapabilities Aug 26, 2026
@nmfisher
nmfisher merged commit cfbb9be into develop Aug 26, 2026
@nmfisher
nmfisher deleted the fix/editable-vertex-buffer-updates branch August 26, 2026 14:25
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