Changes between Version 76 and Version 77 of rfc24_progressive_data_support


Ignore:
Timestamp:
Mar 11, 2010, 3:39:19 PM (14 years ago)
Author:
warmerdam
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • rfc24_progressive_data_support

    v76 v77  
    2424  protected:
    2525    GDALDataset* poDS;
    26         int xOff;
    27         int yOff;
    28         int xSize;
    29         int ySize;
    30         void * pBuf;
    31         int bufXSize;
    32         int bufYSize;
    33         GDALDataType bufType;
    34         int nBandCount;
    35         int* pBandMap;
    36         int nPixelSpace;
    37         int nLineSpace;
    38         int nBandSpace;
    39         long nDataRead;
     26    int          nXOff;
     27    int          nYOff;
     28    int          nXSize;
     29    int          nYSize;
     30    void *       pBuf;
     31    int          nBufXSize;
     32    int          nBufYSize;
     33    GDALDataType eBufType;
     34    int          nBandCount;
     35    int*         panBandMap;
     36    int          nPixelSpace;
     37    int          nLineSpace;
     38    int          nBandSpace;
     39    long         nDataRead;
     40
    4041  public:
    41         GDALAsyncRasterIO(GDALDataset* poDS = NULL);
    42         virtual ~GDALAsyncRasterIO();
    43 
    44         GDALDataset* GetGDALDataset(){return poDS;}
    45         int GetXOffset(){return xOff;}
    46         int GetYOffset(){return yOff;}
    47         int GetXSize(){return xSize;}
    48         int GetYSize(){return ySize;}
    49         void * GetBuffer(){return pBuf;}
    50         int GetBufferXSize(){return bufXSize;}
    51         int GetBufferYSize(){return bufYSize;}
    52         GDALDataType GetBufferType(){return bufType;}
    53         int GetBandCount(){return nBandCount;}
    54         int* GetBandMap(){return pBandMap;}
    55         int GetPixelSpace(){return nPixelSpace;}
    56         int GetLineSpace(){return nLineSpace;}
    57         int GetBandSpace(){return nBandSpace;}
    58         int GetNDataRead(){return nDataRead;}
    59        
    60         /* Returns GARIO_UPDATE, GARIO_NO_MESSAGE (if pending==false and nothing in the queue or if pending==true && timeout != 0 and nothing in the queue at the end of the timeout), GARIO_COMPLETE, GARIO_ERROR */
    61         virtual GDALAsyncStatusType GetNextUpdatedRegion(bool wait, int timeout,
    62                                                    int* pnxbufoff,
    63                                                    int* pnybufoff,
    64                                                    int* pnxbufsize,
    65                                                    int* pnybufsize) = 0;
    66         /* if pending = true, we wait forever if timeout=0, for the timeout time otherwise */
    67         /* if pending = false, we return immediately */
    68         /* the int* are output values */
    69 
    70         // lock a whole buffer.
    71         virtual void LockBuffer() = 0;
    72 
    73         // lock only a block
    74         // the caller must relax a previous lock before asking for a new one
    75         virtual void LockBuffer(int xbufoff, int ybufoff, int xbufsize, int ybufsize) = 0;
    76         virtual void UnlockBuffer() = 0;
    77        
    78         friend class GDALDataset;
     42    GDALAsyncRasterIO(GDALDataset* poDS = NULL);
     43    virtual ~GDALAsyncRasterIO();
     44
     45    GDALDataset* GetGDALDataset() {return poDS;}
     46    int GetXOffset() {return nXOff;}
     47    int GetYOffset() {return nYOff;}
     48    int GetXSize() {return nXSize;}
     49    int GetYSize() {return nYSize;}
     50    void * GetBuffer() {return pBuf;}
     51    int GetBufferXSize() {return nBufXSize;}
     52    int GetBufferYSize() {return nBufYSize;}
     53    GDALDataType GetBufferType() {return eBufType;}
     54    int GetBandCount() {return nBandCount;}
     55    int* GetBandMap() {return panBandMap;}
     56    int GetPixelSpace() {return nPixelSpace;}
     57    int GetLineSpace() {return nLineSpace;}
     58    int GetBandSpace() {return nBandSpace;}
     59
     60    int GetNDataRead(){return nDataRead;}
     61
     62    virtual GDALAsyncStatusType GetNextUpdatedRegion(int nTimeout,
     63                                                     int* pnBufXOff,
     64                                                     int* pnBufYOff,
     65                                                     int* pnBufXSize,
     66                                                     int* pnBufXSize) = 0;
     67
     68    virtual void LockBuffer() = 0;
     69    virtual void LockBuffer(int nBufXOff, int nBufYOff,
     70                            int nBufXSize, int nBufYSize) = 0;
     71    virtual void UnlockBuffer() = 0;
     72
     73    friend class GDALDataset;
    7974};
    8075}}}
    … …  
    9893
    9994{{{
    100         virtual GDALAsyncRasterIO*
    101             BeginAsyncRasterIO(int xOff, int yOff,
    102                                int xSize, int ySize,
    103                                void *pBuf,
    104                                int bufXSize, int bufYSize,
    105                                GDALDataType bufType,
    106                                int nBandCount, int* bandMap,
    107                                int nPixelSpace, int nLineSpace,
    108                                int nBandSpace,
    109                                char **papszOptions);
    110         virtual void EndAsyncRasterIO(GDALAsyncRasterIO *);
     95Status: Development
     96
     97== Summary ==
     98
     99Provide an interface for asynchronous/streaming data access in GDAL.  The initial implementation is for JPIP, but should be generic enough to apply to other streaming / progressive approaches.  Background on the JPIP (Kakadu) implementation can be found in [wiki:rfc24_jpipkak].
     100
     101== Interfaces ==
     102
     103=== GDALAsyncRasterIO ===
     104
     105This new class is intended to represent an active asynchronous raster imagery request.  The request includes information on a source window on the dataset, a target buffer size (implies level of decimation or replication), the buffer type, buffer interleaving, data buffer and bands being requested.  Essentially the same sort of information that is passed in a GDALDataset::!RasterIO() request. 
     106
     107While an implementation of the simple accessors is provided as part of the class, it is intended that the class be subclassed as part of implementation of a particular driver, and custom implementations of !GetNextUpdatedRegion(), !LockBuffer() and !UnlockBuffer() provided.
     108
     109{{{
     110class CPL_DLL GDALAsyncRasterIO
     111{
     112  protected:
     113    GDALDataset* poDS;
     114    int          nXOff;
     115    int          nYOff;
     116    int          nXSize;
     117    int          nYSize;
     118    void *       pBuf;
     119    int          nBufXSize;
     120    int          nBufYSize;
     121    GDALDataType eBufType;
     122    int          nBandCount;
     123    int*         panBandMap;
     124    int          nPixelSpace;
     125    int          nLineSpace;
     126    int          nBandSpace;
     127
     128  public:
     129    GDALAsyncRasterIO();
     130    virtual ~GDALAsyncRasterIO();
     131
     132    GDALDataset* GetGDALDataset() {return poDS;}
     133    int GetXOffset() {return nXOff;}
     134    int GetYOffset() {return nYOff;}
     135    int GetXSize() {return nXSize;}
     136    int GetYSize() {return nYSize;}
     137    void * GetBuffer() {return pBuf;}
     138    int GetBufferXSize() {return nBufXSize;}
     139    int GetBufferYSize() {return nBufYSize;}
     140    GDALDataType GetBufferType() {return eBufType;}
     141    int GetBandCount() {return nBandCount;}
     142    int* GetBandMap() {return panBandMap;}
     143    int GetPixelSpace() {return nPixelSpace;}
     144    int GetLineSpace() {return nLineSpace;}
     145    int GetBandSpace() {return nBandSpace;}
     146
     147    virtual GDALAsyncStatusType
     148        GetNextUpdatedRegion(int nTimeout,
     149                             int* pnBufXOff, int* pnBufYOff,
     150                             int* pnBufXSize, int* pnBufXSize) = 0;
     151    virtual void LockBuffer() {}
     152    virtual void LockBuffer(int nBufXOff, int nBufYOff,
     153                            int nBufXSize, int nBufYSize) {}
     154    virtual void UnlockBuffer() {}
     155};
     156
     157}}}
     158
     159The !GetNextUpdatedRegion() method can be used to wait for an update to the imagery buffer, and to find out what area was updated.   The !LockBuffer() and !UnlockBuffer() methods can be used to temporarily disable updates to the buffer while application code accesses the buffer.  The GetNextUpdatedRegion() method is described in more detail below.
     160
     161==== !GetNextUpdatedRegion() ====
     162
     163{{{
     164GDALAsyncStatusType
     165GDALAsyncRasterio::GetNextUpdatedRegion(int nTimeout,
     166                                        int* pnBufXOff, int* pnBufYOff,
     167                                        int* pnBufXSize, int* pnBufXSize);
     168
     169int nTimeout;
     170      The amount of time to wait for results measured in milliseconds.  If this is
     171      zero available work may be processed but no waiting for the arrival of more
     172      imagery should be done.  Processing available imagery may still take an arbitrary
     173      amount of time.
     174
     175int *pnBufXOff, *pnBufYOff, *pnBufXSize, *pnBufYSize;
     176      The window of data updated within the async io imagery buffer is returned in
     177      these variables. This information can be used to limit screen redraws or other
     178      processing to the portion of the imagery that may have changed.
     179}}}
     180
     181The async return status list is as follows, and will be declared in gdal.h.
     182
     183{{{
     184typedef enum
     185{       
     186        GARIO_PENDING = 0,
     187        GARIO_UPDATE = 1,
     188        GARIO_ERROR = 2,
     189        GARIO_COMPLETE = 3,
     190        GARIO_TypeCount = 4
     191} GDALAsyncStatusType;
     192}}}
     193
     194The meaning as a return value is:
     195
     196 * GARIO_PENDING: No imagery was altered in the buffer, but there is still activity pending, and the application should continue to call GetNextUpdatedRegion() as time permits.
     197 * GARIO_UPDATE: Some of the imagery has been updated, but there is still activity pending.
     198 * GARIO_ERROR: Something has gone wrong.  The asynchronous request should be ended.
     199 * GARIO_COMPLETE: An update has occured and there is no more pending work on this request.  The request should be ended and the buffer used.
     200
     201=== GDALDataset ===
     202
     203The GDALDataset class is extended with methods to create an asynchronous reader, and to cleanup the asynchronous reader.  It is intended that these methods would be subclassed by drivers implementing asynchronous data access.
     204
     205{{{
     206    virtual GDALAsyncRasterIO*
     207        BeginAsyncRasterIO(int nXOff, int nYOff, int nXSize, int nYSize,
     208                           void *pBuf, int nBufXSize, int nBufYSize,
     209                           GDALDataType eBufType,
     210                           int nBandCount, int* panBandMap,
     211                           int nPixelSpace, int nLineSpace, int nBandSpace,
     212                           char **papszOptions);
     213    virtual void EndAsyncRasterIO(GDALAsyncRasterIO *);
    111214}}}
    112215
    … …  
    1342372. A new option named "HEADERS" can be used to send an additional header in the HTTP request.  The JPIPKAK driver will pass accept headers this way.
    135238
     239=== C API ===
     240
     241The following C API wrappers for the C++ classes and methods will be added.  Note that at this time there is no intention to provide C wrappers for all the GDALAsyncRasterIO accessors since the provided information is already available in the application from the call launching the async io.
     242
     243{{{
     244typedef void *GDALAsyncRasterIOH;
     245
     246GDALAsyncStatusType CPL_DLL CPL_STDCALL
     247GDALGetNextUpdatedRegion(GDALAsyncRasterIOH hARIO, int nTimeout,
     248                         int* pnXBufOff, int* pnYBufOff,
     249                         int* pnXBufSize, int* pnYBufSize );
     250void CPL_DLL CPL_STDCALL GDALLockBuffer(GDALAsyncRasterIOH hARIO);
     251void CPL_DLL CPL_STDCALL GDALUnlockBuffer(GDALAsyncRasterIOH hARIO);
     252
     253GDALAsyncRasterIOH CPL_DLL CPL_STDCALL
     254GDALBeginAsyncRasterIO(GDALDatasetH hDS, int nXOff, int nYOff,
     255                       int nXSize, int nYSize,
     256                       void *pBuf, int nBufXSize, int nBufYSize,
     257                       GDALDataType eBufType,
     258                       int nBandCount, int* panBandMap,
     259                       int nPixelSpace, int nLineSpace, int nBandSpace,
     260                       char **papszOptions);
     261void  CPL_DLL CPL_STDCALL
     262GDALEndAsyncRasterIO(GDALDatasetH hDS, GDALAsyncRasterIOH hAsynchRasterIOH);
     263}}}
     264
     265=== SWIG ===
     266
     267It is intended that all the above functions in the C API will be wrapped for SWIG.