Fixed Point Support

Fixed Point Support — Fixed Point API

Synopsis

typedef             ClutterFixed;
#define             CFX_Q
#define             CFX_ONE
#define             CFX_HALF
#define             CFX_MAX
#define             CFX_MIN
#define             CFX_PI
#define             CFX_2PI
#define             CFX_PI_2
#define             CFX_PI_4
#define             CFX_120
#define             CFX_180
#define             CFX_240
#define             CFX_360
#define             CFX_60
#define             CFX_255
#define             CLUTTER_FIXED_TO_INT                (x)
#define             CLUTTER_FIXED_TO_FLOAT              (x)
#define             CLUTTER_FIXED_TO_DOUBLE             (x)
#define             CLUTTER_FLOAT_TO_FIXED              (x)
#define             CLUTTER_FLOAT_TO_INT                (x)
#define             CLUTTER_FLOAT_TO_UINT               (x)
#define             CLUTTER_INT_TO_FIXED                (x)
#define             CLUTTER_FIXED_INT                   (x)
#define             CLUTTER_FIXED_FRACTION              (x)
#define             CLUTTER_FIXED_FLOOR                 (x)
#define             CLUTTER_FIXED_CEIL                  (x)
#define             CLUTTER_FIXED_MUL                   (x,y)
#define             CLUTTER_FIXED_DIV                   (x,y)
typedef             ClutterAngle;
#define             CLUTTER_ANGLE_FROM_DEG              (x)
#define             CLUTTER_ANGLE_FROM_DEGF             (x)
#define             CLUTTER_ANGLE_FROM_DEGX             (x)
#define             CLUTTER_ANGLE_TO_DEGF               (x)
#define             CLUTTER_ANGLE_TO_DEG                (x)
#define             CLUTTER_ANGLE_TO_DEGX               (x)
#define             CLUTTER_ANGLE_MAX_DEG
#define             CFX_RADIANS_TO_DEGREES
#define             clutter_cosi                        (angle)
#define             clutter_cosx                        (angle)
ClutterFixed        clutter_sini                        (ClutterAngle angle);
ClutterFixed        clutter_sinx                        (ClutterFixed angle);
#define             CLUTTER_SQRTI_ARG_10_PERCENT
#define             CLUTTER_SQRTI_ARG_5_PERCENT
#define             CLUTTER_SQRTI_ARG_MAX
gint                clutter_sqrti                       (gint x);
ClutterFixed        clutter_sqrtx                       (ClutterFixed x);
ClutterFixed        clutter_log2x                       (guint x);
guint               clutter_pow2x                       (ClutterFixed x);
guint               clutter_powx                        (guint x,
                                                         ClutterFixed y);
ClutterFixed        clutter_qmulx                       (ClutterFixed op1,
                                                         ClutterFixed op2);
ClutterFixed        clutter_qdivx                       (ClutterFixed op1,
                                                         ClutterFixed op2);
ClutterFixed        clutter_tani                        (ClutterAngle angle);
ClutterFixed        clutter_atani                       (ClutterFixed x);
ClutterFixed        clutter_atan2i                      (ClutterFixed y,
                                                         ClutterFixed x);

#define             CLUTTER_MAXFIXED
#define             CLUTTER_MINFIXED
                    ClutterParamSpecFixed;
GParamSpec*         clutter_param_spec_fixed            (const gchar *name,
                                                         const gchar *nick,
                                                         const gchar *blurb,
                                                         ClutterFixed minimum,
                                                         ClutterFixed maximum,
                                                         ClutterFixed default_value,
                                                         GParamFlags flags);
#define             CLUTTER_VALUE_HOLDS_FIXED           (x)
void                clutter_value_set_fixed             (GValue *value,
                                                         ClutterFixed fixed_);
ClutterFixed        clutter_value_get_fixed             (const GValue *value);

Description

Clutter has a fixed point API targeted at platforms without a floating point unit, such as embedded devices. On such platforms this API should be preferred to the floating point one as it does not trigger the slow path of software emulation, relying on integer math for fixed-to-floating and floating-to-fixed conversion.

It is no recommened for use on platforms with a floating point unit (eg desktop systems) nor for use in bindings.

Basic rules of Fixed Point arithmethic:

  • Two fixed point numbers can be directly added, subtracted and have their modulus taken.

  • To add other numerical type to a fixed point number it has to be first converted to fixed point.

  • A fixed point number can be directly multiplied or divided by an integer.

  • Two fixed point numbers can only be multiplied and divided by the provided CLUTTER_FIXED_MUL and CLUTTER_FIXED_DIV macros.

Details

ClutterFixed

typedef gint32 ClutterFixed;

Fixed point number (16.16)

CFX_Q

#define CFX_Q      16		/* Decimal part size in bits */

Size in bits of decimal part of floating point value.

CFX_ONE

#define CFX_ONE    (1 << CFX_Q)	/* 1 */

1.0 represented as a fixed point value.

CFX_HALF

#define CFX_HALF   32768

0.5 represented as a fixed point value.

CFX_MAX

#define CFX_MAX    0x7fffffff

Maximum fixed point value.

CFX_MIN

#define CFX_MIN    0x80000000

Minimum fixed point value.

CFX_PI

#define CFX_PI     0x0003243f

Fixed point representation of Pi

CFX_2PI

#define CFX_2PI    0x0006487f

Fixed point representation of Pi*2

CFX_PI_2

#define CFX_PI_2   0x00019220   /* pi/2 */

Fixed point representation of Pi/2

CFX_PI_4

#define CFX_PI_4   0x0000c910   /* pi/4 */

Fixed point representation of Pi/4

CFX_120

#define CFX_120 CLUTTER_INT_TO_FIXED (120)

Fixed point representation of the number 120

CFX_180

#define CFX_180 CLUTTER_INT_TO_FIXED (180)

Fixed point representation of the number 180

CFX_240

#define CFX_240 CLUTTER_INT_TO_FIXED (240)

Fixed point representation of the number 240

CFX_360

#define CFX_360 CLUTTER_INT_TO_FIXED (360)

Fixed point representation of the number 360

CFX_60

#define CFX_60  CLUTTER_INT_TO_FIXED (60)

Fixed point representation of the number 60

CFX_255

#define CFX_255 CLUTTER_INT_TO_FIXED (255)

Fixed point representation of the number 255

CLUTTER_FIXED_TO_INT()

#define CLUTTER_FIXED_TO_INT(x)         ((x) >> CFX_Q)

Converts a fixed point value to integer (removing the decimal part).

x :

 a fixed point value

Since 0.6

CLUTTER_FIXED_TO_FLOAT()

#define CLUTTER_FIXED_TO_FLOAT(x)       ((float) ((int)(x) / 65536.0))

Convert a fixed point value to float.

x :

 a fixed point value

CLUTTER_FIXED_TO_DOUBLE()

#define CLUTTER_FIXED_TO_DOUBLE(x)      ((double) ((int)(x) / 65536.0))

Convert a fixed point value to double.

x :

 a fixed point value

CLUTTER_FLOAT_TO_FIXED()

#define CLUTTER_FLOAT_TO_FIXED(x)       (clutter_double_to_fixed ((x)))

Convert a float value to fixed.

x :

 a floating point value

CLUTTER_FLOAT_TO_INT()

#define CLUTTER_FLOAT_TO_INT(x)         (clutter_double_to_int ((x)))

Convert a float value to int.

x :

 a floating point value

CLUTTER_FLOAT_TO_UINT()

#define CLUTTER_FLOAT_TO_UINT(x)         (clutter_double_to_uint ((x)))

Convert a float value to unsigned int.

x :

 a floating point value

CLUTTER_INT_TO_FIXED()

#define CLUTTER_INT_TO_FIXED(x)         ((x) << CFX_Q)

Convert an integer value to fixed point.

x :

 an integer value

CLUTTER_FIXED_INT()

#define CLUTTER_FIXED_INT(x)            CLUTTER_FIXED_TO_INT((x))

Warning

CLUTTER_FIXED_INT has been deprecated since version 0.6 and should not be used in newly-written code. Use CLUTTER_FIXED_TO_INT instead

Convert a fixed point value to integer (removing decimal part).

x :

 a fixed point value

CLUTTER_FIXED_FRACTION()

#define CLUTTER_FIXED_FRACTION(x)       ((x) & ((1 << CFX_Q) - 1))

Retrieves the fractionary part of a fixed point value

x :

 a fixed point value

CLUTTER_FIXED_FLOOR()

#define             CLUTTER_FIXED_FLOOR(x)

Round down a fixed point value to an integer.

x :

 a fixed point value

CLUTTER_FIXED_CEIL()

#define CLUTTER_FIXED_CEIL(x)           (CLUTTER_FIXED_FLOOR (x + 0xffff))

Round up a fixed point value to an integer.

x :

 a fixed point value

CLUTTER_FIXED_MUL()

#define CLUTTER_FIXED_MUL(x,y) ((x) >> 8) * ((y) >> 8)

Multiply two fixed point values

x :

 a fixed point value

y :

 a fixed point value

CLUTTER_FIXED_DIV()

#define CLUTTER_FIXED_DIV(x,y) ((((x) << 8)/(y)) << 8)

Divide two fixed point values

x :

 a fixed point value

y :

 a fixed point value

ClutterAngle

typedef gint32 ClutterAngle;    /* angle such that 1024 == 2*PI */

Integer representation of an angle such that 1024 corresponds to full circle (i.e., 2*Pi).

CLUTTER_ANGLE_FROM_DEG()

#define CLUTTER_ANGLE_FROM_DEG(x)  (CLUTTER_FLOAT_TO_INT (((x) * 1024.0) / 360.0))

x :

CLUTTER_ANGLE_FROM_DEGF()

#define CLUTTER_ANGLE_FROM_DEGF(x) (CLUTTER_FLOAT_TO_INT (((float)(x) * 1024.0f) / 360.0f))

x :

CLUTTER_ANGLE_FROM_DEGX()

#define CLUTTER_ANGLE_FROM_DEGX(x) (CFX_INT((((x)/360)*1024) + CFX_HALF))

x :

CLUTTER_ANGLE_TO_DEGF()

#define CLUTTER_ANGLE_TO_DEGF(x)   (((float)(x) * 360.0)/ 1024.0)

x :

CLUTTER_ANGLE_TO_DEG()

#define CLUTTER_ANGLE_TO_DEG(x)    (((x) * 360.0)/ 1024.0)

x :

CLUTTER_ANGLE_TO_DEGX()

#define CLUTTER_ANGLE_TO_DEGX(x)   (CLUTTER_INT_TO_FIXED((x) * 45)/128)

x :

CLUTTER_ANGLE_MAX_DEG

#define CLUTTER_ANGLE_MAX_DEG 1509949439.6

CFX_RADIANS_TO_DEGREES

#define CFX_RADIANS_TO_DEGREES 0x394bb8

Fixed point representation of the number 180 / pi

clutter_cosi()

#define clutter_cosi(angle) (clutter_sini ((angle) + 256))

Very fast fixed point implementation of cosine function.

ClutterAngle is an integer such that 1024 represents full circle.

angle :

 a ClutterAngle angle

Since 0.2

clutter_cosx()

#define clutter_cosx(angle) (clutter_sinx((angle) + CFX_PI_2))

Fixed point cosine function

angle :

 a ClutterFixed angle in radians

Since 0.2

clutter_sini ()

ClutterFixed        clutter_sini                        (ClutterAngle angle);

Very fast fixed point implementation of sine function.

ClutterAngle is an integer such that 1024 represents full circle.

angle :

 a ClutterAngle

Returns :

 ClutterFixed sine value.

Since 0.2

clutter_sinx ()

ClutterFixed        clutter_sinx                        (ClutterFixed angle);

Fixed point implementation of sine function

angle :

 a ClutterFixed angle in radians

Returns :

 ClutterFixed sine value.

Since 0.2

CLUTTER_SQRTI_ARG_10_PERCENT

#define             CLUTTER_SQRTI_ARG_10_PERCENT

Maximum argument that can be passed to clutter_sqrti for which the resulting error is < 10%

Since 0.6

CLUTTER_SQRTI_ARG_5_PERCENT

#define             CLUTTER_SQRTI_ARG_5_PERCENT

Maximum argument that can be passed to clutter_sqrti for which the resulting error is < 5%

Since 0.6

CLUTTER_SQRTI_ARG_MAX

#define             CLUTTER_SQRTI_ARG_MAX

Maximum argument that can be passed to clutter_sqrti function.

Since 0.6

clutter_sqrti ()

gint                clutter_sqrti                       (gint x);

Very fast fixed point implementation of square root for integers.

This function is at least 6x faster than clib sqrt() on x86, and (this is not a typo!) about 500x faster on ARM without FPU. It's error is < 5% for arguments < CLUTTER_SQRTI_ARG_5_PERCENT and < 10% for arguments < CLUTTER_SQRTI_ARG_10_PERCENT. The maximum argument that can be passed to this function is CLUTTER_SQRTI_ARG_MAX.

x :

 integer value

Returns :

 integer square root.

Since 0.2

clutter_sqrtx ()

ClutterFixed        clutter_sqrtx                       (ClutterFixed x);

A fixed point implementation of squre root

x :

 a ClutterFixed

Returns :

 ClutterFixed square root.

Since 0.2

clutter_log2x ()

ClutterFixed        clutter_log2x                       (guint x);

Calculates base 2 logarithm.

This function is some 2.5 times faster on x86, and over 12 times faster on fpu-less arm, than using libc log().

x :

 value to calculate base 2 logarithm from

Returns :

 base 2 logarithm.

Since 0.4

clutter_pow2x ()

guint               clutter_pow2x                       (ClutterFixed x);

Calculates 2 to x power.

This function is around 11 times faster on x86, and around 22 times faster on fpu-less arm than libc pow(2, x).

x :

 exponent

Returns :

 2 in x power.

Since 0.4

clutter_powx ()

guint               clutter_powx                        (guint x,
                                                         ClutterFixed y);

Calculates x to y power. (Note, if x is a constant it will be faster to calculate the power as clutter_pow2x (CLUTTER_FIXED_MUL(y, log2 (x)))

x :

 base

y :

 ClutterFixed exponent

Returns :

 x in y power.

Since 0.4

clutter_qmulx ()

ClutterFixed        clutter_qmulx                       (ClutterFixed op1,
                                                         ClutterFixed op2);

Multiplies two fixed values using 64bit arithmetic; this provides significantly better precission than the CLUTTER_FIXED_MUL macro, but at performance cost (about 2.7 times slowdown on ARMv5e, and 2 times on x86).

op1 :

 ClutterFixed

op2 :

 ClutterFixed

Returns :

 the result of the operation

Since 0.4

clutter_qdivx ()

ClutterFixed        clutter_qdivx                       (ClutterFixed op1,
                                                         ClutterFixed op2);

Divides two fixed values using 64bit arithmetic; this provides significantly better precission than the CLUTTER_FIXED_DIV macro, but at performance cost.

op1 :

 ClutterFixed

op2 :

 ClutterFixed

Returns :

 ClutterFixed

Since 0.4

clutter_tani ()

ClutterFixed        clutter_tani                        (ClutterAngle angle);

Very fast fixed point implementation of tan function.

ClutterAngle is an integer such that 1024 represents full circle.

angle :

 a ClutterAngle

Returns :

 ClutterFixed sine value.

Since 0.3

clutter_atani ()

ClutterFixed        clutter_atani                       (ClutterFixed x);

Fast fixed-point version of the arctangent function.

x :

 The tangent to calculate the angle for

Returns :

 The angle in radians represented as a ClutterFixed for which the tangent is x.

clutter_atan2i ()

ClutterFixed        clutter_atan2i                      (ClutterFixed y,
                                                         ClutterFixed x);

Calculates the arctangent of y / x but uses the sign of both arguments to return the angle in right quadrant.

y :

 Numerator of tangent

x :

 Denominator of tangent

Returns :

 The arctangent of y / x

CLUTTER_MAXFIXED

#define CLUTTER_MAXFIXED        G_MAXINT16

Higher boundary for ClutterFixed

Since 0.8

CLUTTER_MINFIXED

#define CLUTTER_MINFIXED        G_MININT16

Lower boundary for ClutterFixed

Since 0.8

ClutterParamSpecFixed

typedef struct {
  ClutterFixed  minimum;
  ClutterFixed  maximum;
  ClutterFixed  default_value;
} ClutterParamSpecFixed;

GParamSpec subclass for fixed point based properties

ClutterFixed minimum;

 lower boundary

ClutterFixed maximum;

 higher boundary

ClutterFixed default_value;

 default value

Since 0.8

clutter_param_spec_fixed ()

GParamSpec*         clutter_param_spec_fixed            (const gchar *name,
                                                         const gchar *nick,
                                                         const gchar *blurb,
                                                         ClutterFixed minimum,
                                                         ClutterFixed maximum,
                                                         ClutterFixed default_value,
                                                         GParamFlags flags);

Creates a GParamSpec for properties using ClutterFixed values

name :

 name of the property

nick :

 short name

blurb :

 description (can be translatable)

minimum :

 lower boundary

maximum :

 higher boundary

default_value :

 default value

flags :

 flags for the param spec

Returns :

 the newly created GParamSpec

Since 0.8

CLUTTER_VALUE_HOLDS_FIXED()

#define CLUTTER_VALUE_HOLDS_FIXED(x)    (G_VALUE_HOLDS ((x), CLUTTER_TYPE_FIXED))

Evaluates to TRUE if x holds a ClutterFixed.

x :

 a GValue

Since 0.8

clutter_value_set_fixed ()

void                clutter_value_set_fixed             (GValue *value,
                                                         ClutterFixed fixed_);

Sets value to fixed_.

value :

 a GValue initialized to CLUTTER_TYPE_FIXED

fixed_ :

 the fixed point value to set

Since 0.8

clutter_value_get_fixed ()

ClutterFixed        clutter_value_get_fixed             (const GValue *value);

Gets the fixed point value stored inside value.

value :

 a GValue initialized to CLUTTER_TYPE_FIXED

Returns :

 the value inside the passed GValue

Since 0.8

Generated by GTK-Doc V1.10