Debian Codegraph @

core/libs/dngwriter/extra/dng_sdk/dng_area_task.h

raw
1 /*****************************************************************************/
2 // Copyright 2006-2022 Adobe Systems Incorporated
3 // All Rights Reserved.
4 //
5 // NOTICE: Adobe permits you to use, modify, and distribute this file in
6 // accordance with the terms of the Adobe license agreement accompanying it.
7 /*****************************************************************************/
8
9 /** \file
10 * Class to handle partitioning a rectangular image processing operation taking
11 * into account multiple processing resources and memory constraints.
12 */
13
14 /*****************************************************************************/
15
16 #ifndef __dng_area_task__
17 #define __dng_area_task__
18
19 /*****************************************************************************/
20
21 #include "dng_classes.h"
22 #include "dng_image.h"
23 #include "dng_point.h"
24 #include "dng_string.h"
25 #include "dng_types.h"
26 #include "dng_uncopyable.h"
27
28 #include <functional>
29 #include <vector>
30
31 /*****************************************************************************/
32
33 class dng_area_task_progress: private dng_uncopyable
34 {
35
36 public:
37
38 virtual ~dng_area_task_progress ()
39 {
40 }
41
42 virtual void FinishedTile (const dng_rect & /* tile */) = 0;
43
44 };
45
46 /*****************************************************************************/
47
48 /// @brief Abstract class for rectangular processing operations with support
49 /// for partitioning across multiple processing resources and observing memory
50 /// constraints.
51
52 class dng_area_task
53 {
54
55 protected:
56
57 uint32 fMaxThreads;
58
59 uint32 fMinTaskArea;
60
61 dng_point fUnitCell;
62
63 dng_point fMaxTileSize;
64
65 dng_string fName;
66
67 public:
68
69 explicit dng_area_task (const char *name = "unnamed dng_area_task");
70
71 virtual ~dng_area_task ();
72
73 const char * Name () const
74 {
75 return fName.Get ();
76 }
77
78 /// Getter for the maximum number of threads (resources) that can be
79 /// used for processing
80 ///
81 /// \retval Number of threads, minimum of 1, that can be used for this task.
82
83 virtual uint32 MaxThreads () const
84 {
85 return fMaxThreads;
86 }
87
88 /// Getter for minimum area of a partitioned rectangle.
89 /// Often it is not profitable to use more resources if it requires
90 /// partitioning the input into chunks that are too small, as the
91 /// overhead increases more than the speedup. This method can be
92 /// ovreridden for a specific task to indicate the smallest area for
93 /// partitioning. Default is 256x256 pixels.
94 ///
95 /// \retval Minimum area for a partitoned tile in order to give performant
96 /// operation. (Partitions can be smaller due to small inputs and edge cases.)
97
98 virtual uint32 MinTaskArea () const
99 {
100 return fMinTaskArea;
101 }
102
103 /// Getter for dimensions of which partitioned tiles should be a multiple.
104 /// Various methods of processing prefer certain alignments. The
105 /// partitioning attempts to construct tiles such that the sizes are a
106 /// multiple of the dimensions of this point.
107 ///
108 /// \retval a point giving preferred alignment in x and y
109
110 virtual dng_point UnitCell () const
111 {
112 return fUnitCell;
113 }
114
115 /// Getter for maximum size of a tile for processing.
116 /// Often processing will need to allocate temporary buffers or use
117 /// other resources that are either fixed or in limited supply. The
118 /// maximum tile size forces further partitioning if the tile is bigger
119 /// than this size.
120 ///
121 /// \retval Maximum tile size allowed for this area task.
122
123 virtual dng_point MaxTileSize () const
124 {
125 return fMaxTileSize;
126 }
127
128 /// Getter for RepeatingTile1.
129 /// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to
130 /// establish a set of 0 to 3 tile patterns for which the resulting
131 /// partitions that the final Process method is called on will not cross
132 /// tile boundaries in any of the tile patterns. This can be used for a
133 /// processing routine that needs to read from two tiles and write to a
134 /// third such that all the tiles are aligned and sized in a certain
135 /// way. A RepeatingTile value is valid if it is non-empty. Higher
136 /// numbered RepeatingTile patterns are only used if all lower ones are
137 /// non-empty. A RepeatingTile pattern must be a multiple of UnitCell in
138 /// size for all constraints of the partitioner to be met.
139
140 virtual dng_rect RepeatingTile1 () const;
141
142 /// Getter for RepeatingTile2.
143 /// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to
144 /// establish a set of 0 to 3 tile patterns for which the resulting
145 /// partitions that the final Process method is called on will not cross
146 /// tile boundaries in any of the tile patterns. This can be used for a
147 /// processing routine that needs to read from two tiles and write to a
148 /// third such that all the tiles are aligned and sized in a certain
149 /// way. A RepeatingTile value is valid if it is non-empty. Higher
150 /// numbered RepeatingTile patterns are only used if all lower ones are
151 /// non-empty. A RepeatingTile pattern must be a multiple of UnitCell in
152 /// size for all constraints of the partitioner to be met.
153
154 virtual dng_rect RepeatingTile2 () const;
155
156 /// Getter for RepeatingTile3.
157 /// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to
158 /// establish a set of 0 to 3 tile patterns for which the resulting
159 /// partitions that the final Process method is called on will not cross
160 /// tile boundaries in any of the tile patterns. This can be used for a
161 /// processing routine that needs to read from two tiles and write to a
162 /// third such that all the tiles are aligned and sized in a certain
163 /// way. A RepeatingTile value is valid if it is non-empty. Higher
164 /// numbered RepeatingTile patterns are only used if all lower ones are
165 /// non-empty. A RepeatingTile pattern must be a multiple of UnitCell in
166 /// size for all constraints of the partitioner to be met.
167
168 virtual dng_rect RepeatingTile3 () const;
169
170 /// Task startup method called before any processing is done on partitions.
171 /// The Start method is called before any processing is done and can be
172 /// overridden to allocate temporary buffers, etc.
173 ///
174 /// \param threadCount Total number of threads that will be used for processing.
175 /// Less than or equal to MaxThreads.
176 /// \param dstArea Area to be processed in the current run of the task.
177 /// \param tileSize Size of source tiles which will be processed.
178 /// (Not all tiles will be this size due to edge conditions.)
179 /// \param allocator dng_memory_allocator to use for allocating temporary buffers, etc.
180 /// \param sniffer Sniffer to test for user cancellation and to set up progress.
181
182 virtual void Start (uint32 threadCount,
183 const dng_rect &dstArea,
184 const dng_point &tileSize,
185 dng_memory_allocator *allocator,
186 dng_abort_sniffer *sniffer);
187
188 /// Process one tile or fully partitioned area. This method is
189 /// overridden by derived classes to implement the actual image
190 /// processing. Note that the sniffer can be ignored if it is certain
191 /// that a processing task will complete very quickly. This method
192 /// should never be called directly but rather accessed via Process.
193 /// There is no allocator parameter as all allocation should be done in
194 /// Start.
195 ///
196 /// \param threadIndex 0 to threadCount - 1 index indicating which thread this is.
197 /// (Can be used to get a thread-specific buffer allocated in the Start method.)
198 /// \param tile Area to process.
199 /// \param sniffer dng_abort_sniffer to use to check for user cancellation
200 /// and progress updates.
201
202 virtual void Process (uint32 threadIndex,
203 const dng_rect &tile,
204 dng_abort_sniffer *sniffer) = 0;
205
206 /// Task computation finalization and teardown method. Called after all
207 /// resources have completed processing. Can be overridden to accumulate
208 /// results and free resources allocated in Start.
209 ///
210 /// \param threadCount Number of threads used for processing. Same as value passed to Start.
211
212 virtual void Finish (uint32 threadCount);
213
214 /// Find tile size taking into account repeating tiles, unit cell, and maximum tile size.
215 /// \param area Computation area for which to find tile size.
216 /// \retval Tile size as height and width in point.
217
218 dng_point FindTileSize (const dng_rect &area) const;
219
220 /// Handle one resource's worth of partitioned tiles. Called after
221 /// thread partitioning has already been done. Area may be further
222 /// subdivided to handle maximum tile size, etc. It will be rare to
223 /// override this method.
224 ///
225 /// \param threadIndex 0 to threadCount - 1 index indicating which thread this is.
226 /// \param area Tile area partitioned to this resource.
227 /// \param tileSize size of tiles to use for processing.
228 /// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.
229 /// \param progress optional pointer to progress reporting object.
230
231 void ProcessOnThread (uint32 threadIndex,
232 const dng_rect &area,
233 const dng_point &tileSize,
234 dng_abort_sniffer *sniffer,
235 dng_area_task_progress *progress);
236
237 /// Factory method to make a tile iterator. This iterator will be used
238 /// by a thread to process tiles in an area in a specific order. The
239 /// default implementation uses a forward iterator that visits tiles
240 /// from left to right (inner), top down (outer). Subclasses can
241 /// override this method to produce tile iterators that visit tiles in
242 /// different orders.
243 ///
244 /// \param threadIndex 0 to threadCount - 1 index indicating which thread this is.
245 /// \param tile The tile to be traversed within the tile area.
246 /// \param area Tile area partitioned to this resource.
247
248 virtual dng_base_tile_iterator * MakeTileIterator (uint32 threadIndex,
249 const dng_rect &tile,
250 const dng_rect &area) const;
251
252 /// Factory method to make a tile iterator. This iterator will be used
253 /// by a thread to process tiles in an area in a specific order. The
254 /// default implementation uses a forward iterator that visits tiles
255 /// from left to right (inner), top down (outer). Subclasses can
256 /// override this method to produce tile iterators that visit tiles in
257 /// different orders.
258 ///
259 /// \param threadIndex 0 to threadCount - 1 index indicating which thread this is.
260 /// \param tileSize The tile size to be traversed within the tile area.
261 /// \param area Tile area partitioned to this resource.
262
263 virtual dng_base_tile_iterator * MakeTileIterator (uint32 threadIndex,
264 const dng_point &tileSize,
265 const dng_rect &area) const;
266
267 /// Default resource partitioner that assumes a single resource to be
268 /// used for processing. Implementations that are aware of multiple
269 /// processing resources should override (replace) this method. This is
270 /// usually done in dng_host::PerformAreaTask.
271 ///
272 /// \param task The task to perform.
273 /// \param area The area on which mage processing should be performed.
274 /// \param allocator dng_memory_allocator to use for allocating temporary buffers, etc.
275 /// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.
276 /// \param progress optional pointer to progress reporting object.
277
278 static void Perform (dng_area_task &task,
279 const dng_rect &area,
280 dng_memory_allocator *allocator,
281 dng_abort_sniffer *sniffer,
282 dng_area_task_progress *progress);
283
284 };
285
286 /*****************************************************************************/
287
288 class dng_range_parallel_task: public dng_area_task, dng_uncopyable
289 {
290
291 private:
292
293 static const int32 kDummySize = 16;
294
295 protected:
296
297 dng_host &fHost;
298
299 const int32 fStartIndex;
300 const int32 fStopIndex;
301
302 std::vector<int32> fIndices;
303
304 public:
305
306 dng_range_parallel_task (dng_host &host,
307 int32 startIndex,
308 int32 stopIndex,
309 const char *name = NULL);
310
311 void Run ();
312
313 virtual uint32 RecommendedThreadCount () const;
314
315 virtual int32 MinIndicesPerThread () const;
316
317 virtual void Prepare (uint32 threadCount,
318 dng_memory_allocator *allocator,
319 dng_abort_sniffer *sniffer);
320
321 virtual void ProcessRange (uint32 threadIndex,
322 int32 startIndex,
323 int32 stopIndex,
324 dng_abort_sniffer *sniffer) = 0;
325
326 void Start (uint32 threadCount,
327 const dng_rect &dstArea,
328 const dng_point &tileSize,
329 dng_memory_allocator *allocator,
330 dng_abort_sniffer *sniffer) override;
331
332 void Process (uint32 threadIndex,
333 const dng_rect & /* tile */,
334 dng_abort_sniffer *sniffer) override;
335
336 public:
337
338 class info
339 {
340
341 public:
342
343 int32 fBegin;
344 int32 fEnd;
345 uint32 fMinIndicesPerThread;
346 uint32 fRecommendedThreadCount; // 0 = automatic
347
348 public:
349
350 info (int32 begin,
351 int32 end,
352 uint32 minIndicesPerThread = 1,
353 uint32 recommendedThreadCount = 0)
354
355 : fBegin (begin)
356 , fEnd (end)
357 , fMinIndicesPerThread (minIndicesPerThread)
358 , fRecommendedThreadCount (recommendedThreadCount)
359
360 {
361
362 }
363
364 };
365
366 struct range
367 {
368 uint32 fThreadIndex;
369 int32 fBegin;
370 int32 fEnd;
371 dng_abort_sniffer *fSniffer;
372 };
373
374 typedef std::function<void(const range &)> function_t;
375
376 static void Do (dng_host &host,
377 const info &params,
378 const char *taskName,
379 const function_t &func);
380
381 };
382
383 /*****************************************************************************/
384
385 class dng_get_buffer_task : public dng_area_task
386 {
387
388 private:
389
390 const dng_image &fSrc;
391
392 dng_pixel_buffer &fDst;
393
394 const dng_image::edge_option fEdgeOption;
395
396 public:
397
398 dng_get_buffer_task (const dng_image &image,
399 dng_pixel_buffer &buffer,
400 dng_image::edge_option edgeOption = dng_image::edge_repeat)
401
402 : dng_area_task ("dng_get_buffer_task")
403
404 , fSrc (image)
405 , fDst (buffer)
406
407 , fEdgeOption (edgeOption)
408
409 {
410
411 }
412
413 dng_rect RepeatingTile1 () const override;
414
415 void Process (uint32 /* threadIndex */,
416 const dng_rect &tile,
417 dng_abort_sniffer * /* sniffer */) override;
418
419 };
420
421 /*****************************************************************************/
422
423 class dng_copy_buffer_task : public dng_area_task
424 {
425
426 private:
427
428 const dng_pixel_buffer &fSrc;
429
430 dng_pixel_buffer &fDst;
431
432 public:
433
434 dng_copy_buffer_task (const dng_pixel_buffer &src,
435 dng_pixel_buffer &dst);
436
437 dng_rect RepeatingTile1 () const override;
438
439 void Process (uint32 /* threadIndex */,
440 const dng_rect &tile,
441 dng_abort_sniffer * /* sniffer */) override;
442
443 };
444
445 /*****************************************************************************/
446
447 class dng_put_buffer_task : public dng_area_task
448 {
449
450 private:
451
452 const dng_pixel_buffer &fSrc;
453
454 dng_image &fDst;
455
456 public:
457
458 dng_put_buffer_task (const dng_pixel_buffer &buffer,
459 dng_image &image)
460
461 : dng_area_task ("dng_put_buffer_task")
462
463 , fSrc (buffer)
464
465 , fDst (image)
466
467 {
468
469 }
470
471 dng_rect RepeatingTile1 () const override;
472
473 void Process (uint32 /* threadIndex */,
474 const dng_rect &tile,
475 dng_abort_sniffer * /* sniffer */) override;
476
477 };
478
479 /*****************************************************************************/
480
481 #endif // __dng_area_task__
482
483 /*****************************************************************************/