[Cogl] [PATCH v2] Add a cogl-version header
Robert Bragg
robert at sixbynine.org
Tue Apr 24 10:19:58 PDT 2012
I think you have a minor typo in the commit message where you are
comparing to how clutter defines its version macros. You gave them a
COGL_ instead of a CLUTTER_ prefix.
Apart from that, this looks good to land to me.
Reviewed-by: Robert Bragg <robert at linux.intel.com>
On Tue, Apr 24, 2012 at 5:05 PM, Neil Roberts <neil at linux.intel.com> wrote:
> Here's a second attempt at the patch which adds the COGL_VERSION_CHECK
> and COGL_VERSION_ENCODE macros as we discussed.
>
> I've also moved the generated defines into cogl-defines.h instead of
> generating cogl-version.h because the header is now quite long so it
> doesn't seem right to generate it.
>
> There's also now a test case for it.
>
> Regards,
> - Neil
>
> --- >8 ---
>
> This adds a version header which contains macros to define which
> version of Cogl the application is being compiled against. This helps
> applications that want to support multiple incompatible versions of
> Cogl at compile time.
>
> The macros are called COGL_VERSION_{MAJOR,MINOR,MICRO}. This does not
> match Clutter which names them COGL_{MAJOR,MINOR,MICRO}_VERSION but I
> think the former is nicer and it at least matches Cairo and Pango.
>
> The values of the macro are defined to COGL_VERSION_*_INTERNAL which
> is generated by the configure script into cogl-defines.h.
>
> There is also a macro for the entire version as a string called
> COGL_VERSION_STRING.
>
> The internal utility macros for encoding a 3 part version number into
> a single integer have been moved into the new header so they can be
> used publicly as a convenient way to check if the version is within a
> particular range. There is also a COGL_VERSION_CHECK macro for the
> very common case that a feature will be used since a particular
> version of Cogl. There is a macro called COGL_VERSION which contains
> the pre-encoded version of Cogl being compiled against for
> convenience.
>
> Unlike in Clutter this patch does not add any runtime version
> identification mechanism.
>
> A test case is also added which just contains static asserts to sanity
> check the macros.
> ---
> cogl/Makefile.am | 1 +
> cogl/cogl-defines.h.in | 5 +
> cogl/cogl-gpu-info.c | 2 +-
> cogl/cogl-util.h | 21 ----
> cogl/cogl-version.h | 184 ++++++++++++++++++++++++++++++++
> cogl/cogl.h | 1 +
> doc/reference/cogl2/cogl2-docs.xml.in | 1 +
> doc/reference/cogl2/cogl2-sections.txt | 15 +++
> tests/conform/Makefile.am | 1 +
> tests/conform/test-conform-main.c | 2 +
> tests/conform/test-version.c | 77 +++++++++++++
> 11 files changed, 288 insertions(+), 22 deletions(-)
> create mode 100644 cogl/cogl-version.h
> create mode 100644 tests/conform/test-version.c
>
> diff --git a/cogl/Makefile.am b/cogl/Makefile.am
> index 5a1a5f6..4e821b3 100644
> --- a/cogl/Makefile.am
> +++ b/cogl/Makefile.am
> @@ -96,6 +96,7 @@ cogl_experimental_h = \
> $(srcdir)/cogl-depth-state.h \
> $(srcdir)/cogl-buffer.h \
> $(srcdir)/cogl-pixel-buffer.h \
> + $(srcdir)/cogl-version.h \
> $(NULL)
>
> # driver sources
> diff --git a/cogl/cogl-defines.h.in b/cogl/cogl-defines.h.in
> index ccdca06..a9c0b5c 100644
> --- a/cogl/cogl-defines.h.in
> +++ b/cogl/cogl-defines.h.in
> @@ -40,6 +40,11 @@ G_BEGIN_DECLS
> #define NativeWindowType EGLNativeWindowType
> #endif
>
> +#define COGL_VERSION_MAJOR_INTERNAL @COGL_MAJOR_VERSION@
> +#define COGL_VERSION_MINOR_INTERNAL @COGL_MINOR_VERSION@
> +#define COGL_VERSION_MICRO_INTERNAL @COGL_MICRO_VERSION@
> +#define COGL_VERSION_STRING_INTERNAL "@COGL_VERSION@"
> +
> G_END_DECLS
>
> #endif
> diff --git a/cogl/cogl-gpu-info.c b/cogl/cogl-gpu-info.c
> index 993c590..aa70843 100644
> --- a/cogl/cogl-gpu-info.c
> +++ b/cogl/cogl-gpu-info.c
> @@ -30,7 +30,7 @@
>
> #include "cogl-gpu-info-private.h"
> #include "cogl-context-private.h"
> -#include "cogl-util.h"
> +#include "cogl-version.h"
>
> typedef struct
> {
> diff --git a/cogl/cogl-util.h b/cogl/cogl-util.h
> index 698391a..4458985 100644
> --- a/cogl/cogl-util.h
> +++ b/cogl/cogl-util.h
> @@ -52,27 +52,6 @@
> #define COGL_EXPORT
> #endif
>
> -/* Macros to handle compacting a 3-component version number into an
> - int for quick comparison. This assumes all of the components are
> - <= 1023 */
> -#define COGL_VERSION_COMPONENT_BITS 10
> -#define COGL_VERSION_MAX_COMPONENT_VALUE \
> - ((1 << COGL_VERSION_COMPONENT_BITS) - 1)
> -
> -#define COGL_VERSION_ENCODE(major, minor, micro) \
> - (((major) << (COGL_VERSION_COMPONENT_BITS * 2)) | \
> - ((minor) << COGL_VERSION_COMPONENT_BITS) \
> - | (micro))
> -
> -#define COGL_VERSION_GET_MAJOR(version) \
> - (((version) >> 20) & COGL_VERSION_MAX_COMPONENT_VALUE)
> -
> -#define COGL_VERSION_GET_MINOR(version) \
> - (((version) >> 10) & COGL_VERSION_MAX_COMPONENT_VALUE)
> -
> -#define COGL_VERSION_GET_MICRO(version) \
> - ((version) & COGL_VERSION_MAX_COMPONENT_VALUE)
> -
> int
> _cogl_util_next_p2 (int a);
>
> diff --git a/cogl/cogl-version.h b/cogl/cogl-version.h
> new file mode 100644
> index 0000000..ca1177f
> --- /dev/null
> +++ b/cogl/cogl-version.h
> @@ -0,0 +1,184 @@
> +/*
> + * Cogl
> + *
> + * An object oriented GL/GLES Abstraction/Utility Layer
> + *
> + * Copyright (C) 2012 Intel Corporation.
> + *
> + * This library is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU Lesser General Public
> + * License as published by the Free Software Foundation; either
> + * version 2 of the License, or (at your option) any later version.
> + *
> + * This library is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
> + * Lesser General Public License for more details.
> + *
> + * You should have received a copy of the GNU Lesser General Public
> + * License along with this library. If not, see <http://www.gnu.org/licenses/>.
> + *
> + *
> + */
> +
> +#ifndef __COGL_VERSION_H__
> +#define __COGL_VERSION_H__
> +
> +#include <cogl/cogl-defines.h>
> +
> +/**
> + * SECTION:cogl-version
> + * @short_description: Macros for determining the version of Cogl being used
> + *
> + * Cogl offers a set of macros for checking the version of the library
> + * at compile time.
> + *
> + * Since: 2.0
> + */
> +
> +/**
> + * COGL_VERSION_MAJOR:
> + *
> + * The major version of the Cogl library (1, if %COGL_VERSION is 1.2.3)
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_MAJOR COGL_VERSION_MAJOR_INTERNAL
> +
> +/**
> + * COGL_VERSION_MINOR:
> + *
> + * The minor version of the Cogl library (2, if %COGL_VERSION is 1.2.3)
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_MINOR COGL_VERSION_MINOR_INTERNAL
> +
> +/**
> + * COGL_VERSION_MICRO:
> + *
> + * The micro version of the Cogl library (3, if %COGL_VERSION is 1.2.3)
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_MICRO COGL_VERSION_MICRO_INTERNAL
> +
> +/**
> + * COGL_VERSION_STRING:
> + *
> + * The full version of the Cogl library, in string form (suited for
> + * string concatenation)
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_STRING COGL_VERSION_STRING_INTERNAL
> +
> +/* Macros to handle compacting a 3-component version number into an
> + * int for quick comparison. This assumes all of the components are <=
> + * 1023 and that an int is >= 31 bits */
> +#define COGL_VERSION_COMPONENT_BITS 10
> +#define COGL_VERSION_MAX_COMPONENT_VALUE \
> + ((1 << COGL_VERSION_COMPONENT_BITS) - 1)
> +
> +/**
> + * 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: 2.0
> + */
> +#define COGL_VERSION \
> + COGL_VERSION_ENCODE (COGL_VERSION_MAJOR, \
> + COGL_VERSION_MINOR, \
> + COGL_VERSION_MICRO)
> +
> +/**
> + * COGL_VERSION_ENCODE:
> + * @major: The major part of a version number
> + * @minor: The minor part of a version number
> + * @micro: The micro part of a version number
> + *
> + * 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:
> + *
> + * |[
> + * #if COGL_VERSION >= COGL_VERSION_ENCODE (1, 3, 2) && \
> + * COGL_VERSION <= COGL_VERSION_ENCODE (1, 3, 4)
> + * /<!-- -->* Do the workaround *<!-- -->/
> + * #endif
> + * ]|
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_ENCODE(major, minor, micro) \
> + (((major) << (COGL_VERSION_COMPONENT_BITS * 2)) | \
> + ((minor) << COGL_VERSION_COMPONENT_BITS) \
> + | (micro))
> +
> +/**
> + * COGL_VERSION_GET_MAJOR:
> + * @version: An encoded version number
> + *
> + * Extracts the major part of an encoded version number.
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_GET_MAJOR(version) \
> + (((version) >> (COGL_VERSION_COMPONENT_BITS * 2)) \
> + & COGL_VERSION_MAX_COMPONENT_VALUE)
> +
> +/**
> + * COGL_VERSION_GET_MINOR:
> + * @version: An encoded version number
> + *
> + * Extracts the minor part of an encoded version number.
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_GET_MINOR(version) \
> + (((version) >> COGL_VERSION_COMPONENT_BITS) & \
> + COGL_VERSION_MAX_COMPONENT_VALUE)
> +
> +/**
> + * COGL_VERSION_GET_MICRO:
> + * @version: An encoded version number
> + *
> + * Extracts the micro part of an encoded version number.
> + *
> + * Since: 2.0
> + */
> +#define COGL_VERSION_GET_MICRO(version) \
> + ((version) & COGL_VERSION_MAX_COMPONENT_VALUE)
> +
> +/**
> + * COGL_VERSION_CHECK:
> + * @major: The major part of a version number
> + * @minor: The minor part of a version number
> + * @micro: The micro part of a version number
> + *
> + * 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:
> + *
> + * |[
> + * #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
> + * ]|
> + *
> + * Return value: %TRUE if the Cogl version being compiled against is
> + * greater than or equal to the given three part version number.
> + */
> +#define COGL_VERSION_CHECK(major, minor, micro) \
> + (COGL_VERSION >= COGL_VERSION_ENCODE (major, minor, micro))
> +
> +#endif /* __COGL_VERSION_H__ */
> diff --git a/cogl/cogl.h b/cogl/cogl.h
> index 80e6d9c..7ce7e32 100644
> --- a/cogl/cogl.h
> +++ b/cogl/cogl.h
> @@ -55,6 +55,7 @@
> #include <cogl/cogl-texture.h>
> #include <cogl/cogl-types.h>
> #include <cogl/cogl-path.h>
> +#include <cogl/cogl-version.h>
>
> /*
> * 1.x only api...
> diff --git a/doc/reference/cogl2/cogl2-docs.xml.in b/doc/reference/cogl2/cogl2-docs.xml.in
> index 6c9b91c..8e3a302 100644
> --- a/doc/reference/cogl2/cogl2-docs.xml.in
> +++ b/doc/reference/cogl2/cogl2-docs.xml.in
> @@ -127,6 +127,7 @@
> <xi:include href="xml/cogl-vector.xml"/>
> <xi:include href="xml/cogl-quaternion.xml"/>
> <xi:include href="xml/cogl-types.xml"/>
> + <xi:include href="xml/cogl-version.xml"/>
> </section>
>
> <section id="cogl-integration">
> diff --git a/doc/reference/cogl2/cogl2-sections.txt b/doc/reference/cogl2/cogl2-sections.txt
> index 9c10d68..4f7117a 100644
> --- a/doc/reference/cogl2/cogl2-sections.txt
> +++ b/doc/reference/cogl2/cogl2-sections.txt
> @@ -761,6 +761,21 @@ cogl_vector3_distance
> </SECTION>
>
> <SECTION>
> +<FILE>cogl-version</FILE>
> +<TITLE>Versioning utility macros</TITLE>
> +COGL_VERSION_MAJOR
> +COGL_VERSION_MINOR
> +COGL_VERSION_MICRO
> +COGL_VERSION_STRING
> +COGL_VERSION
> +COGL_VERSION_ENCODE
> +COGL_VERSION_CHECK
> +COGL_VERSION_GET_MAJOR
> +COGL_VERSION_GET_MINOR
> +COGL_VERSION_GET_MICRO
> +</SECTION>
> +
> +<SECTION>
> <FILE>cogl-types</FILE>
> <TITLE>Common Types</TITLE>
> CoglFuncPtr
> diff --git a/tests/conform/Makefile.am b/tests/conform/Makefile.am
> index 394e776..8379fe6 100644
> --- a/tests/conform/Makefile.am
> +++ b/tests/conform/Makefile.am
> @@ -53,6 +53,7 @@ test_sources = \
> test-point-size.c \
> test-point-sprite.c \
> test-no-gl-header.c \
> + test-version.c \
> $(NULL)
>
> test_conformance_SOURCES = $(common_sources) $(test_sources)
> diff --git a/tests/conform/test-conform-main.c b/tests/conform/test-conform-main.c
> index 1e2ddd2..bb1c48c 100644
> --- a/tests/conform/test-conform-main.c
> +++ b/tests/conform/test-conform-main.c
> @@ -95,6 +95,8 @@ main (int argc, char **argv)
> ADD_TEST (test_point_sprite,
> TEST_KNOWN_FAILURE | TEST_REQUIREMENT_POINT_SPRITE);
>
> + ADD_TEST (test_version, 0);
> +
> UNPORTED_TEST (test_viewport);
>
> g_printerr ("Unknown test name \"%s\"\n", argv[1]);
> diff --git a/tests/conform/test-version.c b/tests/conform/test-version.c
> new file mode 100644
> index 0000000..f1d9de9
> --- /dev/null
> +++ b/tests/conform/test-version.c
> @@ -0,0 +1,77 @@
> +#include <cogl/cogl.h>
> +
> +/* These will be redefined in config.h */
> +#undef COGL_ENABLE_EXPERIMENTAL_2_0_API
> +#undef COGL_ENABLE_EXPERIMENTAL_API
> +
> +#include "test-utils.h"
> +#include "config.h"
> +#include <cogl/cogl-util.h>
> +
> +_COGL_STATIC_ASSERT (COGL_VERSION_ENCODE (COGL_VERSION_MAJOR,
> + COGL_VERSION_MINOR,
> + COGL_VERSION_MICRO) ==
> + COGL_VERSION,
> + "The pre-encoded Cogl version does not match the version "
> + "encoding macro");
> +
> +_COGL_STATIC_ASSERT (COGL_VERSION_GET_MAJOR (COGL_VERSION_ENCODE (100,
> + 200,
> + 300)) ==
> + 100,
> + "Getting the major component out of a encoded version "
> + "does not work");
> +_COGL_STATIC_ASSERT (COGL_VERSION_GET_MINOR (COGL_VERSION_ENCODE (100,
> + 200,
> + 300)) ==
> + 200,
> + "Getting the minor component out of a encoded version "
> + "does not work");
> +_COGL_STATIC_ASSERT (COGL_VERSION_GET_MICRO (COGL_VERSION_ENCODE (100,
> + 200,
> + 300)) ==
> + 300,
> + "Getting the micro component out of a encoded version "
> + "does not work");
> +
> +_COGL_STATIC_ASSERT (COGL_VERSION_CHECK (COGL_VERSION_MAJOR,
> + COGL_VERSION_MINOR,
> + COGL_VERSION_MICRO),
> + "Checking the Cogl version against the current version "
> + "does not pass");
> +_COGL_STATIC_ASSERT (!COGL_VERSION_CHECK (COGL_VERSION_MAJOR,
> + COGL_VERSION_MINOR,
> + COGL_VERSION_MICRO + 1),
> + "Checking the Cogl version against a later micro version "
> + "should not pass");
> +_COGL_STATIC_ASSERT (!COGL_VERSION_CHECK (COGL_VERSION_MAJOR,
> + COGL_VERSION_MINOR + 1,
> + COGL_VERSION_MICRO),
> + "Checking the Cogl version against a later minor version "
> + "should not pass");
> +_COGL_STATIC_ASSERT (!COGL_VERSION_CHECK (COGL_VERSION_MAJOR + 1,
> + COGL_VERSION_MINOR,
> + COGL_VERSION_MICRO),
> + "Checking the Cogl version against a later major version "
> + "should not pass");
> +
> +_COGL_STATIC_ASSERT (COGL_VERSION_CHECK (COGL_VERSION_MAJOR - 1,
> + COGL_VERSION_MINOR,
> + COGL_VERSION_MICRO),
> + "Checking the Cogl version against a older major version "
> + "should pass");
> +
> +void
> +test_version (void)
> +{
> + const char *version = g_strdup_printf ("version = %i.%i.%i",
> + COGL_VERSION_MAJOR,
> + COGL_VERSION_MINOR,
> + COGL_VERSION_MICRO);
> +
> + g_assert_cmpstr (version, ==, "version = " COGL_VERSION_STRING);
> +
> + if (cogl_test_verbose ())
> + g_print ("OK\n");
> +}
> +
> --
> 1.7.3.16.g9464b
>
> _______________________________________________
> Cogl mailing list
> Cogl at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/cogl
More information about the Cogl
mailing list