Cleanup: typos in comments.
[blender.git] / source / blender / blenkernel / BKE_object.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16
17 #pragma once
18
19 /** \file
20  * \ingroup bke
21  * \brief General operations, lookup, etc. for blender objects.
22  */
23
24 #include "BLI_compiler_attrs.h"
25 #include "BLI_sys_types.h"
26
27 #include "DNA_object_enums.h"
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 struct Base;
34 struct BoundBox;
35 struct Curve;
36 struct Depsgraph;
37 struct GeometrySet;
38 struct GpencilModifierData;
39 struct HookGpencilModifierData;
40 struct HookModifierData;
41 struct ID;
42 struct Main;
43 struct Mesh;
44 struct ModifierData;
45 struct MovieClip;
46 struct Object;
47 struct RegionView3D;
48 struct RigidBodyWorld;
49 struct Scene;
50 struct ShaderFxData;
51 struct View3D;
52 struct ViewLayer;
53
54 void BKE_object_workob_clear(struct Object *workob);
55 void BKE_object_workob_calc_parent(struct Depsgraph *depsgraph,
56                                    struct Scene *scene,
57                                    struct Object *ob,
58                                    struct Object *workob);
59
60 void BKE_object_transform_copy(struct Object *ob_tar, const struct Object *ob_src);
61 void BKE_object_copy_softbody(struct Object *ob_dst, const struct Object *ob_src, const int flag);
62 struct ParticleSystem *BKE_object_copy_particlesystem(struct ParticleSystem *psys, const int flag);
63 void BKE_object_copy_particlesystems(struct Object *ob_dst,
64                                      const struct Object *ob_src,
65                                      const int flag);
66 void BKE_object_free_particlesystems(struct Object *ob);
67 void BKE_object_free_softbody(struct Object *ob);
68 void BKE_object_free_curve_cache(struct Object *ob);
69
70 void BKE_object_free_derived_caches(struct Object *ob);
71 void BKE_object_free_caches(struct Object *object);
72
73 void BKE_object_modifier_hook_reset(struct Object *ob, struct HookModifierData *hmd);
74 void BKE_object_modifier_gpencil_hook_reset(struct Object *ob,
75                                             struct HookGpencilModifierData *hmd);
76 bool BKE_object_modifier_gpencil_use_time(struct Object *ob, struct GpencilModifierData *md);
77
78 bool BKE_object_shaderfx_use_time(struct Object *ob, struct ShaderFxData *fx);
79
80 bool BKE_object_supports_modifiers(const struct Object *ob);
81 bool BKE_object_support_modifier_type_check(const struct Object *ob, int modifier_type);
82
83 /* Active modifier. */
84 void BKE_object_modifier_set_active(struct Object *ob, struct ModifierData *md);
85 struct ModifierData *BKE_object_active_modifier(const struct Object *ob);
86
87 bool BKE_object_copy_modifier(struct Main *bmain,
88                               struct Scene *scene,
89                               struct Object *ob_dst,
90                               const struct Object *ob_src,
91                               struct ModifierData *md);
92 bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, struct GpencilModifierData *gmd_src);
93 bool BKE_object_modifier_stack_copy(struct Object *ob_dst,
94                                     const struct Object *ob_src,
95                                     const bool do_copy_all,
96                                     const int flag_subdata);
97 void BKE_object_link_modifiers(struct Object *ob_dst, const struct Object *ob_src);
98 void BKE_object_free_modifiers(struct Object *ob, const int flag);
99 void BKE_object_free_shaderfx(struct Object *ob, const int flag);
100
101 void BKE_object_make_proxy(struct Main *bmain,
102                            struct Object *ob,
103                            struct Object *target,
104                            struct Object *cob);
105 void BKE_object_copy_proxy_drivers(struct Object *ob, struct Object *target);
106
107 bool BKE_object_exists_check(struct Main *bmain, const struct Object *obtest);
108 bool BKE_object_is_in_editmode(const struct Object *ob);
109 bool BKE_object_is_in_editmode_vgroup(const struct Object *ob);
110 bool BKE_object_is_in_wpaint_select_vert(const struct Object *ob);
111 bool BKE_object_has_mode_data(const struct Object *ob, eObjectMode object_mode);
112 bool BKE_object_is_mode_compat(const struct Object *ob, eObjectMode object_mode);
113
114 bool BKE_object_data_is_in_editmode(const struct ID *id);
115
116 char *BKE_object_data_editmode_flush_ptr_get(struct ID *id);
117
118 void BKE_object_update_select_id(struct Main *bmain);
119
120 typedef enum eObjectVisibilityResult {
121   OB_VISIBLE_SELF = 1,
122   OB_VISIBLE_PARTICLES = 2,
123   OB_VISIBLE_INSTANCES = 4,
124   OB_VISIBLE_ALL = (OB_VISIBLE_SELF | OB_VISIBLE_PARTICLES | OB_VISIBLE_INSTANCES),
125 } eObjectVisibilityResult;
126
127 int BKE_object_visibility(const struct Object *ob, const int dag_eval_mode);
128
129 struct Object *BKE_object_add_only_object(struct Main *bmain, int type, const char *name)
130     ATTR_NONNULL(1) ATTR_RETURNS_NONNULL;
131 struct Object *BKE_object_add(struct Main *bmain,
132                               struct ViewLayer *view_layer,
133                               int type,
134                               const char *name) ATTR_NONNULL(1, 2) ATTR_RETURNS_NONNULL;
135 struct Object *BKE_object_add_from(struct Main *bmain,
136                                    struct Scene *scene,
137                                    struct ViewLayer *view_layer,
138                                    int type,
139                                    const char *name,
140                                    struct Object *ob_src)
141     ATTR_NONNULL(1, 2, 3, 6) ATTR_RETURNS_NONNULL;
142 struct Object *BKE_object_add_for_data(struct Main *bmain,
143                                        struct ViewLayer *view_layer,
144                                        int type,
145                                        const char *name,
146                                        struct ID *data,
147                                        bool do_id_user) ATTR_RETURNS_NONNULL;
148 void *BKE_object_obdata_add_from_type(struct Main *bmain, int type, const char *name)
149     ATTR_NONNULL(1);
150 int BKE_object_obdata_to_type(const struct ID *id) ATTR_NONNULL(1);
151
152 bool BKE_object_is_libdata(const struct Object *ob);
153 bool BKE_object_obdata_is_libdata(const struct Object *ob);
154
155 struct Object *BKE_object_duplicate(struct Main *bmain,
156                                     struct Object *ob,
157                                     uint dupflag,
158                                     uint duplicate_options);
159
160 void BKE_object_obdata_size_init(struct Object *ob, const float size);
161
162 void BKE_object_scale_to_mat3(struct Object *ob, float r_mat[3][3]);
163 void BKE_object_rot_to_mat3(const struct Object *ob, float r_mat[3][3], bool use_drot);
164 void BKE_object_mat3_to_rot(struct Object *ob, float r_mat[3][3], bool use_compat);
165 void BKE_object_to_mat3(struct Object *ob, float r_mat[3][3]);
166 void BKE_object_to_mat4(struct Object *ob, float r_mat[4][4]);
167 void BKE_object_apply_mat4(struct Object *ob,
168                            const float mat[4][4],
169                            const bool use_compat,
170                            const bool use_parent);
171 void BKE_object_apply_mat4_ex(struct Object *ob,
172                               const float mat[4][4],
173                               struct Object *parent,
174                               const float parentinv[4][4],
175                               const bool use_compat);
176 void BKE_object_matrix_local_get(struct Object *ob, float r_mat[4][4]);
177
178 bool BKE_object_pose_context_check(const struct Object *ob);
179 struct Object *BKE_object_pose_armature_get(struct Object *ob);
180 struct Object *BKE_object_pose_armature_get_visible(struct Object *ob,
181                                                     struct ViewLayer *view_layer,
182                                                     struct View3D *v3d);
183
184 struct Object **BKE_object_pose_array_get_ex(struct ViewLayer *view_layer,
185                                              struct View3D *v3d,
186                                              unsigned int *r_objects_len,
187                                              bool unique);
188 struct Object **BKE_object_pose_array_get_unique(struct ViewLayer *view_layer,
189                                                  struct View3D *v3d,
190                                                  unsigned int *r_objects_len);
191 struct Object **BKE_object_pose_array_get(struct ViewLayer *view_layer,
192                                           struct View3D *v3d,
193                                           unsigned int *r_objects_len);
194
195 struct Base **BKE_object_pose_base_array_get_ex(struct ViewLayer *view_layer,
196                                                 struct View3D *v3d,
197                                                 unsigned int *r_bases_len,
198                                                 bool unique);
199 struct Base **BKE_object_pose_base_array_get_unique(struct ViewLayer *view_layer,
200                                                     struct View3D *v3d,
201                                                     unsigned int *r_bases_len);
202 struct Base **BKE_object_pose_base_array_get(struct ViewLayer *view_layer,
203                                              struct View3D *v3d,
204                                              unsigned int *r_bases_len);
205
206 void BKE_object_get_parent_matrix(struct Object *ob, struct Object *par, float r_parentmat[4][4]);
207
208 /* Compute object world transform and store it in ob->obmat. */
209 void BKE_object_where_is_calc(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob);
210 void BKE_object_where_is_calc_ex(struct Depsgraph *depsgraph,
211                                  struct Scene *scene,
212                                  struct RigidBodyWorld *rbw,
213                                  struct Object *ob,
214                                  float r_originmat[3][3]);
215 void BKE_object_where_is_calc_time(struct Depsgraph *depsgraph,
216                                    struct Scene *scene,
217                                    struct Object *ob,
218                                    float ctime);
219 void BKE_object_where_is_calc_mat4(struct Object *ob, float r_obmat[4][4]);
220
221 /* Possibly belong in own module? */
222 struct BoundBox *BKE_boundbox_alloc_unit(void);
223 void BKE_boundbox_init_from_minmax(struct BoundBox *bb, const float min[3], const float max[3]);
224 void BKE_boundbox_calc_center_aabb(const struct BoundBox *bb, float r_cent[3]);
225 void BKE_boundbox_calc_size_aabb(const struct BoundBox *bb, float r_size[3]);
226 void BKE_boundbox_minmax(const struct BoundBox *bb,
227                          const float obmat[4][4],
228                          float r_min[3],
229                          float r_max[3]);
230
231 struct BoundBox *BKE_object_boundbox_get(struct Object *ob);
232 void BKE_object_dimensions_get(struct Object *ob, float r_vec[3]);
233 void BKE_object_dimensions_set_ex(struct Object *ob,
234                                   const float value[3],
235                                   int axis_mask,
236                                   const float ob_scale_orig[3],
237                                   const float ob_obmat_orig[4][4]);
238 void BKE_object_dimensions_set(struct Object *ob, const float value[3], int axis_mask);
239
240 void BKE_object_empty_draw_type_set(struct Object *ob, const int value);
241 void BKE_object_boundbox_flag(struct Object *ob, int flag, const bool set);
242 void BKE_object_boundbox_calc_from_mesh(struct Object *ob, const struct Mesh *me_eval);
243 bool BKE_object_boundbox_calc_from_evaluated_geometry(struct Object *ob);
244 void BKE_object_minmax(struct Object *ob, float r_min[3], float r_max[3], const bool use_hidden);
245 bool BKE_object_minmax_dupli(struct Depsgraph *depsgraph,
246                              struct Scene *scene,
247                              struct Object *ob,
248                              float r_min[3],
249                              float r_max[3],
250                              const bool use_hidden);
251
252 /* sometimes min-max isn't enough, we need to loop over each point */
253 void BKE_object_foreach_display_point(struct Object *ob,
254                                       const float obmat[4][4],
255                                       void (*func_cb)(const float[3], void *),
256                                       void *user_data);
257 void BKE_scene_foreach_display_point(struct Depsgraph *depsgraph,
258                                      void (*func_cb)(const float[3], void *),
259                                      void *user_data);
260
261 bool BKE_object_parent_loop_check(const struct Object *parent, const struct Object *ob);
262
263 void *BKE_object_tfm_backup(struct Object *ob);
264 void BKE_object_tfm_restore(struct Object *ob, void *obtfm_pt);
265
266 typedef struct ObjectTfmProtectedChannels {
267   float loc[3], dloc[3];
268   float scale[3], dscale[3];
269   float rot[3], drot[3];
270   float quat[4], dquat[4];
271   float rotAxis[3], drotAxis[3];
272   float rotAngle, drotAngle;
273 } ObjectTfmProtectedChannels;
274
275 void BKE_object_tfm_protected_backup(const struct Object *ob, ObjectTfmProtectedChannels *obtfm);
276
277 void BKE_object_tfm_protected_restore(struct Object *ob,
278                                       const ObjectTfmProtectedChannels *obtfm,
279                                       const short protectflag);
280
281 void BKE_object_tfm_copy(struct Object *object_dst, const struct Object *object_src);
282
283 void BKE_object_eval_reset(struct Object *ob_eval);
284
285 /* Dependency graph evaluation callbacks. */
286 void BKE_object_eval_local_transform(struct Depsgraph *depsgraph, struct Object *ob);
287 void BKE_object_eval_parent(struct Depsgraph *depsgraph, struct Object *ob);
288 void BKE_object_eval_constraints(struct Depsgraph *depsgraph,
289                                  struct Scene *scene,
290                                  struct Object *ob);
291 void BKE_object_eval_transform_final(struct Depsgraph *depsgraph, struct Object *ob);
292
293 bool BKE_object_eval_proxy_copy(struct Depsgraph *depsgraph, struct Object *object);
294 void BKE_object_eval_uber_transform(struct Depsgraph *depsgraph, struct Object *ob);
295 void BKE_object_eval_uber_data(struct Depsgraph *depsgraph,
296                                struct Scene *scene,
297                                struct Object *ob);
298 void BKE_object_eval_assign_data(struct Object *object, struct ID *data, bool is_owned);
299
300 void BKE_object_sync_to_original(struct Depsgraph *depsgraph, struct Object *object);
301
302 void BKE_object_eval_ptcache_reset(struct Depsgraph *depsgraph,
303                                    struct Scene *scene,
304                                    struct Object *object);
305
306 void BKE_object_eval_transform_all(struct Depsgraph *depsgraph,
307                                    struct Scene *scene,
308                                    struct Object *object);
309
310 void BKE_object_data_select_update(struct Depsgraph *depsgraph, struct ID *object_data);
311 void BKE_object_select_update(struct Depsgraph *depsgraph, struct Object *object);
312
313 void BKE_object_eval_eval_base_flags(struct Depsgraph *depsgraph,
314                                      struct Scene *scene,
315                                      const int view_layer_index,
316                                      struct Object *object,
317                                      int base_index,
318                                      const bool is_from_set);
319
320 void BKE_object_handle_data_update(struct Depsgraph *depsgraph,
321                                    struct Scene *scene,
322                                    struct Object *ob);
323 void BKE_object_handle_update(struct Depsgraph *depsgraph, struct Scene *scene, struct Object *ob);
324 void BKE_object_handle_update_ex(struct Depsgraph *depsgraph,
325                                  struct Scene *scene,
326                                  struct Object *ob,
327                                  struct RigidBodyWorld *rbw,
328                                  const bool do_proxy_update);
329
330 void BKE_object_sculpt_data_create(struct Object *ob);
331
332 bool BKE_object_obdata_texspace_get(struct Object *ob,
333                                     short **r_texflag,
334                                     float **r_loc,
335                                     float **r_size);
336
337 struct Mesh *BKE_object_get_evaluated_mesh(const struct Object *object);
338 struct Mesh *BKE_object_get_pre_modified_mesh(const struct Object *object);
339 struct Mesh *BKE_object_get_original_mesh(const struct Object *object);
340
341 /* Lattice accessors.
342  * These functions return either the regular lattice, or the edit-mode lattice,
343  * whichever is currently in use. */
344 struct Lattice *BKE_object_get_lattice(const struct Object *object);
345 struct Lattice *BKE_object_get_evaluated_lattice(const struct Object *object);
346
347 int BKE_object_insert_ptcache(struct Object *ob);
348 void BKE_object_delete_ptcache(struct Object *ob, int index);
349 struct KeyBlock *BKE_object_shapekey_insert(struct Main *bmain,
350                                             struct Object *ob,
351                                             const char *name,
352                                             const bool from_mix);
353 bool BKE_object_shapekey_remove(struct Main *bmain, struct Object *ob, struct KeyBlock *kb);
354 bool BKE_object_shapekey_free(struct Main *bmain, struct Object *ob);
355
356 bool BKE_object_flag_test_recursive(const struct Object *ob, short flag);
357
358 bool BKE_object_is_child_recursive(const struct Object *ob_parent, const struct Object *ob_child);
359
360 /* return ModifierMode flag */
361 int BKE_object_is_modified(struct Scene *scene, struct Object *ob);
362 int BKE_object_is_deform_modified(struct Scene *scene, struct Object *ob);
363
364 bool BKE_object_moves_in_time(const struct Object *object, bool recurse_parent);
365
366 int BKE_object_scenes_users_get(struct Main *bmain, struct Object *ob);
367
368 struct MovieClip *BKE_object_movieclip_get(struct Scene *scene,
369                                            struct Object *ob,
370                                            bool use_default);
371
372 void BKE_object_runtime_reset(struct Object *object);
373 void BKE_object_runtime_reset_on_copy(struct Object *object, const int flag);
374 void BKE_object_runtime_free_data(struct Object *object);
375
376 void BKE_object_batch_cache_dirty_tag(struct Object *ob);
377 void BKE_object_data_batch_cache_dirty_tag(struct ID *object_data);
378
379 /* this function returns a superset of the scenes selection based on relationships */
380
381 typedef enum eObRelationTypes {
382   OB_REL_NONE = 0,                      /* Just the selection as is. */
383   OB_REL_PARENT = (1 << 0),             /* Immediate parent. */
384   OB_REL_PARENT_RECURSIVE = (1 << 1),   /* Parents up to root of selection tree. */
385   OB_REL_CHILDREN = (1 << 2),           /* Immediate children. */
386   OB_REL_CHILDREN_RECURSIVE = (1 << 3), /* All children. */
387   OB_REL_MOD_ARMATURE = (1 << 4),       /* Armatures related to the selected objects. */
388   // OB_REL_SCENE_CAMERA = (1 << 5), /* You might want the scene camera too even if unselected? */
389 } eObRelationTypes;
390
391 typedef enum eObjectSet {
392   OB_SET_SELECTED, /* Selected Objects. */
393   OB_SET_VISIBLE,  /* Visible Objects. */
394   OB_SET_ALL,      /* All Objects. */
395 } eObjectSet;
396
397 struct LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer,
398                                                 eObjectSet objectSet,
399                                                 eObRelationTypes includeFilter);
400 struct LinkNode *BKE_object_groups(struct Main *bmain, struct Scene *scene, struct Object *ob);
401 void BKE_object_groups_clear(struct Main *bmain, struct Scene *scene, struct Object *object);
402
403 struct KDTree_3d *BKE_object_as_kdtree(struct Object *ob, int *r_tot);
404
405 bool BKE_object_modifier_use_time(struct Scene *scene,
406                                   struct Object *ob,
407                                   struct ModifierData *md,
408                                   int dag_eval_mode);
409
410 bool BKE_object_modifier_update_subframe(struct Depsgraph *depsgraph,
411                                          struct Scene *scene,
412                                          struct Object *ob,
413                                          bool update_mesh,
414                                          int parent_recursion,
415                                          float frame,
416                                          int type);
417
418 bool BKE_object_empty_image_frame_is_visible_in_view3d(const struct Object *ob,
419                                                        const struct RegionView3D *rv3d);
420 bool BKE_object_empty_image_data_is_visible_in_view3d(const struct Object *ob,
421                                                       const struct RegionView3D *rv3d);
422
423 /* This is an utility function for Python's object.to_mesh() (the naming is not very clear though).
424  * The result is owned by the object.
425  *
426  * The mesh will be freed when object is re-evaluated or is destroyed. It is possible to force to
427  * clear memory used by this mesh by calling BKE_object_to_mesh_clear().
428  *
429  * If preserve_all_data_layers is truth then the modifier stack is re-evaluated to ensure it
430  * preserves all possible custom data layers.
431  *
432  * NOTE: Dependency graph argument is required when preserve_all_data_layers is truth, and is
433  * ignored otherwise. */
434 struct Mesh *BKE_object_to_mesh(struct Depsgraph *depsgraph,
435                                 struct Object *object,
436                                 bool preserve_all_data_layers);
437
438 void BKE_object_to_mesh_clear(struct Object *object);
439
440 /* This is an utility function for Python's object.to_curve().
441  * The result is owned by the object.
442  *
443  * The curve will be freed when object is re-evaluated or is destroyed. It is possible to force
444  * clear memory used by this curve by calling BKE_object_to_curve_clear().
445  *
446  * If apply_modifiers is true and the object is a curve one, then spline deform modifiers are
447  * applied on the curve control points.
448  */
449 struct Curve *BKE_object_to_curve(struct Object *object,
450                                   struct Depsgraph *depsgraph,
451                                   bool apply_modifiers);
452
453 void BKE_object_to_curve_clear(struct Object *object);
454
455 void BKE_object_check_uuids_unique_and_report(const struct Object *object);
456
457 void BKE_object_modifiers_lib_link_common(void *userData,
458                                           struct Object *ob,
459                                           struct ID **idpoin,
460                                           int cb_flag);
461
462 void BKE_object_replace_data_on_shallow_copy(struct Object *ob, struct ID *new_data);
463
464 struct PartEff;
465 struct PartEff *BKE_object_do_version_give_parteff_245(struct Object *ob);
466
467 bool BKE_object_supports_material_slots(struct Object *ob);
468
469 #ifdef __cplusplus
470 }
471 #endif