Blender V5.3
depsgraph_light_linking.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
8
9#pragma once
10
11#include <cstdint>
12
13#include "BLI_map.hh"
14
15#include "BKE_light_linking.h" /* LightLinkingType */
16
17#include "DNA_collection_types.h" /* eCollectionLightLinkingState */
18#include "DNA_object_types.h"
19
20namespace blender {
21
22struct Collection;
24struct Object;
25struct Scene;
26
27namespace deg::light_linking {
28
29namespace internal {
30
31/* Set of light as seen from a receiver perspective. */
32class LightSet {
33 public:
34 /* Maximum possible identifier of a light set. The identifier is 0-based.
35 * The limitation is imposed by the fact that its identifier is converted to a bitmask. */
36 static constexpr int MAX_ID = 63;
37
38 /* Identifier of a light set which is not explicitly linked to anything. */
39 static constexpr int DEFAULT_ID = 0;
40
41 bool operator==(const LightSet &other) const;
42 bool operator!=(const LightSet &other) const
43 {
44 return !(*this == other);
45 }
46
47 uint64_t hash() const;
48
49 /* Lights which are explicitly included/excluded into the light set.
50 *
51 * The light is denoted as a bit mask of a light linking collection. This mask is allocated for
52 * every unique light linking collection on an emitter. */
55};
56
58 public:
59 /* Bitmask which indicates the emitter belongs to all light sets. */
60 static constexpr uint64_t SET_MEMBERSHIP_ALL = ~uint64_t(0);
61
62 /* Get final membership mask in the light sets, considering its inclusion and exclusion. */
63 uint64_t get_mask() const;
64
65 /* Bit masks of the emitter membership in the light sets. */
68};
69
70/* Packed information about emitter.
71 * Emitter is actually corresponding to a light linking collection on an object. */
73 public:
74 /* Maximum possible identifier of a light linking collection. The identifier is 0-based.
75 * The limitation is imposed by the fact that its identifier is converted to a bitmask. */
76 static constexpr int MAX_COLLECTION_ID = 63;
77
78 /* Mask of a light linking collection this emitter uses in its configuration.
79 * A single bit is set in this bit-field which corresponds to an identifier of a light linking
80 * collection in the scene. */
82
83 /* Membership masks for the light and shadow linking. */
86};
87
88/* Helper class which deals with keeping per-emitter data. */
91
92 public:
93 explicit EmitterDataMap(const LightLinkingType link_type) : link_type_(link_type) {}
94
95 /* Returns true if there is no information about emitters at all. */
96 bool is_empty() const
97 {
98 return emitter_data_map_.is_empty();
99 }
100
101 /* Entirely clear the state, become ready for a new light linking relations build. */
102 void clear();
103
104 /* Ensure that the data exists for the given emitter.
105 * The emitter must be original and have light linking collection.
106 *
107 * Note that there is limited number of emitters possible within a scene, When this number is
108 * exceeded an error is printed and a nullptr is returned. */
109 EmitterData *ensure_data_if_possible(const Scene &scene, const Object &emitter);
110
111 /* Get emitter data for the given original or evaluated object.
112 * If the light linking is not configured for this emitted nullptr is returned. */
113 const EmitterData *get_data(const Object &emitter) const;
114
115 /* Returns true if the underlying data of the light linking emitter has been handled, and there
116 * is no need to handle the emitter.
117 * The emitter must be original object. */
118 bool can_skip_emitter(const Object &emitter) const;
119
120 /* Returns an iterator over all emitter data in the map. */
121 MapType::MutableValueIterator values()
122 {
123 return emitter_data_map_.values();
124 }
125
126 private:
127 /* Get linked collection depending on whether this is emitter information for light or shadow
128 * linking. */
129 /* TODO(sergey): Check whether template specialization is preferred here. */
130 const Collection *get_collection(const Object &emitter) const
131 {
132 return BKE_light_linking_collection_get(&emitter, link_type_);
133 }
134
136
137 /* Emitter-centric information: indexed by an original emitter object, contains accumulated
138 * information about emitter. */
139 MapType emitter_data_map_;
140
141 /* Next unique light linking collection ID. */
142 uint64_t next_collection_id_ = 0;
143};
144
145/* Common part of receiver (for light linking) and blocker (for shadow lining) data. */
147 public:
148 explicit LinkingData(const LightLinkingType link_type) : link_type_(link_type) {}
149
150 /* Entirely clear the state, become ready for a new light linking relations build. */
151 void clear();
152
153 /* Link the given object with the given light linking state. */
154 void link_object(const EmitterData &emitter_data,
156 const Object &object);
157
158 /* Compute unique sets of emitters used by receivers or blockers.
159 *
160 * This must be called at the end of depsgraph relations build after all emitters have been
161 * added, and before runtime data can be set as part of evaluation. */
162 void end_build(const Scene &scene, EmitterDataMap &emitter_data_map);
163
164 /* Get an unique index the given object is receiving light or casting shadow from.
165 * The object can either be original or evaluated.
166 *
167 * If the object is not linked to any emitter LightSet::DEFAULT_ID is returned. */
168 uint64_t get_light_set_for(const Object &object) const;
169
170 private:
171 /* Ensure that the light set exists for the given receiver/blocker object.
172 * The object must be original. */
173 LightSet &ensure_light_set_for(const Object &object);
174
175 /* Update the emitter light/shadow set membership after the final unique light set identifier
176 * is known.
177 * The light_set_mask consists of a single bit set corresponding to the light set index. */
178 void update_emitters_membership(EmitterDataMap &emitter_data_map,
179 const LightSet &light_set,
180 uint64_t light_set_mask);
181
182 /* Clear data which is only needed during the build. */
183 void clear_after_build();
184
185 /* Get light set membership information of the emitter data depending whether this linking
186 * data is a light or shadow linking. */
187 /* TODO(sergey): Check whether template specialization is preferred here. */
188 EmitterSetMembership &get_emitter_set_membership(EmitterData &emitter_data) const
189 {
190 if (link_type_ == LIGHT_LINKING_BLOCKER) {
191 return emitter_data.shadow_membership;
192 }
193
194 return emitter_data.light_membership;
195 }
196
198
199 /* Receiver/blocker-centric view of light sets: indexed by an original receiver object, contains
200 * light set which defines from which emitters it receives light from or casts shadow when is lit
201 * ny.
202 *
203 * NOTE: Only available during build. */
204 Map<const Object *, LightSet> light_linked_sets_;
205
206 /* Map from an original receiver/blocker object: map to index of light set for this
207 * receiver/blocker. */
208 /* TODO(sergey): What is the generic term for receiver and blocker which is less generic than
209 * object? */
210 Map<const Object *, uint64_t> object_light_sets_;
211};
212
213} // namespace internal
214
215/* Cached light linking evaluation data.
216 *
217 * This cache is only valid within a specific dependency graph, hence the dependency graph is
218 * expected to own this cache.
219 *
220 * This cache takes care of making it efficient to lookup emitter masks, emitters which affect
221 * given receiver and so on. */
222class Cache {
223 using EmitterData = internal::EmitterData;
224 using EmitterDataMap = internal::EmitterDataMap;
225 using LinkingData = internal::LinkingData;
226
227 public:
228 /* Entirely clear the cache.
229 * Should be called whenever the dependency graph is being re-built, in the beginning of the
230 * build process. */
231 void clear();
232
233 /* Add emitter to the cache.
234 *
235 * This call does nothing if the emitter does not have light configured linking (as in, if it
236 * has light linking collection set to nullptr).
237 *
238 * The emitter must be original. This is asserted, but in release builds passing evaluated
239 * object leads to an undefined behavior. */
240 void add_emitter(const Scene &scene, const Object &emitter);
241
242 /* Compute unique sets of emitters used by receivers and blockers.
243 *
244 * This must be called at the end of depsgraph relations build after all emitters have been
245 * added, and before runtime data can be set as part of evaluation. */
246 void end_build(const Scene &scene);
247
248 /* Set runtime light linking data on evaluated object. */
249 void eval_runtime_data(Object &object_eval) const;
250
251 private:
252 /* Add emitter information specific for light and shadow linking. */
253 void add_light_linking_emitter(const Scene &scene, const Object &emitter);
254 void add_shadow_linking_emitter(const Scene &scene, const Object &emitter);
255
256 /* Add receiver or blocker object with the given light linking configuration.
257 *
258 * The term receiver here is meant in a wider meaning of it. For the light linking it is a
259 * receiver of light, but for the shadow linking is it actually a shadow caster. */
260 void add_receiver_object(const EmitterData &emitter_data,
261 const CollectionLightLinking &collection_light_linking,
262 const Object &receiver);
263 void add_blocker_object(const EmitterData &emitter_data,
264 const CollectionLightLinking &collection_light_linking,
265 const Object &blocker);
266
267 /* Returns true if there is light linking configuration in the scene. */
268 bool has_light_linking() const
269 {
270 return !light_emitter_data_map_.is_empty() || !shadow_emitter_data_map_.is_empty();
271 }
272
273 /* Per-emitter light and shadow linking information. */
274 EmitterDataMap light_emitter_data_map_{LIGHT_LINKING_RECEIVER};
275 EmitterDataMap shadow_emitter_data_map_{LIGHT_LINKING_BLOCKER};
276
277 /* Light and shadow linking data. */
278 LinkingData light_linking_{LIGHT_LINKING_RECEIVER};
279 LinkingData shadow_linking_{LIGHT_LINKING_BLOCKER};
280};
281
282} // namespace deg::light_linking
283
284} // namespace blender
Object groups, one object can be in many groups at once.
Object is a sort of wrapper for general info.
void eval_runtime_data(Object &object_eval) const
void add_emitter(const Scene &scene, const Object &emitter)
EmitterData * ensure_data_if_possible(const Scene &scene, const Object &emitter)
const EmitterData * get_data(const Object &emitter) const
void end_build(const Scene &scene, EmitterDataMap &emitter_data_map)
void link_object(const EmitterData &emitter_data, eCollectionLightLinkingState link_state, const Object &object)
BMesh Iterators.
unsigned __int64 uint64_t
Definition BKE_text.h:91
struct Collection * BKE_light_linking_collection_get(const struct Object *object, LightLinkingType link_type)
#define hash
Definition noise_c.cc:156