Versioning utility macros

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

Synopsis

#define             COGL_VERSION_MAJOR
#define             COGL_VERSION_MINOR
#define             COGL_VERSION_MICRO
#define             COGL_VERSION_STRING
#define             COGL_VERSION
#define             COGL_VERSION_ENCODE                 (major,
                                                         minor,
                                                         micro)
#define             COGL_VERSION_CHECK                  (major,
                                                         minor,
                                                         micro)
#define             COGL_VERSION_GET_MAJOR              (version)
#define             COGL_VERSION_GET_MINOR              (version)
#define             COGL_VERSION_GET_MICRO              (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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 













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
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 













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
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 













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.

Details

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

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
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 













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

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
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 













#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

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.

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.

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.

version :

 An encoded version number

Since 1.12.0

Generated by GTK-Doc V1.19.1