GNOME.org

Fixed Point API

Fixed Point API — Fixed Point API

Functions

#define COGL_FIXED_BITS
#define COGL_FIXED_Q
#define COGL_FIXED_MAX
#define COGL_FIXED_MIN
#define COGL_FIXED_FROM_FLOAT()
#define COGL_FIXED_TO_FLOAT()
#define COGL_FIXED_FROM_INT()
#define COGL_FIXED_TO_INT()
#define COGL_FIXED_FROM_DOUBLE()
#define COGL_FIXED_TO_DOUBLE()
#define COGL_FLOAT_TO_INT()
#define COGL_FLOAT_TO_UINT()
#define COGL_FIXED_EPSILON
#define COGL_FIXED_1
#define COGL_FIXED_0_5
#define COGL_FIXED_30
#define COGL_FIXED_45
#define COGL_FIXED_60
#define COGL_FIXED_90
#define COGL_FIXED_120
#define COGL_FIXED_180
#define COGL_FIXED_240
#define COGL_FIXED_255
#define COGL_FIXED_270
#define COGL_FIXED_360
#define COGL_FIXED_MUL()
#define COGL_FIXED_DIV()
#define COGL_FIXED_MUL_DIV()
#define COGL_FIXED_FAST_DIV()
#define COGL_FIXED_FAST_MUL()
#define COGL_FIXED_FRACTION()
#define COGL_FIXED_FLOOR()
#define COGL_FIXED_CEIL()
#define COGL_FIXED_2_PI
#define COGL_FIXED_PI
#define COGL_FIXED_PI_2
#define COGL_FIXED_PI_4
#define COGL_RADIANS_TO_DEGREES
int cogl_sqrti ()
CoglFixed cogl_fixed_atan2 ()
CoglFixed cogl_fixed_atan ()
CoglFixed cogl_fixed_cos ()
CoglFixed cogl_fixed_log2 ()
unsigned int cogl_fixed_pow ()
unsigned int cogl_fixed_pow2 ()
CoglFixed cogl_fixed_sin ()
CoglFixed cogl_fixed_sqrt ()
CoglFixed cogl_fixed_tan ()
CoglFixed cogl_fixed_div ()
CoglFixed cogl_fixed_mul ()
CoglFixed cogl_fixed_mul_div ()
#define COGL_ANGLE_FROM_DEG()
#define COGL_ANGLE_FROM_DEGX()
#define COGL_ANGLE_TO_DEG()
#define COGL_ANGLE_TO_DEGX()
CoglFixed cogl_angle_cos ()
CoglFixed cogl_angle_sin ()
CoglFixed cogl_angle_tan ()

Types and Values

typedef CoglFixed
#define COGL_SQRTI_ARG_10_PERCENT
#define COGL_SQRTI_ARG_5_PERCENT
#define COGL_SQRTI_ARG_MAX
typedef CoglAngle

Description

COGL 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 notations conversion.

It is not recommened for use on platforms with a floating point unit (e.g. desktop systems), nor for use in language 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 COGL_FIXED_MUL and COGL_FIXED_DIV macros.

The fixed point API is available since COGL 1.0.

Functions

COGL_FIXED_BITS

#define COGL_FIXED_BITS         (32)

Evaluates to the number of bits used by the CoglFixed type.

Since: 1.0

COGL_FIXED_Q

#define COGL_FIXED_Q            (COGL_FIXED_BITS - 16)

Evaluates to the number of bits used for the non-integer part of the CoglFixed type.

Since: 1.0

COGL_FIXED_MAX

#define COGL_FIXED_MAX          (0x7fffffff)

The biggest number representable using CoglFixed

Since: 1.0

COGL_FIXED_MIN

#define COGL_FIXED_MIN          (0x80000000)

The smallest number representable using CoglFixed

Since: 1.0

COGL_FIXED_FROM_FLOAT()

#define COGL_FIXED_FROM_FLOAT(x)        ((float) cogl_double_to_fixed (x))

Converts x from a floating point to a fixed point notation.

Parameters

x

a floating point number

  

Since: 1.0

COGL_FIXED_TO_FLOAT()

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

Converts x from a fixed point to a floating point notation, in single precision.

Parameters

x

a CoglFixed number

  

Since: 1.0

COGL_FIXED_FROM_INT()

#define COGL_FIXED_FROM_INT(x)          ((x) << COGL_FIXED_Q)

Converts x from an integer to a fixed point notation.

Parameters

x

an integer number

  

Since: 1.0

COGL_FIXED_TO_INT()

#define COGL_FIXED_TO_INT(x)            ((x) >> COGL_FIXED_Q)

Converts x from a fixed point notation to an integer, dropping the fractional part without rounding.

Parameters

x

a CoglFixed number

  

Since: 1.0

COGL_FIXED_FROM_DOUBLE()

#define COGL_FIXED_FROM_DOUBLE(x)       (cogl_double_to_fixed (x))

Converts x from a double precision, floating point to a fixed point notation.

Parameters

x

a floating point number

  

Since: 1.0

COGL_FIXED_TO_DOUBLE()

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

Converts x from a fixed point to a floating point notation, in double precision.

Parameters

x

a CoglFixed number

  

Since: 1.0

COGL_FLOAT_TO_INT()

#define COGL_FLOAT_TO_INT(x)            (cogl_double_to_int ((x)))

Converts x from a floating point notation to a signed integer.

Parameters

x

a floatint point number

  

Since: 1.0

COGL_FLOAT_TO_UINT()

#define COGL_FLOAT_TO_UINT(x)           (cogl_double_to_uint ((x)))

Converts x from a floating point notation to an unsigned integer.

Parameters

x

a floatint point number

  

Since: 1.0

COGL_FIXED_EPSILON

#define COGL_FIXED_EPSILON      (1)

A very small number expressed as a CoglFixed number.

Since: 1.0

COGL_FIXED_1

#define COGL_FIXED_1            (1 << COGL_FIXED_Q)

The number 1 expressed as a CoglFixed number.

Since: 1.0

COGL_FIXED_0_5

#define COGL_FIXED_0_5          (32768)

The number 0.5 expressed as a CoglFixed number.

Since: 1.0

COGL_FIXED_30

#define COGL_FIXED_30           (COGL_FIXED_FROM_INT (30))

Evaluates to the number 30 in fixed point notation.

Since: 1.0

COGL_FIXED_45

#define COGL_FIXED_45           (COGL_FIXED_FROM_INT (45))

Evaluates to the number 45 in fixed point notation.

Since: 1.0

COGL_FIXED_60

#define COGL_FIXED_60           (COGL_FIXED_FROM_INT (60))

Evaluates to the number 60 in fixed point notation.

Since: 1.0

COGL_FIXED_90

#define COGL_FIXED_90           (COGL_FIXED_FROM_INT (90))

Evaluates to the number 90 in fixed point notation.

Since: 1.0

COGL_FIXED_120

#define COGL_FIXED_120          (COGL_FIXED_FROM_INT (120))

Evaluates to the number 120 in fixed point notation.

Since: 1.0

COGL_FIXED_180

#define COGL_FIXED_180          (COGL_FIXED_FROM_INT (180))

Evaluates to the number 180 in fixed point notation.

Since: 1.0

COGL_FIXED_240

#define COGL_FIXED_240          (COGL_FIXED_FROM_INT (240))

Evaluates to the number 240 in fixed point notation.

Since: 1.0

COGL_FIXED_255

#define COGL_FIXED_255          (COGL_FIXED_FROM_INT (255))

Evaluates to the number 255 in fixed point notation.

Since: 1.0

COGL_FIXED_270

#define COGL_FIXED_270          (COGL_FIXED_FROM_INT (270))

Evaluates to the number 270 in fixed point notation.

Since: 1.0

COGL_FIXED_360

#define COGL_FIXED_360          (COGL_FIXED_FROM_INT (360))

Evaluates to the number 360 in fixed point notation.

Since: 1.0

COGL_FIXED_MUL()

#define COGL_FIXED_MUL(a,b)             (cogl_fixed_mul ((a), (b)))

Computes (a * b).

Parameters

a

a CoglFixed number

  

b

a CoglFixed number

  

Since: 1.0

COGL_FIXED_DIV()

#define COGL_FIXED_DIV(a,b)             (cogl_fixed_div ((a), (b)))

Computes (a / b).

Parameters

a

a CoglFixed number

  

b

a CoglFixed number

  

Since: 1.0

COGL_FIXED_MUL_DIV()

#define COGL_FIXED_MUL_DIV(a,b,c)       (cogl_fixed_mul_div ((a), (b), (c)))

Computes ((a * b) / c). It is logically equivalent to:

1
 
res = COGL_FIXED_DIV (COGL_FIXED_MUL (a, b), c);

But it is shorter to type.

Parameters

a

a CoglFixed number

  

b

a CoglFixed number

  

c

a CoglFixed number

  

Since: 1.0

COGL_FIXED_FAST_DIV()

#define COGL_FIXED_FAST_DIV(a,b)        ((((a) << 8) / (b)) << 8)

Fast version of COGL_FIXED_DIV, implemented as a macro.

This macro might lose precision. If the precision of the result is important use COGL_FIXED_DIV instead.

Parameters

a

a CoglFixed number

  

b

a CoglFixed number

  

Since: 1.0

COGL_FIXED_FAST_MUL()

#define COGL_FIXED_FAST_MUL(a,b)        ((a) >> 8) * ((b) >> 8)

Fast version of COGL_FIXED_MUL, implemented as a macro.

This macro might lose precision. If the precision of the result is important use COGL_FIXED_MUL instead.

Parameters

a

a CoglFixed number

  

b

a CoglFixed number

  

Since: 1.0

COGL_FIXED_FRACTION()

#define COGL_FIXED_FRACTION(x)          ((x) & ((1 << COGL_FIXED_Q) - 1))

Retrieves the fractionary part of x .

Parameters

x

a CoglFixed number

  

Since: 1.0

COGL_FIXED_FLOOR()

#define             COGL_FIXED_FLOOR(x)

Rounds down a fixed point number to the previous integer.

Parameters

x

a CoglFixed number

  

Since: 1.0

COGL_FIXED_CEIL()

#define COGL_FIXED_CEIL(x)              (COGL_FIXED_FLOOR ((x) + 0xffff))

Rounds up a fixed point number to the next integer.

Parameters

x

a CoglFixed number

  

Since: 1.0

COGL_FIXED_2_PI

#define COGL_FIXED_2_PI         (0x0006487f)

Two times pi, expressed as a CoglFixed number.

Since: 1.0

COGL_FIXED_PI

#define COGL_FIXED_PI           (0x0003243f)

The number pi, expressed as a CoglFixed number.

Since: 1.0

COGL_FIXED_PI_2

#define COGL_FIXED_PI_2         (0x00019220)

Half pi, expressed as a CoglFixed number.

Since: 1.0

COGL_FIXED_PI_4

#define COGL_FIXED_PI_4         (0x0000c910)

pi / 4, expressed as CoglFixed number.

Since: 1.0

COGL_RADIANS_TO_DEGREES

#define COGL_RADIANS_TO_DEGREES (0x394bb8)

Evaluates to 180 / pi in fixed point notation.

Since: 1.0

cogl_sqrti ()

int
cogl_sqrti (int 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 less than 5% for arguments smaller than COGL_SQRTI_ARG_5_PERCENT and less than 10% for narguments smaller than COGL_SQRTI_ARG_10_PERCENT. The maximum argument that can be passed to this function is COGL_SQRTI_ARG_MAX.

Parameters

x

integer value

  

Returns

integer square root.

Since: 1.0

cogl_fixed_atan2 ()

CoglFixed
cogl_fixed_atan2 (CoglFixed a,
                  CoglFixed b);

Computes the arc tangent of a / b but uses the sign of both arguments to return the angle in right quadrant.

Parameters

a

the numerator as a CoglFixed number

  

b

the denominator as a CoglFixed number

  

Returns

the arc tangent of the passed fraction, in fixed point notation

Since: 1.0

cogl_fixed_atan ()

CoglFixed
cogl_fixed_atan (CoglFixed a);

Computes the arc tangent of a .

Parameters

a

a CoglFixed number

  

Returns

the arc tangent of the passed value, in fixed point notation

Since: 1.0

cogl_fixed_cos ()

CoglFixed
cogl_fixed_cos (CoglFixed angle);

Computes the cosine of angle .

Parameters

angle

a CoglFixed number

  

Returns

the cosine of the passed angle, in fixed point notation

Since: 1.0

cogl_fixed_log2 ()

CoglFixed
cogl_fixed_log2 (unsigned int 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().

Parameters

x

value to calculate base 2 logarithm from

  

Returns

base 2 logarithm.

Since: 1.0

cogl_fixed_pow ()

unsigned int
cogl_fixed_pow (unsigned int x,
                CoglFixed y);

Calculates x to the y power.

Parameters

x

base

  

y

CoglFixed exponent

  

Returns

the power of x to the y

Since: 1.0

cogl_fixed_pow2 ()

unsigned int
cogl_fixed_pow2 (CoglFixed x);

Calculates 2 to the 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).

Parameters

x

a CoglFixed number

  

Returns

the power of 2 to the passed value

Since: 1.0

cogl_fixed_sin ()

CoglFixed
cogl_fixed_sin (CoglFixed angle);

Computes the sine of angle .

Parameters

angle

a CoglFixed number

  

Returns

the sine of the passed angle, in fixed point notation

Since: 1.0

cogl_fixed_sqrt ()

CoglFixed
cogl_fixed_sqrt (CoglFixed x);

Computes the square root of x .

Parameters

x

a CoglFixed number

  

Returns

the square root of the passed value, in floating point notation

Since: 1.0

cogl_fixed_tan ()

CoglFixed
cogl_fixed_tan (CoglFixed angle);

Computes the tangent of angle .

Parameters

angle

a CoglFixed number

  

Returns

the tangent of the passed angle, in fixed point notation

Since: 1.0

cogl_fixed_div ()

CoglFixed
cogl_fixed_div (CoglFixed a,
                CoglFixed b);

cogl_fixed_mul ()

CoglFixed
cogl_fixed_mul (CoglFixed a,
                CoglFixed b);

cogl_fixed_mul_div ()

CoglFixed
cogl_fixed_mul_div (CoglFixed a,
                    CoglFixed b,
                    CoglFixed c);

COGL_ANGLE_FROM_DEG()

#define COGL_ANGLE_FROM_DEG(x)  (COGL_FLOAT_TO_INT (((float)(x) * 1024.0f) / 360.0f))

Converts an angle in degrees into a CoglAngle.

Parameters

x

an angle in degrees in floating point notation

  

Since: 1.0

COGL_ANGLE_FROM_DEGX()

#define COGL_ANGLE_FROM_DEGX(x) (COGL_FIXED_TO_INT ((((x) / 360) * 1024) + COGL_FIXED_0_5))

Converts an angle in degrees into a CoglAngle.

Parameters

x

an angle in degrees in fixed point notation

  

Since: 1.0

COGL_ANGLE_TO_DEG()

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

Converts a CoglAngle into an angle in degrees, using floatint point notation.

Parameters

x

a CoglAngle

  

Since: 1.0

COGL_ANGLE_TO_DEGX()

#define COGL_ANGLE_TO_DEGX(x)   (COGL_FIXED_FROM_INT ((x) * 45) / 128)

Converts a CoglAngle into an angle in degrees, using fixed point notation

Parameters

x

a CoglAngle

  

Since: 1.0

cogl_angle_cos ()

CoglFixed
cogl_angle_cos (CoglAngle angle);

Computes the cosine of angle

Parameters

angle

an angle expressed using CoglAngle

  

Returns

the cosine of the passed angle

Since: 1.0

cogl_angle_sin ()

CoglFixed
cogl_angle_sin (CoglAngle angle);

Computes the sine of angle

Parameters

angle

an angle expressed using CoglAngle

  

Returns

the sine of the passed angle

Since: 1.0

cogl_angle_tan ()

CoglFixed
cogl_angle_tan (CoglAngle angle);

Computes the tangent of angle

Parameters

angle

an angle expressed using CoglAngle

  

Returns

the tangent of the passed angle

Since: 1.0

Types and Values

CoglFixed

typedef int32_t CoglFixed;

Fixed point number using a (16.16) notation.

COGL_SQRTI_ARG_10_PERCENT

#define COGL_SQRTI_ARG_10_PERCENT 5590

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

Since: 1.0

COGL_SQRTI_ARG_5_PERCENT

#define COGL_SQRTI_ARG_5_PERCENT 210

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

Since: 1.0

COGL_SQRTI_ARG_MAX

#define COGL_SQRTI_ARG_MAX 0x3fffff

Maximum argument that can be passed to cogl_sqrti() function.

Since: 1.0

CoglAngle

typedef int32_t CoglAngle;

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

Since: 1.0

Generated by GTK-Doc V1.24.1