gst-libs/gst/floatcast/floatcast.h: Don't include config.h in an installed public...

Original commit message from CVS:
* gst-libs/gst/floatcast/floatcast.h:
Don't include config.h in an installed public header, this
might break compilation of applications that don't have such
a header and doesn't necessarily do what it's supposed to do
anyway (ie. check for the lrint/lrintf defines) (#442065).
Add docs for the various macros and document how this header
has to be used (link against libm, etc.); add a few FIXMEs;
include math.h for non-c99 code path.  Based on patch by
Jan Schmidt.

diff --git a/ChangeLog b/ChangeLog
index a148c91..afa0872 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2007-09-25  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * gst-libs/gst/floatcast/floatcast.h:
+         Don't include config.h in an installed public header, this
+         might break compilation of applications that don't have such
+         a header and doesn't necessarily do what it's supposed to do
+         anyway (ie. check for the lrint/lrintf defines) (#442065).
+         Add docs for the various macros and document how this header
+         has to be used (link against libm, etc.); add a few FIXMEs;
+         include math.h for non-c99 code path.  Based on patch by
+         Jan Schmidt.
+         
 2007-09-25  Sebastian Dröge  <slomo@circular-chaos.org>
 
        * configure.ac:

diff --git a/gst-libs/gst/floatcast/floatcast.h b/gst-libs/gst/floatcast/floatcast.h
index fc26513..a05a6fc 100644 (file)
--- a/gst-libs/gst/floatcast/floatcast.h
+++ b/gst-libs/gst/floatcast/floatcast.h
@@ -21,15 +21,24 @@
 /**
  * SECTION:gstfloatcast
  * @short_description: Floating point platform independence macros
+ *
+ * The floatcast.h header file contains a couple of convenience macros for
+ * floating point numbers.
+ *
+ * If you include this header, your application or library must link against
+ * libm (for maths.h support).
+ *
+ * For optimal results, your application's or library's build
+ * system should check whether the C99 functions lrint and lrintf are supported
+ * and define the preprocessor symbols HAVE_LRINT and HAVE_LRINTF if so.  If
+ * you are using autoconf, you can do this by using the AC_C99_FUNC_LRINT and
+ * AC_C99_FUNC_LRINTF checks in your configure.ac or configure.in file and
+ * including your application's config.h header before you include floatcast.h.
  */
 
 #ifndef __FLOATCAST_H__
 #define __FLOATCAST_H__
 
-#ifdef HAVE_CONFIG_H
-#  include "config.h"
-#endif
-
 #include <string.h>
 #include <glib/gtypes.h>
 #include <glib/gutils.h>  /* to make sure inline is defined properly */
@@ -40,7 +49,26 @@
 
 G_BEGIN_DECLS
 
-#if (HAVE_LRINT && HAVE_LRINTF)
+/* FIXME 0.11: these gst_cast_*() functions are not used anywhere, so we could
+ * just as well get rid of them and move the float/double swap macros into
+ * gstutils.h in core */
+
+/**
+ * gst_cast_float:
+ * @x: input value
+ *
+ * Casts a 32-bit floating point value (float) to an integer without bias.
+ */
+/**
+ * gst_cast_double:
+ * @x: input value
+ *
+ * Casts a 64-bit floating point value (double) to an integer without bias.
+ */
+
+/* FIXME: HAVE_LRINT && HAVE_LRINTF are defined by config.h - they should
+ * not be used in an installed header. */
+#if defined(HAVE_LRINT) && defined(HAVE_LRINTF)
 
         /*      These defines enable functionality introduced with the 1999 ISO C
         **      standard. They must be defined before the inclusion of math.h to
@@ -61,12 +89,23 @@ G_BEGIN_DECLS
         #define gst_cast_double(x)      ((gint)lrint(x))
 
 #else
+        #include <math.h>
+
         /* use a standard c cast, but do rounding correctly */
         #define gst_cast_float(x)       ((gint)floor((x)+0.5))
         #define gst_cast_double(x)      ((gint)floor((x)+0.5))
 
 #endif
 
+/* FIXME 0.11: don't use GLib namespace (GDOUBLE_SWAP_LE_BE, GFLOAT_TO_LE,
+ * GFLOAT_TO_BE, GDOUBLE_TO_LE, GDOUBLE_TO_BE) */
+
+/**
+ * GFLOAT_SWAP_LE_BE:
+ * @in: input value
+ *
+ * Swap byte order of a 32-bit floating point value (float).
+ */
 inline static gfloat
 GFLOAT_SWAP_LE_BE(gfloat in)
 {
@@ -81,6 +120,12 @@ GFLOAT_SWAP_LE_BE(gfloat in)
   return u.f;
 }
 
+/**
+ * GDOUBLE_SWAP_LE_BE:
+ * @in: input value
+ *
+ * Swap byte order of a 64-bit floating point value (double).
+ */
 inline static gdouble
 GDOUBLE_SWAP_LE_BE(gdouble in)
 {
@@ -95,6 +140,64 @@ GDOUBLE_SWAP_LE_BE(gdouble in)
   return u.d;
 }
 
+/**
+ * GDOUBLE_TO_LE:
+ * @val: value
+ *
+ * Convert 64-bit floating point value (double) from native byte order into
+ * little endian byte order.
+ */
+/**
+ * GDOUBLE_TO_BE:
+ * @val: value
+ *
+ * Convert 64-bit floating point value (double) from native byte order into
+ * big endian byte order.
+ */
+/**
+ * GDOUBLE_FROM_LE:
+ * @val: value
+ *
+ * Convert 64-bit floating point value (double) from little endian byte order
+ * into native byte order.
+ */
+/**
+ * GDOUBLE_FROM_BE:
+ * @val: value
+ *
+ * Convert 64-bit floating point value (double) from big endian byte order
+ * into native byte order.
+ */
+
+/**
+ * GFLOAT_TO_LE:
+ * @val: value
+ *
+ * Convert 32-bit floating point value (float) from native byte order into
+ * little endian byte order.
+ */
+/**
+ * GFLOAT_TO_BE:
+ * @val: value
+ *
+ * Convert 32-bit floating point value (float) from native byte order into
+ * big endian byte order.
+ */
+/**
+ * GFLOAT_FROM_LE:
+ * @val: value
+ *
+ * Convert 32-bit floating point value (float) from little endian byte order
+ * into native byte order.
+ */
+/**
+ * GFLOAT_FROM_BE:
+ * @val: value
+ *
+ * Convert 32-bit floating point value (float) from big endian byte order
+ * into native byte order.
+ */
+
 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 #define GFLOAT_TO_LE(val)    ((gfloat) (val))
 #define GFLOAT_TO_BE(val)    (GFLOAT_SWAP_LE_BE (val))