RFC 109: Split of gdal_priv.h and addition of public C++ headers

Author:	Even Rouault
Contact:	even.rouault @ spatialys.com
Started:	2025-09-12
Status:	Adopted, implemented
Target:	GDAL 3.12

Summary

This RFC splits the content of gdal_priv.h, the installed header containing declaration for GDAL (raster) C++ classes, into finer grain exported headers. It also adds 3 new exported headers, gdal_raster_cpp.h, gdal_multidim_cpp.h and gdal_vector_cpp.h, the first two ones being essentially the content of current gdal_priv.h header, but with a more engaging name. Those changes are done in a fully backward compatible way: current external users of gdal_priv.h will not have any change to do in their source code.

Motivation

As of today, gdal_priv.h is a 5,600+ line long monolith including 35 classes definitions. There are several disadvantages to that:

• it makes navigating the content of the file difficult for users.

• it may cause longer compilation times when only a subset of the functionality is needed.

• it causes a number of C++ standard or other GDAL header files to be included by default to fulfill the requirements of those classes, but that would not be necessary in third-party code wanting to use the GDAL C++ API.

Another issue is the name itself gdal_priv.h which suggests that this is a private API. While it is true that part of the content of that file is indeed for GDAL private needs, the majority of it is of legitimate use by external C++ users, hence it might be appropriate to offer a more engaging gdal_cpp.h, while still acknowledging that what it exposes might be subject to changes: generally at least ABI changes at each feature release; sometimes API incompatible changes occur.

Technical solution

The content of current gdal_priv.h is spread over the following new exported (installed) header files:

• gdal_multidomainmetadata.h: GDALMultiDomainMetadata class definition

• gdal_majorobject.h: GDALMajorObject class definition

• gdal_defaultoverviews.h: GDALDefaultOverviews class definition

• gdal_openinfo.h: GDALOpenInfo class definition

• gdal_gcp.h: gdal::GCP class definition

• gdal_geotransform: GDALGeoTransform class definition

• gdal_dataset.h: GDALDataset class definition

• gdal_rasterblock.h: GDALRasterBlock class definition

• gdal_colortable.h: GDALColorTable class definition

• gdal_rasterband.h: GDALRasterBand class definition

• gdal_computedrasterband.h: GDALComputedRasterBand class definition

• gdal_maskbands.h: GDALAllValidMaskBand, GDALNoDataMaskBand, GDALNoDataValuesMaskBand, GDALRescaledAlphaBand class definitions (only a subset of out-of-tree drivers might need them)

• gdal_driver.h: GDALDriver class definition

• gdal_drivermanager.h: GDALDriverManager class definition

• gdal_asyncreader.h: GDALAsyncRader class definition

• gdal_multidim.h: definition all classes related to the multidimensional API: GDALGroup, GDALAttribute, GDALMDArray, etc.

• gdal_pam_multidim.h: GDALPamMultiDim and GDALPanMDArray class definitions

• gdal_relationship.h: GDALRelationship class definition

• gdal_cpp_functions.h: public (exported), driver-public (exported) and private (non-exported) C++ methods

Each of this file aims to include the minimum amount of headers (C++ standard headers and GDAL specific headers) required to make it compile in a standalone mode (and this is enforced by a CI check) and use forward class definitions as much as possible.

Three new public entry points header files are added:

• gdal_raster_cpp.h: includes all above files but gdal_multidim.h and gdal_pam_multidim.h

• gdal_multidim_cpp.h: includes gdal_dataset.h, gdal_drivermanager.h, gdal_multidim.h and gdal_pam_multidim.h

• gdal_vector_cpp.h: includes gdal_dataset.h, gdal_drivermanager.h, ogrsf_frmts.h, ogr_feature.h and ogr_geometry.h

The existing gdal_priv.h is modified as following:

• its current inclusion of non-strictly needed GDAL headers, such as CPL ones (cpl_vsi.h, cpl_minixm.h, etc.), GDAL ones (gdal_frmts.h, gdalsubdatasetinfo.h) and OGR ones (ogr_feature.h) are kept by default. Users may define GDAL_PRIV_SKIP_OTHER_GDAL_HEADERS or GDAL_4_0_COMPAT before including gdal_priv.h to avoid including those files.

• its current inclusion of a number of C++ standard headers that might not all be needed is kept by default. Users may define GDAL_PRIV_SKIP_STANDARD_HEADERS or GDAL_4_0_COMPAT before including gdal_priv.h to avoid including those files.

• and finally it includes the new gdal_raster_cpp.h and gdal_multidim_cpp.h files.

The end result is that this whole restructuring should not have any visible effect on current users of gdal_priv.h.

New users targeting only GDAL 3.12+ can now include at their convenience either gdal_raster_cpp.h, gdal_multidim_cpp.h, gdal_vector_cpp.h or any of the new finer grain include files.

Note

The GDALPluginDriverProxy class definition is moved to a GDAL private non-installed gdalplugindriverproxy.h header, since it can only be used by deferred loading plugin drivers, which must thus be in-tree. This class was not CPL_DLL exported.

The GDALAbstractBandBlockCache class definition is moved to a GDAL private non-installed gdal_abstractbandblockcache.h header, since this is an implementation detail, that does not be accessed by users. This class was not CPL_DLL exported.

Backwards compatibility

Changes in this RFC aim at being backward compatible by default.

Documentation

Documentation under https://gdal.org/en/latest/api will be modified to mention the new finer grain headers and entry points.

https://gdal.org/en/latest/tutorials/raster_api_tut.html will be modified to mention the possibility of using the new headers.

Testing

Existing continuous integration should be sufficient to test the non regression;

Related issues and PRs

Candidate implementation: https://github.com/OSGeo/gdal/compare/master...rouault:gdal:gdal_priv_split?expand=1

Funding

Funded by GDAL Sponsorship Program (GSP)

Voting history

+1 from PSC members MikeS, HowardB, DanielM, DanB, JavierJS, KurtS and me, and +0 from JukkaR