There are several aspects of the API that may change over time.

Version numbers are used to document various kinds of compatibility between different versions.

API Version of a Shared Library

Assuming the API is provided in the form of a shared library (also known as DLL), you may be able to upgrade the API to a new version without recompiling your application and also without relinking your application, just by replacing the old shared library with a new one. There might be API releases that contain only static libraries, or no libraries at all. In both cases the discussion in this section does not apply to you.

The interoperability between your application and the shared library is versioned with the API version number and the following protocol. In your application you ask the shared library for a particular API version by passing the API version number as an argument to the interface querying function mi_neuray_factory_deprecated. The shared library then returns either an interface that conforms to this version, or it returns NULL, which means that this version is not supported.

The API version refers to a particular collection of interfaces and their APIs. It is a single integer number that increases over time. The current API version number is provided with the symbolic name MI_NEURAYLIB_API_VERSION, which is the default argument to the interface querying function.

The shared library always supports its own API version number and, if possible, older API version numbers in order to support upgrades from an older shared library version to a newer version. Older API versions of libraries with the same major product version number (see next section) are always supported, while older API versions of libraries with a different major API version are not guaranteed to be supported. Such support will be documented in the Release Notes.

Major and Minor API Product Version

The product version number for the API governs the compatibility on the source code level, that is, the include files and to some extent on the binary level of the shared library. See the previous section for details on binary compatibility.

DiCE API has a product version number, which consists of three components: major version number, minor version number, and version qualifier.

Detailed description:

Major Version Number
Changes in the major version number indicate a disruptive change without guaranteeing compatibility with prior versions. Details are documented in the Release Notes.
See MI_NEURAYLIB_VERSION_MAJOR in Versioning of the DiCE API.
Minor Version Number
Changes in the minor version number, where the major version number remains unchanged, indicate an upwards compatible change. Old sources compile without changes.
See MI_NEURAYLIB_VERSION_MINOR in Versioning of the DiCE API.
Version Qualifier
A string that indicates special versions, such as alpha and beta releases. Final end-customer releases have an empty version qualifier. The compatibility guarantees described here are only given for end-customer releases and do not hold for new features introduced in alpha or beta releases.
See MI_NEURAYLIB_VERSION_QUALIFIER in Versioning of the DiCE API.

See also