Versioning utility macros

## Versioning utility macros Versioning utility macros — Macros for determining the version of Cogl being used |

## Functions

#define | COGL_VERSION_ENCODE()
#define | COGL_VERSION_CHECK()
#define | COGL_VERSION_GET_MAJOR()
#define | COGL_VERSION_GET_MINOR()
#define | COGL_VERSION_GET_MICRO()

## Types and Values

#define | COGL_VERSION_MAJOR
#define | COGL_VERSION_MINOR
#define | COGL_VERSION_MICRO
#define | COGL_VERSION_STRING
#define | COGL_VERSION

## Description

Cogl offers a set of macros for checking the version of the library at compile time.

Cogl adds version information to both API deprecations and additions; by definining the macros `COGL_VERSION_MIN_REQUIRED` and `COGL_VERSION_MAX_ALLOWED`, you can specify the range of Cogl versions whose API you want to use. Functions that were deprecated before, or introduced after, this range will trigger compiler warnings. For instance, if we define the following symbols:

    1
    2
    COGL_VERSION_MIN_REQUIRED = COGL_VERSION_1_6
    COGL_VERSION_MAX_ALLOWED  = COGL_VERSION_1_8

and we have the following functions annotated in the Cogl headers:

    1
    2
    3
    4
    COGL_DEPRECATED_IN_1_4 void cogl_function_A (void);
    COGL_DEPRECATED_IN_1_6 void cogl_function_B (void);
    COGL_AVAILABLE_IN_1_8 void cogl_function_C (void);
    COGL_AVAILABLE_IN_1_10 void cogl_function_D (void);

then any application code using the functions above will get the output:

    1
    2
    3
    4
    cogl_function_A: deprecation warning
    cogl_function_B: no warning
    cogl_function_C: no warning
    cogl_function_D: symbol not available warning

It is possible to disable the compiler warnings by defining the macro `COGL_DISABLE_DEPRECATION_WARNINGS` before including the cogl.h header.

## Functions

### COGL_VERSION_ENCODE()

    #define             COGL_VERSION_ENCODE(major, minor, micro)

Encodes a 3 part version number into a single integer. This can be used to compare the Cogl version. For example if there is a known bug in Cogl versions between 1.3.2 and 1.3.4 you could use the following code to provide a workaround:

    1
    2
    3
    4
    #if COGL_VERSION >= COGL_VERSION_ENCODE (1, 3, 2) && \
        COGL_VERSION <= COGL_VERSION_ENCODE (1, 3, 4)
      /<!-- -->* Do the workaround *<!-- -->/
    #endif

#### Parameters

major | The major part of a version number |
minor | The minor part of a version number |
micro | The micro part of a version number |

Since 1.12.0

### COGL_VERSION_CHECK()

    #define             COGL_VERSION_CHECK(major, minor, micro)

A convenient macro to check whether the Cogl version being compiled against is at least the given version number. For example if the function cogl_pipeline_frobnicate was added in version 2.0.1 and you want to conditionally use that function when it is available, you could write the following:

    1
    2
    3
    4
    5
    6
    #if COGL_VERSION_CHECK (2, 0, 1)
    cogl_pipeline_frobnicate (pipeline);
    #else
    /<!-- -->* Frobnication is not supported. Use a red color instead *<!-- -->/
    cogl_pipeline_set_color_4f (pipeline, 1.0f, 0.0f, 0.0f, 1.0f);
    #endif

#### Parameters

major | The major part of a version number |
minor | The minor part of a version number |
micro | The micro part of a version number |

#### Returns

`TRUE` if the Cogl version being compiled against is greater than or equal to the given three part version number.

Since 1.12.0

### COGL_VERSION_GET_MAJOR()

    #define             COGL_VERSION_GET_MAJOR(version)

Extracts the major part of an encoded version number.

#### Parameters

version | An encoded version number |

Since 1.12.0

### COGL_VERSION_GET_MINOR()

    #define             COGL_VERSION_GET_MINOR(version)

Extracts the minor part of an encoded version number.

#### Parameters

version | An encoded version number |

Since 1.12.0

### COGL_VERSION_GET_MICRO()

    #define             COGL_VERSION_GET_MICRO(version)

Extracts the micro part of an encoded version number.

#### Parameters

version | An encoded version number |

Since 1.12.0

## Types and Values

### COGL_VERSION_MAJOR

    #define COGL_VERSION_MAJOR COGL_VERSION_MAJOR_INTERNAL

The major version of the Cogl library (1, if `COGL_VERSION` is 1.2.3)

Since 1.12.0

### COGL_VERSION_MINOR

    #define COGL_VERSION_MINOR COGL_VERSION_MINOR_INTERNAL

The minor version of the Cogl library (2, if `COGL_VERSION` is 1.2.3)

Since 1.12.0

### COGL_VERSION_MICRO

    #define COGL_VERSION_MICRO COGL_VERSION_MICRO_INTERNAL

The micro version of the Cogl library (3, if `COGL_VERSION` is 1.2.3)

Since 1.12.0

### COGL_VERSION_STRING

    #define COGL_VERSION_STRING COGL_VERSION_STRING_INTERNAL

The full version of the Cogl library, in string form (suited for string concatenation)

Since 1.12.0

### COGL_VERSION

    #define             COGL_VERSION

The Cogl version encoded into a single integer using the `COGL_VERSION_ENCODE()` macro. This can be used for quick comparisons with particular versions.

Since 1.12.0