warp.bvh\_query\_next
=====================

.. function:: warp._src.lang.bvh_query_next(query: _BvhQueryAabb, index: int32, max_dist: float32) -> bool

   .. hlist::
      :columns: 8

      * Kernel

   Advance a BVH query to the next overlapping item and report whether one was found.
   
   Call :func:`bvh_query_next` in a ``while`` loop together with :func:`bvh_query_aabb`,
   :func:`bvh_query_ray`, :func:`bvh_query_capsule`, or :func:`bvh_query_sphere`.
   
   For plain ray queries (:func:`bvh_query_ray`), ``max_dist`` bounds how far along the ray to
   look for intersections, measured in multiples of ``dir``'s length (so it is a distance only if
   ``dir`` was normalized). For capsule queries (:func:`bvh_query_capsule`), pass
   ``dir = p1 - p0`` (unnormalized) together with ``max_dist = 1.0`` to sweep from ``p0`` to
   ``p1``. ``max_dist`` has no effect on AABB or sphere queries.
   
   Note that increasing ``max_dist`` may miss intersections: a subtree already rejected for being
   beyond ``max_dist`` is never revisited, even if a later, larger ``max_dist`` would reach it. It
   is therefore only safe to monotonically *reduce* ``max_dist`` during a query.
   
   :param query: The query to advance, from :func:`bvh_query_aabb`, :func:`bvh_query_ray`, :func:`bvh_query_capsule`, or :func:`bvh_query_sphere`
   :param index: Output; receives the index of the current overlapping item in the
                 ``lowers``/``uppers`` arrays passed to :class:`warp.Bvh`.
   :param max_dist: For ray queries, the maximum distance along the ray to check for intersections
                    (in multiples of ``dir``'s length). ``max_dist`` has no effect on AABB or sphere queries.
   
   :returns: ``True`` if another overlapping item was found (its index written to ``index``), ``False``
             if the query is exhausted. When the function returns ``False``, ``index`` is unchanged.
   
   .. rubric:: Example
   
   .. testcode::
   
       @wp.kernel
       def query_region(bvh_id: wp.uint64, lowers: wp.array[wp.vec3], uppers: wp.array[wp.vec3],
                        lo: wp.vec3, hi: wp.vec3, centers: wp.array[wp.vec3]):
           query = wp.bvh_query_aabb(bvh_id, lo, hi)
           item = int(0)
           while wp.bvh_query_next(query, item):
               centers[item] = 0.5 * (lowers[item] + uppers[item])
   
       lowers = wp.array([[0, 0, 0], [2, 0, 0], [4, 0, 0]], dtype=wp.vec3)
       uppers = wp.array([[1, 1, 1], [3, 1, 1], [5, 1, 1]], dtype=wp.vec3)
       bvh = wp.Bvh(lowers=lowers, uppers=uppers)
   
       centers = wp.zeros(3, dtype=wp.vec3)  # center of each object whose box overlaps the region
       wp.launch(query_region, dim=1, inputs=[bvh.id, lowers, uppers, wp.vec3(0.5, 0.5, 0.5), wp.vec3(2.5, 0.5, 0.5)], outputs=[centers])
       print(centers.numpy().tolist())
   
   .. testoutput::
   
       [[0.5, 0.5, 0.5], [2.5, 0.5, 0.5], [0.0, 0.0, 0.0]]
   

.. function:: warp._src.lang.bvh_query_next(query: _BvhQueryRay, index: int32, max_dist: float32) -> bool
   :noindex:

   .. hlist::
      :columns: 8

      * Kernel

   Advance a :func:`bvh_query_ray` query to the next intersected item.

.. function:: warp._src.lang.bvh_query_next(query: _BvhQueryCapsule, index: int32, max_dist: float32) -> bool
   :noindex:

   .. hlist::
      :columns: 8

      * Kernel

   Advance a :func:`bvh_query_capsule` query to the next intersected item.

.. function:: warp._src.lang.bvh_query_next(query: _BvhQuerySphere, index: int32, max_dist: float32) -> bool
   :noindex:

   .. hlist::
      :columns: 8

      * Kernel

   Advance a :func:`bvh_query_sphere` query to the next intersected item.

.. function:: warp._src.lang.bvh_query_next(query: BvhQuery, index: int32, max_dist: float32) -> bool
   :noindex:

   .. hlist::
      :columns: 8

      * Kernel

   Advance a BVH query whose kind is selected at runtime to the next overlapping item.