Canvas2D: Inline doc updated (#1201)

* Change text drawing starting location to the right place in case of multi-line

* Fix textSize null case

* Canvas2D: enhance text rendering quality

* Canvas2D: small api to access global position of prim

* Canvas2D
Inline documentation updated

src/Canvas2d/babylon.bounding2d.ts

@@ -28,18 +28,31 @@
             this.extent = Vector2.Zero();
         }
 
+        /**
+         * Create a BoundingInfo2D object from a given size
+         * @param size the size that will be used to set the extend, radius will be computed from it.
+         */
         public static CreateFromSize(size: Size): BoundingInfo2D {
             let r = new BoundingInfo2D();
             BoundingInfo2D.CreateFromSizeToRef(size, r);
             return r;
         }
 
+        /**
+         * Create a BoundingInfo2D object from a given radius
+         * @param radius the radius to use, the extent will be computed from it.
+         */
         public static CreateFromRadius(radius: number): BoundingInfo2D {
             let r = new BoundingInfo2D();
             BoundingInfo2D.CreateFromRadiusToRef(radius, r);
             return r;
         }
 
+        /**
+         * Create a BoundingInfo2D object from a list of points.
+         * The resulted object will be the smallest bounding area that includes all the given points.
+         * @param points an array of points to compute the bounding object from.
+         */
         public static CreateFromPoints(points: Vector2[]): BoundingInfo2D {
             let r = new BoundingInfo2D();
             BoundingInfo2D.CreateFromPointsToRef(points, r);
@@ -47,6 +60,11 @@
             return r;
         }
 
+        /**
+         * Update a BoundingInfo2D object using the given Size as input
+         * @param size the bounding data will be computed from this size.
+         * @param b must be a valid/allocated object, it will contain the result of the operation
+         */
         public static CreateFromSizeToRef(size: Size, b: BoundingInfo2D) {
             if (!size) {
                 size = Size.Zero();
@@ -58,6 +76,11 @@
             b.radius = b.extent.length();
         }
 
+        /**
+         * Update a BoundingInfo2D object using the given radius as input
+         * @param radius the bounding data will be computed from this radius
+         * @param b must be a valid/allocated object, it will contain the result of the operation
+         */
         public static CreateFromRadiusToRef(radius: number, b: BoundingInfo2D) {
             b.center.x = b.center.y = 0;
             let r = +radius;
@@ -66,6 +89,11 @@
             b.radius = r;
         }
 
+        /**
+         * Update a BoundingInfo2D object using the given points array as input
+         * @param points the point array to use to update the bounding data
+         * @param b must be a valid/allocated object, it will contain the result of the operation
+         */
         public static CreateFromPointsToRef(points: Vector2[], b: BoundingInfo2D) {
             let xmin = Number.MAX_VALUE, ymin = Number.MAX_VALUE, xmax = Number.MIN_VALUE, ymax = Number.MIN_VALUE;
             for (let p of points) {
@@ -77,6 +105,14 @@
             BoundingInfo2D.CreateFromMinMaxToRef(xmin, xmax, ymin, ymax, b);
         }
 
+        /**
+         * Update a BoundingInfo2D object using the given min/max values as input
+         * @param xmin the smallest x coordinate
+         * @param xmax the biggest x coordinate
+         * @param ymin the smallest y coordinate
+         * @param ymax the buggest y coordinate
+         * @param b must be a valid/allocated object, it will contain the result of the operation
+         */
         public static CreateFromMinMaxToRef(xmin: number, xmax: number, ymin: number, ymax: number, b: BoundingInfo2D) {
             let w = xmax - xmin;
             let h = ymax - ymin;
@@ -97,12 +133,19 @@
             return r;
         }
 
+        /**
+         * return the max extend of the bounding info
+         */
         public max(): Vector2 {
             let r = Vector2.Zero();
             this.maxToRef(r);
             return r;
         }
 
+        /**
+         * Update a vector2 with the max extend of the bounding info
+         * @param result must be a valid/allocated vector2 that will contain the result of the operation
+         */
         public maxToRef(result: Vector2) {
             result.x = this.center.x + this.extent.x;
             result.y = this.center.y + this.extent.y;
@@ -120,7 +163,7 @@
         }
 
         /**
-         * Compute the union of this BoundingInfo2D with a given one, return a new BoundingInfo2D as a result
+         * Compute the union of this BoundingInfo2D with a given one, returns a new BoundingInfo2D as a result
          * @param other the second BoundingInfo2D to compute the union with this one
          * @return a new instance containing the result of the union
          */
@@ -171,7 +214,13 @@
             BoundingInfo2D.CreateFromMinMaxToRef(xmin, xmax, ymin, ymax, result);
         }
 
-        doesIntersect(pickPosition: Vector2): boolean {
+        /**
+         * Check if the given point is inside the BoundingInfo.
+         * The test is first made on the radius, then inside the rectangle described by the extent
+         * @param pickPosition the position to test
+         * @return true if the point is inside, false otherwise
+         */
+        public doesIntersect(pickPosition: Vector2): boolean {
             // is it inside the radius?
             let pickLocal = pickPosition.subtract(this.center);
             if (pickLocal.lengthSquared() <= (this.radius * this.radius)) {

src/Canvas2d/babylon.brushes2d.ts

@@ -66,10 +66,10 @@
         }
     }
 
+    @className("SolidColorBrush2D")
     /**
      * This class implements a Brush that will be drawn with a uniform solid color (i.e. the same color everywhere in the content where the brush is assigned to).
      */
-    @className("SolidColorBrush2D")
     export class SolidColorBrush2D extends LockableBase implements IBrush2D {
         constructor(color: Color4, lock: boolean = false) {
             super();
@@ -81,6 +81,9 @@
             }
         }
 
+        /**
+         * Return true if the brush is transparent, false if it's totally opaque
+         */
         isTransparent(): boolean {
             return this._color && this._color.a < 1.0;
         }
@@ -111,6 +114,9 @@
     }
 
     @className("GradientColorBrush2D")
+    /**
+     * This class implements a Gradient Color Brush, the brush color will blend from a first given color to a second one.
+     */
     export class GradientColorBrush2D extends LockableBase implements IBrush2D {
         constructor(color1: Color4, color2: Color4, translation: Vector2 = Vector2.Zero(), rotation: number = 0, scale: number = 1, lock: boolean = false) {
             super();
@@ -126,11 +132,16 @@
             }
         }
 
+        /**
+         * Return true if the brush is transparent, false if it's totally opaque
+         */
         isTransparent(): boolean {
             return (this._color1 && this._color1.a < 1.0) || (this._color2 && this._color2.a < 1.0);
         }
 
-
+        /**
+         * First color, the blend will start from this color
+         */
         public get color1(): Color4 {
             return this._color1;
         }
@@ -143,6 +154,9 @@
             this._color1 = value;
         }
 
+        /**
+         * Second color, the blend will end to this color
+         */
         public get color2(): Color4 {
             return this._color2;
         }
@@ -155,6 +169,10 @@
             this._color2 = value;
         }
 
+        /**
+         * Translation vector to apply on the blend
+         * Default is [0;0]
+         */
         public get translation(): Vector2 {
             return this._translation;
         }
@@ -167,6 +185,11 @@
             this._translation = value;
         }
 
+        /**
+         * Rotation in radian to apply to the brush
+         * Default direction of the brush is vertical, you can change this using this property.
+         * Default is 0.
+         */
         public get rotation(): number {
             return this._rotation;
         }
@@ -179,6 +202,10 @@
             this._rotation = value;
         }
 
+        /**
+         * Scale factor to apply to the gradient.
+         * Default is 1: no scale.
+         */
         public get scale(): number {
             return this._scale;
         }
@@ -191,10 +218,16 @@
             this._scale = value;
         }
 
+        /**
+         * Return a string describing the brush
+         */
         public toString(): string {
             return `C1:${this._color1};C2:${this._color2};T:${this._translation.toString()};R:${this._rotation};S:${this._scale};`;
         }
 
+        /**
+         * Build a unique key string for the given parameters
+         */
         public static BuildKey(color1: Color4, color2: Color4, translation: Vector2, rotation: number, scale: number) {
             return `C1:${color1};C2:${color2};T:${translation.toString()};R:${rotation};S:${scale};`;
         }

src/Canvas2d/babylon.canvas2d.ts

@@ -1,5 +1,6 @@
 module BABYLON {
 
+    // This class contains data that lifetime is bounding to the Babylon Engine object
     export class Canvas2DEngineBoundData {
         public GetOrAddModelCache<TInstData>(key: string, factory: (key: string) => ModelRenderCache): ModelRenderCache {
             return this._modelCache.getOrAddWithFactory(key, factory);
@@ -19,7 +20,12 @@
     }
 
     @className("Canvas2D")
-    export class Canvas2D extends Group2D {
+    /**
+     * The Canvas2D main class.
+     * This class is extended in both ScreenSpaceCanvas2D and WorldSpaceCanvas2D which are designed only for semantic use.
+     * User creates a Screen or WorldSpace canvas which is a 2D surface area that will draw the primitives that were added as children.
+     */
+    export abstract class Canvas2D extends Group2D {
         /**
          * In this strategy only the direct children groups of the Canvas will be cached, their whole content (whatever the sub groups they have) into a single bitmap.
          * This strategy doesn't allow primitives added directly as children of the Canvas.
@@ -160,7 +166,7 @@
             this._isScreenSpace = (settings.isScreenSpace == null) ? true : settings.isScreenSpace;
         }
 
-        public static hierarchyLevelMaxSiblingCount: number = 10;
+        public static hierarchyLevelMaxSiblingCount: number = 50;
 
         private _setupInteraction(enable: boolean) {
             // No change detection
@@ -722,7 +728,6 @@
 
         /**
          * Check if the WebGL Instanced Array extension is supported or not
-         * @returns {} 
          */
         public get supportInstancedArray() {
             return this._supprtInstancedArray;
@@ -828,6 +833,10 @@
             this._setupInteraction(enable);
         }
 
+        /**
+         * Access the babylon.js' engine bound data, do not invoke this method, it's for internal purpose only
+         * @returns {} 
+         */
         public get _engineData(): Canvas2DEngineBoundData {
             return this.__engineData;
         }
@@ -838,7 +847,6 @@
             }
         }
 
-
         private __engineData: Canvas2DEngineBoundData;
         private _interactionEnabled: boolean;
         private _primPointerInfo: PrimitivePointerInfo;
@@ -1043,7 +1051,11 @@
          */
         private static _groupTextureCacheSize = 1024;
 
-
+        /**
+         * Internal method used to register a Scene Node to track position for the given group
+         * Do not invoke this method, for internal purpose only.
+         * @param group the group to track its associated Scene Node
+         */
         public _registerTrackedNode(group: Group2D) {
             if (group._isFlagSet(SmartPropertyPrim.flagTrackedGroup)) {
                 return;
@@ -1053,6 +1065,11 @@
             group._setFlags(SmartPropertyPrim.flagTrackedGroup);
         }
 
+        /**
+         * Internal method used to unregister a tracked Scene Node
+         * Do not invoke this method, it's for internal purpose only.
+         * @param group the group to unregister its tracked Scene Node from.
+         */
         public _unregisterTrackedNode(group: Group2D) {
             if (!group._isFlagSet(SmartPropertyPrim.flagTrackedGroup)) {
                 return;
@@ -1084,10 +1101,24 @@
             return Canvas2D._solidColorBrushes.getOrAddWithFactory(hexValue, () => new SolidColorBrush2D(Color4.FromHexString(hexValue), true));
         }
 
+        /**
+         * Get a Gradient Color Brush
+         * @param color1 starting color
+         * @param color2 engine color
+         * @param translation translation vector to apply. default is [0;0]
+         * @param rotation rotation in radian to apply to the brush, initial direction is top to bottom. rotation is counter clockwise. default is 0.
+         * @param scale scaling factor to apply. default is 1.
+         */
         public static GetGradientColorBrush(color1: Color4, color2: Color4, translation: Vector2 = Vector2.Zero(), rotation: number = 0, scale: number = 1): IBrush2D {
             return Canvas2D._gradientColorBrushes.getOrAddWithFactory(GradientColorBrush2D.BuildKey(color1, color2, translation, rotation, scale), () => new GradientColorBrush2D(color1, color2, translation, rotation, scale, true));
         }
 
+        /**
+         * Create a solid or gradient brush from a string value.
+         * @param brushString should be either
+         *  - "solid: #RRGGBBAA" or "#RRGGBBAA"
+         *  - "gradient: #FF808080, #FFFFFFF[, [10:20], 180, 1]" for color1, color2, translation, rotation (degree), scale. The last three are optionals, but if specified must be is this order. "gradient:" can be omitted.
+         */
         public static GetBrushFromString(brushString: string): IBrush2D {
             // Note: yes, I hate/don't know RegEx.. Feel free to add your contribution to the cause!
 
@@ -1150,50 +1181,61 @@
         private static _solidColorBrushes: StringDictionary<IBrush2D> = new StringDictionary<IBrush2D>();
         private static _gradientColorBrushes: StringDictionary<IBrush2D> = new StringDictionary<IBrush2D>();
     }
+
     @className("WorldSpaceCanvas2D")
+    /**
+     * Class to create a WorldSpace Canvas2D.
+     */
     export class WorldSpaceCanvas2D extends Canvas2D {
         /**
          * Create a new 2D WorldSpace Rendering Canvas, it is a 2D rectangle that has a size (width/height) and a world transformation information to place it in the world space.
          * This kind of canvas can't have its Primitives directly drawn in the Viewport, they need to be cached in a bitmap at some point, as a consequence the DONT_CACHE strategy is unavailable. For now only CACHESTRATEGY_CANVAS is supported, but the remaining strategies will be soon.
          * @param scene the Scene that owns the Canvas
          * @param size the dimension of the Canvas in World Space
-         * Options:
+         * @param settings a combination of settings, possible ones are
+         *  - children: an array of direct children primitives
          *  - id: a text identifier, for information purpose only, default is null.
-         *  - position the position of the Canvas in World Space, default is [0,0,0]
-         *  - rotation the rotation of the Canvas in World Space, default is Quaternion.Identity()
+         *  - worldPosition the position of the Canvas in World Space, default is [0,0,0]
+         *  - worldRotation the rotation of the Canvas in World Space, default is Quaternion.Identity()
          *  - renderScaleFactor A scale factor applied to create the rendering texture that will be mapped in the Scene Rectangle. If you set 2 for instance the texture will be twice large in width and height. A greater value will allow to achieve a better rendering quality. Default value is 1.
          * BE AWARE that the Canvas true dimension will be size*renderScaleFactor, then all coordinates and size will have to be express regarding this size.
          * TIPS: if you want a renderScaleFactor independent reference of frame, create a child Group2D in the Canvas with position 0,0 and size set to null, then set its scale property to the same amount than the renderScaleFactor, put all your primitive inside using coordinates regarding the size property you pick for the Canvas and you'll be fine.
          * - sideOrientation: Unexpected behavior occur if the value is different from Mesh.DEFAULTSIDE right now, so please use this one, which is the default.
          * - cachingStrategy Must be CACHESTRATEGY_CANVAS for now, which is the default.
-         *  - enableInteraction: if true the pointer events will be listened and rerouted to the appropriate primitives of the Canvas2D through the Prim2DBase.onPointerEventObservable observable property. Default is false (the opposite of ScreenSpace).
+         * - enableInteraction: if true the pointer events will be listened and rerouted to the appropriate primitives of the Canvas2D through the Prim2DBase.onPointerEventObservable observable property. Default is false (the opposite of ScreenSpace).
          * - isVisible: true if the canvas must be visible, false for hidden. Default is true.
+         * - backgroundRoundRadius: the round radius of the background, either backgroundFill or backgroundBorder must be specified.
+         * - backgroundFill: the brush to use to create a background fill for the canvas. can be a string value (see Canvas2D.GetBrushFromString) or a IBrush2D instance.
+         * - backgroundBorder: the brush to use to create a background border for the canvas. can be a string value (see Canvas2D.GetBrushFromString) or a IBrush2D instance.
+         * - backgroundBorderThickness: if a backgroundBorder is specified, its thickness can be set using this property
          * - customWorldSpaceNode: if specified the Canvas will be rendered in this given Node. But it's the responsibility of the caller to set the "worldSpaceToNodeLocal" property to compute the hit of the mouse ray into the node (in world coordinate system) as well as rendering the cached bitmap in the node itself. The properties cachedRect and cachedTexture of Group2D will give you what you need to do that.
+         * - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(scene: Scene, size: Size, settings?: {
 
-            children?: Array<Prim2DBase>,
-            id?: string,
-            worldPosition?: Vector3,
-            worldRotation?: Quaternion,
-            renderScaleFactor?: number,
-            sideOrientation?: number,
-            cachingStrategy?: number,
-            enableInteraction?: boolean,
-            isVisible?: boolean,
-            backgroundRoundRadius?: number,
-            backgroundFill?: IBrush2D | string,
-            backgroundBorder?: IBrush2D | string,
+            children                 ?: Array<Prim2DBase>,
+            id                       ?: string,
+            worldPosition            ?: Vector3,
+            worldRotation            ?: Quaternion,
+            renderScaleFactor        ?: number,
+            sideOrientation          ?: number,
+            cachingStrategy          ?: number,
+            enableInteraction        ?: boolean,
+            isVisible                ?: boolean,
+            backgroundRoundRadius    ?: number,
+            backgroundFill           ?: IBrush2D | string,
+            backgroundBorder         ?: IBrush2D | string,
             backgroundBorderThickNess?: number,
-            customWorldSpaceNode?: Node,
-            marginTop?: number | string,
-            marginLeft?: number | string,
-            marginRight?: number | string,
-            marginBottom?: number | string,
-            margin?: number | string,
-            marginHAlignment?: number,
-            marginVAlignment?: number,
-            marginAlignment?: string,
+            customWorldSpaceNode     ?: Node,
+            paddingTop               ?: number | string,
+            paddingLeft              ?: number | string,
+            paddingRight             ?: number | string,
+            paddingBottom            ?: number | string,
+            padding                  ?: string,
 
         }) {
             Prim2DBase._isCanvasInit = true;
@@ -1244,6 +1286,9 @@
     }
 
     @className("ScreenSpaceCanvas2D")
+    /**
+     * Class to create a ScreenSpace Canvas2D
+     */
     export class ScreenSpaceCanvas2D extends Canvas2D {
         /**
          * Create a new 2D ScreenSpace Rendering Canvas, it is a 2D rectangle that has a size (width/height) and a position relative to the bottom/left corner of the screen.
@@ -1251,62 +1296,56 @@
          * All caching strategies will be available.
          * PLEASE NOTE: the origin of a Screen Space Canvas is set to [0;0] (bottom/left) which is different than the default origin of a Primitive which is centered [0.5;0.5]
          * @param scene the Scene that owns the Canvas
-         * Options:
+         * @param settings a combination of settings, possible ones are
+         *  - children: an array of direct children primitives
          *  - id: a text identifier, for information purpose only
-         *  - pos: the position of the canvas, relative from the bottom/left of the scene's viewport. Alternatively you can set the x and y properties directly. Default value is [0, 0]
+         *  - x: the position along the x axis (horizontal), relative to the left edge of the viewport. you can alternatively use the position setting.
+         *  - y: the position along the y axis (vertically), relative to the bottom edge of the viewport. you can alternatively use the position setting.
+         *  - position: the position of the canvas, relative from the bottom/left of the scene's viewport. Alternatively you can set the x and y properties directly. Default value is [0, 0]
+         *  - width: the width of the Canvas. you can alternatively use the size setting.
+         *  - height: the height of the Canvas. you can alternatively use the size setting.
          *  - size: the Size of the canvas. Alternatively the width and height properties can be set. If null two behaviors depend on the cachingStrategy: if it's CACHESTRATEGY_CACHECANVAS then it will always auto-fit the rendering device, in all the other modes it will fit the content of the Canvas
          *  - cachingStrategy: either CACHESTRATEGY_TOPLEVELGROUPS, CACHESTRATEGY_ALLGROUPS, CACHESTRATEGY_CANVAS, CACHESTRATEGY_DONTCACHE. Please refer to their respective documentation for more information. Default is Canvas2D.CACHESTRATEGY_DONTCACHE
          *  - enableInteraction: if true the pointer events will be listened and rerouted to the appropriate primitives of the Canvas2D through the Prim2DBase.onPointerEventObservable observable property. Default is true.
          *  - isVisible: true if the canvas must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         * - backgroundRoundRadius: the round radius of the background, either backgroundFill or backgroundBorder must be specified.
+         * - backgroundFill: the brush to use to create a background fill for the canvas. can be a string value (see BABYLON.Canvas2D.GetBrushFromString) or a IBrush2D instance.
+         * - backgroundBorder: the brush to use to create a background border for the canvas. can be a string value (see BABYLON.Canvas2D.GetBrushFromString) or a IBrush2D instance.
+         * - backgroundBorderThickness: if a backgroundBorder is specified, its thickness can be set using this property
+         * - customWorldSpaceNode: if specified the Canvas will be rendered in this given Node. But it's the responsibility of the caller to set the "worldSpaceToNodeLocal" property to compute the hit of the mouse ray into the node (in world coordinate system) as well as rendering the cached bitmap in the node itself. The properties cachedRect and cachedTexture of Group2D will give you what you need to do that.
+         * - paddingTop: top padding, can be a number (will be pixels) or a string (see BABYLON.PrimitiveThickness.fromString)
+         * - paddingLeft: left padding, can be a number (will be pixels) or a string (see BABYLON.PrimitiveThickness.fromString)
+         * - paddingRight: right padding, can be a number (will be pixels) or a string (see BABYLON.PrimitiveThickness.fromString)
+         * - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see BABYLON.PrimitiveThickness.fromString)
+         * - padding: top, left, right and bottom padding formatted as a single string (see BABYLON.PrimitiveThickness.fromString)
          */
         constructor(scene: Scene, settings?: {
 
-            children?: Array<Prim2DBase>,
-            id?: string,
-            x?: number,
-            y?: number,
-            position?: Vector2,
-            origin?: Vector2,
-            width?: number,
-            height?: number,
-            size?: Size,
-            cachingStrategy?: number,
-            enableInteraction?: boolean,
-            isVisible?: boolean,
-            backgroundRoundRadius?: number,
-            backgroundFill?: IBrush2D | string,
-            backgroundBorder?: IBrush2D | string,
+            children                 ?: Array<Prim2DBase>,
+            id                       ?: string,
+            x                        ?: number,
+            y                        ?: number,
+            position                 ?: Vector2,
+            origin                   ?: Vector2,
+            width                    ?: number,
+            height                   ?: number,
+            size                     ?: Size,
+            cachingStrategy          ?: number,
+            enableInteraction        ?: boolean,
+            isVisible                ?: boolean,
+            backgroundRoundRadius    ?: number,
+            backgroundFill           ?: IBrush2D | string,
+            backgroundBorder         ?: IBrush2D | string,
             backgroundBorderThickNess?: number,
-            marginTop?: number | string,
-            marginLeft?: number | string,
-            marginRight?: number | string,
-            marginBottom?: number | string,
-            margin?: string,
-            marginHAlignment?: number,
-            marginVAlignment?: number,
-            marginAlignment?: string,
+            paddingTop               ?: number | string,
+            paddingLeft              ?: number | string,
+            paddingRight             ?: number | string,
+            paddingBottom            ?: number | string,
+            padding                  ?: string,
 
         }) {
             Prim2DBase._isCanvasInit = true;
             super(scene, settings);
-
-            //let c = new Canvas2D();
-
-            //if (!settings) {
-            //    c.setupCanvas(scene, null, null, 1, true, Canvas2D.CACHESTRATEGY_DONTCACHE, true, Vector2.Zero(), true, null, null, null, null, null, null);
-            //    c.position = Vector2.Zero();
-            //} else {
-            //    let pos = settings.position || new Vector2(settings.x || 0, settings.y || 0);
-            //    let size = (!settings.size && !settings.width && !settings.height) ? null : (settings.size || (new Size(settings.width || 0, settings.height || 0)));
-
-            //    c.setupCanvas(scene, settings.id || null, size, 1, true, settings.cachingStrategy || Canvas2D.CACHESTRATEGY_DONTCACHE, settings.enableInteraction || true, settings.origin || Vector2.Zero(), settings.isVisible || true, settings.marginTop, settings.marginLeft, settings.marginRight, settings.marginBottom, settings.hAlignment || PrimitiveAlignment.AlignLeft, settings.vAlignment || PrimitiveAlignment.AlignTop);
-            //    c.position = pos;
-            //}
-
-            //return c;
         }
     }
 

src/Canvas2d/babylon.canvas2dLayoutEngine.ts

@@ -3,7 +3,7 @@
     @className("LayoutEngineBase")
     /**
      * This is the base class you have to extend in order to implement your own Layout Engine.
-     * Note that for performance reason, each different Layout Engine type must be instanced only once, good practice is through a static `Singleton`property defined in the type itself.
+     * Note that for performance reason, each different Layout Engine type can be exposed as one/many singleton or must be instanced each time.
      * If data has to be associated to a given primitive you can use the SmartPropertyPrim.addExternalData API to do it.
      */
     export class LayoutEngineBase implements ILockable {
@@ -36,6 +36,10 @@
     }
 
     @className("CanvasLayoutEngine")
+    /**
+     * The default Layout Engine, primitive are positioning into a Canvas, using their x/y coordinates.
+     * This layout must be used as a Singleton through the CanvasLayoutEngine.Singleton property.
+     */
     export class CanvasLayoutEngine extends LayoutEngineBase {
         public static Singleton: CanvasLayoutEngine = new CanvasLayoutEngine();
 
@@ -79,6 +83,10 @@
 
 
     @className("StackPanelLayoutEngine")
+    /**
+     * A stack panel layout. Primitive will be stack either horizontally or vertically.
+     * This Layout type must be used as a Singleton, use the StackPanelLayoutEngine.Horizontal for an horizontal stack panel or StackPanelLayoutEngine.Vertical for a vertical one.
+     */
     export class StackPanelLayoutEngine extends LayoutEngineBase {
         constructor() {
             super();

src/Canvas2d/babylon.ellipse2d.ts

@@ -164,12 +164,18 @@
     }
 
     @className("Ellipse2D")
+    /**
+     * Ellipse Primitive class
+     */
     export class Ellipse2D extends Shape2D {
 
         public static acutalSizeProperty: Prim2DPropInfo;
         public static subdivisionsProperty: Prim2DPropInfo;
 
         @instanceLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 1, pi => Ellipse2D.acutalSizeProperty = pi, false, true)
+        /**
+         * Get/Set the size of the ellipse
+         */
         public get actualSize(): Size {
             if (this._actualSize) {
                 return this._actualSize;
@@ -182,6 +188,9 @@
         }
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 2, pi => Ellipse2D.subdivisionsProperty = pi)
+        /**
+         * Get/set the number of subdivisions used to draw the ellipsis. Default is 64.
+         */
         public get subdivisions(): number {
             return this._subdivisions;
         }
@@ -204,20 +213,31 @@
 
         /**
          * Create an Ellipse 2D Shape primitive
-         * @param parent the parent primitive, must be a valid primitive (or the Canvas)
-         * options:
+         * @param settings a combination of settings, possible ones are
+         *  - parent: the parent primitive/canvas, must be specified if the primitive is not constructed as a child of another one (i.e. as part of the children array setting)
+         *  - children: an array of direct children 
          *  - id: a text identifier, for information purpose
          *  - position: the X & Y positions relative to its parent. Alternatively the x and y properties can be set. Default is [0;0]
+         *  - rotation: the initial rotation (in radian) of the primitive. default is 0
+         *  - scale: the initial scale of the primitive. default is 1
          *  - origin: define the normalized origin point location, default [0.5;0.5]
          *  - size: the size of the group. Alternatively the width and height properties can be set. Default will be [10;10].
          *  - subdivision: the number of subdivision to create the ellipse perimeter, default is 64.
-         *  - fill: the brush used to draw the fill content of the ellipse, you can set null to draw nothing (but you will have to set a border brush), default is a SolidColorBrush of plain white.
-         *  - border: the brush used to draw the border of the ellipse, you can set null to draw nothing (but you will have to set a fill brush), default is null.
-         *  - borderThickness: the thickness of the drawn border, default is 1.
-         *  - isVisible: true if the primitive must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         *  - fill: the brush used to draw the fill content of the ellipse, you can set null to draw nothing (but you will have to set a border brush), default is a SolidColorBrush of plain white. can also be a string value (see Canvas2D.GetBrushFromString)
+         *  - border: the brush used to draw the border of the ellipse, you can set null to draw nothing (but you will have to set a fill brush), default is null. can be a string value (see Canvas2D.GetBrushFromString)
+         * - marginTop: top margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - marginLeft: left margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - marginRight: right margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - marginBottom: bottom margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - margin: top, left, right and bottom margin formatted as a single string (see PrimitiveThickness.fromString)
+         * - marginHAlignment: one value of the PrimitiveAlignment type's static properties
+         * - marginVAlignment: one value of the PrimitiveAlignment type's static properties
+         * - marginAlignment: a string defining the alignment, see PrimitiveAlignment.fromString
+         * - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(settings?: {
 
@@ -227,6 +247,8 @@
             position          ?: Vector2,
             x                 ?: number,
             y                 ?: number,
+            rotation          ?: number,
+            scale             ?: number,
             origin            ?: Vector2,
             size              ?: Size,
             width             ?: number,
@@ -249,9 +271,6 @@
             paddingRight      ?: number | string,
             paddingBottom     ?: number | string,
             padding           ?: string,
-            paddingHAlignment ?: number,
-            paddingVAlignment ?: number,
-
         }) {
 
             // Avoid checking every time if the object exists

src/Canvas2d/babylon.group2d.ts

@@ -1,5 +1,9 @@
 module BABYLON {
     @className("Group2D")
+    /**
+     * A non renderable primitive that defines a logical group.
+     * Can also serve the purpose of caching its content into a bitmap to reduce rendering overhead
+     */
     export class Group2D extends Prim2DBase {
         static GROUP2D_PROPCOUNT: number = Prim2DBase.PRIM2DBASE_PROPCOUNT + 5;
 
@@ -24,49 +28,61 @@
 
         /**
          * Create an Logical or Renderable Group.
-         * @param parent the parent primitive, must be a valid primitive (or the Canvas)
-         * options:
+         * @param settings a combination of settings, possible ones are
+         *  - parent: the parent primitive/canvas, must be specified if the primitive is not constructed as a child of another one (i.e. as part of the children array setting)
+         *  - children: an array of direct children
          *  - id a text identifier, for information purpose
          *  - position: the X & Y positions relative to its parent. Alternatively the x and y properties can be set. Default is [0;0]
+         *  - rotation: the initial rotation (in radian) of the primitive. default is 0
+         *  - scale: the initial scale of the primitive. default is 1
          *  - origin: define the normalized origin point location, default [0.5;0.5]
          *  - size: the size of the group. Alternatively the width and height properties can be set. If null the size will be computed from its content, default is null.
          *  - cacheBehavior: Define how the group should behave regarding the Canvas's cache strategy, default is Group2D.GROUPCACHEBEHAVIOR_FOLLOWCACHESTRATEGY
+         *  - layoutEngine: either an instance of a layout engine based class (StackPanel.Vertical, StackPanel.Horizontal) or a string ('canvas' for Canvas layout, 'StackPanel' or 'HorizontalStackPanel' for horizontal Stack Panel layout, 'VerticalStackPanel' for vertical Stack Panel layout).
          *  - isVisible: true if the group must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         * - marginTop: top margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - marginLeft: left margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - marginRight: right margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - marginBottom: bottom margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - margin: top, left, right and bottom margin formatted as a single string (see PrimitiveThickness.fromString)
+         * - marginHAlignment: one value of the PrimitiveAlignment type's static properties
+         * - marginVAlignment: one value of the PrimitiveAlignment type's static properties
+         * - marginAlignment: a string defining the alignment, see PrimitiveAlignment.fromString
+         * - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         * - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(settings?: {
 
-            parent?: Prim2DBase,
-            children?: Array<Prim2DBase>,
-            id?: string,
-            position?: Vector2,
-            x?: number,
-            y?: number,
-            trackNode?: Node,
-            origin?: Vector2,
-            size?: Size,
-            width?: number,
-            height?: number,
-            cacheBehavior?: number,
-            layoutEngine?: LayoutEngineBase | string,
-            isVisible?: boolean,
-            marginTop?: number | string,
-            marginLeft?: number | string,
-            marginRight?: number | string,
-            marginBottom?: number | string,
-            margin?: number | string,
+            parent          ?: Prim2DBase,
+            children        ?: Array<Prim2DBase>,
+            id              ?: string,
+            position        ?: Vector2,
+            x               ?: number,
+            y               ?: number,
+            trackNode       ?: Node,
+            origin          ?: Vector2,
+            size            ?: Size,
+            width           ?: number,
+            height          ?: number,
+            cacheBehavior   ?: number,
+            layoutEngine    ?: LayoutEngineBase | string,
+            isVisible       ?: boolean,
+            marginTop       ?: number | string,
+            marginLeft      ?: number | string,
+            marginRight     ?: number | string,
+            marginBottom    ?: number | string,
+            margin          ?: number | string,
             marginHAlignment?: number,
             marginVAlignment?: number,
-            marginAlignment?: string,
-            paddingTop?: number | string,
-            paddingLeft?: number | string,
-            paddingRight?: number | string,
-            paddingBottom?: number | string,
-            padding?: string,
-            paddingHAlignment?: number,
-            paddingVAlignment?: number,
+            marginAlignment ?: string,
+            paddingTop      ?: number | string,
+            paddingLeft     ?: number | string,
+            paddingRight    ?: number | string,
+            paddingBottom   ?: number | string,
+            padding         ?: string,
 
         }) {
             if (settings == null) {
@@ -237,6 +253,9 @@
             this._groupRender();
         }
 
+        /**
+         * Get/set the Scene's Node that should be tracked, the group's position will follow the projected position of the Node.
+         */
         public get trackedNode(): Node {
             return this._trackedNode;
         }

src/Canvas2d/babylon.lines2d.ts

@@ -169,13 +169,44 @@
     }
 
     @className("Lines2D")
+    /**
+     * Primitive drawing a series of line segments
+     */
     export class Lines2D extends Shape2D {
+
+        /**
+         * No Cap to apply on the extremity
+         */
         static get NoCap() { return Lines2D._noCap; }
+
+        /**
+         * A round cap, will use the line thickness as diameter
+         */
         static get RoundCap() { return Lines2D._roundCap; }
+
+        /**
+         * Creates a triangle at the extremity.
+         */
         static get TriangleCap() { return Lines2D._triangleCap; }
+
+        /**
+         * Creates a Square anchor at the extremity, the square size is twice the thickness of the line
+         */
         static get SquareAnchorCap() { return Lines2D._squareAnchorCap; }
+
+        /**
+         * Creates a round anchor at the extremity, the diameter is twice the thickness of the line
+         */
         static get RoundAnchorCap() { return Lines2D._roundAnchorCap; }
+
+        /**
+         * Creates a diamond anchor at the extremity.
+         */
         static get DiamondAnchorCap() { return Lines2D._diamondAnchorCap; }
+
+        /**
+         * Creates an arrow anchor at the extremity. the arrow base size is twice the thickness of the line
+         */
         static get ArrowCap() { return Lines2D._arrowCap; }
 
         public static pointsProperty: Prim2DPropInfo;
@@ -185,6 +216,9 @@
         public static endCapProperty: Prim2DPropInfo;
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 1, pi => Lines2D.pointsProperty = pi)
+        /**
+         * Get the list of points that define the Lines2D primitive. You shouldn't try to change the list or its content. it's not supported right now.
+         */
         public get points(): Vector2[] {
             return this._points;
         }
@@ -195,6 +229,9 @@
         }
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 2, pi => Lines2D.fillThicknessProperty = pi)
+        /**
+         * Get the thickness of the line. You shouldn't try to change this value, it's not supported right now.
+         */
         public get fillThickness(): number {
             return this._fillThickness;
         }
@@ -204,6 +241,10 @@
         }
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 3, pi => Lines2D.closedProperty = pi)
+        /**
+         * Get if the Lines2D is a closed shape (true) or an opened one (false).
+         * Don't change this property, setter is for internal purpose only.
+         */
         public get closed(): boolean {
             return this._closed;
         }
@@ -213,6 +254,9 @@
         }
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 4, pi => Lines2D.startCapProperty = pi)
+        /**
+         * Get the start cap of the line. You shouldn't try to change this value, it's not supported right now.
+         */
         public get startCap(): number {
             return this._startCap;
         }
@@ -222,6 +266,9 @@
         }
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 5, pi => Lines2D.endCapProperty = pi)
+        /**
+         * Get the end cap of the line. You shouldn't try to change this value, it's not supported right now.
+         */
         public get endCap(): number {
             return this._endCap;
         }
@@ -332,23 +379,36 @@
 
         /**
          * Create an 2D Lines Shape primitive. The defined lines may be opened or closed (see below)
-         * @param parent the parent primitive, must be a valid primitive (or the Canvas)
          * @param points an array that describe the points to use to draw the line, must contain at least two entries.
-         * options:
+         * @param settings a combination of settings, possible ones are
+         *  - parent: the parent primitive/canvas, must be specified if the primitive is not constructed as a child of another one (i.e. as part of the children array setting)
+         *  - children: an array of direct children
          *  - id a text identifier, for information purpose
          *  - position: the X & Y positions relative to its parent. Alternatively the x and y properties can be set. Default is [0;0]
+         *  - rotation: the initial rotation (in radian) of the primitive. default is 0
+         *  - scale: the initial scale of the primitive. default is 1
          *  - origin: define the normalized origin point location, default [0.5;0.5]
          *  - fillThickness: the thickness of the fill part of the line, can be null to draw nothing (but a border brush must be given), default is 1.
          *  - closed: if false the lines are said to be opened, the first point and the latest DON'T connect. if true the lines are said to be closed, the first and last point will be connected by a line. For instance you can define the 4 points of a rectangle, if you set closed to true a 4 edges rectangle will be drawn. If you set false, only three edges will be drawn, the edge formed by the first and last point won't exist. Default is false.
-         *  - Draw a cap of the given type at the start of the first line, you can't define a Cap if the Lines2D is closed. Default is Lines2D.NoCap.
-         *  - Draw a cap of the given type at the end of the last line, you can't define a Cap if the Lines2D is closed. Default is Lines2D.NoCap.
-         *  - fill: the brush used to draw the fill content of the lines, you can set null to draw nothing (but you will have to set a border brush), default is a SolidColorBrush of plain white.
-         *  - border: the brush used to draw the border of the lines, you can set null to draw nothing (but you will have to set a fill brush), default is null.
+         *  - startCap: Draw a cap of the given type at the start of the first line, you can't define a Cap if the Lines2D is closed. Default is Lines2D.NoCap.
+         *  - endCap: Draw a cap of the given type at the end of the last line, you can't define a Cap if the Lines2D is closed. Default is Lines2D.NoCap.
+         *  - fill: the brush used to draw the fill content of the lines, you can set null to draw nothing (but you will have to set a border brush), default is a SolidColorBrush of plain white. can be a string value (see Canvas2D.GetBrushFromString)
+         *  - border: the brush used to draw the border of the lines, you can set null to draw nothing (but you will have to set a fill brush), default is null. can be a string value (see Canvas2D.GetBrushFromString)
          *  - borderThickness: the thickness of the drawn border, default is 1.
          *  - isVisible: true if the primitive must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         *  - marginTop: top margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginLeft: left margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginRight: right margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginBottom: bottom margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - margin: top, left, right and bottom margin formatted as a single string (see PrimitiveThickness.fromString)
+         *  - marginHAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginVAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginAlignment: a string defining the alignment, see PrimitiveAlignment.fromString
+         *  - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(points: Vector2[], settings?: {
 
@@ -358,6 +418,8 @@
             position         ?: Vector2,
             x                ?: number,
             y                ?: number,
+            rotation         ?: number,
+            scale            ?: number,
             origin           ?: Vector2,
             fillThickness    ?: number,
             closed           ?: boolean,
@@ -380,8 +442,6 @@
             paddingRight     ?: number | string,
             paddingBottom    ?: number | string,
             padding          ?: string,
-            paddingHAlignment?: number,
-            paddingVAlignment?: number,
         }) {
 
             if (!settings) {

src/Canvas2d/babylon.prim2dBase.ts

@@ -291,6 +291,9 @@
         }
     }
 
+    /**
+     * Defines the horizontal and vertical alignment information for a Primitive.
+     */
     export class PrimitiveAlignment {
         constructor(changeCallback: () => void) {
             this._changedCallback = changeCallback;
@@ -298,12 +301,35 @@
             this._vertical = PrimitiveAlignment.AlignBottom;
         }
 
-        public static get AlignLeft():    number { return PrimitiveAlignment._AlignLeft;   }
-        public static get AlignTop():     number { return PrimitiveAlignment._AlignTop;    }
-        public static get AlignRight():   number { return PrimitiveAlignment._AlignRight;  }
-        public static get AlignBottom():  number { return PrimitiveAlignment._AlignBottom; }
-        public static get AlignCenter():  number { return PrimitiveAlignment._AlignCenter; }
-        public static get AlignStretch(): number { return PrimitiveAlignment._AlignStretch;}
+        /**
+         * Alignment is made relative to the left edge of the Primitive. Valid for horizontal alignment only.
+         */
+        public static get AlignLeft(): number { return PrimitiveAlignment._AlignLeft; }
+
+        /**
+         * Alignment is made relative to the top edge of the Primitive. Valid for vertical alignment only.
+         */
+        public static get AlignTop(): number { return PrimitiveAlignment._AlignTop; }
+
+        /**
+         * Alignment is made relative to the right edge of the Primitive. Valid for horizontal alignment only.
+         */
+        public static get AlignRight(): number { return PrimitiveAlignment._AlignRight; }
+
+        /**
+         * Alignment is made relative to the bottom edge of the Primitive. Valid for vertical alignment only.
+         */
+        public static get AlignBottom(): number { return PrimitiveAlignment._AlignBottom; }
+
+        /**
+         * Alignment is made to center the content from equal distance to the opposite edges of the Primitive
+         */
+        public static get AlignCenter(): number { return PrimitiveAlignment._AlignCenter; }
+
+        /**
+         * The content is stretched toward the opposite edges of the Primitive
+         */
+        public static get AlignStretch(): number { return PrimitiveAlignment._AlignStretch; }
 
         private static _AlignLeft    = 1;
         private static _AlignTop     = 1;   // Same as left
@@ -312,6 +338,9 @@
         private static _AlignCenter  = 3;
         private static _AlignStretch = 4;
 
+        /**
+         * Get/set the horizontal alignment. Use one of the AlignXXX static properties of this class
+         */
         public get horizontal(): number {
             return this._horizontal;
         }
@@ -325,6 +354,9 @@
             this._changedCallback();
         }
 
+        /**
+         * Get/set the vertical alignment. Use one of the AlignXXX static properties of this class
+         */
         public get vertical(): number {
             return this._vertical;
         }
@@ -342,6 +374,10 @@
         private _horizontal: number;
         private _vertical: number;
 
+        /**
+         * Set the horizontal alignment from a string value.
+         * @param text can be either: 'left','right','center','stretch'
+         */
         setHorizontal(text: string) {
             let v = text.trim().toLocaleLowerCase();
             switch (v) {
@@ -360,6 +396,10 @@
             }
         }
 
+        /**
+         * Set the vertical alignment from a string value.
+         * @param text can be either: 'top','bottom','center','stretch'
+         */
         setVertical(text: string) {
             let v = text.trim().toLocaleLowerCase();
             switch (v) {
@@ -378,6 +418,10 @@
             }
         }
 
+        /**
+         * Set the horizontal and or vertical alignments from a string value.
+         * @param text can be: [<h:|horizontal:><left|right|center|stretch>], [<v:|vertical:><top|bottom|center|stretch>]
+         */
         fromString(value: string) {
             let m = value.trim().split(",");
             for (let v of m) {
@@ -419,6 +463,10 @@
         }
     }
 
+    /**
+     * Define a thickness toward every edges of a Primitive to allow margin and padding.
+     * The thickness can be expressed as pixels, percentages, inherit the value of the parent primitive or be auto.
+     */
     export class PrimitiveThickness {
         constructor(parentAccess: () => PrimitiveThickness, changedCallback: () => void) {
             this._parentAccess = parentAccess;
@@ -435,10 +483,15 @@
             this._pixels[3] = 0;
         }
 
-        public fromString(margin: string) {
+        /**
+         * Set the thickness from a string value
+         * @param thickness format is "top: <value>, left:<value>, right:<value>, bottom:<value>" each are optional, auto will be set if it's omitted.
+         * Values are: 'auto', 'inherit', 'XX%' for percentage, 'XXpx' or 'XX' for pixels.
+         */
+        public fromString(thickness: string) {
             this._clear();
 
-            let m = margin.trim().split(",");
+            let m = thickness.trim().split(",");
 
             let res = false;
             for (let cm of m) {
@@ -459,6 +512,14 @@
 
         }
 
+        /**
+         * Set the thickness from multiple string
+         * Possible values are: 'auto', 'inherit', 'XX%' for percentage, 'XXpx' or 'XX' for pixels.
+         * @param top the top thickness to set
+         * @param left the left thickness to set
+         * @param right the right thickness to set
+         * @param bottom the bottom thickness to set
+         */
         public fromStrings(top: string, left: string, right: string, bottom: string): PrimitiveThickness {
             this._clear();
 
@@ -470,6 +531,13 @@
             return this;
         }
 
+        /**
+         * Set the thickness from pixel values
+         * @param top the top thickness in pixels to set
+         * @param left the left thickness in pixels to set
+         * @param right the right thickness in pixels to set
+         * @param bottom the bottom thickness in pixels to set
+         */
         public fromPixels(top: number, left: number, right: number, bottom: number): PrimitiveThickness {
             this._clear();
 
@@ -481,6 +549,10 @@
             return this;
         }
 
+        /**
+         * Apply the same pixel value to all edges
+         * @param margin the value to set, in pixels.
+         */
         public fromUniformPixels(margin: number): PrimitiveThickness {
             this._clear();
 
@@ -492,6 +564,9 @@
             return this;
         }
 
+        /**
+         * Set all edges in auto
+         */
         public auto(): PrimitiveThickness {
             this._clear();
 
@@ -714,6 +789,9 @@
             }
         }
 
+        /**
+         * Get/set the top thickness. Possible values are: 'auto', 'inherit', 'XX%' for percentage, 'XXpx' or 'XX' for pixels.
+         */
         public get top(): string {
             return this._getStringValue(0);
         }
@@ -722,6 +800,9 @@
             this._setStringValue(value, 0, true);
         }
 
+        /**
+         * Get/set the left thickness. Possible values are: 'auto', 'inherit', 'XX%' for percentage, 'XXpx' or 'XX' for pixels.
+         */
         public get left(): string {
             return this._getStringValue(1);
         }
@@ -730,6 +811,9 @@
             this._setStringValue(value, 1, true);
         }
 
+        /**
+         * Get/set the right thickness. Possible values are: 'auto', 'inherit', 'XX%' for percentage, 'XXpx' or 'XX' for pixels.
+         */
         public get right(): string {
             return this._getStringValue(2);
         }
@@ -738,6 +822,9 @@
             this._setStringValue(value, 2, true);
         }
 
+        /**
+         * Get/set the bottom thickness. Possible values are: 'auto', 'inherit', 'XX%' for percentage, 'XXpx' or 'XX' for pixels.
+         */
         public get bottom(): string {
             return this._getStringValue(3);
         }
@@ -746,6 +833,9 @@
             this._setStringValue(value, 3, true);
         }
 
+        /**
+         * Get/set the top thickness in pixel.
+         */
         public get topPixels(): number {
             return this._pixels[0];
         }
@@ -754,6 +844,10 @@
             this._setPixels(value, 0, true);
 
         }
+
+        /**
+         * Get/set the left thickness in pixel.
+         */
         public get leftPixels(): number {
             return this._pixels[1];
         }
@@ -762,6 +856,10 @@
             this._setPixels(value, 1, true);
 
         }
+
+        /**
+         * Get/set the right thickness in pixel.
+         */
         public get rightPixels(): number {
             return this._pixels[2];
         }
@@ -770,6 +868,10 @@
             this._setPixels(value, 2, true);
 
         }
+
+        /**
+         * Get/set the bottom thickness in pixel.
+         */
         public get bottomPixels(): number {
             return this._pixels[3];
         }
@@ -779,6 +881,11 @@
 
         }
 
+        /**
+         * Get/set the top thickness in percentage.
+         * The get will return a valid value only if the edge type is percentage.
+         * The Set will change the edge mode if needed
+         */
         public get topPercentage(): number {
             return this._percentages[0];
         }
@@ -787,6 +894,11 @@
             this._setPercentage(value, 0, true);
 
         }
+        /**
+         * Get/set the left thickness in percentage.
+         * The get will return a valid value only if the edge mode is percentage.
+         * The Set will change the edge mode if needed
+         */
         public get leftPercentage(): number {
             return this._percentages[1];
         }
@@ -795,6 +907,11 @@
             this._setPercentage(value, 1, true);
 
         }
+        /**
+         * Get/set the right thickness in percentage.
+         * The get will return a valid value only if the edge mode is percentage.
+         * The Set will change the edge mode if needed
+         */
         public get rightPercentage(): number {
             return this._percentages[2];
         }
@@ -803,6 +920,11 @@
             this._setPercentage(value, 2, true);
 
         }
+        /**
+         * Get/set the bottom thickness in percentage.
+         * The get will return a valid value only if the edge mode is percentage.
+         * The Set will change the edge mode if needed
+         */
         public get bottomPercentage(): number {
             return this._percentages[3];
         }
@@ -811,34 +933,47 @@
             this._setPercentage(value, 3, true);
 
         }
+
+        /**
+         * Get/set the top mode. The setter shouldn't be used, other setters with value should be preferred
+         */
         public get topMode(): number {
             return this._getType(0, false);
         }
 
-        public get leftMode(): number {
-            return this._getType(1, false);
-        }
-
-        public get rightMode(): number {
-            return this._getType(2, false);
-        }
-
-        public get bottomMode(): number {
-            return this._getType(3, false);
-        }
-
         public set topMode(mode: number) {
             this._setType(0, mode);
         }
 
+        /**
+         * Get/set the left mode. The setter shouldn't be used, other setters with value should be preferred
+         */
+        public get leftMode(): number {
+            return this._getType(1, false);
+        }
+
         public set leftMode(mode: number) {
             this._setType(1, mode);
         }
 
+        /**
+         * Get/set the right mode. The setter shouldn't be used, other setters with value should be preferred
+         */
+        public get rightMode(): number {
+            return this._getType(2, false);
+        }
+
         public set rightMode(mode: number) {
             this._setType(2, mode);
         }
 
+        /**
+         * Get/set the bottom mode. The setter shouldn't be used, other setters with value should be preferred
+         */
+        public get bottomMode(): number {
+            return this._getType(3, false);
+        }
+
         public set bottomMode(mode: number) {
             this._setType(3, mode);
         }
@@ -874,6 +1009,14 @@
             }
         }
 
+        /**
+         * Compute the positioning/size of an area considering the thickness of this object and a given alignment
+         * @param sourceArea the source area
+         * @param contentSize the content size to position/resize
+         * @param alignment the alignment setting
+         * @param dstOffset the position of the content
+         * @param dstArea the new size of the content
+         */
         public computeWithAlignment(sourceArea: Size, contentSize: Size, alignment: PrimitiveAlignment, dstOffset: Vector2, dstArea: Size) {
             // Fetch some data
             let topType      = this._getType(0, true);
@@ -1005,6 +1148,12 @@
             }
         }
 
+        /**
+         * Compute an area and its position considering this thickness properties based on a given source area
+         * @param sourceArea the source area
+         * @param dstOffset the position of the resulting area
+         * @param dstArea the size of the resulting area
+         */
         public compute(sourceArea: Size, dstOffset: Vector2, dstArea: Size) {
             this._computePixels(0, sourceArea, true);
             this._computePixels(1, sourceArea, true);
@@ -1018,6 +1167,11 @@
             dstArea.height = sourceArea.height - (dstOffset.y + this.topPixels);
         }
 
+        /**
+         * Compute an area considering this thickness properties based on a given source area
+         * @param sourceArea the source area
+         * @param result the resulting area
+         */
         computeArea(sourceArea: Size, result: Size) {
             this._computePixels(0, sourceArea, true);
             this._computePixels(1, sourceArea, true);
@@ -1451,6 +1605,7 @@
          * Position of the primitive, relative to its parent.
          * BEWARE: if you change only position.x or y it won't trigger a property change and you won't have the expected behavior.
          * Use this property to set a new Vector2 object, otherwise to change only the x/y use Prim2DBase.x or y properties.
+         * Setting this property may have no effect is specific alignment are in effect.
          */
         @dynamicLevelProperty(1, pi => Prim2DBase.positionProperty = pi, false, true)
         public get position(): Vector2 {
@@ -1655,11 +1810,6 @@
             return this._zOrder || (1 - this._hierarchyDepthOffset);
         }
 
-        @dynamicLevelProperty(5, pi => Prim2DBase.originProperty = pi, false, true)
-        public set origin(value: Vector2) {
-            this._origin = value;
-        }
-
         /**
          * Get or set the minimal size the Layout Engine should respect when computing the primitive's actualSize.
          * The Primitive's size won't be less than specified.
@@ -1697,7 +1847,7 @@
         }
 
         /**
-         * The origin defines the normalized coordinate of the center of the primitive, from the top/left corner.
+         * The origin defines the normalized coordinate of the center of the primitive, from the bottom/left corner.
          * The origin is used only to compute transformation of the primitive, it has no meaning in the primitive local frame of reference
          * For instance:
          * 0,0 means the center is bottom/left. Which is the default for Canvas2D instances
@@ -1709,6 +1859,11 @@
             return this._origin;
         }
 
+        @dynamicLevelProperty(5, pi => Prim2DBase.originProperty = pi, false, true)
+        public set origin(value: Vector2) {
+            this._origin = value;
+        }
+
         @dynamicLevelProperty(6, pi => Prim2DBase.levelVisibleProperty = pi)
         /**
          * Let the user defines if the Primitive is hidden or not at its level. As Primitives inherit the hidden status from their parent, only the isVisible property give properly the real visible state.
@@ -1801,6 +1956,10 @@
             return this._marginAlignment;
         }
 
+        /**
+         * Get/set the layout engine to use for this primitive.
+         * The default layout engine is the CanvasLayoutEngine.
+         */
         public get layoutEngine(): LayoutEngineBase {
             if (!this._layoutEngine) {
                 this._layoutEngine = CanvasLayoutEngine.Singleton;
@@ -1816,6 +1975,11 @@
             this._changeLayoutEngine(value);
         }
 
+        /**
+         * Get/set the layout are of this primitive.
+         * The Layout area is the zone allocated by the Layout Engine for this particular primitive. Margins/Alignment will be computed based on this area.
+         * The setter should only be called by a Layout Engine class.
+         */
         public get layoutArea(): Size {
             return this._layoutArea;
         }
@@ -1828,6 +1992,10 @@
             this._layoutArea = val;
         }
 
+        /**
+         * Get/set the layout area position (relative to the parent primitive).
+         * The setter should only be called by a Layout Engine class.
+         */
         public get layoutAreaPos(): Vector2 {
             return this._layoutAreaPos;
         }
@@ -2095,6 +2263,9 @@
             this._children.push(child);
         }
 
+        /**
+         * Dispose the primitive, remove it from its parent.
+         */
         public dispose(): boolean {
             if (!super.dispose()) {
                 return false;
@@ -2405,6 +2576,10 @@
             }
         }
 
+        /**
+         * Get the content are of this primitive, this area is computed using the padding property and also possibly the primitive type itself.
+         * Children of this primitive will be positioned relative to the bottom/left corner of this area.
+         */
         public get contentArea(): Size {
             // Check for positioning update
             if (this._isFlagSet(SmartPropertyPrim.flagPositioningDirty)) {

src/Canvas2d/babylon.rectangle2d.ts

@@ -165,6 +165,9 @@
     }
 
     @className("Rectangle2D")
+    /**
+     * The Rectangle Primitive type
+     */
     export class Rectangle2D extends Shape2D {
 
         public static actualSizeProperty: Prim2DPropInfo;
@@ -172,6 +175,9 @@
         public static roundRadiusProperty: Prim2DPropInfo;
 
         @instanceLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 1, pi => Rectangle2D.actualSizeProperty = pi, false, true)
+        /**
+         * Get/set the rectangle size (width/height)
+         */
         public get actualSize(): Size {
             if (this._actualSize) {
                 return this._actualSize;
@@ -184,6 +190,10 @@
         }
 
         @modelLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 2, pi => Rectangle2D.notRoundedProperty = pi)
+        /**
+         * Get if the rectangle is notRound (returns true) or rounded (returns false).
+         * Don't use the setter, it's for internal purpose only
+         */
         public get notRounded(): boolean {
             return this._notRounded;
         }
@@ -193,6 +203,9 @@
         }
 
         @instanceLevelProperty(Shape2D.SHAPE2D_PROPCOUNT + 3, pi => Rectangle2D.roundRadiusProperty = pi)
+        /**
+         * Get/set the round Radius, a value of 0 for a sharp edges rectangle, otherwise the value will be used as the diameter of the round to apply on corder. The Rectangle2D.notRounded property will be updated accordingly.
+         */
         public get roundRadius(): number {
             return this._roundRadius;
         }
@@ -285,20 +298,33 @@
 
         /**
          * Create an Rectangle 2D Shape primitive. May be a sharp rectangle (with sharp corners), or a rounded one.
-         * @param parent the parent primitive, must be a valid primitive (or the Canvas)
-         * options:
+         * @param settings a combination of settings, possible ones are
+         *  - parent: the parent primitive/canvas, must be specified if the primitive is not constructed as a child of another one (i.e. as part of the children array setting)
+         *  - children: an array of direct children
          *  - id a text identifier, for information purpose
-         *  - position: the X & Y positions relative to its parent. Alternatively the x and y properties can be set. Default is [0;0]
+         *  - position: the X & Y positions relative to its parent. Alternatively the x and y settings can be set. Default is [0;0]
+         *  - rotation: the initial rotation (in radian) of the primitive. default is 0
+         *  - scale: the initial scale of the primitive. default is 1
          *  - origin: define the normalized origin point location, default [0.5;0.5]
-         *  - size: the size of the group. Alternatively the width and height properties can be set. Default will be [10;10].
-         *  - roundRadius: if the rectangle has rounded corner, set their radius, default is 0 (to get a sharp rectangle).
-         *  - fill: the brush used to draw the fill content of the ellipse, you can set null to draw nothing (but you will have to set a border brush), default is a SolidColorBrush of plain white.
-         *  - border: the brush used to draw the border of the ellipse, you can set null to draw nothing (but you will have to set a fill brush), default is null.
+         *  - size: the size of the group. Alternatively the width and height settings can be set. Default will be [10;10].
+         *  - roundRadius: if the rectangle has rounded corner, set their radius, default is 0 (to get a sharp edges rectangle).
+         *  - fill: the brush used to draw the fill content of the rectangle, you can set null to draw nothing (but you will have to set a border brush), default is a SolidColorBrush of plain white. can also be a string value (see Canvas2D.GetBrushFromString)
+         *  - border: the brush used to draw the border of the rectangle, you can set null to draw nothing (but you will have to set a fill brush), default is null. can also be a string value (see Canvas2D.GetBrushFromString)
          *  - borderThickness: the thickness of the drawn border, default is 1.
          *  - isVisible: true if the primitive must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         *  - marginTop: top margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginLeft: left margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginRight: right margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginBottom: bottom margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - margin: top, left, right and bottom margin formatted as a single string (see PrimitiveThickness.fromString)
+         *  - marginHAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginVAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginAlignment: a string defining the alignment, see PrimitiveAlignment.fromString
+         *  - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(settings ?: {
             parent           ?: Prim2DBase, 
@@ -331,8 +357,6 @@
             paddingRight     ?: number | string,
             paddingBottom    ?: number | string,
             padding          ?: string,
-            paddingHAlignment?: number,
-            paddingVAlignment?: number,
         }) {
 
             // Avoid checking every time if the object exists

src/Canvas2d/babylon.renderablePrim2d.ts

@@ -324,13 +324,22 @@
     }
 
     @className("RenderablePrim2D")
-    export class RenderablePrim2D extends Prim2DBase {
+    /**
+     * The abstract class for primitive that render into the Canvas2D
+     */
+    export abstract class RenderablePrim2D extends Prim2DBase {
         static RENDERABLEPRIM2D_PROPCOUNT: number = Prim2DBase.PRIM2DBASE_PROPCOUNT + 5;
 
         public static isAlphaTestProperty: Prim2DPropInfo;
         public static isTransparentProperty: Prim2DPropInfo;
 
         @dynamicLevelProperty(Prim2DBase.PRIM2DBASE_PROPCOUNT + 0, pi => RenderablePrim2D.isAlphaTestProperty = pi)
+        /**
+         * Get/set if the Primitive is from the AlphaTest rendering category.
+         * The AlphaTest category is the rendering pass with alpha blend, depth compare and write activated.
+         * Primitives that render with an alpha mask should be from this category.
+         * The setter should be used only by implementers of new primitive type.
+         */
         public get isAlphaTest(): boolean {
             return this._isAlphaTest;
         }
@@ -340,6 +349,10 @@
         }
 
         @dynamicLevelProperty(Prim2DBase.PRIM2DBASE_PROPCOUNT + 1, pi => RenderablePrim2D.isTransparentProperty = pi)
+        /**
+         * Get/set if the Primitive is from the Transparent rendering category.
+         * The setter should be used only by implementers of new primitive type.
+         */
         public get isTransparent(): boolean {
             return this._isTransparent;
         }
@@ -360,6 +373,9 @@
             this._transparentPrimitiveInfo = null;
         }
 
+        /**
+         * Dispose the primitive and its resources, remove it from its parent
+         */
         public dispose(): boolean {
             if (!super.dispose()) {
                 return false;

src/Canvas2d/babylon.shape2d.ts

@@ -1,7 +1,12 @@
 module BABYLON {
 
     @className("Shape2D")
-    export class Shape2D extends RenderablePrim2D {
+    /**
+     * The abstract class for parametric shape based Primitives types.
+     * Shape2D based primitives are composed of two parts: fill and border, both are optional but at least one must be specified.
+     * The fill part is the primitive 'body', the border is a border around this body. The border has a thickness that can be changed.
+     */
+    export abstract class Shape2D extends RenderablePrim2D {
         static SHAPE2D_BORDERPARTID            = 1;
         static SHAPE2D_FILLPARTID              = 2;
         static SHAPE2D_CATEGORY_BORDER         = "Border";
@@ -16,6 +21,9 @@
         public static borderThicknessProperty: Prim2DPropInfo;
 
         @modelLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 1, pi => Shape2D.borderProperty = pi, true)
+        /**
+         * Get/set the brush to render the Border part of the Primitive
+         */
         public get border(): IBrush2D {
             return this._border;
         }
@@ -25,6 +33,9 @@
             this._updateTransparencyStatus();
         }
 
+        /**
+         * Get/set the brush to render the Fill part of the Primitive
+         */
         @modelLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 2, pi => Shape2D.fillProperty = pi, true)
         public get fill(): IBrush2D {
             return this._fill;
@@ -36,6 +47,9 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 3, pi => Shape2D.borderThicknessProperty = pi)
+        /**
+         * Get/set the thickness of the border part.
+         */
         public get borderThickness(): number {
             return this._borderThickness;
         }

src/Canvas2d/babylon.smartPropertyPrim.ts

@@ -16,13 +16,32 @@
         typeLevelCompare: boolean;
     }
 
+    /**
+     * Custom type of the propertyChanged observable
+     */
     export class PropertyChangedInfo {
+        /**
+         * Previous value of the property
+         */
         oldValue: any;
+        /**
+         * New value of the property
+         */
         newValue: any;
+
+        /**
+         * Name of the property that changed its value
+         */
         propertyName: string;
     }
 
+    /**
+     * Property Changed interface
+     */
     export interface IPropertyChanged {
+        /**
+         * PropertyChanged observable
+         */
         propertyChanged: Observable<PropertyChangedInfo>;
     }
 
@@ -133,7 +152,10 @@
     }
 
     @className("SmartPropertyPrim")
-    export class SmartPropertyPrim implements IPropertyChanged {
+    /**
+     * Base class of the primitives, implementing core crosscutting features
+     */
+    export abstract  class SmartPropertyPrim implements IPropertyChanged {
 
         constructor() {
             this._flags = 0;
@@ -526,28 +548,57 @@
             return this._externalData.remove(key);
         }
 
+        /**
+         * Check if a given flag is set
+         * @param flag the flag value
+         * @return true if set, false otherwise
+         */
         public _isFlagSet(flag: number): boolean {
             return (this._flags & flag) !== 0;
         }
 
+        /**
+         * Check if all given flags are set
+         * @param flags the flags ORed
+         * @return true if all the flags are set, false otherwise
+         */
         public _areAllFlagsSet(flags: number): boolean {
             return (this._flags & flags) === flags;
         }
 
+        /**
+         * Check if at least one flag of the given flags is set
+         * @param flags the flags ORed
+         * @return true if at least one flag is set, false otherwise
+         */
         public _areSomeFlagsSet(flags: number): boolean {
             return (this._flags & flags) !== 0;
         }
 
+        /**
+         * Clear the given flags
+         * @param flags the flags to clear
+         */
         public _clearFlags(flags: number) {
             this._flags &= ~flags;
         }
 
+        /**
+         * Set the given flags to true state
+         * @param flags the flags ORed to set
+         * @return the flags state before this call
+         */
         public _setFlags(flags: number): number {
             let cur = this._flags;
             this._flags |= flags;
             return cur;
         }
 
+        /**
+         * Change the state of the given flags
+         * @param flags the flags ORed to change
+         * @param state true to set them, false to clear them
+         */
         public _changeFlags(flags: number, state: boolean) {
             if (state) {
                 this._flags |= flags;

src/Canvas2d/babylon.sprite2d.ts

@@ -117,6 +117,9 @@
     }
 
     @className("Sprite2D")
+    /**
+     * Primitive that displays a Sprite/Picture
+     */
     export class Sprite2D extends RenderablePrim2D {
         static SPRITE2D_MAINPARTID = 1;
 
@@ -128,6 +131,9 @@
         public static alignToPixelProperty: Prim2DPropInfo;
 
         @modelLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 1, pi => Sprite2D.textureProperty = pi)
+        /**
+         * Get/set the texture that contains the sprite to display
+         */
         public get texture(): Texture {
             return this._texture;
         }
@@ -137,6 +143,9 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 2, pi => Sprite2D.actualSizeProperty = pi, false, true)
+        /**
+         * Get/set the actual size of the sprite to display
+         */
         public get actualSize(): Size {
             if (this._actualSize) {
                 return this._actualSize;
@@ -149,6 +158,9 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 3, pi => Sprite2D.spriteLocationProperty = pi)
+        /**
+         * Get/set the sprite location (in pixels) in the texture
+         */
         public get spriteLocation(): Vector2 {
             return this._location;
         }
@@ -158,6 +170,10 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 4, pi => Sprite2D.spriteFrameProperty = pi)
+        /**
+         * Get/set the sprite frame to display.
+         * The frame number is just an offset applied horizontally, based on the sprite's width. it does not wrap, all the frames must be on the same line.
+         */
         public get spriteFrame(): number {
             return this._spriteFrame;
         }
@@ -167,6 +183,9 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 5, pi => Sprite2D.invertYProperty = pi)
+        /**
+         * Get/set if the sprite texture coordinates should be inverted on the Y axis
+         */
         public get invertY(): boolean {
             return this._invertY;
         }
@@ -175,6 +194,9 @@
             this._invertY = value;
         }
 
+        /**
+         * Get/set if the sprite rendering should be aligned to the target rendering device pixel or not
+         */
         public get alignToPixel(): boolean {
             return this._alignToPixel;
         }
@@ -187,6 +209,9 @@
             BoundingInfo2D.CreateFromSizeToRef(this.size, this._levelBoundingInfo);
         }
 
+        /**
+         * Get the animatable array (see http://doc.babylonjs.com/tutorials/Animations)
+         */
         public getAnimatables(): IAnimatable[] {
             let res = new Array<IAnimatable>();
 
@@ -203,20 +228,33 @@
 
         /**
          * Create an 2D Sprite primitive
-         * @param parent the parent primitive, must be a valid primitive (or the Canvas)
          * @param texture the texture that stores the sprite to render
-         * options:
+         * @param settings a combination of settings, possible ones are
+         *  - parent: the parent primitive/canvas, must be specified if the primitive is not constructed as a child of another one (i.e. as part of the children array setting)
+         *  - children: an array of direct children
          *  - id a text identifier, for information purpose
          *  - position: the X & Y positions relative to its parent. Alternatively the x and y properties can be set. Default is [0;0]
+         *  - rotation: the initial rotation (in radian) of the primitive. default is 0
+         *  - scale: the initial scale of the primitive. default is 1
          *  - origin: define the normalized origin point location, default [0.5;0.5]
-         *  - spriteSize: the size of the sprite, if null the size of the given texture will be used, default is null.
-         *  - spriteLocation: the location in the texture of the top/left corner of the Sprite to display, default is null (0,0)
+         *  - spriteSize: the size of the sprite (in pixels), if null the size of the given texture will be used, default is null.
+         *  - spriteLocation: the location (in pixels) in the texture of the top/left corner of the Sprite to display, default is null (0,0)
          *  - invertY: if true the texture Y will be inverted, default is false.
          *  - alignToPixel: if true the sprite's texels will be aligned to the rendering viewport pixels, ensuring the best rendering quality but slow animations won't be done as smooth as if you set false. If false a texel could lies between two pixels, being blended by the texture sampling mode you choose, the rendering result won't be as good, but very slow animation will be overall better looking. Default is true: content will be aligned.
          *  - isVisible: true if the sprite must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         *  - marginTop: top margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginLeft: left margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginRight: right margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginBottom: bottom margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - margin: top, left, right and bottom margin formatted as a single string (see PrimitiveThickness.fromString)
+         *  - marginHAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginVAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginAlignment: a string defining the alignment, see PrimitiveAlignment.fromString
+         *  - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(texture: Texture, settings?: {
 
@@ -226,6 +264,8 @@
             position         ?: Vector2,
             x                ?: number,
             y                ?: number,
+            rotation         ?: number,
+            scale            ?: number,
             origin           ?: Vector2,
             spriteSize       ?: Size,
             spriteLocation   ?: Vector2,
@@ -245,8 +285,6 @@
             paddingRight     ?: number | string,
             paddingBottom    ?: number | string,
             padding          ?: string,
-            paddingHAlignment?: number,
-            paddingVAlignment?: number,
         }) {
 
             if (!settings) {

src/Canvas2d/babylon.text2d.ts

@@ -114,6 +114,9 @@
     }
 
     @className("Text2D")
+    /**
+     * Primitive that render text using a specific font
+     */
     export class Text2D extends RenderablePrim2D {
         static TEXT2D_MAINPARTID = 1;
 
@@ -123,6 +126,10 @@
         public static sizeProperty: Prim2DPropInfo;
 
         @modelLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 1, pi => Text2D.fontProperty = pi, false, true)
+        /**
+         * Get/set the font name to use, using HTML CSS notation.
+         * Set is not supported right now.
+         */
         public get fontName(): string {
             return this._fontName;
         }
@@ -135,6 +142,9 @@
         }
 
         @dynamicLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 2, pi => Text2D.defaultFontColorProperty = pi)
+        /**
+         * Get/set the font default color
+         */
         public get defaultFontColor(): Color4 {
             return this._defaultFontColor;
         }
@@ -144,6 +154,10 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 3, pi => Text2D.textProperty = pi, false, true)
+        /**
+         * Get/set the text to render.
+         * \n \t character are supported. 
+         */
         public get text(): string {
             return this._text;
         }
@@ -159,6 +173,10 @@
         }
 
         @instanceLevelProperty(RenderablePrim2D.RENDERABLEPRIM2D_PROPCOUNT + 4, pi => Text2D.sizeProperty = pi)
+        /**
+         * Get/set the size of the area where the text is drawn.
+         * You should not set this size, the default behavior compute the size based on the actual text.
+         */
         public get size(): Size {
             if (this._size != null) {
                 return this._size;
@@ -170,6 +188,9 @@
             this._size = value;
         }
 
+        /**
+         * Get the actual size of the Text2D primitive
+         */
         public get actualSize(): Size {
             if (this._actualSize) {
                 return this._actualSize;
@@ -177,6 +198,9 @@
             return this.size;
         }
 
+        /**
+         * Get the area that bounds the text associated to the primitive
+         */
         public get textSize(): Size {
             if (!this._textSize) {
                 if (this.owner) {
@@ -203,6 +227,9 @@
             return this._fontTexture;
         }
 
+        /**
+         * Dispose the primitive, remove it from its parent
+         */
         public dispose(): boolean {
             if (!super.dispose()) {
                 return false;
@@ -222,20 +249,33 @@
 
         /**
          * Create a Text primitive
-         * @param parent the parent primitive, must be a valid primitive (or the Canvas)
          * @param text the text to display
-         * Options:
+         * @param settings a combination of settings, possible ones are
+         *  - parent: the parent primitive/canvas, must be specified if the primitive is not constructed as a child of another one (i.e. as part of the children array setting)
+         *  - children: an array of direct children
          *  - id a text identifier, for information purpose
          *  - position: the X & Y positions relative to its parent. Alternatively the x and y properties can be set. Default is [0;0]
+         *  - rotation: the initial rotation (in radian) of the primitive. default is 0
+         *  - scale: the initial scale of the primitive. default is 1
          *  - origin: define the normalized origin point location, default [0.5;0.5]
          *  - fontName: the name/size/style of the font to use, following the CSS notation. Default is "12pt Arial".
          *  - defaultColor: the color by default to apply on each letter of the text to display, default is plain white.
          *  - areaSize: the size of the area in which to display the text, default is auto-fit from text content.
          *  - tabulationSize: number of space character to insert when a tabulation is encountered, default is 4
          *  - isVisible: true if the text must be visible, false for hidden. Default is true.
-         *  - marginTop/Left/Right/Bottom: define the margin for the corresponding edge, if all of them are null, margin is not used in layout computing. Default Value is null for each.
-         *  - hAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
-         *  - vAlighment: define horizontal alignment of the Canvas, alignment is optional, default value null: no alignment.
+         *  - marginTop: top margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginLeft: left margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginRight: right margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - marginBottom: bottom margin, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - margin: top, left, right and bottom margin formatted as a single string (see PrimitiveThickness.fromString)
+         *  - marginHAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginVAlignment: one value of the PrimitiveAlignment type's static properties
+         *  - marginAlignment: a string defining the alignment, see PrimitiveAlignment.fromString
+         *  - paddingTop: top padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingLeft: left padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingRight: right padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - paddingBottom: bottom padding, can be a number (will be pixels) or a string (see PrimitiveThickness.fromString)
+         *  - padding: top, left, right and bottom padding formatted as a single string (see PrimitiveThickness.fromString)
          */
         constructor(text: string, settings?: {
 
@@ -245,6 +285,8 @@
             position         ?: Vector2,
             x                ?: number,
             y                ?: number,
+            rotation         ?: number,
+            scale            ?: number,
             origin           ?: Vector2,
             fontName         ?: string,
             defaultFontColor ?: Color4,
@@ -264,8 +306,6 @@
             paddingRight     ?: number | string,
             paddingBottom    ?: number | string,
             padding          ?: string,
-            paddingHAlignment?: number,
-            paddingVAlignment?: number,
         }) {
 
             if (!settings) {

src/Canvas2d/babylon.worldSpaceCanvas2dNode.ts

@@ -1,6 +1,6 @@
 module BABYLON {
     /**
-     * This is the class that is used to display a World Space Canvas into a scene
+     * This is the class that is used to display a World Space Canvas into a 3D scene
      */
     export class WorldSpaceCanvas2DNode extends Mesh {
         constructor(name: string, scene: Scene, canvas: Canvas2D) {