full api documentation for h2d and h3d Object

h2d/Object.hx

@@ -10,23 +10,58 @@ class Object {
 	var parentContainer : Object;
 
 	/**
-		The parent `Sprite` in the scene tree.
+		The parent object in the scene tree.
 	**/
 	public var parent(default, null) : Object;
+
 	/**
-		How many immediate children this sprite has.
+		How many immediate children this object has.
 	**/
 	public var numChildren(get, never) : Int;
 
+	/**
+		The name of the object, can be used to retrieve an object within a tree by using `getObjectByName` (default null)
+	**/
+	public var name : String;
+
+	/**
+		The x position (in pixels) of the object relative to its parent.
+	**/
 	public var x(default,set) : Float;
+
+	/**
+		The y position (in pixels) of the object relative to its parent.
+	**/
 	public var y(default, set) : Float;
+
+	/**
+		The amount of horizontal scaling of this object (default 1.0)
+	**/
 	public var scaleX(default,set) : Float;
+
+	/**
+		The amount of vertical scaling of this object (default 1.0)
+	**/
 	public var scaleY(default,set) : Float;
+
+	/**
+		The rotation angle of this object, in radians.
+	**/
 	public var rotation(default, set) : Float;
+
+	/**
+		Is the object and its children are displayed on screen (default true).
+	**/
 	public var visible(default, set) : Bool;
-	public var name : String;
+
+	/**
+		The amount of transparency of the Object (default 1.0)
+	**/
 	public var alpha : Float = 1.;
 
+	/**
+		The post process filter for this object.
+	**/
 	public var filter(default,set) : h2d.filter.Filter;
 
 	var matA : Float;
@@ -40,6 +75,9 @@ class Object {
 	var allocated : Bool;
 	var lastFrame : Int;
 
+	/**
+		Create a new empty object, and adds it to the parent object if not null.
+	**/
 	public function new( ?parent : Object ) {
 		matA = 1; matB = 0; matC = 0; matD = 1; absX = 0; absY = 0;
 		x = 0; y = 0; scaleX = 1; scaleY = 1; rotation = 0;
@@ -51,9 +89,9 @@ class Object {
 	}
 
 	/**
-		Returns the bounds of the sprite for its whole content, recursively.
+		Return the bounds of the object for its whole content, recursively.
 		If relativeTo is null, it will return the bounds in the absolute coordinates.
-		If not, it will return the bounds relative to the specified sprite coordinates.
+		If not, it will return the bounds relative to the specified object coordinates.
 		You can pass an already allocated bounds or getBounds will allocate one for you and return it.
 	**/
 	public function getBounds( ?relativeTo : Object, ?out : h2d.col.Bounds ) : h2d.col.Bounds {
@@ -72,8 +110,8 @@ class Object {
 	}
 
 	/**
-		This is similar to getBounds(parent), but instead of the full content, it will return
-		the size based on the alignement of the Sprite. For instance for a text, getBounds will return
+		Similar to getBounds(parent), but instead of the full content, it will return
+		the size based on the alignement of the object. For instance for a text, getBounds will return
 		the full glyphs size whereas getSize() will ignore the pixels under the baseline.
 	**/
 	public function getSize( ?out : h2d.col.Bounds ) : h2d.col.Bounds {
@@ -89,6 +127,9 @@ class Object {
 		return out;
 	}
 
+	/**
+		Find a single object in the tree by calling `f` on each and returning the first not-null value returned, or null if not found.
+	**/
 	public function find<T>( f : Object -> Null<T> ) : Null<T> {
 		var v = f(this);
 		if( v != null )
@@ -100,6 +141,9 @@ class Object {
 		return null;
 	}
 
+	/**
+		Find several objects in the tree by calling `f` on each and returning all the not-null values returned.
+	**/
 	public function findAll<T>( f : Object -> Null<T>, ?arr : Array<T> ) : Array<T> {
 		if( arr == null ) arr = [];
 		var v = f(this);
@@ -202,13 +246,19 @@ class Object {
 		out.addPos(x * rA + y * rC, x * rB + y * rD);
 	}
 
-	public function getSpritesCount() : Int {
+	/**
+		Return the total number of children, recursively.
+	**/
+	public function getObjectsCount() : Int {
 		var k = 0;
 		for( c in children )
-			k += c.getSpritesCount() + 1;
+			k += c.getObjectsCount() + 1;
 		return k;
 	}
 
+	/**
+		Convert a local position (or [0,0] if pt is null) relative to the object origin into an absolute screen position, applying all the inherited transforms.
+	**/
 	public function localToGlobal( ?pt : h2d.col.Point ) : h2d.col.Point {
 		syncPos();
 		if( pt == null ) pt = new h2d.col.Point();
@@ -219,6 +269,9 @@ class Object {
 		return pt;
 	}
 
+	/**
+		Convert an absolute screen position into a local position relative to the object origin, applying all the inherited transforms.
+	**/
 	public function globalToLocal( pt : h2d.col.Point ) : h2d.col.Point {
 		syncPos();
 		pt.x -= absX;
@@ -245,10 +298,16 @@ class Object {
 		return b;
 	}
 
+	/**
+		Add a child object at the end of the children list.
+	**/
 	public function addChild( s : Object ) : Void {
 		addChildAt(s, children.length);
 	}
 
+	/**
+		Insert a child object at the specified position of the children list.
+	**/
 	public function addChildAt( s : Object, pos : Int ) : Void {
 		if( pos < 0 ) pos = 0;
 		if( pos > children.length ) pos = children.length;
@@ -317,6 +376,9 @@ class Object {
 		m.y = absY;
 	}
 
+	/**
+		Remove the given object from our immediate children list if it's part of it.
+	**/
 	public function removeChild( s : Object ) {
 		if( children.remove(s) ) {
 			if( s.allocated ) s.onRemove();
@@ -333,6 +395,9 @@ class Object {
 			s.setParentContainer(c);
 	}
 
+	/**
+		Remove all children from our immediate children list
+	**/
 	public function removeChildren() {
 		while( numChildren>0 )
 			removeChild( getChildAt(0) );
@@ -346,6 +411,9 @@ class Object {
 		if( this != null && parent != null ) parent.removeChild(this);
 	}
 
+	/**
+		Draw the object and all its children into the given Texture
+	**/
 	public function drawTo( t : h3d.mat.Texture ) {
 		var s = getScene();
 		var needDispose = s == null;
@@ -509,7 +577,7 @@ class Object {
 	}
 
 	/**
-		Will clip a local bounds with our global viewport
+		Clip a local bounds with our global viewport
 	**/
 	function clipBounds( ctx : RenderContext, bounds : h2d.col.Bounds ) {
 		var view = ctx.tmpBounds;
@@ -711,46 +779,70 @@ class Object {
 		return rotation = v;
 	}
 
+	/**
+		Move the object by the specied amount along its current direction (rotation angle).
+	**/
 	public function move( dx : Float, dy : Float ) {
 		x += dx * Math.cos(rotation);
 		y += dy * Math.sin(rotation);
 	}
 
+	/**
+		Set the position of the object relative to its parent.
+	**/
 	public inline function setPosition( x : Float, y : Float ) {
 		this.x = x;
 		this.y = y;
 	}
 
+	/**
+		Rotate the object by the given angle (in radians)
+	**/
 	public inline function rotate( v : Float ) {
 		rotation += v;
 	}
 
+	/**
+		Scale uniformly the object by the given factor.
+	**/
 	public inline function scale( v : Float ) {
 		scaleX *= v;
 		scaleY *= v;
 	}
 
+	/**
+		Set the uniform scale for the object.
+	**/
 	public inline function setScale( v : Float ) {
 		scaleX = v;
 		scaleY = v;
 	}
 
+	/**
+		Return the `n`th element among our immediate children list, or null if there is no.
+	**/
 	public inline function getChildAt( n ) {
 		return children[n];
 	}
 
-	public function getChildIndex( s ) {
+	/**
+		Return the index of the object `o` within our immediate children list, or `-1` if it is not part of our children list.
+	**/
+	public function getChildIndex( o ) {
 		for( i in 0...children.length )
-			if( children[i] == s )
+			if( children[i] == o )
 				return i;
 		return -1;
 	}
 
-	public function getSpriteByName( name : String ) {
+	/**
+		Search for an object recursively by name, return null if not found.
+	**/
+	public function getObjectByName( name : String ) {
 		if( this.name == name )
 			return this;
 		for( c in children ) {
-			var o = c.getSpriteByName(name);
+			var o = c.getObjectByName(name);
 			if( o != null ) return o;
 		}
 		return null;
@@ -760,6 +852,9 @@ class Object {
 		return children.length;
 	}
 
+	/**
+		Return an iterator over this object immediate children
+	**/
 	public inline function iterator() {
 		return new hxd.impl.ArrayIterator(children);
 	}

h3d/scene/Object.hx

@@ -30,23 +30,68 @@ class Object implements hxd.impl.Serializable {
 
 	@:s var flags : ObjectFlags;
 	var children : Array<Object>;
+
+	/**
+		The parent object in the scene tree.
+	**/
 	public var parent(default, null) : Object;
+
+	/**
+		How many immediate children this object has.
+	**/
 	public var numChildren(get, never) : Int;
 
+	/**
+		The name of the object, can be used to retrieve an object within a tree by using `getObjectByName` (default null)
+	**/
 	@:s public var name : Null<String>;
+
+	/**
+		The x position of the object relative to its parent.
+	**/
 	@:s public var x(default,set) : Float;
+
+	/**
+		The y position of the object relative to its parent.
+	**/
 	@:s public var y(default, set) : Float;
+
+	/**
+		The z position of the object relative to its parent.
+	**/
 	@:s public var z(default, set) : Float;
+
+	/**
+		The amount of scaling along the X axis of this object (default 1.0)
+	**/
 	@:s public var scaleX(default,set) : Float;
+
+	/**
+		The amount of scaling along the Y axis of this object (default 1.0)
+	**/
 	@:s public var scaleY(default, set) : Float;
+
+	/**
+		The amount of scaling along the Z axis of this object (default 1.0)
+	**/
 	@:s public var scaleZ(default,set) : Float;
+
+
+	/**
+		Is the object and its children are displayed on screen (default true).
+	**/
 	public var visible(get, set) : Bool;
+
 	var allocated(get,set) : Bool;
 
 	/**
 		Follow a given object or joint as if it was our parent. Ignore defaultTransform when set.
 	**/
 	@:s public var follow(default, set) : Object;
+
+	/**
+		When follow is set, only follow the position and ignore both scale and rotation.
+	**/
 	public var followPositionOnly(get, set) : Bool;
 
 	/**
@@ -56,12 +101,6 @@ class Object implements hxd.impl.Serializable {
 	public var defaultTransform(default, set) : h3d.Matrix;
 	@:s public var currentAnimation(default, null) : h3d.anim.Animation;
 
-	/**
-		When selecting the lights to apply to this object, we will use the camera target as reference
-		instead of the object absolute position. This is useful for very large objects so they can get good lighting.
-	**/
-	public var lightCameraCenter(get, set) : Bool;
-
 	/**
 		Inform that the object is not to be displayed and his animation doesn't have to be sync. Unlike visible, this doesn't apply to children unless inheritCulled is set to true.
 	**/
@@ -83,7 +122,7 @@ class Object implements hxd.impl.Serializable {
 	public var ignoreBounds(get, set) : Bool;
 
 	/**
-		When enabled, the object is ignore when using getCollider()
+		When enabled, the object is ignored when using getCollider()
 	**/
 	public var ignoreCollide(get, set) : Bool;
 
@@ -97,12 +136,21 @@ class Object implements hxd.impl.Serializable {
 	**/
 	public var ignoreParentTransform(get, set) : Bool;
 
+	/**
+		When selecting the lights to apply to this object, we will use the camera target as reference
+		instead of the object absolute position. This is useful for very large objects so they can get good lighting.
+	**/
+	public var lightCameraCenter(get, set) : Bool;
+
 	var absPos : h3d.Matrix;
 	var invPos : h3d.Matrix;
 	var qRot : h3d.Quat;
 	var posChanged(get,set) : Bool;
 	var lastFrame : Int;
 
+	/**
+		Create a new empty object, and adds it to the parent object if not null.
+	**/
 	public function new( ?parent : Object ) {
 		flags = new ObjectFlags();
 		absPos = new h3d.Matrix();
@@ -141,17 +189,23 @@ class Object implements hxd.impl.Serializable {
 	inline function set_allowSerialize(b) return !flags.set(FNoSerialize, !b);
 	inline function set_ignoreParentTransform(b) return flags.set(FIgnoreParentTransform, b);
 
+	/**
+		Create an animation instance bound to the object, set it as currentAnimation and play it.
+	**/
 	public function playAnimation( a : h3d.anim.Animation ) {
 		return currentAnimation = a.createInstance(this);
 	}
 
 	/**
-		Changes the current animation. This animation should be an instance that was created by playAnimation!
+		Change the current animation. This animation should be an instance that was previously created by playAnimation.
 	**/
 	public function switchToAnimation( a : h3d.anim.Animation ) {
 		return currentAnimation = a;
 	}
 
+	/**
+		Stop the current animation. If recursive is set to true, all children will also stop their animation
+	**/
 	public function stopAnimation( ?recursive = false ) {
 		currentAnimation = null;
 		if(recursive) {
@@ -184,6 +238,9 @@ class Object implements hxd.impl.Serializable {
 				c.applyAnimationTransform();
 	}
 
+	/**
+		Return the total number of children, recursively.
+	**/
 	public function getObjectsCount() {
 		var k = 0;
 		for( c in children )
@@ -191,6 +248,9 @@ class Object implements hxd.impl.Serializable {
 		return k;
 	}
 
+	/**
+		Search for a material recursively by name, return it or null if not found.
+	**/
 	public function getMaterialByName( name : String ) : h3d.mat.Material {
 		for( o in children ) {
 			var m = o.getMaterialByName(name);
@@ -199,6 +259,9 @@ class Object implements hxd.impl.Serializable {
 		return null;
 	}
 
+	/**
+		Find a single object in the tree by calling `f` on each and returning the first not-null value returned, or null if not found.
+	**/
 	public function find<T>( f : Object -> Null<T> ) : Null<T> {
 		var v = f(this);
 		if( v != null )
@@ -210,6 +273,9 @@ class Object implements hxd.impl.Serializable {
 		return null;
 	}
 
+	/**
+		Find several objects in the tree by calling `f` on each and returning all the not-null values returned.
+	**/
 	public function findAll<T>( f : Object -> Null<T>, ?arr : Array<T> ) : Array<T> {
 		if( arr == null ) arr = [];
 		var v = f(this);
@@ -220,6 +286,9 @@ class Object implements hxd.impl.Serializable {
 		return arr;
 	}
 
+	/**
+		Return all materials in the tree.
+	**/
 	public function getMaterials( ?a : Array<h3d.mat.Material> ) {
 		if( a == null ) a = [];
 		for( o in children )
@@ -228,7 +297,7 @@ class Object implements hxd.impl.Serializable {
 	}
 
 	/**
-		Transform a point from the local object coordinates to the global ones. The point is modified and returned.
+		Convert a local position (or [0,0] if pt is null) relative to the object origin into an absolute global position, applying all the inherited transforms.
 	**/
 	public function localToGlobal( ?pt : h3d.Vector ) {
 		syncPos();
@@ -238,7 +307,7 @@ class Object implements hxd.impl.Serializable {
 	}
 
 	/**
-		Transform a point from the global coordinates to the object local ones. The point is modified and returned.
+		Convert an absolute global position into a local position relative to the object origin, applying all the inherited transforms.
 	**/
 	public function globalToLocal( pt : h3d.Vector ) {
 		pt.transform3x4(getInvPos());
@@ -260,13 +329,17 @@ class Object implements hxd.impl.Serializable {
 	}
 
 	/**
-		Return the bounds of this object, in absolute position.
+		Return the bounds of this object and all its children, in absolute global coordinates.
 	**/
-	public function getBounds( ?b : h3d.col.Bounds, rec = false ) {
-		if( !rec )
-			syncPos();
+	@:final public function getBounds( ?b : h3d.col.Bounds ) {
 		if( b == null )
 			b = new h3d.col.Bounds();
+		if( parent != null )
+			parent.syncPos();
+		return getBoundsRec(b);
+	}
+
+	function getBoundsRec( b : h3d.col.Bounds ) {
 		if( posChanged ) {
 			for( c in children )
 				c.posChanged = true;
@@ -274,10 +347,13 @@ class Object implements hxd.impl.Serializable {
 			calcAbsPos();
 		}
 		for( c in children )
-			c.getBounds(b, true);
+			c.getBoundsRec(b);
 		return b;
 	}
 
+	/**
+		Return all meshes part of this tree
+	**/
 	public function getMeshes( ?out : Array<Mesh> ) {
 		if( out == null ) out = [];
 		var m = Std.instance(this, Mesh);
@@ -287,10 +363,16 @@ class Object implements hxd.impl.Serializable {
 		return out;
 	}
 
+	/**
+		Search for an mesh recursively by name, return null if not found.
+	**/
 	public function getMeshByName( name : String) {
 		return Std.instance(getObjectByName(name), Mesh);
 	}
 
+	/**
+		Search for an object recursively by name, return null if not found.
+	**/
 	public function getObjectByName( name : String ) {
 		if( this.name == name )
 			return this;
@@ -301,6 +383,9 @@ class Object implements hxd.impl.Serializable {
 		return null;
 	}
 
+	/**
+		Make a copy of the object and all its children.
+	**/
 	public function clone( ?o : Object ) : Object {
 		if( o == null ) o = new Object();
 		#if debug
@@ -327,10 +412,16 @@ class Object implements hxd.impl.Serializable {
 		return o;
 	}
 
+	/**
+		Add a child object at the end of the children list.
+	**/
 	public function addChild( o : Object ) {
 		addChildAt(o, children.length);
 	}
 
+	/**
+		Insert a child object at the specified position of the children list.
+	**/
 	public function addChildAt( o : Object, pos : Int ) {
 		if( pos < 0 ) pos = 0;
 		if( pos > children.length ) pos = children.length;
@@ -360,6 +451,9 @@ class Object implements hxd.impl.Serializable {
 		}
 	}
 
+	/**
+		Iterate on all mesh that are currently visible and not culled in the tree. Call `callb` for each mesh found.
+	**/
 	public function iterVisibleMeshes( callb : Mesh -> Void ) {
 		if( !visible || (culled && inheritCulled) )
 			return;
@@ -390,6 +484,9 @@ class Object implements hxd.impl.Serializable {
 			c.onRemove();
 	}
 
+	/**
+		Remove the given object from our immediate children list if it's part of it.
+	**/
 	public function removeChild( o : Object ) {
 		if( children.remove(o) ) {
 			if( o.allocated ) o.onRemove();
@@ -398,7 +495,26 @@ class Object implements hxd.impl.Serializable {
 		}
 	}
 
-	function getScene() {
+	/**
+		Remove all children from our immediate children list
+	**/
+	public function removeChildren() {
+		while( numChildren>0 )
+			removeChild( getChildAt(0) );
+	}
+
+	/**
+		Same as parent.removeChild(this), but does nothing if parent is null.
+		In order to capture add/removal from scene, you can override onAdd/onRemove/onParentChanged
+	**/
+	public inline function remove() {
+		if( this != null && parent != null ) parent.removeChild(this);
+	}
+
+	/**
+		Return the Scene this object is part of, or null if not added to a Scene.
+	**/
+	public function getScene() {
 		var p = this;
 		while( p.parent != null ) p = p.parent;
 		return Std.instance(p, Scene);
@@ -412,10 +528,16 @@ class Object implements hxd.impl.Serializable {
 		return absPos;
 	}
 
+	/**
+		Tell if the object is a Mesh.
+	**/
 	public inline function isMesh() {
 		return Std.instance(this, Mesh) != null;
 	}
 
+	/**
+		If the object is a Mesh, return the corresponding Mesh. If not, throw an exception.
+	**/
 	public function toMesh() : Mesh {
 		var m = Std.instance(this, Mesh);
 		if( m != null )
@@ -424,7 +546,7 @@ class Object implements hxd.impl.Serializable {
 	}
 
 	/**
-		Build and returns the global absolute recursive collider for the object.
+		Build and return the global absolute recursive collider for the object.
 		Returns null if no collider was found or if ignoreCollide was set to true.
 	**/
 	@:final public function getCollider() : h3d.col.Collider {
@@ -469,14 +591,6 @@ class Object implements hxd.impl.Serializable {
 		return null;
 	}
 
-	/**
-		Same as parent.removeChild(this), but does nothing if parent is null.
-		In order to capture add/removal from scene, you can override onAdd/onRemove/onParentChanged
-	**/
-	public inline function remove() {
-		if( this != null && parent != null ) parent.removeChild(this);
-	}
-
 	function draw( ctx : RenderContext ) {
 	}
 
@@ -633,6 +747,9 @@ class Object implements hxd.impl.Serializable {
 		return v;
 	}
 
+	/**
+		Set the position of the object relative to its parent.
+	**/
 	public inline function setPosition( x : Float, y : Float, z : Float ) {
 		this.x = x;
 		this.y = y;
@@ -640,6 +757,9 @@ class Object implements hxd.impl.Serializable {
 		posChanged = true;
 	}
 
+	/**
+		Set the position, scale and rotation of the object relative to its parent based on the specified transform matrix.
+	**/
 	public function setTransform( mat : h3d.Matrix ) {
 		var s = mat.getScale();
 		this.x = mat.tx;
@@ -653,9 +773,9 @@ class Object implements hxd.impl.Serializable {
 		posChanged = true;
 	}
 
-	/*
-		Rotate around the current rotation axis.
-	*/
+	/**
+		Rotate around the current rotation axis by the specified angles (in radian).
+	**/
 	public function rotate( rx : Float, ry : Float, rz : Float ) {
 		var qTmp = new h3d.Quat();
 		qTmp.initRotation(rx, ry, rz);
@@ -663,34 +783,57 @@ class Object implements hxd.impl.Serializable {
 		posChanged = true;
 	}
 
+	/**
+		Set the rotation using the specified angles (in radian).
+	**/
 	public function setRotation( rx : Float, ry : Float, rz : Float ) {
 		qRot.initRotation(rx, ry, rz);
 		posChanged = true;
 	}
 
+	/**
+		Set the rotation using the specified axis and angle of rotation around it (in radian).
+	**/
 	public function setRotationAxis( ax : Float, ay : Float, az : Float, angle : Float ) {
 		qRot.initRotateAxis(ax, ay, az, angle);
 		posChanged = true;
 	}
 
+	/**
+		Set the rotation using the specified look at direction
+	**/
 	public function setDirection( v : h3d.Vector ) {
 		qRot.initDirection(v);
 		posChanged = true;
 	}
 
+	/**
+		Return the direction in which the object rotation is currently oriented to
+	**/
 	public function getDirection() {
 		return qRot.getDirection();
 	}
 
+	/**
+		Return the quaternion representing the current object rotation.
+		Dot not modify as it's not a copy.
+	**/
 	public function getRotationQuat() {
 		return qRot;
 	}
 
+	/**
+		Set the quaternion representing the current object rotation.
+		Dot not modify the value afterwards as no copy is made.
+	**/
 	public function setRotationQuat(q) {
 		qRot = q;
 		posChanged = true;
 	}
 
+	/**
+		Scale uniformly the object by the given factor.
+	**/
 	public inline function scale( v : Float ) {
 		scaleX *= v;
 		scaleY *= v;
@@ -698,6 +841,9 @@ class Object implements hxd.impl.Serializable {
 		posChanged = true;
 	}
 
+	/**
+		Set the uniform scale for the object.
+	**/
 	public inline function setScale( v : Float ) {
 		scaleX = v;
 		scaleY = v;
@@ -705,22 +851,44 @@ class Object implements hxd.impl.Serializable {
 		posChanged = true;
 	}
 
+	/**
+		Return both class name and object name if any.
+	**/
 	public function toString() {
 		return Type.getClassName(Type.getClass(this)).split(".").pop() + (name == null ? "" : "(" + name + ")");
 	}
 
+	/**
+		Return the `n`th element among our immediate children list, or null if there is no.
+	**/
 	public inline function getChildAt( n ) {
 		return children[n];
 	}
 
+	/**
+		Return the index of the object `o` within our immediate children list, or `-1` if it is not part of our children list.
+	**/
+	public function getChildIndex( o ) {
+		for( i in 0...children.length )
+			if( children[i] == o )
+				return i;
+		return -1;
+	}
+
 	inline function get_numChildren() {
 		return children.length;
 	}
 
+	/**
+		Return an iterator over this object immediate children
+	**/
 	public inline function iterator() : hxd.impl.ArrayIterator<Object> {
 		return new hxd.impl.ArrayIterator(children);
 	}
 
+	/**
+		Free the GPU memory for this object and its children
+	**/
 	public function dispose() {
 		for( c in children )
 			c.dispose();