MIGRATION_GUIDE.TXT

MIGRATION GUIDE FROM GDAL 3.11 to GDAL 3.12
-------------------------------------------

- The following changes have been done to the "gdal" command line interface:

  * Sub-commands "buffer", "explode-collections", "make-valid", "segmentize",
    "simplify", "swap-xy" of "gdal vector geom" are now directly available
    under "gdal vector". Support for the old location is kept for 3.12, but
    will be definitely removed in 3.13.
  * Furthermore, sub-command "set-type" of "gdal vector geom" is renamed as
    "set-geom-type" and also placed under "gdal vector".

- Methods GDALRasterAttributeTable::SetValue() now return a CPLErr instead of
  void. This will impact in particular out-of-tree drivers that implement those
  methods in a subclass of GDALRasterAttributeTable.

MIGRATION GUIDE FROM GDAL 3.10 to GDAL 3.11
-------------------------------------------

- The introduction of the gdal_fwd.h header that normalizes forward declarations
  of GDAL public opaque types may cause issues with downstream users of the
  GDAL API that would have redefined themselves those types, particularly when
  building against a GDAL built in DEBUG mode where the type aliases are stricter
  than in release mode.

- The OGRLayer::GetExtent(OGREnvelope*, int bForce) and
  OGRLayer::GetExtent(int iGeomField, OGREnvelope*, int bForce) methods are
  no longer virtual methods that are implemented by drivers, and the ``int bForce``
  parameter is now a ``bool bForce``.
  Drivers may implement the new IGetExtent(int iGeomField, OGREnvelope*,
  bool bForce) protected virtual method. The public method checks that the
  iGeomField value is in range.
  Similarly for OGRLayer::GetExtent3D(int iGeomField, OGREnvelope3D*, int bForce)
  which is now a user facing method (with the change that the ``int bForce`` is now a
  ``bool bForce``). Drivers may implement the new IGetExtent3D(int iGeomField, OGREnvelope3D*,
  bool bForce) protected virtual method. The public method checks that the
  iGeomField value is in range.

- The OGRLayer::SetSpatialFilter() and SetSpatialFilterRect() methods are
  no longer virtual methods that are implemented by drivers. They now return
  OGRErr instead of void, `and accept a ``const OGRGeometry*``). Drivers may implement
  the new ISetSpatialFilter(int iGeomField, const OGRGeometry*) protected virtual method.
  The public methods check that the iGeomField value is in range.

- GDAL drivers may now return raster bands with the new data types
  GDT_Float16 or GDT_CFloat16. Code that use the GDAL API must be
  ready to react to the new data type, possibly by doing RasterIO()
  requests with eBufType==GDT_Float32, if they can't deal natively
  with Float16 values.

- If only a specific GDAL Minor version is to be supported, this must now be
  specified in the find_package call in CMake via a version range specification.

- The following methods
  OGRCoordinateTransformation::Transform(size_t nCount, double *x, double *y,
  double *z, double *t, int *pabSuccess) and
  OGRCoordinateTransformation::TransformWithErrorCodes(size_t nCount, double *x,
  double *y, double *z, double *t, int *panErrorCodes) are modified to return
  FALSE as soon as at least one point fails to transform (to be consistent with
  the other form of Transform() that doesn't take a "t" argument), whereas
  previously they would return FALSE only if no transformation was found. When
  FALSE is returned the pabSuccess[] or panErrorCodes[] arrays indicate which
  point succeeded or failed to transform.

  The GDALTransformerFunc callback and its implementations (GenImgProjTransformer,
  RPCTransformer, etc.) are also modified to return FALSE as soon as at least
  one point fails to transform.

MIGRATION GUIDE FROM GDAL 3.9 to GDAL 3.10
------------------------------------------

- The OGR SQL parser has been modified to evaluate NULL values in boolean
  operations similarly to other SQL engines (SQLite, PostgreSQL, etc.). Previously,
  with a foo=NULL field, expressions ``foo NOT IN ('bar')`` and ``foo NOT LIKE ('bar')``
  would evaluate as true. Now the result is false (with the NULL state being
  propagated to it). Concretely, to get the same results as in previous versions,
  the above expressions must be rewritten as ``foo IS NULL OR foo NOT IN ('bar')``
  and ``foo IS NULL OR foo NOT LIKE ('bar')``.

- MEM driver: opening a dataset with the MEM::: syntax is now disabled by
  default because of security implications. This can be enabled by setting the
  GDAL_MEM_ENABLE_OPEN build or configuration option. Creation of a 0-band MEM
  dataset, and using the GDALDataset::AddBand() method with the DATAPOINTER,
  PIXELOFFSET and LINEOFFSET options is the recommended way. For example, like
  in https://github.com/OSGeo/gdal/blob/e32a2fde41a555b7948cece9ab9b4e979138e7dd/gcore/rasterio.cpp#L1534-L1576

- The Erdas Imagine (HFA) and Derived drivers are now optional drivers. Users
  building with GDAL_BUILD_OPTIONAL_DRIVERS=OFF may need to explicitly enable
  them with GDAL_ENABLE_DRIVER_HFA=ON and GDAL_ENABLE_DRIVER_DERIVED=ON.
  The MapInfo, OGR_VRT and KML drivers are now an optional driver. Users
  building with OGR_BUILD_OPTIONAL_DRIVERS=OFF may need to explicitly enable
  them with OGR_ENABLE_DRIVER_TAB=ON, OGR_ENABLE_DRIVER_VRT=ON and
  OGR_ENABLE_DRIVER_KML=ON.

- User code using VSIFEofL() to potentially to end read loops should also test
  the return code of the new VSIFError() function. Some virtual file systems
  that used to report errors through VSIFEofL() now do through VSIFError().

- Out-of-tree implementations of VSIVirtualHandle():
  2 new required virtual methods must be implemented: int Error(), and
  void ClearErr() following POSIX semantics of ferror() and clearerr().
  This is to distinguish Read() that returns less bytes than requested because
  of an error (Error() != 0) or because of end-of-file (Eof() != 0)

  The VSIFilesystemPluginCallbacksStruct structure is extended with 2
  corresponding optional (but recommended to be implemented to reliably detect
  reading errors) callbacks "error" and "clear_err".

- Python bindings: Band.GetStatistics() and Band.ComputeStatistics() now
  return a None value in case of error (when exceptions are not enabled)

- New color interpretation (GCI_xxxx) items have been added to the GDALColorInterp
  enumeration. Code testing color interpretation may need to be adapted.

MIGRATION GUIDE FROM GDAL 3.8 to GDAL 3.9
-----------------------------------------

- Out-of-tree vector drivers:
  * OGRLayer::CreateField() now takes a const OGRFieldDefn* instead of a
    OGRFieldDefn*.
  * OGRLayer::CreateGeomField() now takes a const OGRGeomFieldDefn* instead of
    a OGRGeomFieldDefn*.
  * OGRLayer::ICreateLayer() has a new prototype, due to RFC 99 "Geometry
    coordinate precision" changes.

    The fastest migration path is from:

    OGRLayer *
         MyDataset::ICreateLayer(const char* pszLayerName,
                                 const OGRSpatialReference *poSpatialRef,
                                 OGRwkbGeometryType eGType, char **papszOptions)
    {
        ...
    }

    to

    OGRLayer *
         MyDataset::ICreateLayer(const char *pszLayerName,
                                 const OGRGeomFieldDefn *poGeomFieldDefn,
                                 CSLConstList papszOptions)
    {
        const auto eGType = poGeomFieldDefn ? poGeomFieldDefn->GetType() : wkbNone;
        const auto poSpatialRef =
            poGeomFieldDefn ? poGeomFieldDefn->GetSpatialRef() : nullptr;
        ...
    }

- Sealed feature and field definition (RFC 97). A number of drivers now "seal"
  their layer definition, which might cause issue to user code currently
  mis-using setters of OGRFeatureDefn, OGRFieldDefn or OGRGeomFieldDefn on such
  instances.
  The drivers that have been updated to seal their layer definition are:
  GeoPackage, PostgreSQL, Shapefile, OpenFileGDB, MITAB, Memory, GeoJSON, JSONFG,
  TopoJSON, ESRIJSON, ODS, XLSX.

- OGRLayer::SetIgnoredFields() now accepts a ``CSLConstList papszIgnoredFields``
  instead of a ``const char** papszIgnoredFields``

MIGRATION GUIDE FROM GDAL 3.7 to GDAL 3.8
-----------------------------------------

- Out-of-tree vector drivers:
  * GDALDataset::ICreateLayer() now takes a const OGRSpatialReference* instead
    of a OGRSpatialReference*. Drivers should clone the passed SRS if they need
    to keep it.

- The /vsimem virtual file system is modified to automatically create parent
  directories when a file is created. (e.g., creating /vsimem/parent/child.txt
  would cause the directory /vsimem/parent to be created.) If the parent
  directory cannot be created because the file /vsimem/parent exists, file
  creation will now fail.

- In SWIG bindings, the function FileFromMemBuffer now returns an error code
  if the file could not be created.


MIGRATION GUIDE FROM GDAL 3.6 to GDAL 3.7
-----------------------------------------

- Following RFC 87, PIXELTYPE=SIGNEDBYTE in IMAGE_STRUCTURE metadata domain is
  no longer reported by drivers that used to do it. The new GDT_Int8 data type
  is now reported.
  On writing, the PIXELTYPE=SIGNEDBYTE creation option is preserved in drivers
  that used to support it, but is deprecated and external code should rather use
  the GDT_Int8 data type.

- The VSILFILE* type is no longer aliased to FILE* in builds without the DEBUG
  define (that is production builds). External code that used FILE* with
  GDAL VSI*L API has to be changed to use VSILFILE*.
  This aliasing dates back to old times where both types were indifferently
  used in the code base. In the mean time, this was cleaned up. But there was a
  drawback of having VSILFILE* being either a dedicated type oor an alias of
  FILE* depending whether DEBUG is defined, especially with the C++ API, for
  people building their plugins with DEBUG and running them against a non-DEBUG
  GDAL build, or the reverse.

- GDALFlushCache() and GDALDataset::FlushCache() are modified to return a CPLErr
  error code instead of void. Affects out-of-tree drivers.

- A Close() virtual method is added to GDALDataset per RFC 91. Out-of-tree
  drivers with write support are encouraged to implement it for error
  propagation.

- Pansharpening now requires that panchromatic and multispectral bands have
  valid geotransform (in early versions, it was assumed in the case of missing
  geotransform that they covered the same geospatial extent).
  The undocumented VRT pansharpened MSShiftX and MSShiftY options (and the
  corresponding C++ GDALPansharpenOptions::dfMSShiftX and dfMSShiftY members)
  have been removed, due to using the inverted convention as one would expect,
  and being sub-par solution compared to using geotransform to correlate pixels
  of panchromatic and multispectral bands.

- OGRCoordinateTransformation::GetSourceCS() and GetTargetCS() now returns
  a const OGRSpatialReference*

- OGRGeometry::getSpatialReference() now returns a const OGRSpatialReference*

- OGRGeomFieldDefn::GetSpatialRef() now returns a const OGRSpatialReference*

MIGRATION GUIDE FROM GDAL 3.5 to GDAL 3.6
-----------------------------------------

- Out-of-tree vector drivers:
  * GDALDataset::IBuildOverviews(): parameters panOverviewList and panBandList
    are now of type 'const int*' (previously 'int*')
    Added a CSLConstList papszOptions member.
  * GDALRasterBand::BuildOverviews(): parameter panOverviewList is now of
    type 'const int*' (previously 'int*')
    Added a CSLConstList papszOptions member.
  * Compatibility layers of GDAL 3.0 _GetProjectionRef(), _GetGCPProjectionRef(),
    _SetProjection(), _SetGCPs() have been removed

MIGRATION GUIDE FROM GDAL 3.4 to GDAL 3.5
-----------------------------------------

- GDAL drivers may now return raster bands with the new data types GDT_Int64 or
  GDT_UInt64.
- Make GDALProxyRasterBand::RefUnderlyingRasterBand() / UnrefUnderlyingRasterBand() const. May affect out-of-tree drivers

MIGRATION GUIDE FROM GDAL 3.3 to GDAL 3.4
-----------------------------------------

- Out-of-tree vector drivers:
    * OGRFeatureDefn protected member variables have been changed.
        - (nFieldCount, papoFieldDefn)        ==> std::vector<std::unique_ptr<OGRFieldDefn>> apoFieldDefn{};
        - (nGeomFieldCount, paoGeomFieldDefn) ==> std::vector<std::unique_ptr<OGRGeomFieldDefn>> apoGeomFieldDefn{};
    * OGRFeatureDefn::AddGeomFieldDefn( OGRGeomFieldDefn *, bCopy = FALSE ) is
      replaced by AddGeomFieldDefn( std::unique_ptr<OGRGeomFieldDefn>&& )
    * GDALDataset::FlushCache() and GDALRasterBand::FlushCache() now takes a bool bAtClosing argument.
      That argument is set to true when FlushCache() is called from the dataset/band destructor.
      This can be used as a hint, for example to avoid doing extra work if the dataset is marked
      for deletion at closing. Driver implementing that method should propagate the argument to the
      base implementation when calling it.

MIGRATION GUIDE FROM GDAL 3.2 to GDAL 3.3
-----------------------------------------

- Python bindings:
  * Python 2 is no longer supported per RFC 77. Python 3.6 or later required
  * "osgeo.utils" was replaced by "osgeo_utils" (more details: see RFC78)
  * The following undocumented, untested utility scripts are no longer installed as system scripts and were moved
    from "gdal/swig/python/gdal-utils" to: "gdal/swig/python/gdal-utils/samples":
    - epsg_tr.py
    - esri2wkt.py
    - gcps2vec.py
    - gcps2wld.py
    - gdal_auth.py
    - gdalchksum.py
    - gdalident.py
    - gdalimport.py
    - mkgraticule.py
    In order to import sample script X (i.e. `epsg_tr`) as a module, use: `from osgeo_utils.samples import X`.
    In order to run it as a script run: `python -m osgeo_utils.samples.X`.
  * packaging:
    - "gdal/swig/python/samples" moved to: "gdal/swig/python/gdal-utils/osgeo_utils/samples"
    - "gdal/swig/python/scripts" moved to: "gdal/swig/python/gdal-utils/scripts"
- gdaldem TRI: default algorithm has been changed to use Riley et al. 1999. Use -alg Wilson to select the algorithm used previously
- Disable by default raster drivers DODS, JPEG2000(Jasper), JPEGLS, MG4LIDAR, FUJIBAS, IDA, INGR, ZMAP and vector driver ARCGEN, ArcObjects, CLOUDANT, COUCHDB, DB2, DODS, FME, GEOMEDIA, GTM, INGRES, MONGODB, REC, WALK at runtime, unless the GDAL_ENABLE_DEPRECATED_DRIVER_{drivername} configuration option is set to YES. Those drivers are planned for complete removal in GDAL 3.5
- Perl bindings are deprecated. Removal planned for GDAL 3.5. Use Geo::GDAL::FFI instead
- Removal of BNA, AeronavFAA, HTF, OpenAir, SEGUKOOA, SEGY, SUA, XPlane, BPG, E00GRID, EPSILON, IGNFHeightASCIIGrid, NTV1 drivers. Moved to (unsupported) https://github.com/OSGeo/gdal-extra-drivers repository.

MIGRATION GUIDE FROM GDAL 3.1 to GDAL 3.2
-----------------------------------------

- Python bindings: old-style, deprecated for many years, import method of
  importing the gdal module through "import gdal" is no longer available.
  "from osgeo import gdal" must now be used. This holds true for the ogr, osr,
  gdalconst and gdalnumeric modules.


MIGRATION GUIDE FROM GDAL 3.0 to GDAL 3.1
-----------------------------------------

- OGR SQL: the 'LIKE' operator is now case sensitive by default. ILIKE (supported
  in previous versions) must be used for case insensitive comparison. The
  OGR_SQL_LIKE_AS_ILIKE configuration option can be set to YES to make LIKE behave
  in a case insensitive way as in previous versions.

MIGRATION GUIDE FROM GDAL 2.4 to GDAL 3.0
-----------------------------------------

- Unix Build: ./configure arguments --without-bsb, --without-grib,
  and --without-mrf have been renamed to --disable-driver-bsb,
  --disable-driver-grib and --disable-driver-mrf
 - Unix build: Arguments of --with-pg changed to yes/no only.
- Substantial changes, sometimes backward incompatible, in coordinate reference
  system and coordinate transformations have been introduced per
  https://gdal.org/en/latest/development/rfc/rfc73_proj6_wkt2_srsbarn.html
    * OSRImportFromEPSG() takes into account official axis order.
      Traditional GIS-friendly axis order can be restored with
      OGRSpatialReference::SetAxisMappingStrategy(OAMS_TRADITIONAL_GIS_ORDER);
    * Same for SetWellKnownGeogCS("WGS84") / SetFromUserInput("WGS84")
    * removal of OPTGetProjectionMethods(), OPTGetParameterList() and OPTGetParameterInfo()
      No equivalent.
    * removal of OSRFixup() and OSRFixupOrdering(): no longer needed since objects
      constructed are always valid
    * removal of OSRStripCTParms(). Use OSRExportToWktEx() instead with the
      FORMAT=SQSQL option
    * exportToWkt() outputs AXIS nodes
    * OSRIsSame(): now takes into account data axis to CRS axis mapping, unless
      IGNORE_DATA_AXIS_TO_SRS_AXIS_MAPPING=YES is set as an option to OSRIsSameEx()
    * ogr_srs_api.h: SRS_WKT_WGS84 macro is no longer declared by default since
      WKT without AXIS is too ambiguous. Preferred remediation: use SRS_WKT_WGS84_LAT_LONG.
      Or #define USE_DEPRECATED_SRS_WKT_WGS84 before including ogr_srs_api.h

Out-of-tree drivers:
* GDALDataset::GetProjectionRef() made non-virtual.
  Replaced by GetSpatialRef() virtual method.
  Compatibility emulation possible by defining:
    const char* _GetProjectionRef() override; // note leading underscore
    const OGRSpatialReference* GetSpatialRef() const override {
        return GetSpatialRefFromOldGetProjectionRef();
    }

* GDALDataset::SetProjection() made non-virtual.
  Replaced by SetSpatialRef() virtual method.
  Compatibility emulation possible by defining:
    CPLErr _SetProjection(const char*) override; // note leading underscore
    CPLErr SetSpatialRef(const OGRSpatialReference* poSRS) override {
        return OldSetProjectionFromSetSpatialRef(poSRS);
    }

* GDALDataset::GetGCPProjection() made non-virtual.
  Replaced by GetGCPSpatialRef() virtual method.
  Compatibility emulation possible by defining:
    const char* _GetGCPProjectionRef() override; // note leading underscore
    const OGRSpatialReference* GetGCPSpatialRef() const override {
        return GetGCPSpatialRefFromOldGetGCPProjection();
    }

* GDALDataset::SetGCPs(..., const char* pszWKT) made non-virtual.
  Replaced by SetGCPs(..., const OGRSpatialReference* poSRS) virtual mode.
    CPLErr _SetGCPs( int nGCPCount, const GDAL_GCP *pasGCPList,
                    const char *pszGCPProjection ) override; // note leading underscore
    CPLErr SetGCPs( int nGCPCountIn, const GDAL_GCP *pasGCPListIn,
                    const OGRSpatialReference* poSRS ) override {
        return OldSetGCPsFromNew(nGCPCountIn, pasGCPListIn, poSRS);
    }

MIGRATION GUIDE FROM GDAL 2.3 to GDAL 2.4
-----------------------------------------

1) Out-of-tree drivers: RawRasterBand() constructor changes

RawRasterBand now only accepts a VSILFILE* file. Consequently the void* fpRaw
argument has become a VSILFILE* one. And the bIsVSIL = FALSE argument has
been removed. The int bOwnsFP = FALSE has seen its default value suppressed,
and has seen its type changed to the RawRasterBand::OwnFP::YES/NO enumeration,
to detect places where your code must be changed.

Caution: code like RawRasterBand(..., bNativeOrder, TRUE) must be changed to
RawRasterBand(..., bNativeOrder, RawRasterBand::OwnFP::NO, the TRUE value
being the bIsVSIL value, and the default argument being bOwnsFP == FALSE.

MIGRATION GUIDE FROM GDAL 2.2 to GDAL 2.3
-----------------------------------------

1) RFC 70: Guessing output format from output file name extension for utilities

Link: https://gdal.org/en/latest/development/rfc/rfc70_output_format_guess.html

Before GDAL 2.3, if not specifying the output format to utilities, GeoTIFF or
Shapefile were assumed for most utilities. Now, the output format will be
guessed from the output filename extension. This might break usages where
non-standard extensions are used for GeoTIFF or Shapefile output when -f/-of is
not specified (but warnings were already emitted in such situations).

2) RFC 68: C++11 Compilation requirement

Link: https://gdal.org/en/latest/development/rfc/rfc68_cplusplus11.html

GDAL now requires a C++11 compatible compiler. External code using GDAL C++ API
will also need to enable at least C++11 compilation mode, if the compiler
defaults to C++98/C++03.

3) Stricter const-ness in OGRGeomFieldDefn, OGRFeatureDefn and OGRFeature
   classes, impacting out-of-tree drivers that subclass them.

   The following methods are now const qualified:

     OGRGeomFieldDefn class:
        virtual OGRSpatialReference* GetSpatialRef() const

     OGRFeatureDefn class:
        virtual const char* GetName() const
        virtual int GetFieldCount() const
        virtual int GetFieldIndex(const char*) const
        virtual int GetGeomFieldCount() const
        virtual int GetGeomFieldIndex(const char*) const
        virtual OGRwkbGeometryType GetGeomType() const
        virtual OGRFeatureDefn* Clone() const
        virtual int IsGeometryIgnored() const
        virtual int IsSame(const OGRFeatureDefn*) const // argument is const now too

     OGRFeature class:
        virtual OGRBoolean Equal(const OGRFeature*) const // argument is const now too
        virtual const char* GetStyleString() const
        virtual OGRStyleTable* GetStyleTable() const

    The following virtual methods, offering const alternatives to their
    non-const equivalent methods, should be overloaded if the non-const
    method is overloaded.

     OGRFeatureDefn class:
        virtual const OGRFieldDefn* GetFieldDefn(int) const
        virtual const OGRGeomFieldDefn* GetGeomFieldDefn(int) const


MIGRATION GUIDE FROM GDAL 2.1 to GDAL 2.2
-----------------------------------------

A) RFC 64: Triangle, Polyhedral surface and TIN

Link: https://gdal.org/en/latest/development/rfc/rfc64_triangle_polyhedralsurface_tin.html

Vector drivers can now return geometries of type wkbPolyhedralSurface, wkbTIN
and wkbTriangle; and their Z, M and ZM variants (as well as for the type of
geometry fields). Client code, as well as out-of-tree drivers that support
writing geometries, must be ready to deal with them.

B) RFC 67: Null values in OGR

Link: https://gdal.org/en/latest/development/rfc/rfc67_nullfieldvalues.html

Previously, the "unset" state of a field was used both for a unset state
(ie no information for the field of the feature) or the NULL state of the
field. Now there is OGR_F_IsFieldSet() / OGRFeature::IsFieldSet() for the
unset state, and a new OGR_F_IsFieldNull() / OGRFeature::IsFieldNull() for the
new NULL state. Code that used OGR_F_IsFieldSet() / OGRFeature::IsFieldSet()
should also test the NULL state, otherwise empty strings or 0 numeric values
will be returned. A convenient way of migrating is to replace the use of
OGR_F_IsFieldSet() / OGRFeature::IsFieldSet() by OGR_F_IsFieldSetAndNotNull() /
OGRFeature::IsFieldSetAndNotNull() if there is no need to distinguish both
states.
On the writing side, a few drivers will now distinguish between the unset
and null state, namely GeoJSON, CouchDB, Cloudant, MongoDB, ElasticSearch and
GML. For example, for the GeoJSON driver, in GDAL 2.1 or before, a unset field
was written as field_name: null. Starting with GDAL 2.2, only fields explicitly
set as null with OGR_F_SetFieldNull() will be written with a null value.
Unset fields of a feature will not be present in the corresponding JSon feature
element.

MIGRATION GUIDE FROM GDAL 2.0 to GDAL 2.1
------------------------------------------

A) RFC 61: Support for measured geometries

Link: https://gdal.org/en/latest/development/rfc/rfc61_support_for_measured_geometries.html

The OGRwkbGeometryType enumeration has been extended with new values for the
M and ZM variants of the geometry types. Client code may have to be upgraded
to take into account those new values. Note that the wkbPolyhedralSurface, wkbTIN
and wkbTriangle types and their Z, M and ZM variants, have also been introduced
as a provision for a potential support in a future version (they are unused in
OGR core and drivers for now).

Previously the ESRI Shapefile driver read XYM data as XYZ. Now it is read
as XYM.

MIGRATION GUIDE FROM GDAL 1.11 to GDAL 2.0
------------------------------------------

This file documents backwards incompatible changes. You are strongly encouraged
to read the relevant RFCs for details and rationale for those changes.

Changes to the Perl bindings API are listed in swig/perl/Changes-in-the-API-in-2.0.

A) RFC 46: Unification of GDAL and OGR driver models

Link: https://gdal.org/en/latest/development/rfc/rfc46_gdal_ogr_unification.html

C++ API:

  * OGRSFDriverRegistrar and OGRSFDriver are now deprecated. Use GDALDriverManager
    and GDALDriver instead.

  * The following methods from OGRSFDriverRegistrar are removed : Open(),
    OpenShared(), ReleaseDataSource(), DeregisterDriver(), AutoLoadDrivers()
    GetDriver() and GetDriverByName() now return a GDALDriver* instance.

  * OGRDataSource::CreateLayer() specialized implementations should be renamed
    as ICreateLayer() to benefit from layer creation options validation.

  * OGRLayer::GetInfo() has been removed.

  * All methods of OGRDataSource have been transferred to GDALDataset, except
    SyncToDisk() that should now be implemented as FlushCache() in drivers.

  * GDALOpenInfo::papszSiblingFiles member is now private. Use the new
    GetSiblingFiles() method instead.

  * GDALOpenInfo::fp member is replaced by fpL member of type VSILFILE*.

  * OGRSFDriver::CopyDataSource() has been removed.

  * GDALDriverManager::GetHome() and SetHome() have been removed.

Out-of-tree drivers :

  * Read RFC 46 for the needed changes. Changes in GDALOpenInfo will impact GDAL
    drivers. GDAL drivers should also declare SetMetadataItem( GDAL_DCAP_RASTER, "YES" ).
    OGRDataSource::CreateLayer() and SyncToDisk() changes will affect OGR drivers.

Behavior changes :

  * GDALDriverManager::GetDriverCount() and GetDriver() return both raster and
    vector drivers. The nature of a driver can be tested with the GDAL_DCAP_RASTER
    and GDAL_DCAP_VECTOR driver metadata item.

  * GetRefCount() starts at 1 for OGRDataSource instead of 0.

B) RFC 49: Curve geometries

Link: https://gdal.org/en/latest/development/rfc/rfc49_curve_geometries.html

C/C++ API :

  * Use of wkb25DBit macro is strongly discouraged, as not compatible with new
    geometry types. Use wkbFlatten(), wkbHasZ(), wkbSetZ() instead
  * OGRwkbGeometryType enumeration has new values.

Behavior changes :

  * GML, NAS, WFS, PostGIS, VRT, GeoPackage and CSV drivers can return non-linear geometries.
    Applications that do not wish to get such geometries can call
    OGRSetNonLinearGeometriesEnabledFlag(FALSE)

Out-of-tree drivers :

  * Read RFC 49 for the needed changes. CreateFeature() and SetFeature() virtual
    methods must be renamed ICreateFeature() and ISetFeature().

C) RFC 51: RasterIO() improvements : resampling and progress callback

Link: https://gdal.org/en/latest/development/rfc/rfc51_rasterio_resampling_progress.html

Out-of-tree drivers :

  * Read RFC 51 for the needed changes. GDALRasterBand and GDALDataset::IRasterIO()
    take a new GDALRasterIOExtraArg* psExtraArg argument.
    GDALRasterBand and GDALDataset::RasterIO() take a new
    GDALRasterIOExtraArg* psExtraArg argument

D) RFC 31: OGR 64bit Integer Fields and FIDs

Link: https://gdal.org/en/latest/development/rfc/rfc31_ogr_64.html

C++ API:
  * OGRLayer::GetFeature(), OGRLayer::DeleteFeature(), OGRLayer::SetNextByIndex() take a GIntBig instead of a long
  * OGRFeature::GetFID() and OGRLayer::GetFeatureCount() now returns a GIntBig

C API:
  * OGR_L_GetFeature(), OGR_L_DeleteFeature(), OGR_L_SetNextByIndex() take a GIntBig instead of a long
  * OGR_F_GetFID() and OGR_L_GetFeatureCount() now returns a GIntBig

Behavior changes :
  * OFTInteger64 and OFTIntegerList64 can be returned whereas OGRFieldType is returned.

Out-of-tree drivers :
  * Virtual method signature change: OGRLayer::GetFeature(), OGRLayer::DeleteFeature(),
    OGRLayer::SetNextByIndex() take a GIntBig argument instead of a long
  * Virtual method signature change: OGRLayer::GetFeatureCount() now returns a GIntBig
  * OGRFeature::GetFID() returns a GIntBig

E) RFC 52: Strict OGR SQL quoting

Link: https://gdal.org/en/latest/development/rfc/rfc52_strict_sql_quoting.html

No API changes

Behavior changes:
  * Identifiers, i.e column names or table names, can no longer be quoted with
    single quote characters, but must use double quote characters if quoting is
    needed, conforming with SQL 92 syntax. Failure to do the change will not
    necessarily need to verbose errors at runtime since an expression like
    WHERE 'a_column_name' = 'a_value' will now always evaluate to FALSE whereas
    it would have been interpreted as WHERE "a_column_name" = 'a_value" if
    a_column_name was indeed a column name.

F) RFC 53: OGR not-null constraints and default values

Link: https://gdal.org/en/latest/development/rfc/rfc53_ogr_notnull_default.html

API changes:
    * OGRFieldDefn::SetDefault() now takes a const char* as argument.
      OGRFieldDefn::GetDefaultRef() removed and replaced by GetDefault() that
      returns a const char*

G) RFC 54: Dataset transactions

Link: https://gdal.org/en/latest/development/rfc/rfc54_dataset_transactions.html

Only API additions.

Behavior changes:
  * As described in the RFC, subtle behavior changes can be observed with the PG driver,
    related to implicit transactions that were flushed before and are no longer now,
    but this should hopefully be restricted to non-typical use cases. So some cases that "worked" before might
    no longer work, but the new behavior should hopefully be more understandable.

  * The PG and SQLite drivers could accept apparently nested calls to StartTransaction()
    (at the layer level). This is no longer possible since they are now redirected
    to dataset transactions, that explicitly do not support it.

H) RFC 55: Refined SetFeature() and DeleteFeature() semantics

Link: https://gdal.org/en/latest/development/rfc/rfc55_refined_setfeature_deletefeature_semantics.html

Behavior changes:
    * Drivers will now return OGRERR_NON_EXISTING_FEATURE when calling SetFeature()
      or DeleteFeature() with a feature id that does not exist.

I) RFC 56:

Link: https://gdal.org/en/latest/development/rfc/rfc56_millisecond_precision.html

API/ABI changes:

  * OGRField.Date structure has now a Reserved field that must be set to 0 when
    using the OGRFeature::SetField( int i, OGRField * puValue ) method.
    The "GByte Second" field is now a "float Second".

  * OGRFeature::SetField( int i, int nYear, int nMonth, int nDay,
                          int nHour=0, int nMinute=0, float fSecond=0.f,
                          int nTZFlag = 0 )
    and the variant that take a const char* as first argument now accept a
    floating-point number for seconds.

API additions :

    * OGRFeature::GetFieldAsDateTime( int i,
                                     int *pnYear, int *pnMonth, int *pnDay,
                                     int *pnHour, int *pnMinute, float *pfSecond,
                                     int *pnTZFlag );

    * OGR_F_GetFieldAsDateTimeEx() and OGR_F_SetFieldDateTimeEx() are added.

Driver related changes:

    * The following functions, mainly used by driver implementations, have
      seen their signature change :

        int CPL_DLL OGRParseXMLDateTime( const char* pszXMLDateTime,
                                        OGRField* psField );
        int CPL_DLL OGRParseRFC822DateTime( const char* pszRFC822DateTime,
                                            OGRField* psField );
        char CPL_DLL * OGRGetRFC822DateTime(const OGRField* psField);
        char CPL_DLL * OGRGetXMLDateTime(const OGRField* psField);

Behavior changes:

    * OGRFeature::GetFieldAsString() will now output milliseconds if a DateTime/Time
      field has such precision.
    * Drivers will now output milliseconds if a DateTime/Time field has such precision.

J) RFC 57: 64-bit bucket count for histograms

Link: https://gdal.org/en/latest/development/rfc/rfc57_histogram_64bit_count.html

C++ API:
  * GDALRasterBand::GetHistogram() and GDALRasterBand::SetDefaultHistogram() take a GUIntBig* instead of a int* for bucket counts.
  * GDALRasterBand::GetDefaultHistogram() takes a GUIntBig** instead of a int** for bucket counts.
  * GDALRasterBand::GetRasterSampleOverview() takes a GUIntBig instead of int.

C API:
  * GDALGetRasterHistogramEx(), GDALGetDefaultHistogramEx() and GDALSetDefaultHistogramEx() are added
    and deprecate the old interfaces.
  * GDALGetRasterSampleOverviewEx() is added.

Out-of-tree drivers :
  * See the virtual method API changes mentioned above in the C++ API paragraph.

MIGRATION GUIDE FROM GDAL 1.10 to GDAL 1.11
-------------------------------------------

This file documents backwards incompatible changes.

C++ API:

  * GDALRasterAttributeTable is now an abstract class.
    See https://gdal.org/en/latest/development/rfc/rfc40_enhanced_rat_support.html
    The functionality of GDAL 1.X GDALRasterAttributeTable is now in
    GDALDefaultRasterAttributeTable.

OGR drivers :

  * Due to RFC 41, if a OGR driver calls SetGeomType(wkbNone) on a layer,
    it will be impossible to affect geometries to features of that layer.
    This worked before, although it was inconsistent, but it does no longer now.
    In the development of RFC 41, the CSV and VRT drivers have been upgraded
    to fix such errors.

Changes that should likely not impact anybody :

   * OGRGeometry::exportToGEOS() and OGRGeometryFactory::createFromGEOS() now
     take a GEOSContextHandle_t argument ( GEOS >= 3.1.0 )

   * OGRGeometryFactory::getGEOSGeometryFactory() has been removed.
     This method returned NULL since 2006
     ( https://github.com/OSGeo/gdal/commit/42d5fd976795b9c85aac2c4ffac12025e21697c1#diff-9b267dec2a69d6f56247a5525195973890780ce50ae8c9c809bf4818754f4e46L885 )