[gdal-dev] GDAL Driver Changes

[Frank Warmerdam]

Simon Perkins wrote:
> While I think these changes are good, it does cause the slight
> problem that the C++ API of GDAL, defined in gdal_priv.h has just
> changed. As a result, some software I have that uses GDAL no
> longer works. 

Simon,

What specifically in the API has changed that is causing problems?

> I can update my code to work with the new API, but
> a more serious problem is how do I tell which version of the
> library users have installed? Or should I not have relied on the
> C++ API remaining constant? 

I think it is unwise to depend on the C++ API remaining binary
compatible between versions. It should generally remain compilation
compatible. Retaining binary compatibility in C++ APIs is very
difficult, as even adding a new virtual function at a location other
than the end of a class can cause binary incompatbilities. Fixing
const correctness issues is another example of a seemingly harmless
changes that foils C++ binary compatibility (as I realized to my
horror after changing the OGR API for const correctness issues).

As for determining versions, I have put some effort into defining
version numbers, release dates and release names in gdal.h for
determining at compile time the version of GDAL in use:

#ifndef GDAL_VERSION_NUM
# define GDAL_VERSION_NUM	1170
#endif
#ifndef GDAL_RELEASE_DATE
# define GDAL_RELEASE_DATE 20020416	
#endif
#ifndef GDAL_RELEASE_NAME
# define GDAL_RELEASE_NAME "1.1.7"
#endif

The C function GDALVersionInfo() can also be used to fetch the
above values from a GDAL shared library at runtime should that
prove necessary.

> Are we supposed to use the C
> interface only? Hopefully these API changes will happen rarely,
> but if they do happen then we should try to retain backwards
> compatibility. In this case that was probably impossible since
> there was no C++ accessor function for the format short name.

Right, though there was the C GDALGetDriverShortName() function
which continues to work.

Note that part of my rationale in putting so much information into
metadata was to ensure easier expandability in the future without
changes to the API.

> Another small issue is that when I wrote the FITS driver for
> GDAL, I wanted to handle reading and writing of arbitrary
> metadata stored in the header. As a result, if you set items in
> the metadata of a FITSDataset, then the driver will attempt to
> write that information to the FITS file when the dataset is
> closed. As it happens, that doesn't mess things up here since the
> FITS driver only writes metadata with a key 8 or less characters
> long, as required by the FITS format, so none of the new metadata
> will get written by mistake (their keys are all longer than 8
> chars). However, this is more through accident than design so I
> should probably do something more sensible. Is this the kind of
> problem that the "domain" field of the metadata was intended to
> solve?

The metadata is specifically set on the GDALDriver object for the
format, not the GDALDataset. I agree that putting stuff like this
on the GDALDatasets would have significantly interfered with the
existing normal use of metadata about datasets.

If I were to want to do something similar on datasets (such as
have metadata items that could be queried to find out information
about a dataset like whether it supports some operation) I would
indeed utilize a specific domain to avoid conflict with existing
metadata optionations. In the current case though I felt that
since drivers had not previously used metadata for anything, and
since it seemed logical that this kind of information be in the
"primary domain" it would be OK.

To summarize, I am not currently aiming to make the GDAL C++ API binary
compatible accross versions, though I do intend to make it source compatible
(at the application level). I will also try to make it source compatible
at the driver level, but with a lesser degree of certainty than for the
calling application.

I am concerned about compatibility issues, and I appreciate hearing concerns
for developers and users of GDAL.

PS. I did update the FITS driver, though I didn't test it.

Best regards,

-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up | Frank Warmerdam, warmerdam at p...
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush | Geospatial Programmer for Rent