source/blender/blenkernel/BKE_mesh.h

   1 /* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
   2  *
   3  * SPDX-License-Identifier: GPL-2.0-or-later */
   4 #pragma once
   5
   6 /** \file
   7  * \ingroup bke
   8  */
   9
  10 #include <cstdint>
  11
  12 #include "BLI_array.hh"
  13 #include "BLI_string_ref.hh"
  14
  15 #include "DNA_mesh_types.h"
  16
  17 struct BMesh;
  18 struct BMeshCreateParams;
  19 struct BMeshFromMeshParams;
  20 struct BMeshToMeshParams;
  21 struct CustomData;
  22 struct CustomData_MeshMasks;
  23 struct Depsgraph;
  24 struct KeyBlock;
  25 struct LinkNode;
  26 struct ListBase;
  27 struct MDeformVert;
  28 struct MDisps;
  29 struct MFace;
  30 struct Main;
  31 struct MemArena;
  32 struct Mesh;
  33 struct Object;
  34 struct Scene;
  35
  36 /* TODO: Move to `BKE_mesh_types.hh` when possible. */
  37 enum eMeshBatchDirtyMode : int8_t {
  38   BKE_MESH_BATCH_DIRTY_ALL = 0,
  39   BKE_MESH_BATCH_DIRTY_SELECT,
  40   BKE_MESH_BATCH_DIRTY_SELECT_PAINT,
  41   BKE_MESH_BATCH_DIRTY_SHADING,
  42   BKE_MESH_BATCH_DIRTY_UVEDIT_ALL,
  43   BKE_MESH_BATCH_DIRTY_UVEDIT_SELECT,
  44 };
  45
  46 /* `mesh.cc` */
  47
  48 BMesh *BKE_mesh_to_bmesh_ex(const Mesh *mesh,
  49                             const BMeshCreateParams *create_params,
  50                             const BMeshFromMeshParams *convert_params);
  51 /**
  52  * \param active_shapekey: See #BMeshFromMeshParams::active_shapekey.
  53  * \param add_key_index: See #BMeshFromMeshParams::add_key_index.
  54  */
  55 BMesh *BKE_mesh_to_bmesh(Mesh *mesh,
  56                          int active_shapekey,
  57                          bool add_key_index,
  58                          const BMeshCreateParams *params);
  59
  60 Mesh *BKE_mesh_from_bmesh_nomain(BMesh *bm,
  61                                  const BMeshToMeshParams *params,
  62                                  const Mesh *me_settings);
  63 Mesh *BKE_mesh_from_bmesh_for_eval_nomain(BMesh *bm,
  64                                           const CustomData_MeshMasks *cd_mask_extra,
  65                                           const Mesh *me_settings);
  66
  67 /**
  68  * Add original index (#CD_ORIGINDEX) layers if they don't already exist. This is meant to be used
  69  * when creating an evaluated mesh from an original edit mode mesh, to allow mapping from the
  70  * evaluated vertices to the originals.
  71  *
  72  * The mesh is expected to of a `ME_WRAPPER_TYPE_MDATA` wrapper type. This is asserted.
  73  */
  74 void BKE_mesh_ensure_default_orig_index_customdata(Mesh *mesh);
  75
  76 /**
  77  * Same as #BKE_mesh_ensure_default_orig_index_customdata but does not perform any checks: they
  78  * must be done by the caller.
  79  */
  80 void BKE_mesh_ensure_default_orig_index_customdata_no_check(Mesh *mesh);
  81
  82 /**
  83  * Free (or release) any data used by this mesh (does not free the mesh itself).
  84  * Only use for undo, in most cases `BKE_id_free(nullptr, me)` should be used.
  85  */
  86 void BKE_mesh_free_data_for_undo(Mesh *mesh);
  87
  88 /**
  89  * Remove all geometry and derived data like caches from the mesh.
  90  */
  91 void BKE_mesh_clear_geometry(Mesh *mesh);
  92
  93 /**
  94  * Same as #BKE_mesh_clear_geometry, but also clears attribute meta-data like active attribute
  95  * names and vertex group names. Used when the geometry is *entirely* replaced.
  96  */
  97 void BKE_mesh_clear_geometry_and_metadata(Mesh *mesh);
  98
  99 Mesh *BKE_mesh_add(Main *bmain, const char *name);
 100
 101 /**
 102  * A version of #BKE_mesh_copy_parameters that is intended for evaluated output
 103  * (the modifier stack for example).
 104  *
 105  * \warning User counts are not handled for ID's.
 106  */
 107 void BKE_mesh_copy_parameters_for_eval(Mesh *me_dst, const Mesh *me_src);
 108 /**
 109  * Copy user editable settings that we want to preserve
 110  * when a new mesh is based on an existing mesh.
 111  */
 112 void BKE_mesh_copy_parameters(Mesh *me_dst, const Mesh *me_src);
 113 void BKE_mesh_ensure_skin_customdata(Mesh *mesh);
 114
 115 /** Add face offsets to describe faces to a new mesh. */
 116 void BKE_mesh_face_offsets_ensure_alloc(Mesh *mesh);
 117
 118 Mesh *BKE_mesh_new_nomain(int verts_num, int edges_num, int faces_num, int corners_num);
 119 Mesh *BKE_mesh_new_nomain_from_template(
 120     const Mesh *me_src, int verts_num, int edges_num, int faces_num, int corners_num);
 121 Mesh *BKE_mesh_new_nomain_from_template_ex(const Mesh *me_src,
 122                                            int verts_num,
 123                                            int edges_num,
 124                                            int tessface_num,
 125                                            int faces_num,
 126                                            int corners_num,
 127                                            CustomData_MeshMasks mask);
 128
 129 /**
 130  * Performs copy for use during evaluation.
 131  */
 132 Mesh *BKE_mesh_copy_for_eval(const Mesh &source);
 133
 134 /**
 135  * These functions construct a new Mesh,
 136  * contrary to #BKE_mesh_to_curve_nurblist which modifies ob itself.
 137  */
 138 Mesh *BKE_mesh_new_nomain_from_curve(const Object *ob);
 139 Mesh *BKE_mesh_new_nomain_from_curve_displist(const Object *ob, const ListBase *dispbase);
 140
 141 bool BKE_mesh_attribute_required(blender::StringRef name);
 142
 143 blender::Array<blender::float3> BKE_mesh_orco_verts_get(const Object *ob);
 144 void BKE_mesh_orco_verts_transform(Mesh *mesh,
 145                                    blender::MutableSpan<blender::float3> orco,
 146                                    bool invert);
 147 void BKE_mesh_orco_verts_transform(Mesh *mesh, float (*orco)[3], int totvert, bool invert);
 148
 149 /**
 150  * Add a #CD_ORCO layer to the Mesh if there is none already.
 151  */
 152 void BKE_mesh_orco_ensure(Object *ob, Mesh *mesh);
 153
 154 Mesh *BKE_mesh_from_object(Object *ob);
 155 void BKE_mesh_assign_object(Main *bmain, Object *ob, Mesh *mesh);
 156 void BKE_mesh_to_curve_nurblist(const Mesh *mesh, ListBase *nurblist, int edge_users_test);
 157 void BKE_mesh_to_curve(Main *bmain, Depsgraph *depsgraph, Scene *scene, Object *ob);
 158 void BKE_mesh_to_pointcloud(Main *bmain, Depsgraph *depsgraph, Scene *scene, Object *ob);
 159 void BKE_pointcloud_to_mesh(Main *bmain, Depsgraph *depsgraph, Scene *scene, Object *ob);
 160 void BKE_mesh_material_index_remove(Mesh *mesh, short index);
 161 bool BKE_mesh_material_index_used(Mesh *mesh, short index);
 162 void BKE_mesh_material_index_clear(Mesh *mesh);
 163 void BKE_mesh_material_remap(Mesh *mesh, const unsigned int *remap, unsigned int remap_len);
 164
 165 void BKE_mesh_texspace_calc(Mesh *mesh);
 166 void BKE_mesh_texspace_ensure(Mesh *mesh);
 167 void BKE_mesh_texspace_get(Mesh *mesh, float r_texspace_location[3], float r_texspace_size[3]);
 168 void BKE_mesh_texspace_get_reference(Mesh *mesh,
 169                                      char **r_texspace_flag,
 170                                      float **r_texspace_location,
 171                                      float **r_texspace_size);
 172
 173 /**
 174  * Create new mesh from the given object at its current state.
 175  * The caller owns the result mesh.
 176  *
 177  * If \a preserve_all_data_layers is true then the modifier stack is re-evaluated to ensure it
 178  * preserves all possible custom data layers.
 179  *
 180  * \note Dependency graph argument is required when preserve_all_data_layers is true, and is
 181  * ignored otherwise.
 182  */
 183 Mesh *BKE_mesh_new_from_object(Depsgraph *depsgraph,
 184                                Object *object,
 185                                bool preserve_all_data_layers,
 186                                bool preserve_origindex);
 187
 188 /**
 189  * This is a version of BKE_mesh_new_from_object() which stores mesh in the given main database.
 190  * However, that function enforces object type to be a geometry one, and ensures a mesh is always
 191  * generated, be it empty.
 192  */
 193 Mesh *BKE_mesh_new_from_object_to_bmain(Main *bmain,
 194                                         Depsgraph *depsgraph,
 195                                         Object *object,
 196                                         bool preserve_all_data_layers);
 197
 198 /**
 199  * Move data from a mesh outside of the main data-base into a mesh in the data-base.
 200  * Takes ownership of the source mesh.
 201  */
 202 void BKE_mesh_nomain_to_mesh(Mesh *mesh_src, Mesh *mesh_dst, Object *ob);
 203 void BKE_mesh_nomain_to_meshkey(Mesh *mesh_src, Mesh *mesh_dst, KeyBlock *kb);
 204
 205 /* Vertex level transformations & checks (no evaluated mesh). */
 206
 207 /* basic vertex data functions */
 208 void BKE_mesh_transform(Mesh *mesh, const float mat[4][4], bool do_keys);
 209 void BKE_mesh_translate(Mesh *mesh, const float offset[3], bool do_keys);
 210
 211 void BKE_mesh_tessface_clear(Mesh *mesh);
 212
 213 void BKE_mesh_mselect_clear(Mesh *mesh);
 214 void BKE_mesh_mselect_validate(Mesh *mesh);
 215 /**
 216  * \return the index within `me->mselect`, or -1
 217  */
 218 int BKE_mesh_mselect_find(const Mesh *mesh, int index, int type);
 219 /**
 220  * \return The index of the active element.
 221  */
 222 int BKE_mesh_mselect_active_get(const Mesh *mesh, int type);
 223 void BKE_mesh_mselect_active_set(Mesh *mesh, int index, int type);
 224
 225 void BKE_mesh_count_selected_items(const Mesh *mesh, int r_count[3]);
 226
 227 /* *** mesh_normals.cc *** */
 228
 229 /** Return true if the mesh vertex normals either are not stored or are dirty. */
 230 bool BKE_mesh_vert_normals_are_dirty(const Mesh *mesh);
 231
 232 /** Return true if the mesh face normals either are not stored or are dirty. */
 233 bool BKE_mesh_face_normals_are_dirty(const Mesh *mesh);
 234
 235 /**
 236  * References a contiguous loop-fan.
 237  * Combined with the automatically calculated face corner normal, this gives a dimensional
 238  * coordinate space used to convert normals between the "custom normal" #short2 representation and
 239  * a regular #float3 format.
 240  */
 241 struct MLoopNorSpace {
 242   /** The automatically computed face corner normal, not including influence of custom normals. */
 243   float vec_lnor[3];
 244   /**
 245    * Reference vector, orthogonal to #vec_lnor, aligned with one of the edges (borders) of the
 246    * smooth fan, called 'reference edge'.
 247    */
 248   float vec_ref[3];
 249   /** Third vector, orthogonal to #vec_lnor and #vec_ref. */
 250   float vec_ortho[3];
 251   /**
 252    * Reference angle around #vec_ortho, in ]0, pi] range, between #vec_lnor and the reference edge.
 253    *
 254    * A 0.0 value marks that space as invalid, as it can only happen in extremely degenerate
 255    * geometry cases (it would mean that the default normal is perfectly aligned with the reference
 256    * edge).
 257    */
 258   float ref_alpha;
 259   /**
 260    * Reference angle around #vec_lnor, in ]0, 2pi] range, between the reference edge and the other
 261    * border edge of the fan.
 262    *
 263    * A 0.0 value marks that space as invalid, as it can only happen in degenerate geometry cases
 264    * (it would mean that all the edges connected to that corner of the smooth fan are perfectly
 265    * aligned).
 266    */
 267   float ref_beta;
 268   /** All loops using this lnor space (i.e. smooth fan of loops),
 269    * as (depending on owning MLoopNorSpaceArrary.data_type):
 270    *     - Indices (uint_in_ptr), or
 271    *     - BMLoop pointers. */
 272   struct LinkNode *loops;
 273   char flags;
 274 };
 275 /**
 276  * MLoopNorSpace.flags
 277  */
 278 enum {
 279   MLNOR_SPACE_IS_SINGLE = 1 << 0,
 280 };
 281
 282 /**
 283  * Collection of #MLoopNorSpace basic storage & pre-allocation.
 284  */
 285 struct MLoopNorSpaceArray {
 286   MLoopNorSpace **lspacearr; /* Face corner aligned array */
 287   struct LinkNode
 288       *loops_pool; /* Allocated once, avoids to call BLI_linklist_prepend_arena() for each loop! */
 289   char data_type;  /* Whether we store loop indices, or pointers to BMLoop. */
 290   int spaces_num;  /* Number of clnors spaces defined in this array. */
 291   struct MemArena *mem;
 292 };
 293 /**
 294  * MLoopNorSpaceArray.data_type
 295  */
 296 enum {
 297   MLNOR_SPACEARR_LOOP_INDEX = 0,
 298   MLNOR_SPACEARR_BMLOOP_PTR = 1,
 299 };
 300
 301 /* Low-level custom normals functions. */
 302 void BKE_lnor_spacearr_init(MLoopNorSpaceArray *lnors_spacearr, int numLoops, char data_type);
 303 void BKE_lnor_spacearr_clear(MLoopNorSpaceArray *lnors_spacearr);
 304 void BKE_lnor_spacearr_free(MLoopNorSpaceArray *lnors_spacearr);
 305
 306 /**
 307  * Utility for multi-threaded calculation that ensures
 308  * `lnors_spacearr_tls` doesn't share memory with `lnors_spacearr`
 309  * that would cause it not to be thread safe.
 310  *
 311  * \note This works as long as threads never operate on the same loops at once.
 312  */
 313 void BKE_lnor_spacearr_tls_init(MLoopNorSpaceArray *lnors_spacearr,
 314                                 MLoopNorSpaceArray *lnors_spacearr_tls);
 315 /**
 316  * Utility for multi-threaded calculation
 317  * that merges `lnors_spacearr_tls` into `lnors_spacearr`.
 318  */
 319 void BKE_lnor_spacearr_tls_join(MLoopNorSpaceArray *lnors_spacearr,
 320                                 MLoopNorSpaceArray *lnors_spacearr_tls);
 321
 322 MLoopNorSpace *BKE_lnor_space_create(MLoopNorSpaceArray *lnors_spacearr);
 323
 324 /**
 325  * Should only be called once.
 326  * Beware, this modifies ref_vec and other_vec in place!
 327  * In case no valid space can be generated, ref_alpha and ref_beta are set to zero
 328  * (which means 'use auto lnors').
 329  */
 330 void BKE_lnor_space_define(MLoopNorSpace *lnor_space,
 331                            const float lnor[3],
 332                            const float vec_ref[3],
 333                            const float vec_other[3],
 334                            blender::Span<blender::float3> edge_vectors);
 335
 336 /**
 337  * Add a new given loop to given lnor_space.
 338  * Depending on \a lnor_space->data_type, we expect \a bm_loop to be a pointer to BMLoop struct
 339  * (in case of BMLOOP_PTR), or nullptr (in case of LOOP_INDEX), loop index is then stored in
 340  * pointer. If \a is_single is set, the BMLoop or loop index is directly stored in \a
 341  * lnor_space->loops pointer (since there is only one loop in this fan), else it is added to the
 342  * linked list of loops in the fan.
 343  */
 344 void BKE_lnor_space_add_loop(MLoopNorSpaceArray *lnors_spacearr,
 345                              MLoopNorSpace *lnor_space,
 346                              int corner,
 347                              void *bm_loop,
 348                              bool is_single);
 349 void BKE_lnor_space_custom_data_to_normal(const MLoopNorSpace *lnor_space,
 350                                           const short clnor_data[2],
 351                                           float r_custom_lnor[3]);
 352 void BKE_lnor_space_custom_normal_to_data(const MLoopNorSpace *lnor_space,
 353                                           const float custom_lnor[3],
 354                                           short r_clnor_data[2]);
 355
 356 /**
 357  * Computes average per-vertex normals from given custom loop normals.
 358  *
 359  * \param clnors: The computed custom loop normals.
 360  * \param r_vert_clnors: The (already allocated) array where to store averaged per-vertex normals.
 361  */
 362 void BKE_mesh_normals_loop_to_vertex(int numVerts,
 363                                      const int *corner_verts,
 364                                      int numLoops,
 365                                      const float (*clnors)[3],
 366                                      float (*r_vert_clnors)[3]);
 367
 368 /**
 369  * High-level custom normals functions.
 370  */
 371 bool BKE_mesh_has_custom_loop_normals(Mesh *mesh);
 372
 373 /* *** mesh_evaluate.cc *** */
 374
 375 float BKE_mesh_calc_area(const Mesh *mesh);
 376
 377 bool BKE_mesh_center_median(const Mesh *mesh, float r_cent[3]);
 378 /**
 379  * Calculate the center from faces,
 380  * use when we want to ignore vertex locations that don't have connected faces.
 381  */
 382 bool BKE_mesh_center_median_from_faces(const Mesh *mesh, float r_cent[3]);
 383 bool BKE_mesh_center_of_surface(const Mesh *mesh, float r_cent[3]);
 384 /**
 385  * \note Mesh must be manifold with consistent face-winding,
 386  * see #mesh_calc_face_volume_centroid for details.
 387  */
 388 bool BKE_mesh_center_of_volume(const Mesh *mesh, float r_cent[3]);
 389
 390 /**
 391  * Calculate the volume and center.
 392  *
 393  * \param r_volume: Volume (unsigned).
 394  * \param r_center: Center of mass.
 395  */
 396 void BKE_mesh_calc_volume(const float (*vert_positions)[3],
 397                           int mverts_num,
 398                           const blender::int3 *corner_tris,
 399                           int corner_tris_num,
 400                           const int *corner_verts,
 401                           float *r_volume,
 402                           float r_center[3]);
 403
 404 /**
 405  * Flip a single corner's #MDisps structure,
 406  * low level function to be called from face-flipping code which re-arranged the mdisps themselves.
 407  */
 408 void BKE_mesh_mdisp_flip(MDisps *md, bool use_loop_mdisp_flip);
 409
 410 /**
 411  * Account for custom-data such as UVs becoming detached because of imprecision
 412  * in custom-data interpolation.
 413  * Without running this operation subdivision surface can cause UVs to be disconnected,
 414  * see: #81065.
 415  */
 416 void BKE_mesh_merge_customdata_for_apply_modifier(Mesh *mesh);
 417
 418 /* Flush flags. */
 419
 420 /* spatial evaluation */
 421 /**
 422  * This function takes the difference between 2 vertex-coord-arrays
 423  * (\a vert_cos_src, \a vert_cos_dst),
 424  * and applies the difference to \a vert_cos_new relative to \a vert_cos_org.
 425  *
 426  * \param vert_cos_src: reference deform source.
 427  * \param vert_cos_dst: reference deform destination.
 428  *
 429  * \param vert_cos_org: reference for the output location.
 430  * \param vert_cos_new: resulting coords.
 431  */
 432 void BKE_mesh_calc_relative_deform(const int *face_offsets,
 433                                    int faces_num,
 434                                    const int *corner_verts,
 435                                    int totvert,
 436
 437                                    const float (*vert_cos_src)[3],
 438                                    const float (*vert_cos_dst)[3],
 439
 440                                    const float (*vert_cos_org)[3],
 441                                    float (*vert_cos_new)[3]);
 442
 443 /* *** mesh_validate.cc *** */
 444
 445 /**
 446  * Validates and corrects a Mesh.
 447  *
 448  * \returns true if a change is made.
 449  */
 450 bool BKE_mesh_validate(Mesh *mesh, bool do_verbose, bool cddata_check_mask);
 451 /**
 452  * Checks if a Mesh is valid without any modification. This is always verbose.
 453  * \returns True if the mesh is valid.
 454  */
 455 bool BKE_mesh_is_valid(Mesh *mesh);
 456 /**
 457  * Check all material indices of faces are valid, invalid ones are set to 0.
 458  * \returns True if the material indices are valid.
 459  */
 460 bool BKE_mesh_validate_material_indices(Mesh *mesh);
 461
 462 /**
 463  * Validate the mesh, \a do_fixes requires \a mesh to be non-null.
 464  *
 465  * \return false if no changes needed to be made.
 466  */
 467 bool BKE_mesh_validate_arrays(Mesh *mesh,
 468                               float (*vert_positions)[3],
 469                               unsigned int verts_num,
 470                               blender::int2 *edges,
 471                               unsigned int edges_num,
 472                               MFace *legacy_faces,
 473                               unsigned int legacy_faces_num,
 474                               const int *corner_verts,
 475                               int *corner_edges,
 476                               unsigned int corners_num,
 477                               const int *face_offsets,
 478                               unsigned int faces_num,
 479                               MDeformVert *dverts, /* assume totvert length */
 480                               bool do_verbose,
 481                               bool do_fixes,
 482                               bool *r_change);
 483
 484 /**
 485  * \returns is_valid.
 486  */
 487 bool BKE_mesh_validate_all_customdata(CustomData *vert_data,
 488                                       uint verts_num,
 489                                       CustomData *edge_data,
 490                                       uint edges_num,
 491                                       CustomData *corner_data,
 492                                       uint corners_num,
 493                                       CustomData *face_data,
 494                                       uint faces_num,
 495                                       bool check_meshmask,
 496                                       bool do_verbose,
 497                                       bool do_fixes,
 498                                       bool *r_change);
 499
 500 void BKE_mesh_strip_loose_faces(Mesh *mesh);
 501
 502 /* **** Depsgraph evaluation **** */
 503
 504 void BKE_mesh_eval_geometry(Depsgraph *depsgraph, Mesh *mesh);
 505
 506 /* Draw Cache */
 507 void BKE_mesh_batch_cache_dirty_tag(Mesh *mesh, eMeshBatchDirtyMode mode);
 508 void BKE_mesh_batch_cache_free(void *batch_cache);
 509
 510 extern void (*BKE_mesh_batch_cache_dirty_tag_cb)(Mesh *mesh, eMeshBatchDirtyMode mode);
 511 extern void (*BKE_mesh_batch_cache_free_cb)(void *batch_cache);
 512
 513 /* `mesh_debug.cc` */
 514
 515 #ifndef NDEBUG
 516 char *BKE_mesh_debug_info(const Mesh *mesh) ATTR_NONNULL(1) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT;
 517 void BKE_mesh_debug_print(const Mesh *mesh) ATTR_NONNULL(1);
 518 #endif