1 /*****************************************************************************/
2 // Copyright 2006 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 /* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_area_task.h#1 $ */
10 /* $DateTime: 2012/05/30 13:28:51 $ */
11 /* $Change: 832332 $ */
12 /* $Author: tknoll $ */
13 
14 /** \file
15  * Class to handle partitioning a rectangular image processing operation taking into account multiple processing resources and memory constraints.
16  */
17 
18 /*****************************************************************************/
19 
20 #ifndef __dng_area_task__
21 #define __dng_area_task__
22 
23 /*****************************************************************************/
24 
25 #include "dng_classes.h"
26 #include "dng_point.h"
27 #include "dng_types.h"
28 
29 /*****************************************************************************/
30 
31 /// \brief Abstract class for rectangular processing operations with support for partitioning across multiple processing resources and observing memory constraints.
32 
33 class dng_area_task
34 	{
35 
36 	protected:
37 
38 		uint32 fMaxThreads;
39 
40 		uint32 fMinTaskArea;
41 
42 		dng_point fUnitCell;
43 
44 		dng_point fMaxTileSize;
45 
46 	public:
47 
48 		dng_area_task ();
49 
50 		virtual ~dng_area_task ();
51 
52 		/// Getter for the maximum number of threads (resources) that can be used for processing
53 		///
54 		/// \retval Number of threads, minimum of 1, that can be used for this task.
55 
MaxThreads()56 		virtual uint32 MaxThreads () const
57 			{
58 			return fMaxThreads;
59 			}
60 
61 		/// Getter for minimum area of a partitioned rectangle.
62 		/// Often it is not profitable to use more resources if it requires partitioning the input into chunks that are too small,
63 		/// as the overhead increases more than the speedup. This method can be ovreridden for a specific task to indicate the smallest
64 		/// area for partitioning. Default is 256x256 pixels.
65 		///
66 		/// \retval Minimum area for a partitoned tile in order to give performant operation. (Partitions can be smaller due to small inputs and edge cases.)
67 
MinTaskArea()68 		virtual uint32 MinTaskArea () const
69 			{
70 			return fMinTaskArea;
71 			}
72 
73 		/// Getter for dimensions of which partitioned tiles should be a multiple.
74 		/// Various methods of processing prefer certain alignments. The partitioning attempts to construct tiles such that the
75 		/// sizes are a multiple of the dimensions of this point.
76 		///
77 		/// \retval a point giving preferred alignment in x and y
78 
UnitCell()79 		virtual dng_point UnitCell () const
80 			{
81 			return fUnitCell;
82 			}
83 
84 		/// Getter for maximum size of a tile for processing.
85 		/// Often processing will need to allocate temporary buffers or use other resources that are either fixed or in limited supply.
86 		/// The maximum tile size forces further partitioning if the tile is bigger than this size.
87 		///
88 		/// \retval Maximum tile size allowed for this area task.
89 
MaxTileSize()90 		virtual dng_point MaxTileSize () const
91 			{
92 			return fMaxTileSize;
93 			}
94 
95 		/// Getter for RepeatingTile1.
96 		/// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to establish a set of 0 to 3 tile patterns for which
97 		/// the resulting partitions that the final Process method is called on will not cross tile boundaries in any of the
98 		/// tile patterns. This can be used for a processing routine that needs to read from two tiles and write to a third
99 		/// such that all the tiles are aligned and sized in a certain way. A RepeatingTile value is valid if it is non-empty.
100 		/// Higher numbered RepeatingTile patterns are only used if all lower ones are non-empty. A RepeatingTile pattern must
101 		/// be a multiple of UnitCell in size for all constraints of the partitionerr to be met.
102 
103 		virtual dng_rect RepeatingTile1 () const;
104 
105 		/// Getter for RepeatingTile2.
106 		/// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to establish a set of 0 to 3 tile patterns for which
107 		/// the resulting partitions that the final Process method is called on will not cross tile boundaries in any of the
108 		/// tile patterns. This can be used for a processing routine that needs to read from two tiles and write to a third
109 		/// such that all the tiles are aligned and sized in a certain way. A RepeatingTile value is valid if it is non-empty.
110 		/// Higher numbered RepeatingTile patterns are only used if all lower ones are non-empty. A RepeatingTile pattern must
111 		/// be a multiple of UnitCell in size for all constraints of the partitionerr to be met.
112 
113 		virtual dng_rect RepeatingTile2 () const;
114 
115 		/// Getter for RepeatingTile3.
116 		/// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to establish a set of 0 to 3 tile patterns for which
117 		/// the resulting partitions that the final Process method is called on will not cross tile boundaries in any of the
118 		/// tile patterns. This can be used for a processing routine that needs to read from two tiles and write to a third
119 		/// such that all the tiles are aligned and sized in a certain way. A RepeatingTile value is valid if it is non-empty.
120 		/// Higher numbered RepeatingTile patterns are only used if all lower ones are non-empty. A RepeatingTile pattern must
121 		/// be a multiple of UnitCell in size for all constraints of the partitionerr to be met.
122 
123 		virtual dng_rect RepeatingTile3 () const;
124 
125 		/// Task startup method called before any processing is done on partitions.
126 		/// The Start method is called before any processing is done and can be overridden to allocate temporary buffers, etc.
127 		///
128 		/// \param threadCount Total number of threads that will be used for processing. Less than or equal to MaxThreads.
129 		/// \param tileSize Size of source tiles which will be processed. (Not all tiles will be this size due to edge conditions.)
130 		/// \param allocator dng_memory_allocator to use for allocating temporary buffers, etc.
131 		/// \param sniffer Sniffer to test for user cancellation and to set up progress.
132 
133 		virtual void Start (uint32 threadCount,
134 							const dng_point &tileSize,
135 							dng_memory_allocator *allocator,
136 							dng_abort_sniffer *sniffer);
137 
138 		/// Process one tile or fully partitioned area.
139 		/// This method is overridden by derived classes to implement the actual image processing. Note that the sniffer can be ignored if it is certain that a
140 		/// processing task will complete very quickly.
141 		/// This method should never be called directly but rather accessed via Process.
142 		/// There is no allocator parameter as all allocation should be done in Start.
143 		///
144 		/// \param threadIndex 0 to threadCount - 1 index indicating which thread this is. (Can be used to get a thread-specific buffer allocated in the Start method.)
145 		/// \param tile Area to process.
146 		/// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.
147 
148 		virtual void Process (uint32 threadIndex,
149 							  const dng_rect &tile,
150 							  dng_abort_sniffer *sniffer) = 0;
151 
152 		/// Task computation finalization and teardown method.
153 		/// Called after all resources have completed processing. Can be overridden to accumulate results and free resources allocated in Start.
154 		///
155 		/// \param threadCount Number of threads used for processing. Same as value passed to Start.
156 
157 		virtual void Finish (uint32 threadCount);
158 
159 		/// Find tile size taking into account repeating tiles, unit cell, and maximum tile size.
160 		/// \param area Computation area for which to find tile size.
161 		/// \retval Tile size as height and width in point.
162 
163 		dng_point FindTileSize (const dng_rect &area) const;
164 
165 		/// Handle one resource's worth of partitioned tiles.
166 		/// Called after thread partitioning has already been done. Area may be further subdivided to handle maximum tile size, etc.
167 		/// It will be rare to override this method.
168 		///
169 		/// \param threadIndex 0 to threadCount - 1 index indicating which thread this is.
170 		/// \param area Tile area partitioned to this resource.
171 		/// \param tileSize
172 		/// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.
173 
174 		void ProcessOnThread (uint32 threadIndex,
175 							  const dng_rect &area,
176 							  const dng_point &tileSize,
177 							  dng_abort_sniffer *sniffer);
178 
179 		/// Default resource partitioner that assumes a single resource to be used for processing.
180 		/// Implementations that are aware of multiple processing resources should override (replace) this method.
181 		/// This is usually done in dng_host::PerformAreaTask .
182 		/// \param task The task to perform.
183 		/// \param area The area on which mage processing should be performed.
184 		/// \param allocator dng_memory_allocator to use for allocating temporary buffers, etc.
185 		/// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.
186 
187 		static void Perform (dng_area_task &task,
188 				  			 const dng_rect &area,
189 				  			 dng_memory_allocator *allocator,
190 				  			 dng_abort_sniffer *sniffer);
191 
192 	};
193 
194 /*****************************************************************************/
195 
196 #endif
197 
198 /*****************************************************************************/
199