"Fossies" - the Fresh Open Source Software Archive

Member "gdal-3.0.2/doc/api.dox" (28 Oct 2019, 3253 Bytes) of package /linux/privat/gdal-3.0.2.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "api.dox" see the Fossies "Dox" file reference documentation.

    1 /*!
    2 
    3 \typedef int (*GDALProgressFunc)(double dfComplete, const char *pszMessage, void *pProgressArg)
    4 
    5 \brief Callback progress definition for long operations.
    6 
    7 GDALProcessFunc is a typedef defining the signature of functions to be
    8 used with GDAL as callbacks to report the progress of long running processes.
    9 Typically these are functions that would update a GUI progress bar showing how
   10 much of a process is done.
   11 
   12 A number of GDAL functions and methods accept GDALProcessFunc arguments along
   13 with an opaque application supplied data item (pProgressArg) which are then
   14 used to implement progress reporting.  The GDALDataset::BuildOverviews(), and
   15 GDALDriver::CreateCopy() methods are examples of two methods that utilize
   16 the progress semantics.
   17 
   18 \code
   19   int (*GDALProgressFunc)(double dfComplete, const char *pszMessage,
   20                           void *pProgressArg);
   21 \endcode
   22 
   23 @param dfComplete The ratio of completeness of the process from 0.0 for just
   24 started to 1.0 for completed.
   25 
   26 @param pszMessage An optional message string to display.  This is usually NULL.
   27 
   28 @param pProgressArg Application supplied opaque data normally used by the
   29 callback to display the result.
   30 
   31 @return TRUE if the operation should continue or FALSE if the user has
   32 requested a cancel.
   33 
   34 For example, an application might implement the following simple
   35 text progress reporting mechanism, using pData to pass a default message:
   36 
   37 \code
   38  int MyTextProgress( double dfComplete, const char *pszMessage, void *pData)
   39  {
   40      if( pszMessage != NULL )
   41          printf( "%d%% complete: %s\n", (int) (dfComplete*100), pszMessage );
   42      else if( pData != NULL )
   43          printf( "%d%% complete:%s\n", (int) (dfComplete*100),
   44                  (char) pData );
   45      else
   46          printf( "%d%% complete.\n", (int) (dfComplete*100) );
   47 
   48      return TRUE;
   49  }
   50 \endcode
   51 
   52 This could be utilized with the GDALDataset::BuildOverviews() method like
   53 this:
   54 
   55 \code
   56       int       anOverviewList[3] = {2, 4, 8};
   57 
   58       poDataset->BuildOverviews( "NEAREST", 3, anOverviewList, 0, NULL,
   59                                  MyTextProgress, "building overviews" );
   60 \endcode
   61 
   62 In addition to reporting progress to the user, the GDALProcessFunc mechanism
   63 also provides a mechanism for a user interface to return a request from the
   64 user to cancel the operation to the algorithm via the return value.  If FALSE
   65 is returned, the algorithm should terminate the operation and return as
   66 quickly as possible.
   67 
   68 More often that implementing custom progress functions, applications
   69 will just use existing progress functions like GDALDummyProgress(),
   70 GDALTermProgress() and GDALScaledProgress().  Python scripts also can pass
   71 progress functions.
   72 
   73 Application code implementing GDALProgressFunc semantics should remember
   74 a few things:
   75 <ol>
   76 <li> Be wary of NULL progress functions being passed in.  The pfnProgress
   77 argument can be set to GDALDummyProgress() in this case for simplicity.
   78 
   79 <li> Always check the return value to watch for a FALSE indicating the
   80 operation should be terminated.
   81 
   82 <li> The ratio of completeness should vary from 0.0 to 1.0.  Please ensure the
   83 exact value 1.0 is always returned at the end of the algorithm as some
   84 GUI display mechanisms use this as a clue to pop down the progress monitor.
   85 
   86 */