adobe-source-commits

[Foster B. <fos...@us...>]

Update of /cvsroot/adobe-source/adobe-source/adobe/documentation/sources/gil
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv1031/adobe/documentation/sources/gil

Modified Files:
	main.dox 
Added Files:
	design_guide.dox tutorial.dox 
Log Message:
asl 1.0.13

Index: main.dox
===================================================================
RCS file: /cvsroot/adobe-source/adobe-source/adobe/documentation/sources/gil/main.dox,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** main.dox	9 Jan 2006 19:31:34 -0000	1.2
--- main.dox	3 Feb 2006 18:20:42 -0000	1.3
***************
*** 3,59 ****
  \ingroup asl_home
  \author Lubomir Bourdev and Hailin Jin \n
! 		Advanced Graphics Technology \n
! 		Adobe Systems Inc.
! 
! \section gil_toc GIL Table of Contents
! 	- \ref GILConcepts
! 		- \ref PointConcept
! 		- \ref ChannelConcept
! 		- \ref ColorSpaceTypeConcept
! 		- \ref PixelConcept
! 		- \ref IteratorConcept
! 			- \ref IteratorAdaptorConcept
! 			- \ref StepIteratorConcept
! 			- \ref ImageIteratorConcept
! 		- \ref LocatorConcept
! 			- \ref LocatorNDConcept
! 			- \ref Locator2DConcept
! 			- \ref XYLocatorConcept
! 		- \ref ImageViewConcept
! 			- \ref ImageViewNDConcept
! 			- \ref ImageView2DConcept
! 			- \ref GILImageViewConcept
! 		- \ref ImageConcept
! 			- \ref ImageNDConcept
! 			- \ref Image2DConcept
! 			- \ref GILImageConcept
! 	- \ref GILModels
! 		- \ref Channel
! 		- \ref ColorSpaces
! 			- \ref CMYK
! 			- \ref ColorConvert
! 			- \ref GRAY
! 			- \ref LAB
! 			- \ref RGB
! 			- \ref RGBA
! 		- \ref Pixel
! 			- \ref ChannelAccessor
! 			- \ref ColorBase
! 		- \ref Iterators
! 			- \ref PlanarPtr
! 			- \ref IteratorTraits
! 			- \ref ByteOperations
! 				- \ref byte_step
! 				- \ref byte_distance
! 				- \ref byte_advance
! 				- \ref byte_advanced
! 				- \ref byte_advanced_ref
! 		- \ref ImageView
! 			- \ref ImageViewConstructors
! 		- \ref Image
! 		- \ref Variant
! 		- \ref Metafunctions
! 			- \ref type_factory
! 		- \ref Algorithms
  
  \section IntroSec Introduction
--- 3,8 ----
  \ingroup asl_home
  \author Lubomir Bourdev and Hailin Jin \n
!         Advanced Graphics Technology \n
!         Adobe Systems Inc.
  
  \section IntroSec Introduction
***************
*** 63,76 ****
  \par
  The library is designed with the following five goals in mind:
! 	- <b>Generality:</b> Abstracts image representations from algorithms on images. It allows for writing code once and have it work for any image type.
! 	- <b>Performance:</b> Speed has been instrumental to the design of the library. The generic algorithms provided in the library are comparable in speed to hand-coding the algorithm for a specific image type.
! 	- <b>Flexibility:</b> Compile-type parameter resolution results in faster code, but severely limits code flexibility. The library allows for any image parameter to be specified at run time (for a minor performance cost comparable to a virtual call overhead).
! 	- <b>Extensibility:</b> It is easy to extend the library with new color spaces and image types. Library extensions typically require no changes to the library core; at the same time existing image algorithms apply to new color spaces and image types.
! 	- <b>Compatibility:</b> The library is designed as an STL and Boost complement. Generic STL algorithms can be used for pixel manipulation, and they are especially optimized. The library works with existing raw pixel data from another image library and can even be integrated into a third-party reference counting mechanism.
  
  \section ResourcesSec Resources
! 	- \ref BeforeAfterExample "See the GIL difference!" Example of code before and after GIL.
! 	- A tutorial is nearing completion and should be released soon.
! 	- A detailed GIL design guide is also nearing completion and should be released soon.
  
  \section InstallationSec Installation
--- 12,25 ----
  \par
  The library is designed with the following five goals in mind:
!     - <b>Generality:</b> Abstracts image representations from algorithms on images. It allows for writing code once and have it work for any image type.
!     - <b>Performance:</b> Speed has been instrumental to the design of the library. The generic algorithms provided in the library are comparable in speed to hand-coding the algorithm for a specific image type.
!     - <b>Flexibility:</b> Compile-type parameter resolution results in faster code, but severely limits code flexibility. The library allows for any image parameter to be specified at run time (for a minor performance cost comparable to a virtual call overhead).
!     - <b>Extensibility:</b> It is easy to extend the library with new color spaces and image types. Library extensions typically require no changes to the library core; at the same time existing image algorithms apply to new color spaces and image types.
!     - <b>Compatibility:</b> The library is designed as an STL and Boost complement. Generic STL algorithms can be used for pixel manipulation, and they are especially optimized. The library works with existing raw pixel data from another image library and can even be integrated into a third-party reference counting mechanism.
  
  \section ResourcesSec Resources
!     - \ref BeforeAfterExample "See the GIL difference!" Example of code before and after GIL.
!     - A Quick, Hands-on  \ref GILTutorial "Tutorial". (In <a href="gil_tutorial.pdf">PDF</a>)
!     - A Detailed \ref GILDesignGuide "Design Guide". (In <a href="gil_design_guide.pdf">PDF</a>)
  
  \section InstallationSec Installation
***************
*** 80,87 ****
  
  \section AcknowledgementsSec Acknowledgements
! 	- <b>Jon Brandt</b>, <b>Mark Ruzon</b> and <b>Paul McJones</b> spent significant time reviewing the library and documentation and provided valuable feedback.
! 	- <b>Alex Stepanov</b>'s class has directly inspired this project. Alex's "start from the inside" and "bottom up" principles have been applied throughout the design.
! 	- <b>Sean Parent</b> and Alex Stepanov suggested splitting the image into a 'container' and 'range' classes
! 	- <b>Bjarne Stroustrup</b> reviewed the core library design
  */
  
--- 29,87 ----
  
  \section AcknowledgementsSec Acknowledgements
!     - <b>Jon Brandt</b>, <b>Mark Ruzon</b> and <b>Paul McJones</b> spent significant time reviewing the library and documentation and provided valuable feedback.
!     - <b>Alex Stepanov</b>'s class has directly inspired this project. Alex's "start from the inside" and "bottom up" principles have been applied throughout the design.
!     - <b>Sean Parent</b> and Alex Stepanov suggested splitting the image into a 'container' and 'range' classes
!     - <b>Bjarne Stroustrup</b> reviewed the core library design
! 
! \section gil_toc GIL Table of Contents
!     - \ref GILConcepts
!         - \ref PointConcept
!         - \ref ChannelConcept
!         - \ref ColorSpaceTypeConcept
!         - \ref PixelConcept
!         - \ref IteratorConcept
!             - \ref IteratorAdaptorConcept
!             - \ref StepIteratorConcept
!             - \ref ImageIteratorConcept
!         - \ref LocatorConcept
!             - \ref LocatorNDConcept
!             - \ref Locator2DConcept
!             - \ref XYLocatorConcept
!         - \ref ImageViewConcept
!             - \ref ImageViewNDConcept
!             - \ref ImageView2DConcept
!             - \ref GILImageViewConcept
!         - \ref ImageConcept
!             - \ref ImageNDConcept
!             - \ref Image2DConcept
!             - \ref GILImageConcept
!     - \ref GILModels
!         - \ref Channel
!         - \ref ColorSpaces
!             - \ref CMYK
!             - \ref ColorConvert
!             - \ref GRAY
!             - \ref LAB
!             - \ref RGB
!             - \ref RGBA
!         - \ref Pixel
!             - \ref ChannelAccessor
!             - \ref ColorBase
!         - \ref Iterators
!             - \ref PlanarPtr
!             - \ref IteratorTraits
!             - \ref ByteOperations
!                 - \ref byte_step
!                 - \ref byte_distance
!                 - \ref byte_advance
!                 - \ref byte_advanced
!                 - \ref byte_advanced_ref
!         - \ref ImageView
!             - \ref ImageViewConstructors
!         - \ref Image
!         - \ref Variant
!         - \ref Metafunctions
!             - \ref type_factory
!         - \ref Algorithms
  */
  
***************
*** 89,167 ****
  /// \ingroup asl_gil
  /// \brief GIL concept definitions, archetypes and concept checks
! 	/// @defgroup PointConcept Point
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for N-dimensional point and refinement for 2D
  Ê
! 	/// @defgroup ChannelConcept Channel
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for channel and mutable channel
  Ê
! 	/// @defgroup ColorSpaceTypeConcept Color Space
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for color space type
  Ê
! 	/// @defgroup PixelConcept Pixel
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for pixel and mutable pixel
  Ê
! 	/// @defgroup IteratorConcept Iterator
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for iterators over pixels (fundamental, step, adaptor and image-pixel iterators over immutable/mutable pixels)
! 		/// @defgroup IteratorAdaptorConcept Iterator Adaptor
! 		/// @ingroup IteratorConcept
! 		/// \brief Concept for an iterator adaptor over a base iterator
  Ê
! 		/// @defgroup StepIteratorConcept Step Iterator
! 		/// @ingroup IteratorConcept
! 		/// \brief Concept for an iterator that has non-fundamental step
  Ê
! 		/// @defgroup ImageIteratorConcept Image Iterator
! 		/// @ingroup IteratorConcept
! 		/// \brief Concept for an iterator over all pixels in an image
  Ê
! 	/// @defgroup LocatorConcept Locator
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for locator (generalization of iterator in N-dimensional space)
! 		/// @defgroup LocatorNDConcept N-Dimensional Locator
! 		/// @ingroup LocatorConcept
! 		/// \brief Concept for an N-dimensional locator over immutable/mutable values
  Ê
! 		/// @defgroup Locator2DConcept 2-Dimensional Locator
! 		/// @ingroup LocatorConcept
! 		/// \brief Concept for a 2-dimensional locator over immutable/mutable values
  Ê
! 		/// @defgroup XYLocatorConcept GIL's 2-Dimensional Pixel Locator
! 		/// @ingroup LocatorConcept
! 		/// \brief Concept for GIL's 2-dimensional locator over immutable/mutable pixels
  Ê
! 	/// @defgroup ImageViewConcept Image View
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for image view (N-dimensional range)
! 		/// @defgroup ImageViewNDConcept N-Dimensional Image View
! 		/// @ingroup ImageViewConcept
! 		/// \brief Concept for an N-dimensional range over immutable/mutable values
  Ê
! 		/// @defgroup ImageView2DConcept 2-Dimensional Image View
! 		/// @ingroup ImageViewConcept
! 		/// \brief Concept for a 2-dimensional range over immutable/mutable values
  Ê
! 		/// @defgroup GILImageViewConcept GIL's 2-Dimensional Pixel Image View
! 		/// @ingroup ImageViewConcept
! 		/// \brief Concept for GIL's 2-dimensional range over immutable/mutable pixels
  Ê
! 	/// @defgroup ImageConcept Image
! 	/// @ingroup GILConcepts
! 	/// \brief Concept for image (N-dimensional container)
! 		/// @defgroup ImageNDConcept N-Dimensional Image
! 		/// @ingroup ImageConcept
! 		/// \brief Concept for an N-dimensional container of immutable/mutable values
  Ê
! 		/// @defgroup Image2DConcept 2-Dimensional Image
! 		/// @ingroup ImageConcept
! 		/// \brief Concept for a 2-dimensional container of immutable/mutable values
  Ê
! 		/// @defgroup GILImageConcept GIL's 2-Dimensional Pixel Image
! 		/// @ingroup ImageConcept
! 		/// \brief Concept for GIL's 2-dimensional container of immutable/mutable pixels
  Ê
  /// @defgroup GILModels GIL Models
--- 89,167 ----
  /// \ingroup asl_gil
  /// \brief GIL concept definitions, archetypes and concept checks
!     /// @defgroup PointConcept Point
!     /// @ingroup GILConcepts
!     /// \brief Concept for N-dimensional point and refinement for 2D
  Ê
!     /// @defgroup ChannelConcept Channel
!     /// @ingroup GILConcepts
!     /// \brief Concept for channel and mutable channel
  Ê
!     /// @defgroup ColorSpaceTypeConcept Color Space
!     /// @ingroup GILConcepts
!     /// \brief Concept for color space type
  Ê
!     /// @defgroup PixelConcept Pixel
!     /// @ingroup GILConcepts
!     /// \brief Concept for pixel and mutable pixel
  Ê
!     /// @defgroup IteratorConcept Iterator
!     /// @ingroup GILConcepts
!     /// \brief Concept for iterators over pixels (fundamental, step, adaptor and image-pixel iterators over immutable/mutable pixels)
!         /// @defgroup IteratorAdaptorConcept Iterator Adaptor
!         /// @ingroup IteratorConcept
!         /// \brief Concept for an iterator adaptor over a base iterator
  Ê
!         /// @defgroup StepIteratorConcept Step Iterator
!         /// @ingroup IteratorConcept
!         /// \brief Concept for an iterator that has non-fundamental step
  Ê
!         /// @defgroup ImageIteratorConcept Image Iterator
!         /// @ingroup IteratorConcept
!         /// \brief Concept for an iterator over all pixels in an image
  Ê
!     /// @defgroup LocatorConcept Locator
!     /// @ingroup GILConcepts
!     /// \brief Concept for locator (generalization of iterator in N-dimensional space)
!         /// @defgroup LocatorNDConcept N-Dimensional Locator
!         /// @ingroup LocatorConcept
!         /// \brief Concept for an N-dimensional locator over immutable/mutable values
  Ê
!         /// @defgroup Locator2DConcept 2-Dimensional Locator
!         /// @ingroup LocatorConcept
!         /// \brief Concept for a 2-dimensional locator over immutable/mutable values
  Ê
!         /// @defgroup XYLocatorConcept GIL's 2-Dimensional Pixel Locator
!         /// @ingroup LocatorConcept
!         /// \brief Concept for GIL's 2-dimensional locator over immutable/mutable pixels
  Ê
!     /// @defgroup ImageViewConcept Image View
!     /// @ingroup GILConcepts
!     /// \brief Concept for image view (N-dimensional range)
!         /// @defgroup ImageViewNDConcept N-Dimensional Image View
!         /// @ingroup ImageViewConcept
!         /// \brief Concept for an N-dimensional range over immutable/mutable values
  Ê
!         /// @defgroup ImageView2DConcept 2-Dimensional Image View
!         /// @ingroup ImageViewConcept
!         /// \brief Concept for a 2-dimensional range over immutable/mutable values
  Ê
!         /// @defgroup GILImageViewConcept GIL's 2-Dimensional Pixel Image View
!         /// @ingroup ImageViewConcept
!         /// \brief Concept for GIL's 2-dimensional range over immutable/mutable pixels
  Ê
!     /// @defgroup ImageConcept Image
!     /// @ingroup GILConcepts
!     /// \brief Concept for image (N-dimensional container)
!         /// @defgroup ImageNDConcept N-Dimensional Image
!         /// @ingroup ImageConcept
!         /// \brief Concept for an N-dimensional container of immutable/mutable values
  Ê
!         /// @defgroup Image2DConcept 2-Dimensional Image
!         /// @ingroup ImageConcept
!         /// \brief Concept for a 2-dimensional container of immutable/mutable values
  Ê
!         /// @defgroup GILImageConcept GIL's 2-Dimensional Pixel Image
!         /// @ingroup ImageConcept
!         /// \brief Concept for GIL's 2-dimensional container of immutable/mutable pixels
  Ê
  /// @defgroup GILModels GIL Models
***************
*** 169,251 ****
  /// \brief Standard models of GIL concepts
  Ê
! 	/// @defgroup Channel Channel
! 	/// @ingroup GILModels
! 	/// \brief Channel and channel operations
  Ê
! 	/// @defgroup ColorSpaces Color Space
! 	/// @ingroup GILModels
! 	/// \brief Color spaces and color space conversion
  Ê
! 	/// @defgroup Pixel Pixel
! 	/// @ingroup GILModels
! 	/// \brief Pixel and pixel-related functions
  ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ
! 		/// @defgroup ChannelAccessor Channel Accessor
! 		/// @ingroup Pixel
! 		/// \brief Classes allowing accessing a channel of a pixel
  Ê
! 		/// @defgroup ColorBase Color Bases
! 		/// @ingroup Pixel
! 		/// \brief A bundle of channel values/references/pointers of a given color space
  Ê
! 	/// @defgroup Iterators Pixel Iterators
! 	/// @ingroup GILModels
! 	/// \brief Iterators operating on pixels
  Ê
! 		/// @defgroup PlanarPtr Planar Pointers
! 		/// @ingroup Iterators
! 		/// \brief Implementations of pointers to planar pixels
  Ê
! 		/// @defgroup IteratorTraits Iterator Traits
! 		/// @ingroup Iterators
! 		/// \brief Traits for pixel iterators
  Ê
! 		/// @defgroup ByteOperations Byte-level operations
! 		/// @ingroup Iterators
! 		/// \brief Byte-level operations on pixel iterators
  Ê
! 			/// @defgroup byte_step byte_step
! 			/// @ingroup ByteOperations
! 			/// \brief returns the number of bytes from the current pixel of a pointer to the next
  Ê
! 			/// @defgroup byte_distance byte_distance
! 			/// @ingroup ByteOperations
! 			/// \brief Returns the distance in bytes from the first pixel iterator to the second
  Ê
! 			/// @defgroup byte_advance byte_advance
! 			/// @ingroup ByteOperations
! 			/// \brief Moves a pixel iterator a given distance in bytes
  Ê
! 			/// @defgroup byte_advanced byte_advanced
! 			/// @ingroup ByteOperations
! 			/// \brief Returns a pixel iterator a given byte distance away from a given pixel iterator
  Ê
! 			/// @defgroup byte_advanced_ref byte_advanced_ref
! 			/// @ingroup ByteOperations
! 			/// \brief Shortcut to advancing a pixel iterator by a given number of bytes and taking the reference in case the compiler is not smart enough
  Ê
! 	/// \defgroup ImageView Image View
! 	/// @ingroup GILModels
! 	/// \brief Image views and related operations
  Ê
! 		/// @defgroup ImageViewConstructors Image View Constructors
! 		/// @ingroup ImageView
! 		/// \brief Methods for constructing image views from raw data or other image views
  Ê
! 	/// \defgroup Image Image
! 	/// @ingroup GILModels
! 	/// \brief Images and related operations
  Ê
! 	/// @defgroup Variant Variant
! 	/// @ingroup GILModels
! 	/// \brief Support for concepts with run-time instantiation. Used in GIL to provide images and image views of run-time specified color space, channel depth, etc.
  Ê
! 	/// @defgroup Metafunctions Meta-functions
! 	/// @ingroup GILModels
! 	/// \brief Meta-functions that construct types or return type properties
  Ê
! 	/// @defgroup Algorithms Algorithms
! 	/// @ingroup GILModels
! 	/// \brief Some basic STL-style algorithms when applied to images (as opposed to ranges)
  Ê
  /// \brief namespace for functions not directly needed by the client
--- 169,251 ----
  /// \brief Standard models of GIL concepts
  Ê
!     /// @defgroup Channel Channel
!     /// @ingroup GILModels
!     /// \brief Channel and channel operations
  Ê
!     /// @defgroup ColorSpaces Color Space
!     /// @ingroup GILModels
!     /// \brief Color spaces and color space conversion
  Ê
!     /// @defgroup Pixel Pixel
!     /// @ingroup GILModels
!     /// \brief Pixel and pixel-related functions
  ÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊÊ
!         /// @defgroup ChannelAccessor Channel Accessor
!         /// @ingroup Pixel
!         /// \brief Classes allowing accessing a channel of a pixel
  Ê
!         /// @defgroup ColorBase Color Bases
!         /// @ingroup Pixel
!         /// \brief A bundle of channel values/references/pointers of a given color space
  Ê
!     /// @defgroup Iterators Pixel Iterators
!     /// @ingroup GILModels
!     /// \brief Iterators operating on pixels
  Ê
!         /// @defgroup PlanarPtr Planar Pointers
!         /// @ingroup Iterators
!         /// \brief Implementations of pointers to planar pixels
  Ê
!         /// @defgroup IteratorTraits Iterator Traits
!         /// @ingroup Iterators
!         /// \brief Traits for pixel iterators
  Ê
!         /// @defgroup ByteOperations Byte-level operations
!         /// @ingroup Iterators
!         /// \brief Byte-level operations on pixel iterators
  Ê
!             /// @defgroup byte_step byte_step
!             /// @ingroup ByteOperations
!             /// \brief returns the number of bytes from the current pixel of a pointer to the next
  Ê
!             /// @defgroup byte_distance byte_distance
!             /// @ingroup ByteOperations
!             /// \brief Returns the distance in bytes from the first pixel iterator to the second
  Ê
!             /// @defgroup byte_advance byte_advance
!             /// @ingroup ByteOperations
!             /// \brief Moves a pixel iterator a given distance in bytes
  Ê
!             /// @defgroup byte_advanced byte_advanced
!             /// @ingroup ByteOperations
!             /// \brief Returns a pixel iterator a given byte distance away from a given pixel iterator
  Ê
!             /// @defgroup byte_advanced_ref byte_advanced_ref
!             /// @ingroup ByteOperations
!             /// \brief Shortcut to advancing a pixel iterator by a given number of bytes and taking the reference in case the compiler is not smart enough
  Ê
!     /// \defgroup ImageView Image View
!     /// @ingroup GILModels
!     /// \brief Image views and related operations
  Ê
!         /// @defgroup ImageViewConstructors Image View Constructors
!         /// @ingroup ImageView
!         /// \brief Methods for constructing image views from raw data or other image views
  Ê
!     /// \defgroup Image Image
!     /// @ingroup GILModels
!     /// \brief Images and related operations
  Ê
!     /// @defgroup Variant Variant
!     /// @ingroup GILModels
!     /// \brief Support for concepts with run-time instantiation. Used in GIL to provide images and image views of run-time specified color space, channel depth, etc.
  Ê
!     /// @defgroup Metafunctions Meta-functions
!     /// @ingroup GILModels
!     /// \brief Meta-functions that construct types or return type properties
  Ê
!     /// @defgroup Algorithms Algorithms
!     /// @ingroup GILModels
!     /// \brief Some basic STL-style algorithms when applied to images (as opposed to ranges)
  Ê
  /// \brief namespace for functions not directly needed by the client

--- NEW FILE: tutorial.dox ---
////////////////////////////////////////////////////////////////////////////////////////
/// \file               
/// \brief Doxygen documentation
/// \author Lubomir Bourdev and Hailin Jin \n
///         Adobe Systems Incorporated
///
///
////////////////////////////////////////////////////////////////////////////////////////

/**
\page GILTutorial Generic Image Library Tutorial

\author Lubomir Bourdev (lbo...@ad...) and Hailin Jin (hl...@ad...) \n
        Adobe Systems Incorporated

\version 1.0
\date    January 10, 2006

The Generic Image Library (GIL) is a C++ library that abstracts image representations from algorithms and allows writing code that can work on 
a variety of images with performance similar to hand-writing for a specific image type.
<p>This document will give you a jump-start in using GIL. It does not discuss the underlying design
of the library and does not cover all aspects of it. You can find a detailed library design document on the main GIL web page at http://opensource.adobe.com/gil

- \ref InstallSec
- \ref ObjectsSec
    - \ref UsefulTypedefs
    - \ref GenericObjects
    - \ref RelatedTypes
- \ref ImageAndViewSec
    - \ref ImageSec
    - \ref ImageViewSec
    - \ref ImageViewFactory
- \ref ManipulatingImages
    - \ref ContextIndepdendentPixOp
    - \ref GenericAndSpecialized
    - \ref ContextAwareOperations
- \ref VariantSec
- \ref ExtendingGIL
- \ref CodeExamples
    - \ref HistogramExample
    - \ref SafeAreaExample
    - \ref GDIExample


\section InstallSec     Installation

GIL is part of Adobe Software Library (ASL) which can be installed at http://opensource.adobe.com.
GIL consists of header files only and can be used as stand-alone also. Its only dependency is boost. 
There is no library to link against. Including \p image_view_factory.hpp will be sufficient for most projects.

\section ObjectsSec     Basic Concepts

<i>Pixels</i> are the fundamental building blocks of images. A pixel is a sequence of channels whose number and interpretation are defined by a color space.
<i>Pixel iterators</i> are any random access iterators that operate on pixels. A built-in C pointer to a pixel is a valid pixel iterator. 
<i>Pixel xy locators</i> (or just pixel locators) are like iterators, but allow navigation in both x and y. <i>Image view</i> provides access to a 2D array of pixels without
ownership. It is to images what a range is to STL-s containers. Most image-level algorithms operate on image views. Image views allow 1D and 2D access
of the pixels and provide iterators to traverse the rows and columns.
An <i>image</i> is a container of pixels. It allocates and deallocates the pixels and can provide its associated image view.
\subsection UsefulTypedefs Typedefs for Concrete Types

There are typedefs to refer to any concrete image, pixel iterator, pixel locator, pixel reference or pixel value. They follow this pattern:
<p>
\e ColorSpace + \e BitDepth + ("c") + ("_planar") + ("_step") + \e ClassType
<p>
Where \e ColorSpace also indicates the ordering of components. Examples are \p rgb, \p bgr, \p cmyk, \p rgba. \e BitDepth can be \p 8,\p 16,\p 32. 
\p c indicates object operating over immutable pixels. \p _planar indicates planar organization (as opposed to interleaved). \p _step indicates special image views, 
locators and iterators which traverse the data in non-trivial way (for example, backwards or every other pixel). 
\e ClassType is \p _image (image), \p _view (image view), \p _loc (pixel 2D locator) \p _ptr (pixel iterator), \p _ref (pixel reference), 
\p _pixel (pixel value). Here are examples:

\code
bgr8_image               i;     // 8-bit interleaved BGR image
cmyk16_pixel;            x;     // 16-bit CMYK pixel value;
cmyk16c_planar_ref       p(x);  // const reference to a 16-bit planar CMYK pixel x.
rgb32_planar_step_ptr   ii;     // step pointer to a 32-bit planar RGB pixel.
\endcode

\subsection GenericObjects Generic Representation

Let \p T be a channel type (\p bits8 (or \p unsigned \p char), \p bits16 (or \p unsigned \p short), \p bits32 (or \p float), etc),
and \p C be a color space tag (\p rgb_tag, \p bgr_tag, \p rgba_tag, \p cmyk_tag, etc.)
This is how pixel constructs are defined generically:

\code
pixel<T,C>              v;      // any pixel value
pixel<T,C>&             r(x);   // reference to an interleaved pixel x
pixel<T,C>*             p;      // pointer to an interleaved pixel
pixel<const T,C>*       p;      // pointer to a constant interleaved pixel

pixel<T&,C>             pr(x);  // reference to any planar pixel x
pixel<const T&,C>       cpr(x); // constant reference to any planar pixel x
planar_ptr<T,C>         pp;     // pointer to any planar pixel

// factory metafunctions (see the design guide for more)
typename iterator_type<T,C,true>::type it;        // equivalent to planar_ptr<T,C> ('true' means planar)
typename view_type<T,C,false>::type img_view;     // interleaved image view
typename image_type<T,C,true>::type img;          // planar image of channel type T, color space tag C
typename type_from_x_iterator<X_IT>::view_type v; // image view corresponding to a given pixel iterator X_IT
\endcode

\subsection RelatedTypes Getting a Type Related to a Given Type

As the example illustrates, planar pixels have non-standard pointers and references. You never have to worry about knowing the correct
type - if you have a pointer to a pixel, you can query related types via its \p std::iterator_traits. All pixel iterators have traits that
define the types related to the pixel iterator. For example, the iterator traits for a raw (interleaved) pointer to a pixel look like this:

\code
namespace std {
template <typename T, typename C>
struct iterator_traits<pixel<T,C>*> {
    typedef random_access_iterator_tag  iterator_category;
    typedef pixel<T,C>  value_type;
    typedef ptrdiff_t   difference_type;
    typedef value_type& reference;
    typedef value_type* pointer;

    typedef T           channel_type;       // color channel
    typedef C           color_space_tag;    // color space identifier        
    typedef ...         const_reference;    // reference to immutable pixel
    typedef ...         const_type;         // iterator over immutable pixels
    typedef ...         dynamic_step_type;  // iterator that can skip over pixels
    static const bool   is_planar=false;    // planar vs interleaved
    statoc const bool   is_base=true;       // base iterator vs adaptor over another iterator

};
}
\endcode

Note that pixel iterators have additional types in their iterator traits, the most common of which are shown above. 
Locators, image views and images don't have traits classes, but provide most of the above as member typedefs.

One important typedef is \p const_type. It returns the type otherwise identical to the source type, but operating over immutable pixels.
Note the difference from a constant type - a 
constant iterator (locator, image view) does not allow modifying itself (advancing the iterator, resizing the image view) but may or may
not allow modifying the underlying pixels. \p const_type returns a type that does not allow modifying the underlying pixels.

\section ImageAndViewSec Images and Image Views

\section ImageSec Image

An image is a 2D container. It allocates memory for the pixels in its constructor, deallocates it in its destructor, and deep-copies the pixels 
in its copy constructor. Images can be created given width, height, and (optionally) row alignment policy:

\code
// 10x10 interleaved 8-bit RGB image with 4-byte alignment for rows
rgb8_image my_rgb8_img(10,10, 4);

// 10x10 planar 16-bit CMYK image. Dimensions can also be specified via point_type:
typedef point2<ptrdiff_t> point_type;
cmyk16_planar_image img(point_type(10,10));

// 10x10 generic planar image of type T and color space CS.
typename image_type<T,CS,true>::type my_generic_img(10,10);
\endcode

\section ImageViewSec Image View

Image data is accessed via image view. An image view is a lightweight delimiter of a 2D array of pixels with shallow copy 
constructor and assignment operator. It is similar to a range (a pair of iterators) in STL. Algorithms typically operate on image views.
Images are only used to allocate and hold ...
 
[truncated message content]