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