[harrism]

What this PR is, and why

Part of the 13.2 work for #2232. The GPU tools allocate their output through a prototype buffer. They use only its type and resource(), and they take scratch memory through a separate ResourceT. This PR adds resource forms beside the prototype forms, which keep their call shapes and are not deprecated.

• Free functions: voxelsToGrid, both pointsToGrid forms, indexToGrid and addBlindData take (…, stream, resource).
  • One resource, held by value (pass a ResourceRef to borrow), allocates both the scratch and the output. The output is a GridHandle<cuda::Buffer<std::byte, R>>.
  • Passing a cudaStream_t selects this form. When the stream sits where the prototype goes, the prototype forms leave overload resolution, so every compiler resolves the call the same way. (nvcc found one shape ambiguous when this relied on partial ordering.)
  • A literal 0 there fails with a message to write cudaStream_t(0), and a synchronous resource gets a message naming cuda::AsyncFromSync.
• Builder classes: build() beside getHandle(buffer) on PointsToGrid, Dilate, Merge, Prune, Refine, Coarsen, MeshToGrid and IndexToGrid. MeshToGrid also gets buildWithUDF() beside getHandleAndUDF().
  • The output allocates through the builder's own resource, so one pool serves the scratch and the result, as a buffer that borrows that resource.
  • getHandle(points, n) would have been ambiguous with the existing defaulted-buffer overload, hence the new name.
  • DistributedPointsToGrid is left out: its output must be managed memory that every GPU can reach.

Bugs fixed along the way

• addBlindData name overflow. It copied the blind-data name into its 256-byte field with an unchecked strcpy, so a longer name overflowed the host stack.
  • Both forms now validate before launching: a null or too-long name, a null grid, or null data with a nonzero count throws.
  • Its scratch came only from the default resource, so a ResourceRef couldn't drive it. The resource form takes the resource explicitly.
• Argument checks in the builders. The IndexToGrid and PointsToGrid constructors reject a null source grid, a singular or non-finite map, a non-positive or non-finite voxel size, and a non-positive density target, before allocating anything, so the prototype forms, the resource forms, getHandle() and build() all reject them. The free functions also reject a negative point count.
• Missing definition. pointsToGrid(points, n, voxelSize, type, buffer, stream) was declared but never defined, and is now defined. NanoVDB: merge and split single-space device grid handles, and deprecate the dual overloads (CUDA) #2370 defines it too; whichever lands second keeps one copy.

Testing

• New tests: each resource form and each build() produces the same bytes as its prototype counterpart, every allocation goes through the given resource and balances, and the argument checks throw.
• Platform: one GPU (RTX PRO 6000 Blackwell), nvcc 12.6, -Werror.
• Results: all single-GPU suites pass. Examples, tools and the Python module build warning-free. Merged together with the resource-equality PR, everything still builds and passes.

🤖 Generated with Claude Code

[swahtz]

The resource forms look like the right direction. Taking a stream to select them, and the error messages for a literal 0 and for a synchronous resource, should make them easy to use correctly. I'm requesting changes for the createNanoGrid gap and the validation that build() skips. The other comments are smaller.

One merge-order note, outside the diff. The multi-set pointsToGrid at PointsToGrid.cuh:1548 still calls pointsToGrid<BuildT, PtrT, BufferT, ResourceT>(...) with four template arguments. The single-set templates take three, so it still fails to compile ("no instance of overloaded function pointsToGrid matches the argument list" with nvcc), even with the missing definition now in place. #2370 fixes the multi-set overloads. If this PR lands first, that form stays broken until #2370 lands.

[harrism]

Thanks @swahtz. Every inline thread has a reply; the fixes are in 0393979 and 0dc2ddd. On the merge-order note: agreed. #2370 fixes the multi-set overloads and lands ahead of this one in the planned order (#2329 → #2370 → #2371 → #2372 → #2373 → #2374). This PR rebases onto it then, and the duplicate voxelSize pointsToGrid definition resolves in #2370's favour.

[swahtz]

Great, thanks for addressing my notes, lgtm