## Unit conversion

Unit conversion — A logical distance unit.

## Synopsis

    typedef             ClutterUnit;
    #define             CLUTTER_UNITS_FROM_DEVICE           (x)
    #define             CLUTTER_UNITS_TO_DEVICE             (x)
    #define             CLUTTER_UNITS_FROM_FIXED            (x)
    #define             CLUTTER_UNITS_TO_FIXED              (x)
    #define             CLUTTER_UNITS_FROM_FLOAT            (x)
    #define             CLUTTER_UNITS_TO_FLOAT              (x)
    #define             CLUTTER_UNITS_FROM_INT              (x)
    #define             CLUTTER_UNITS_TO_INT                (x)
    #define             CLUTTER_UNITS_FROM_PANGO_UNIT       (x)
    #define             CLUTTER_UNITS_TO_PANGO_UNIT         (x)
    #define             CLUTTER_UNITS_TMP_FROM_DEVICE       (x)
    #define             CLUTTER_UNITS_TMP_TO_DEVICE         (x)
    #define             CLUTTER_UNITS_FROM_STAGE_WIDTH_PERCENTAGE(x)
    #define             CLUTTER_UNITS_FROM_STAGE_HEIGHT_PERCENTAGE(x)
    #define             CLUTTER_UNITS_FROM_PARENT_WIDTH_PERCENTAGE(a, x)
    #define             CLUTTER_UNITS_FROM_PARENT_HEIGHT_PERCENTAGE(a, x)
    #define             CLUTTER_UNITS_FROM_MM               (x)
    #define             CLUTTER_UNITS_FROM_MMX              (x)
    #define             CLUTTER_UNITS_FROM_POINTS           (x)
    #define             CLUTTER_UNITS_FROM_POINTSX          (x)

    #define             CLUTTER_MAXUNIT
    #define             CLUTTER_MINUNIT
                        ClutterParamSpecUnit;
    GParamSpec *        clutter_param_spec_unit             (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             ClutterUnit minimum,
                                                             ClutterUnit maximum,
                                                             ClutterUnit default_value,
                                                             GParamFlags flags);
    #define             CLUTTER_VALUE_HOLDS_UNIT            (x)
    void                clutter_value_set_unit              (GValue *value,
                                                             ClutterUnit units);
    ClutterUnit         clutter_value_get_unit              (const GValue *value);

## Description

Clutter units are logical units with granularity greater than that of the device units; they are used by ClutterActorBox and the units-based family of ClutterActor functions. To convert between Clutter units and device units, use `CLUTTER_UNITS_FROM_DEVICE` and `CLUTTER_UNITS_TO_DEVICE` macros.

ClutterUnits can be converted from other units like millimeters, typographic points (at the current resolution) and percentages. It is also possible to convert fixed point values to and from ClutterUnit values.

In order to register a ClutterUnit property, the ClutterParamSpecUnit GParamSpec sub-class should be used:

      GParamSpec *pspec;

      pspec = clutter_param_spec_unit ("width",
                                       "Width",
                                       "Width of the actor, in units",
                                       0, CLUTTER_MAXUNIT,
                                       0,
                                       G_PARAM_READWRITE);
      g_object_class_install_property (gobject_class, PROP_WIDTH, pspec);

A GValue holding units can be manipulated using `clutter_value_set_unit()` and `clutter_value_get_unit()`. GValues containing a ClutterUnit value can also be transformed to GValues containing integer values - with a loss of precision:

      static gboolean
      units_to_int (const GValue *src,
                    GValue       *dest)
      {
        g_return_val_if_fail (CLUTTER_VALUE_HOLDS_UNIT (src), FALSE);

        g_value_init (dest, G_TYPE_INT);
        return g_value_transform (src, &dest);
      }

The code above is equivalent to:

      static gboolean
      units_to_int (const GValue *src,
                    GValue       *dest)
      {
        g_return_val_if_fail (CLUTTER_VALUE_HOLDS_UNIT (src), FALSE);

        g_value_init (dest, G_TYPE_INT);
        g_value_set_int (dest,
                         CLUTTER_UNITS_TO_INT (clutter_value_get_unit (src)));

        return TRUE;
      }

ClutterUnit is available since Clutter 0.4

## Details

### ClutterUnit

    typedef gint32 ClutterUnit;

Device independent unit used by Clutter. The value held can be transformed into other units, likes pixels.

Since 0.4

### CLUTTER_UNITS_FROM_DEVICE()

    #define CLUTTER_UNITS_FROM_DEVICE(x)     CLUTTER_UNITS_FROM_INT ((x))

Converts `x` from pixels to ClutterUnits

`x` : | value in pixels

Since 0.6

### CLUTTER_UNITS_TO_DEVICE()

    #define CLUTTER_UNITS_TO_DEVICE(x)       CLUTTER_UNITS_TO_INT ((x))

Converts `x` from ClutterUnits to pixels

`x` : | value in ClutterUnits

Since 0.6

### CLUTTER_UNITS_FROM_FIXED()

    #define CLUTTER_UNITS_FROM_FIXED(x)      (x)

`x` : |

### CLUTTER_UNITS_TO_FIXED()

    #define CLUTTER_UNITS_TO_FIXED(x)        (x)

`x` : |

### CLUTTER_UNITS_FROM_FLOAT()

    #define CLUTTER_UNITS_FROM_FLOAT(x)      CLUTTER_FLOAT_TO_FIXED ((x))

`x` : |

### CLUTTER_UNITS_TO_FLOAT()

    #define CLUTTER_UNITS_TO_FLOAT(x)        CLUTTER_FIXED_TO_FLOAT ((x))

`x` : |

### CLUTTER_UNITS_FROM_INT()

    #define CLUTTER_UNITS_FROM_INT(x)        CLUTTER_INT_TO_FIXED ((x))

`x` : |

### CLUTTER_UNITS_TO_INT()

    #define CLUTTER_UNITS_TO_INT(x)          CLUTTER_FIXED_TO_INT ((x))

`x` : |

### CLUTTER_UNITS_FROM_PANGO_UNIT()

    #define CLUTTER_UNITS_FROM_PANGO_UNIT(x) ((x) << 6)

Converts a value in Pango units to ClutterUnits

`x` : | value in Pango units

Since 0.6

### CLUTTER_UNITS_TO_PANGO_UNIT()

    #define CLUTTER_UNITS_TO_PANGO_UNIT(x)   ((x) >> 6)

Converts a value in ClutterUnits to Pango units

`x` : | value in ClutterUnits

Since 0.6

### CLUTTER_UNITS_TMP_FROM_DEVICE()

    #define CLUTTER_UNITS_TMP_FROM_DEVICE(x) (x)

`x` : |

### CLUTTER_UNITS_TMP_TO_DEVICE()

    #define CLUTTER_UNITS_TMP_TO_DEVICE(x)   (x)

`x` : |

### CLUTTER_UNITS_FROM_STAGE_WIDTH_PERCENTAGE()

    #define             CLUTTER_UNITS_FROM_STAGE_WIDTH_PERCENTAGE(x)

`x` : |

### CLUTTER_UNITS_FROM_STAGE_HEIGHT_PERCENTAGE()

    #define             CLUTTER_UNITS_FROM_STAGE_HEIGHT_PERCENTAGE(x)

`x` : |

### CLUTTER_UNITS_FROM_PARENT_WIDTH_PERCENTAGE()

    #define             CLUTTER_UNITS_FROM_PARENT_WIDTH_PERCENTAGE(a, x)

`a` : |
`x` : |

### CLUTTER_UNITS_FROM_PARENT_HEIGHT_PERCENTAGE()

    #define             CLUTTER_UNITS_FROM_PARENT_HEIGHT_PERCENTAGE(a, x)

`a` : |
`x` : |

### CLUTTER_UNITS_FROM_MM()

    #define             CLUTTER_UNITS_FROM_MM(x)

Converts a value in millimeters into ClutterUnits

`x` : | a value in millimeters

Since 0.6

### CLUTTER_UNITS_FROM_MMX()

    #define             CLUTTER_UNITS_FROM_MMX(x)

`x` : |

### CLUTTER_UNITS_FROM_POINTS()

    #define             CLUTTER_UNITS_FROM_POINTS(x)

Converts a value in typographic points into ClutterUnits

`x` : | a value in typographic points

Since 0.6

### CLUTTER_UNITS_FROM_POINTSX()

    #define             CLUTTER_UNITS_FROM_POINTSX(x)

`x` : |

### CLUTTER_MAXUNIT

    #define CLUTTER_MAXUNIT         (0x7fffffff)

Higher boundary for a ClutterUnit

Since 0.8

### CLUTTER_MINUNIT

    #define CLUTTER_MINUNIT         (0x80000000)

Lower boundary for a ClutterUnit

Since 0.8

### ClutterParamSpecUnit

    typedef struct {
      ClutterUnit   minimum;
      ClutterUnit   maximum;
      ClutterUnit   default_value;
    } ClutterParamSpecUnit;

GParamSpec subclass for unit based properties.

ClutterUnit `minimum`; | lower boundary
ClutterUnit `maximum`; | higher boundary
ClutterUnit `default_value`; | default value

Since 0.8

### clutter_param_spec_unit ()

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

Creates a GParamSpec for properties using ClutterUnits.

`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_UNIT()

    #define CLUTTER_VALUE_HOLDS_UNIT(x)       (G_VALUE_HOLDS ((x), CLUTTER_TYPE_UNIT))

Evaluates to `TRUE` if `x` holds ClutterUnits.

`x` : | a GValue

Since 0.8

### clutter_value_set_unit ()

    void                clutter_value_set_unit              (GValue *value,
                                                             ClutterUnit units);

Sets `value` to `units`

`value` : | a GValue initialized to CLUTTER_TYPE_UNIT
`units` : | the units to set

Since 0.8

### clutter_value_get_unit ()

    ClutterUnit         clutter_value_get_unit              (const GValue *value);

Gets the ClutterUnits contained in `value`.

`value` : | a GValue initialized to CLUTTER_TYPE_UNIT
Returns : | the units inside the passed GValue

Since 0.8