= RFC 24: GDAL Progressive Data Support = 

Author: Norman Barker[[BR]]
Contact: nbarker@ittvis.com[[BR]]
Status: Development

== Summary ==

To provide an interface for data streaming support to GDAL.  The RFC focuses on JPIP but should be generic to apply to other streaming / progressive formats.

== Definitions ==

'''JPIP''': JPEG 2000 Interactive Protocol

== Objective ==

To provide an interface to a streaming data source in a convenient manner for RasterIO operations within GDAL and to expose this interface via swig.

Note this RFC originally explored using an Observer pattern as per implementations in Java [http://java.sun.com/j2se/1.4.2/docs/api/javax/imageio/event/IIOReadUpdateListener.html imageio update] but after detailed discussions with [http://thread.gmane.org/gmane.comp.gis.gdal.devel/16409/focus=16630 Tamas Szekeres, Even Rouault and Adam Nowacki] a simpler interface is proposed to reduce the potential for problems by having the callback implemented by another thread.

Each swig wrapper language will have its own design pattern for event handling (the image updates) and the proposed interface will allow that pattern implementation to be provided, even if simulated.

== Implementation ==

The implementation is a definition of an interface for streaming support data support within GDAL. Concrete implementations of this interface will follow.  Currently the most convenient JPIP streaming developer library is [http://www.kakadusoftware.com Kakadu] however since GDAL is also a developer library, only stubs can be distributed to conform to Kakadu licensing ([http://trac.osgeo.org/gdal/wiki/JP2KAK JP2KAK]).  Vendors are also interested in using GDAL for streaming support and a standard interface will allow these plugins to be incorporated. e.g. [http://www.gdal.org/frmt_jp2ecw.html ECW], [http://www.gdal.org/frmt_mrsid.html MrSID].

To support reading streaming data from a progressive server it will be necessary to communicate between different threads.  In general it's safer not to do this by shared memory, but by explicit message passing using asynchronous queues. e.g. [http://library.gnome.org/devel/glib/2.12/glib-Asynchronous-Queues.html Glib Asynchronous Queues], [http://en.wikipedia.org/wiki/Message_queue Wikipedia Message Queues]

This interface results in a subclass of GDALDataset, and currently supports dataset level access only, not raster band access.  Access to the stream per band is not precluded by this design and can be added as a later RFC.

=== Class Diagram ===

[[Image(class.png)]]

Implementing !GDALAsyncDataset allows the user application to decide when and how often the updates occur, and reduces the potential negative impacts of threading by providing a clear synchonization point, !NextAsyncRasterIOMessage().

!GDALAsyncRasterIOMessage contains a buffer that is described the getParameters() function which returns a struct with the parameters passed into ProgressiveRasterIO.  Note that no lock() / unlock() on the buffer is required as each buffer represents a call to the server and is a separate instance. 

Each !GDALAsyncRasterIOMessage will be small, it only contains the data for the currently requested window at a particular resolution level. These requests are usually proportional, i.e small window implies high resolution, large window implies low resolution. 





=== Sequence of Events ===