[FEATURE] Engine-owned visual vertex buffer (set_vverts / get_vverts API)

[duburcqa]

Summary

Adds vverts_state to KinematicSolver as the single engine-side ground truth for per-frame world-space visual vertex positions. Surfaces set_vverts / get_vverts at solver, entity, and vgeom levels. Rasterizer picks up user overrides via a lazy migration to per-env vertex-buffer rendering; collision/sdf rendering is unchanged.

This is the renderer half. PR #2769 (visual-mesh raycasting) rebases on top of this — its kernel_copy_custom_vverts and parallel _custom_vverts buffer go away because vverts_state is now the engine-level buffer everyone reads.

Supersedes the closed #2768 by relocating the buffer from KinematicEntity to the solver.

Design

• vverts_state.pos: gs.qd_vec3, (n_vverts_, B) — populated by kernel_update_all_vverts (vgeom-pose × init_pos) in KinematicSolver.update_vgeoms.
• vverts_info.is_custom: gs.qd_int — flips to 1 for entries written by set_vverts. FK skips them so user data survives step().
• KinematicOptions.batch_vverts_info: bool = False (mirrors batch_links_info / batch_dofs_info / batch_joints_info). When True, the whole vverts_info struct gains a B dimension; without it, partial envs_idx on set_vverts raises.
• set_vverts(verts, envs_idx=None) / get_vverts(envs_idx=None) at KinematicSolver, KinematicEntity, Vgeom. vverts=None clears. Plane entities are refused.
• Rasterizer: non-custom entities keep the existing instancing path. Entities with any custom vvert migrate to per-env pyrender nodes that re-upload from vverts_state.pos each frame. Clear migrates back; the restored render is byte-identical to baseline.
• Zero-copy on set_vverts when supported; warns once per build on non-zero-copy backends and uses a fallback kernel.

Test plan

• tests/test_render.py::test_set_vverts[False-RASTERIZER] and [True-RASTERIZER] cover the API + render path end-to-end (round-trip, broadcast forms, get-returns-copy, vgeom-level write, Plane refusal, migration back, partial-envs error for unbatched, mixed user/FK envs for batched).
• Reviewers verify the vverts_info batching change doesn't break existing consumers (only one in genesis/vis/batch_renderer.py; adjusted to take env-0 slice when batched).

Relationship to other PRs

• Replaces [FEATURE] Per-frame visual vertex deformation for KinematicEntity #2768 (closed) — the entity-side _custom_vverts buffer is gone; engine state on the solver is the new ground truth.
• PR [FEATURE] Visual-mesh raycasting for KinematicEntity (depth camera, lidar) #2769 (visual-mesh raycasting) is expected to rebase on top of this. The cleanup it needs is mechanical:
  • Drop kernel_copy_custom_vverts (obsolete — vverts_state is already the ground truth).
  • Simplify _update_visual_bvh_for_solver (just call solver.update_vgeoms(); FK is properly wired now).
  • Replace entity.has_custom_vverts checks with is_custom-based logic where still needed.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0c6587a54c

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Detect custom vverts across the full entity range

_entity_has_custom_vverts only inspects entity.vvert_start, so it misses overrides written to any later slice (e.g., RigidVisGeom.set_vverts on a non-first vgeom). In that case update_rigid never migrates the entity to the per-env vertex-upload path, and the custom vertices are ignored in rendering/sensors even though set_vverts succeeded. This regresses correctness for multi-vgeom entities where users override a subset that does not include the first vertex.

Useful? React with 👍 / 👎.