Blender V5.3
IO_abstract_hierarchy_iterator.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2019 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
22
23#pragma once
24
26
27#include "BLI_hash.hh"
28#include "BLI_map.hh"
30#include "BLI_set.hh"
31
32#include "DEG_depsgraph.hh"
33
34#include <string>
35
36namespace blender {
37
38struct Depsgraph;
39struct DupliObject;
40struct ID;
41struct Main;
42struct Object;
43struct ParticleSystem;
44
45namespace io {
46
49
50/* HierarchyContext structs are created by the AbstractHierarchyIterator. Each HierarchyContext
51 * struct contains everything necessary to export a single object to a file. */
53 /*********** Determined during hierarchy iteration: ***************/
54 Object *object; /* Evaluated object. */
59 std::string export_name;
60
61 /* When weak_export=true, the object will be exported only as transform, and only if is an
62 * ancestor of an object with weak_export=false.
63 *
64 * In other words: when weak_export=true but this object has no children, or all descendants also
65 * have weak_export=true, this object (and by recursive reasoning all its descendants) will be
66 * excluded from the export.
67 *
68 * The export hierarchy is kept as close to the hierarchy in Blender as possible. As such, an
69 * object that serves as a parent for another object, but which should NOT be exported itself, is
70 * exported only as transform (i.e. as empty). This happens with objects that are invisible when
71 * exporting with "Visible Only" enabled, for example. */
73
74 /* When true, this object should check its parents for animation data when determining whether
75 * it's animated. This is necessary when a parent object in Blender is not part of the export. */
77
78 /* The flag makes unambiguous the fact that the current context targets object or data. This is
79 * notably used in USDHierarchyIterator::create_usd_export_context: options like
80 * merge_parent_xform option is meaningless for object, it only makes sense for data. */
82
83 /* This flag tells, within a object data context, if an object is the parent of other objects.
84 * This is useful when exporting UsdGeomGprim: those cannot be nested into each other. For
85 * example, an UsdGeomMesh cannot have other UsdGeomMesh as descendants and other hierarchy
86 * strategies need to be adopted.
87 */
89
90 /* When true this is duplisource object. This flag is used to identify instance prototypes. */
92
93 /* This flag tells whether an object is a valid point instance of other objects.
94 * If true, it means the object has a valid reference path and its value can be included
95 * in the instances data of UsdGeomPointInstancer. */
97
98 /* This flag tells if an object is a valid prototype of a point instancer. */
100
101 /* True if this context is a descendant of any context with is_point_instance set to true.
102 * This helps skip redundant instancing data during export. */
104
105 /*********** Determined during writer creation: ***************/
106 float4x4 parent_matrix_inv_world; /* Inverse of the parent's world matrix. */
107 std::string export_path; /* Hierarchical path, such as "/grandparent/parent/object_name". */
108 ParticleSystem *particle_system; /* Only set for particle/hair writers. */
109
110 /* Hierarchical path of the object this object is duplicating; only set when this object should
111 * be stored as a reference to its original. It can happen that the original is not part of the
112 * exported objects, in which case this string is empty even though 'duplicator' is set. */
114
115 /* Export path of the higher-up exported data. For transforms, this is the export path of the
116 * parent object. For object data, this is the export path of that object's transform.
117 *
118 * From the exported file's point of view, this is the path to the parent in that file. The term
119 * "parent" is not used here to avoid confusion with Blender's meaning of the word (which always
120 * refers to a different object). */
122
123 /* Return a HierarchyContext representing the root of the export hierarchy. */
124 static const HierarchyContext *root();
125
126 /* For handling instanced collections, instances created by particles, etc. */
127 bool is_instance() const;
128 void mark_as_instance_of(const std::string &reference_export_path);
130 bool is_prototype() const;
131
132 /* For handling point instancing (Instance on Points geometry node). */
133 bool is_point_instancer() const;
134
135 bool is_object_visible(enum eEvaluationMode evaluation_mode) const;
136};
137
138/* Abstract writer for objects. Create concrete subclasses to write to USD, Alembic, etc.
139 *
140 * Instantiated by the AbstractHierarchyIterator on the first frame an object exists. Generally
141 * that's the first frame to be exported, but can be later, for example when objects are
142 * instantiated by particles. The AbstractHierarchyWriter::write() function is called on every
143 * frame the object exists in the dependency graph and should be exported.
144 */
146 public:
147 virtual ~AbstractHierarchyWriter() = default;
148 virtual void write(HierarchyContext &context) = 0;
149 /* TODO(Sybren): add function like absent() that's called when a writer was previously created,
150 * but wasn't used while exporting the current frame (for example, a particle-instanced mesh of
151 * which the particle is no longer alive). */
152 protected:
153 /* Return true if the data written by this writer changes over time.
154 * Note that this function assumes this is an object data writer. Transform writers should not
155 * call this but implement their own logic. */
156 virtual bool check_is_animated(const HierarchyContext &context) const;
157
158 /* Helper functions for animation checks. */
159 static bool check_has_physics(const HierarchyContext &context);
160 static bool check_has_deforming_physics(const HierarchyContext &context);
161};
162
163/* Determines which subset of the writers actually gets to write. */
165 bool transforms : 1;
166 bool shapes : 1;
167};
168
169/* EnsuredWriter represents an AbstractHierarchyWriter* combined with information whether it was
170 * newly created or not. It's returned by AbstractHierarchyIterator::ensure_writer(). */
171class EnsuredWriter {
172 private:
174
175 /* Is set to truth when ensure_writer() did not find existing writer and created a new one.
176 * Is set to false when writer has been re-used or when allocation of the new one has failed
177 * (`writer` will be `nullptr` in that case and bool(ensured_writer) will be false). */
178 bool newly_created_;
179
181
182 public:
184
185 static EnsuredWriter empty();
186 static EnsuredWriter existing(AbstractHierarchyWriter *writer);
187 static EnsuredWriter newly_created(AbstractHierarchyWriter *writer);
188
189 bool is_newly_created() const;
190
191 /* These operators make an EnsuredWriter* act as an AbstractHierarchyWriter* */
192 operator bool() const;
194};
195
196/* Unique identifier for a (potentially duplicated) object.
197 *
198 * Instances of this class serve as key in the export graph of the
199 * AbstractHierarchyIterator. */
201 public:
203 Object *duplicated_by; /* nullptr for real objects. */
205
206 protected:
208
209 public:
213 static ObjectIdentifier for_duplicated_object(const DupliObject *dupli_object,
215
216 bool is_root() const;
217
219 {
221 }
222};
223
224bool operator==(const ObjectIdentifier &obj_ident_a, const ObjectIdentifier &obj_ident_b);
225
226/* AbstractHierarchyIterator iterates over objects in a dependency graph, and constructs export
227 * writers. These writers are then called to perform the actual writing to a USD or Alembic file.
228 *
229 * Dealing with file- and scene-level data (for example, creating a USD scene, setting the frame
230 * rate, etc.) is not part of the AbstractHierarchyIterator class structure, and should be done
231 * in separate code.
232 */
234 public:
235 /* Mapping from export path to writer. */
237 /* All the children of some object, as per the export hierarchy. */
239 /* Mapping from an object and its duplicator to the object's export-children. */
241 /* Mapping from ID to its export path. This is used for instancing; given an
242 * instanced datablock, the export path of the original can be looked up. */
244 /* Mapping from ID name to a set of names logically residing "under" it. Used for unique
245 * name generation. */
247 /* IDs of all duplisource objects, used to identify instance prototypes. */
249
250 protected:
254 Depsgraph *depsgraph_;
259
260 public:
261 explicit AbstractHierarchyIterator(Main *bmain, Depsgraph *depsgraph);
263
264 /* Iterate over the depsgraph, create writers, and tell the writers to write.
265 * Main entry point for the AbstractHierarchyIterator, must be called for every to-be-exported
266 * (sub)frame. */
267 virtual void iterate_and_write();
268
269 /* Release all writers. Call after all frames have been exported. */
270 void release_writers();
271
272 /* Determine which subset of writers is used for exporting.
273 * Set this before calling iterate_and_write().
274 *
275 * Note that writers are created for each iterated object, regardless of this option. When a
276 * writer is created it will also write the current iteration, to ensure the hierarchy is
277 * complete. The `export_subset` option is only in effect when the writer already existed from a
278 * previous iteration. */
279 void set_export_subset(ExportSubset export_subset);
280
281 /* Convert the given name to something that is valid for the exported file format.
282 * This base implementation is a no-op; override in a concrete subclass. */
283 virtual std::string make_valid_name(const std::string &name) const;
284
285 virtual std::string make_unique_name(const std::string &original_name,
286 Set<std::string> &used_names);
287
288 /* Return the name of this ID datablock that is valid for the exported file format. Overriding is
289 * only necessary if make_valid_name(id->name+2) is not suitable for the exported file format.
290 * NULL-safe: when `id == nullptr` this returns an empty string. */
291 virtual std::string get_id_name(const ID *id) const;
292
293 /* Given a HierarchyContext of some Object *, return an export path that is valid for its
294 * object->data. Overriding is necessary when the exported format does NOT expect the object's
295 * data to be a child of the object. */
296 virtual std::string get_object_data_path(const HierarchyContext *context) const;
297
298 private:
299 void debug_print_export_graph(const ExportGraph &graph) const;
300
301 void export_graph_construct();
302 void connect_loose_objects();
303 void export_graph_prune();
304 void export_graph_clear();
305
306 void visit_object(Object *object, Object *export_parent, bool weak_export);
307 void visit_dupli_object(const DupliObject *dupli_object,
308 Object *duplicator,
309 const DupliParentFinder &dupli_parent_finder);
310
311 void context_update_for_graph_index(HierarchyContext *context,
312 const ObjectIdentifier &graph_index) const;
313
314 void determine_export_paths(const HierarchyContext *parent_context);
315 bool determine_duplication_references(const HierarchyContext *parent_context,
316 const std::string &indent);
317
318 /* These three functions create writers and call their write() method. */
319 void make_writers(const HierarchyContext *parent_context);
320 void make_writer_object_data(const HierarchyContext *context);
321 void make_writers_particle_systems(const HierarchyContext *transform_context);
322
323 /* Return the appropriate HierarchyContext for the data of the object represented by
324 * object_context. */
325 HierarchyContext context_for_object_data(const HierarchyContext *object_context) const;
326
327 /* Convenience wrappers around get_id_name(). */
328 std::string get_object_name(const Object *object) const;
329 std::string get_object_name(const Object *object, const Object *parent);
330 std::string get_object_data_name(const Object *object) const;
331
332 using create_writer_func =
334 /* Ensure that a writer exists; if it doesn't, call create_func(context).
335 *
336 * The create_func function should be one of the create_XXXX_writer(context) functions declared
337 * below. */
338 EnsuredWriter ensure_writer(const HierarchyContext *context, create_writer_func create_func);
339
340 protected:
341 /* Construct a valid path for the export file format. This class concatenates by using '/' as a
342 * path separator, which is valid for both Alembic and USD. */
343 virtual std::string path_concatenate(const std::string &parent_path,
344 const std::string &child_path) const;
345
346 /* Return whether this object should be marked as 'weak export' or not.
347 *
348 * When this returns false, writers for the transform and data are created,
349 * and dupli-objects dupli-object generated from this object will be passed to
350 * should_visit_dupli_object().
351 *
352 * When this returns true, only a transform writer is created and marked as
353 * 'weak export'. In this case, the transform writer will be removed before
354 * exporting starts, unless a descendant of this object is to be exported.
355 * Dupli-object generated from this object will also be skipped.
356 *
357 * See HierarchyContext::weak_export.
358 */
359 virtual bool mark_as_weak_export(const Object *object) const;
360
361 virtual bool should_visit_dupli_object(const DupliObject *dupli_object,
362 const Object *duplicator) const;
363
366 const HierarchyContext *context,
367 const DupliObject *dupli_object,
368 const DupliParentFinder &dupli_parent_finder);
369
370 /* These functions should create an AbstractHierarchyWriter subclass instance, or return
371 * nullptr if the object or its data should not be exported. Returning a nullptr for
372 * data/hair/particle will NOT prevent the transform to be written.
373 *
374 * The returned writer is owned by the AbstractHierarchyWriter, and should be freed in
375 * delete_object_writer().
376 *
377 * The created AbstractHierarchyWriter instances should NOT keep a copy of the context pointer.
378 * The context can be stack-allocated and go out of scope. */
383
384 /* Called by release_writers() to free what the create_XXX_writer() functions allocated. */
385 virtual void release_writer(AbstractHierarchyWriter *writer) = 0;
386
387 /* Return true if data writers should be created for this context. */
388 virtual bool include_data_writers(const HierarchyContext *) const
389 {
390 return true;
391 }
392
393 /* Return true if children of the context should be converted to writers. */
394 virtual bool include_child_writers(const HierarchyContext *) const
395 {
396 return true;
397 }
398
399 AbstractHierarchyWriter *get_writer(const std::string &export_path) const;
401};
402
403} // namespace io
404} // namespace blender
Map< ObjectIdentifier, ExportChildren > ExportGraph
Map< std::string, Set< std::string > > ExportUsedNameMap
virtual ObjectIdentifier determine_graph_index_object(const HierarchyContext *context)
virtual bool include_child_writers(const HierarchyContext *) const
virtual void release_writer(AbstractHierarchyWriter *writer)=0
ExportChildren * graph_children(const HierarchyContext *context)
virtual bool mark_as_weak_export(const Object *object) const
void set_export_subset(ExportSubset export_subset)
virtual std::string get_id_name(const ID *id) const
virtual AbstractHierarchyWriter * create_particle_writer(const HierarchyContext *context)=0
virtual AbstractHierarchyWriter * create_transform_writer(const HierarchyContext *context)=0
AbstractHierarchyIterator(Main *bmain, Depsgraph *depsgraph)
virtual bool should_visit_dupli_object(const DupliObject *dupli_object, const Object *duplicator) const
virtual std::string make_unique_name(const std::string &original_name, Set< std::string > &used_names)
virtual std::string path_concatenate(const std::string &parent_path, const std::string &child_path) const
virtual ObjectIdentifier determine_graph_index_dupli(const HierarchyContext *context, const DupliObject *dupli_object, const DupliParentFinder &dupli_parent_finder)
AbstractHierarchyWriter * get_writer(const std::string &export_path) const
virtual AbstractHierarchyWriter * create_data_writer(const HierarchyContext *context)=0
virtual AbstractHierarchyWriter * create_hair_writer(const HierarchyContext *context)=0
virtual std::string make_valid_name(const std::string &name) const
Map< std::string, AbstractHierarchyWriter * > WriterMap
virtual std::string get_object_data_path(const HierarchyContext *context) const
virtual bool include_data_writers(const HierarchyContext *) const
virtual bool check_is_animated(const HierarchyContext &context) const
virtual void write(HierarchyContext &context)=0
static bool check_has_deforming_physics(const HierarchyContext &context)
virtual ~AbstractHierarchyWriter()=default
static bool check_has_physics(const HierarchyContext &context)
static EnsuredWriter existing(AbstractHierarchyWriter *writer)
static EnsuredWriter newly_created(AbstractHierarchyWriter *writer)
AbstractHierarchyWriter * operator->()
static ObjectIdentifier for_graph_root()
static ObjectIdentifier for_duplicated_object(const DupliObject *dupli_object, Object *duplicated_by)
static ObjectIdentifier for_real_object(Object *object)
static ObjectIdentifier for_hierarchy_context(const HierarchyContext *context)
ObjectIdentifier(Object *object, Object *duplicated_by, const PersistentID &persistent_id)
bool operator==(const Error &left, const Error &right)
BMesh Iterators.
unsigned __int64 uint64_t
Definition BKE_text.h:91
MatBase< float, 4, 4 > float4x4
constexpr uint64_t get_default_hash(const T &v, const Args &...args)
Definition BLI_hash.hh:252
bool is_object_visible(enum eEvaluationMode evaluation_mode) const
static const HierarchyContext * root()
void mark_as_instance_of(const std::string &reference_export_path)