/src/dng_sdk/source/dng_area_task.h

Source
/*****************************************************************************/
// Copyright 2006 Adobe Systems Incorporated
// All Rights Reserved.
//
// NOTICE:  Adobe permits you to use, modify, and distribute this file in
// accordance with the terms of the Adobe license agreement accompanying it.
/*****************************************************************************/

/* $Id: //mondo/dng_sdk_1_4/dng_sdk/source/dng_area_task.h#1 $ */ 
/* $DateTime: 2012/05/30 13:28:51 $ */
/* $Change: 832332 $ */
/* $Author: tknoll $ */

/** \file
 * Class to handle partitioning a rectangular image processing operation taking into account multiple processing resources and memory constraints.
 */

/*****************************************************************************/

#ifndef __dng_area_task__
#define __dng_area_task__

/*****************************************************************************/

#include "dng_classes.h"
#include "dng_point.h"
#include "dng_types.h"

/*****************************************************************************/

/// \brief Abstract class for rectangular processing operations with support for partitioning across multiple processing resources and observing memory constraints.

class dng_area_task
  {
  
  protected:
  
    uint32 fMaxThreads;
  
    uint32 fMinTaskArea;
    
    dng_point fUnitCell;
    
    dng_point fMaxTileSize;
    
  public:
  
    dng_area_task ();
    
    virtual ~dng_area_task ();

    /// Getter for the maximum number of threads (resources) that can be used for processing
    ///
    /// \retval Number of threads, minimum of 1, that can be used for this task.

    virtual uint32 MaxThreads () const
      {
      return fMaxThreads;
      }

    /// Getter for minimum area of a partitioned rectangle.
    /// Often it is not profitable to use more resources if it requires partitioning the input into chunks that are too small,
    /// as the overhead increases more than the speedup. This method can be ovreridden for a specific task to indicate the smallest
    /// area for partitioning. Default is 256x256 pixels.
    ///
    /// \retval Minimum area for a partitoned tile in order to give performant operation. (Partitions can be smaller due to small inputs and edge cases.)

    virtual uint32 MinTaskArea () const
      {
      return fMinTaskArea;
      }

    /// Getter for dimensions of which partitioned tiles should be a multiple.
    /// Various methods of processing prefer certain alignments. The partitioning attempts to construct tiles such that the
    /// sizes are a multiple of the dimensions of this point.
    ///
    /// \retval a point giving preferred alignment in x and y

    virtual dng_point UnitCell () const
      {
      return fUnitCell;
      }

    /// Getter for maximum size of a tile for processing.
    /// Often processing will need to allocate temporary buffers or use other resources that are either fixed or in limited supply.
    /// The maximum tile size forces further partitioning if the tile is bigger than this size.
    ///
    /// \retval Maximum tile size allowed for this area task.

    virtual dng_point MaxTileSize () const
      {
      return fMaxTileSize;
      }

    /// Getter for RepeatingTile1.
    /// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to establish a set of 0 to 3 tile patterns for which
    /// the resulting partitions that the final Process method is called on will not cross tile boundaries in any of the
    /// tile patterns. This can be used for a processing routine that needs to read from two tiles and write to a third
    /// such that all the tiles are aligned and sized in a certain way. A RepeatingTile value is valid if it is non-empty.
    /// Higher numbered RepeatingTile patterns are only used if all lower ones are non-empty. A RepeatingTile pattern must
    /// be a multiple of UnitCell in size for all constraints of the partitionerr to be met.

    virtual dng_rect RepeatingTile1 () const;
    
    /// Getter for RepeatingTile2.
    /// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to establish a set of 0 to 3 tile patterns for which
    /// the resulting partitions that the final Process method is called on will not cross tile boundaries in any of the
    /// tile patterns. This can be used for a processing routine that needs to read from two tiles and write to a third
    /// such that all the tiles are aligned and sized in a certain way. A RepeatingTile value is valid if it is non-empty.
    /// Higher numbered RepeatingTile patterns are only used if all lower ones are non-empty. A RepeatingTile pattern must
    /// be a multiple of UnitCell in size for all constraints of the partitionerr to be met.

    virtual dng_rect RepeatingTile2 () const;

    /// Getter for RepeatingTile3.
    /// RepeatingTile1, RepeatingTile2, and RepeatingTile3 are used to establish a set of 0 to 3 tile patterns for which
    /// the resulting partitions that the final Process method is called on will not cross tile boundaries in any of the
    /// tile patterns. This can be used for a processing routine that needs to read from two tiles and write to a third
    /// such that all the tiles are aligned and sized in a certain way. A RepeatingTile value is valid if it is non-empty.
    /// Higher numbered RepeatingTile patterns are only used if all lower ones are non-empty. A RepeatingTile pattern must
    /// be a multiple of UnitCell in size for all constraints of the partitionerr to be met.
    
    virtual dng_rect RepeatingTile3 () const;

    /// Task startup method called before any processing is done on partitions.
    /// The Start method is called before any processing is done and can be overridden to allocate temporary buffers, etc.
    ///
    /// \param threadCount Total number of threads that will be used for processing. Less than or equal to MaxThreads.
    /// \param tileSize Size of source tiles which will be processed. (Not all tiles will be this size due to edge conditions.)
    /// \param allocator dng_memory_allocator to use for allocating temporary buffers, etc.
    /// \param sniffer Sniffer to test for user cancellation and to set up progress.

    virtual void Start (uint32 threadCount,
              const dng_point &tileSize,
              dng_memory_allocator *allocator,
              dng_abort_sniffer *sniffer);

    /// Process one tile or fully partitioned area.
    /// 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
    /// processing task will complete very quickly.
    /// This method should never be called directly but rather accessed via Process.
    /// There is no allocator parameter as all allocation should be done in Start.
    ///
    /// \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.)
    /// \param tile Area to process.
    /// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.

    virtual void Process (uint32 threadIndex,
                const dng_rect &tile,
                dng_abort_sniffer *sniffer) = 0;
    
    /// Task computation finalization and teardown method.
    /// Called after all resources have completed processing. Can be overridden to accumulate results and free resources allocated in Start.
    ///
    /// \param threadCount Number of threads used for processing. Same as value passed to Start.

    virtual void Finish (uint32 threadCount);

    /// Find tile size taking into account repeating tiles, unit cell, and maximum tile size.
    /// \param area Computation area for which to find tile size.
    /// \retval Tile size as height and width in point.

    dng_point FindTileSize (const dng_rect &area) const;

    /// Handle one resource's worth of partitioned tiles. 
    /// Called after thread partitioning has already been done. Area may be further subdivided to handle maximum tile size, etc.
    /// It will be rare to override this method.
    ///
    /// \param threadIndex 0 to threadCount - 1 index indicating which thread this is.
    /// \param area Tile area partitioned to this resource.
    /// \param tileSize
    /// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.

    void ProcessOnThread (uint32 threadIndex,
                const dng_rect &area,
                const dng_point &tileSize,
                dng_abort_sniffer *sniffer);

    /// Default resource partitioner that assumes a single resource to be used for processing.
    /// Implementations that are aware of multiple processing resources should override (replace) this method.
    /// This is usually done in dng_host::PerformAreaTask .
    /// \param task The task to perform.
    /// \param area The area on which mage processing should be performed.
    /// \param allocator dng_memory_allocator to use for allocating temporary buffers, etc.
    /// \param sniffer dng_abort_sniffer to use to check for user cancellation and progress updates.

    static void Perform (dng_area_task &task,
                 const dng_rect &area,
                 dng_memory_allocator *allocator,
                 dng_abort_sniffer *sniffer);

  };

/*****************************************************************************/

#endif
  
/*****************************************************************************/

Line	Count	Source
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
56		virtual uint32 MaxThreads () const
57	0	{
58	0	return fMaxThreads;
59	0	}
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
68		virtual uint32 MinTaskArea () const
69	0	{
70	0	return fMinTaskArea;
71	0	}
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
79		virtual dng_point UnitCell () const
80	58.0k	{
81	58.0k	return fUnitCell;
82	58.0k	}
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
90		virtual dng_point MaxTileSize () const
91	58.0k	{
92	58.0k	return fMaxTileSize;
93	58.0k	}
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		/*****************************************************************************/

Coverage Report

Created: 2026-04-01 06:23