/*!

\typedef int (*GDALProgressFunc)(double dfComplete, const char *pszMessage, void *pProgressArg)

\brief Callback progress definition for long operations.

GDALProcessFunc is a typedef defining the signature of functions to be
used with GDAL as callbacks to report the progress of long running processes.
Typically these are functions that would update a GUI progress bar showing how
much of a process is done.

A number of GDAL functions and methods accept GDALProcessFunc arguments along
with an opaque application supplied data item (pProgressArg) which are then
used to implement progress reporting.  The GDALDataset::BuildOverviews(), and
GDALDriver::CreateCopy() methods are examples of two methods that utilize
the progress semantics.

\code
  int (*GDALProgressFunc)(double dfComplete, const char *pszMessage,
                          void *pProgressArg);
\endcode

@param dfComplete The ratio of completeness of the process from 0.0 for just
started to 1.0 for completed.

@param pszMessage An optional message string to display.  This is usually NULL.

@param pProgressArg Application supplied opaque data normally used by the
callback to display the result.

@return TRUE if the operation should continue or FALSE if the user has
requested a cancel.

For example, an application might implement the following simple
text progress reporting mechanism, using pData to pass a default message:

\code
 int MyTextProgress( double dfComplete, const char *pszMessage, void *pData)
 {
     if( pszMessage != NULL )
         printf( "%d%% complete: %s\n", (int) (dfComplete*100), pszMessage );
     else if( pData != NULL )
         printf( "%d%% complete:%s\n", (int) (dfComplete*100),
                 (char) pData );
     else
         printf( "%d%% complete.\n", (int) (dfComplete*100) );

     return TRUE;
 }
\endcode

This could be utilized with the GDALDataset::BuildOverviews() method like
this:

\code
      int       anOverviewList[3] = {2, 4, 8};

      poDataset->BuildOverviews( "NEAREST", 3, anOverviewList, 0, NULL,
                                 MyTextProgress, "building overviews" );
\endcode

In addition to reporting progress to the user, the GDALProcessFunc mechanism
also provides a mechanism for a user interface to return a request from the
user to cancel the operation to the algorithm via the return value.  If FALSE
is returned, the algorithm should terminate the operation and return as
quickly as possible.

More often that implementing custom progress functions, applications
will just use existing progress functions like GDALDummyProgress(),
GDALTermProgress() and GDALScaledProgress().  Python scripts also can pass
progress functions.

Application code implementing GDALProgressFunc semantics should remember
a few things:
<ol>
<li> Be wary of NULL progress functions being passed in.  The pfnProgress
argument can be set to GDALDummyProgress() in this case for simplicity.

<li> Always check the return value to watch for a FALSE indicating the
operation should be terminated.

<li> The ratio of completeness should vary from 0.0 to 1.0.  Please ensure the
exact value 1.0 is always returned at the end of the algorithm as some
GUI display mechanisms use this as a clue to pop down the progress monitor.

*/