source/dng_area_task.h - platform/external/dng_sdk - Git at Google

 /*****************************************************************************/
 // 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

 /*****************************************************************************/
	/*****************************************************************************/
	// 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

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