76 | | |
77 | | The async status list is as follows, and will be declared in gdal.h. |
78 | | |
79 | | {{{ |
80 | | typedef enum |
81 | | { |
82 | | GARIO_PENDING = 0, |
83 | | GARIO_UPDATE = 1, |
84 | | GARIO_ERROR = 2, |
85 | | GARIO_COMPLETE = 3, |
86 | | GARIO_TypeCount = 4 |
87 | | } GDALAsyncStatusType; |
88 | | }}} |
89 | | |
90 | | === GDALDataset === |
91 | | |
92 | | The 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. |
93 | | |
94 | | {{{ |
95 | | Status: Development |
96 | | |
97 | | == Summary == |
98 | | |
99 | | Provide 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 | | |
105 | | This 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 | | |
107 | | While 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 | | {{{ |
110 | | class 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 | | |
159 | | The !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. |