0
@@ -1,5 +1,10 @@
0
 2008-04-17  Emmanuele Bassi  <ebassi@openedhand.com>
0
 
0
+	* HACKING: Amend coding style and tenets, as it is now possible
0
+	to install and use unit based properties in a safe way.
0
+
0
+2008-04-17  Emmanuele Bassi  <ebassi@openedhand.com>
0
+
0
   * clutter/clutter-units.h:
0
   * clutter/clutter-fixed.h: Add boundaries for fixed point
0
   and units values.

0
@@ -3,7 +3,7 @@ GENERAL
0
 
0
 General notes and rules on clutter core hacking;
0
 
0
- - GNU style indentation, please wrap at 80 chars. 
0
+ - GNU style indentation, please try hard to wrap at 80 chars.
0
 
0
  - All non static public API funcs should be documented in the source files
0
    via gtk-doc. Structures, enumerations and macros should be documented in
0
@@ -14,31 +14,48 @@ General notes and rules on clutter core hacking;
0
    of mutexes.
0
 
0
  - All public functions with float parameters should also provide a fixed
0
-   point version. Fixed point should be used internally.
0
+   point version, with the 'x' postfix to the function name, e.g.:
0
+   
0
+     clutter_actor_set_foo      - floating point
0
+     clutter_actor_set_foox     - fixed point
0
+
0
+   Fixed point should be always be used internally, except when precision
0
+   is paramount.
0
 
0
  - All public functions dealing with pixels should also provide a
0
-   ClutterUnit version. ClutterUnit should be used internally.
0
+   ClutterUnit version, with the 'u' postfix to the function name, e.g:
0
+
0
+     clutter_actor_set_bar      - pixels
0
+     clutter_actor_set_baru     - units
0
+   
0
+   ClutterUnit should always be used internally.
0
 
0
  - Properties should always be in floating point (never fixed point).
0
-   The precision should be double for unbounded properties (e.g.
0
-   (-MAX_DOUBLE, MAX_DOUBLE)), and single for bounded properties (e.g.:
0
-   [0.0, 1.0]).
0
+   The preferred precision is double. 
0
+
0
+ - Properties should use pixels whenever is possible. If sub-pixel
0
+   precision is fundamental, use ClutterParamSpecUnit and
0
+   clutter_param_spec_unit() to install ClutterUnit properties, and
0
+   clutter_value_set_unit()/clutter_value_get_unit() to handle GValues in
0
+   a safe way. Never install a ClutterUnit property using a GParamSpecInt.
0
 
0
  - Public entry points must always check their arguments with
0
    g_return_if_fail() or g_return_val_if_fail().
0
 
0
- - Private entry points should use g_assert() to verify internal state.
0
+ - Private entry points should use g_assert() to verify internal state;
0
+   do not use g_return_if_fail()/g_return_val_if_fail() as they might
0
+   be compiled out.
0
 
0
  - Really try to avoid if possible additions to clutter-private.h. Use
0
    accessor functions instead.
0
 
0
- - Don't add direct GL calls but wrap with cogl (also adding GL ES Version)
0
+ - Don't add direct GL calls but wrap with cogl (also adding GLES
0
+   version if possible, or at least a stub).
0
 
0
  - Use CLUTTER_NOTE() macro for debug statements.
0
 
0
  - New features should also include an exhaustive test unit under tests.
0
 
0
-
0
 RELEASES
0
 ========
0