WIP: Sculpt: new C++ brush vertex API #109549

Joseph Eagar · 2023-06-30T09:15:41+02:00

Joseph Eagar commented

2023-06-30 09:15:41 +02:00

This PR implements a new C++ API for sculpt brushes, blender::bke::pbvh::foreach_brush_verts. It is meant to replace the current brush code pattern. Brushes are created in single functions using a lambda callback API. There are four callbacks:

Note: Review the API first.

A vertex filter callback. This tests if a vertex is inside the brush, and also returns the squared distance. Brushes thus still handle radius testing and falloff on their own.
A pre-execution node visit callback. It returns any custom per-node data this brush needs as a struct.
The main execution callback. We use a generic lambda to allow for greater template specialization of the underlying iterators.
A post-execution node visit callback.

The execution callback is provided a range, whose iteration values provide the following members, similar to PBVHVertIter:

{
  PBVHVertRef vertex;
  float *co;
  const float *no;
  float *mask;
  bool is_mesh;
  BrushsCustomNodeData node_data;
  PBVHNode *node;
  int vertex_node_index; /* PBVHVertIter.i */
}

Internally foreach_brush_verts works by building a flat list of vertices which is allocated to tasks via parallel_for. It still uses BKE_pbvh_vertex_iter_begin (which will need its own C++ implementation).

This is faster in some situations but not others. SCULPT_smooth has been ported to the new API (the new and old versions are executed and runtimes are printed in the console). The new API is faster on multi-core CPUs on mid-resolution meshes, where the old system fails to allocate work to enough threads. The overhead of building the flat vertex list is not worth it for single-threaded CPUs or meshes with a high resolution to achieve multicore task saturation.

To solve this I plan to write a second node-based iterator back-end, that can be used on single-core systems or if some heuristic of the ratio of nodes to vertices is met.

Example:


void ExampleBrush(
    Sculpt *sd, Object *ob, Span<PBVHNode *> nodes, float bstrength)
{
  SCOPED_TIMER(__func__);

  SculptSession *ss = ob->sculpt;
  Brush *brush = BKE_paint_brush(&sd->paint);

  /* Per-node custom data. */
  struct NodeData {
    AutomaskingNodeData automask_data;
  };

  SculptBrushTest test;
  SculptBrushTestFn sculpt_brush_test_sq_fn = SCULPT_brush_test_init_with_falloff_shape(
      ss, &test, brush->falloff_shape);

  blender::bke::pbvh::foreach_brush_verts<NodeData>(
      ss->pbvh,
      nodes,
      true,
      /* Filter brush verts. */
      [&](PBVHVertRef vertex, const float *co, const float *no, float mask, float *r_dist) {
        SculptBrushTest test2 = test;
        bool ret = sculpt_brush_test_sq_fn(&test2, co);
        if (ret) {
          *r_dist = test2.dist;
        }
        return ret;
      },

      /* Visit nodes before run. */
      [&](PBVHNode *node) {
        NodeData data = {};
        SCULPT_automasking_node_begin(ob, ss, ss->cache->automasking, &data.automask_data, node);
        return data;
      },
      
      /*  Main execution block.  We use a generic lambda to allow
        *  for iterator specialization.
        */
      [&](auto range) {
        const int thread_id = BLI_task_parallel_thread_id(nullptr);
        for (auto &vd : range) {
           SCULPT_automasking_node_update<NodeData>(ss, &vd.node_data->automask_data, vd);
           //...brush code, use vd.co, vd.no, vd.vertex, etc.
          }
        }
      },
      [&](PBVHNode *node, NodeData *node_data) {});
  }

This PR implements a new C++ API for sculpt brushes, `blender::bke::pbvh::foreach_brush_verts`. It is meant to replace the current brush code pattern. Brushes are created in single functions using a lambda callback API. There are four callbacks: **Note: Review the API first.** * A vertex filter callback. This tests if a vertex is inside the brush, and also returns the squared distance. Brushes thus still handle radius testing and falloff on their own. * A pre-execution node visit callback. It returns any custom per-node data this brush needs as a struct. * The main execution callback. We use a generic lambda to allow for greater template specialization of the underlying iterators. * A post-execution node visit callback. The execution callback is provided a range, whose iteration values provide the following members, similar to PBVHVertIter: ```Cpp { PBVHVertRef vertex; float *co; const float *no; float *mask; bool is_mesh; BrushsCustomNodeData node_data; PBVHNode *node; int vertex_node_index; /* PBVHVertIter.i */ } ``` Internally `foreach_brush_verts` works by building a flat list of vertices which is allocated to tasks via `parallel_for`. It still uses `BKE_pbvh_vertex_iter_begin` (which will need its own C++ implementation). This is faster in some situations but not others. `SCULPT_smooth` has been ported to the new API (the new *and old* versions are executed and runtimes are printed in the console). The new API is faster on multi-core CPUs on mid-resolution meshes, where the old system fails to allocate work to enough threads. The overhead of building the flat vertex list is not worth it for single-threaded CPUs or meshes with a high resolution to achieve multicore task saturation. To solve this I plan to write a second node-based iterator back-end, that can be used on single-core systems or if some heuristic of the ratio of nodes to vertices is met. Example: ```Cpp void ExampleBrush( Sculpt *sd, Object *ob, Span<PBVHNode *> nodes, float bstrength) { SCOPED_TIMER(__func__); SculptSession *ss = ob->sculpt; Brush *brush = BKE_paint_brush(&sd->paint); /* Per-node custom data. */ struct NodeData { AutomaskingNodeData automask_data; }; SculptBrushTest test; SculptBrushTestFn sculpt_brush_test_sq_fn = SCULPT_brush_test_init_with_falloff_shape( ss, &test, brush->falloff_shape); blender::bke::pbvh::foreach_brush_verts<NodeData>( ss->pbvh, nodes, true, /* Filter brush verts. */ [&](PBVHVertRef vertex, const float *co, const float *no, float mask, float *r_dist) { SculptBrushTest test2 = test; bool ret = sculpt_brush_test_sq_fn(&test2, co); if (ret) { *r_dist = test2.dist; } return ret; }, /* Visit nodes before run. */ [&](PBVHNode *node) { NodeData data = {}; SCULPT_automasking_node_begin(ob, ss, ss->cache->automasking, &data.automask_data, node); return data; }, /* Main execution block. We use a generic lambda to allow * for iterator specialization. */ [&](auto range) { const int thread_id = BLI_task_parallel_thread_id(nullptr); for (auto &vd : range) { SCULPT_automasking_node_update<NodeData>(ss, &vd.node_data->automask_data, vd); //...brush code, use vd.co, vd.no, vd.vertex, etc. } } }, [&](PBVHNode *node, NodeData *node_data) {}); } ```

Joseph Eagar added 1 commit 2023-06-30 09:15:54 +02:00

7e3ad1fbd0 Sculpt: C++ new brush vertex API

This PR implements a new C++ API for brush code,
blender::bke::pbvh::foreach_brush_verts.
It gathers verts visible to a brush
into a single flat array that is fed to
parallel_for.  This is much more efficient
than breaking brush tasks down by PBVHNodes.

Brush code is also much more clearer, as brushes can
be written in one function with lambdas.

Note: this does not itself replace
BKE_pbvh_vertex_iter_begin although it will
replace most uses of it.

Joseph Eagar added 4 commits 2023-07-03 06:42:14 +02:00

339fb54a48 Create a brush iter inside the sculpt module.

0a97d08bba Merge branch 'main' into temp-sculpt-brush-iter

a31343369e Deal with build system hell

58a0996d45 temp-sculpt-brush-iter: Get new sculpt brush exec api working

Joseph Eagar added 1 commit 2023-07-03 09:15:05 +02:00

4033d82170 commit current code

Joseph Eagar added 1 commit 2023-07-03 14:19:39 +02:00

2e93b2c343 Commit current code

Joseph Eagar added 1 commit 2023-07-04 03:22:53 +02:00

3846c4e769 Add missing file

Joseph Eagar added 1 commit 2023-07-10 15:15:32 +02:00