From: Adeel Kazmi <adeel.kazmi@samsung.com>
Date: Tue, 2 Jun 2015 15:38:20 +0000 (+0100)
Subject: (Programmin Guide) Images
X-Git-Tag: dali_1.0.43~5
X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=6e3cc5416aae71df67186e7f8b9f6ae580238e84;hp=e5d428fa360321eaf40a95e80cff3de48d59ccff

(Programmin Guide) Images

Change-Id: I642e0a6d3eb1563d0d7a001df76dbfd5f3b6f3ea
---

diff --git a/docs/content/images/resource/9-patch-full.png b/docs/content/images/resource/9-patch-full.png
new file mode 100644
index 0000000..3895bc8
Binary files /dev/null and b/docs/content/images/resource/9-patch-full.png differ
diff --git a/docs/content/images/resource/9-patch-zoomed.png b/docs/content/images/resource/9-patch-zoomed.png
new file mode 100644
index 0000000..2196d66
Binary files /dev/null and b/docs/content/images/resource/9-patch-zoomed.png differ
diff --git a/docs/content/images/resource/9-patch.png b/docs/content/images/resource/9-patch.png
new file mode 100644
index 0000000..7a20d38
Binary files /dev/null and b/docs/content/images/resource/9-patch.png differ
diff --git a/docs/content/main.md b/docs/content/main.md
index 29aea03..27937d2 100644
--- a/docs/content/main.md
+++ b/docs/content/main.md
@@ -41,9 +41,9 @@
   + [Shader Animation](@ref animation-shader)
 
 ### Resources
- + Resource Image
- + 9 Patch Image
- + Buffer Image
+ + [Resource Image](@ref resource-image)
+ + [9 Patch Image](@ref resource-9-patch)
+ + [Buffer Image](@ref resource-buffer)
 
 ### Control Base Class
  + [Background Feature](@ref background)
diff --git a/docs/content/programming-guide/constraints.h b/docs/content/programming-guide/constraints.h
index 183e0d7..7780cc2 100644
--- a/docs/content/programming-guide/constraints.h
+++ b/docs/content/programming-guide/constraints.h
@@ -1,7 +1,7 @@
 /*! \page constraints Constraints
  *
 
-<h2 class="pg">Introduction</h2>
+<h1 class="pg">Introduction</h1>
 
 Constraints are used to modify the property of an actor, based on other properties of the same actor; properties of the actor's parent; or properties of another actor altogether, when the modification needs to be at run-time.
 Custom functions or functors can be supplied, where the desired value of the property can be calculated.
@@ -15,7 +15,7 @@ This means that Constraints override the values set by Animations.
 
 Not all properties can be used as a constraint input, please see Dali::Handle::IsPropertyAConstraintInput() for more details.
 
-<h2 class="pg">When to use a Constraint</h2>
+<h1 class="pg">When to use a Constraint</h1>
 
 Constraints are designed as a way of modifying properties that cannot be modified by any existing built in functionality; Like Animations, Size negotiation or Parent anchor, origin settings.
 As they provide the ability for the application developer to execute their own code within the update thread, DALi can no-longer guarantee the timeliness of this code, or how optimised it may be.
@@ -60,13 +60,13 @@ Consider the following use cases as an example of when and when not to use a con
 
 For most general cases, the position and size requirements of a child or parent actor (from it's child or parent) can be calculated with Size Negotiation.
 
-<h2 class="pg">Constraint Sources</h2>
+<h1 class="pg">Constraint Sources</h1>
 
 These are properties of this (or another actor) that are used as inputs into the constraint.
 The constraint will take these values, optionally perform a calculation on them (if using a custom functor) and write the result to the specified property of the target actor.
 The source actor is specified as either the same actor, it's parent or another actor.
 
-<h3 class="pg">Local Source</h3>
+<h2 class="pg">Local Source</h2>
 
 A local source is based on the local properties (i.e. size, position, scale, orientation, color) of an actor.
 For example, the actor's orientation could be used as a constraint input source.
@@ -75,7 +75,7 @@ For example, the actor's orientation could be used as a constraint input source.
 Dali::ConstraintSource source( Dali::LocalSource( Dali::Actor::Property::ORIENTATION ) );
 @endcode
 
-<h3 class="pg">Parent Source</h3>
+<h2 class="pg">Parent Source</h2>
 
 A parent source is based on properties of the actor's parent.
 For example, a parent's position can be used as a constraint input source.
@@ -84,7 +84,7 @@ For example, a parent's position can be used as a constraint input source.
 Dali::ConstraintSource source( Dali::ParentSource( Dali::Actor::Property::POSITION ) );
 @endcode
 
-<h3 class="pg">Source</h3>
+<h2 class="pg">Source</h2>
 
 Finally, you can base your source on the properties of another handle altogether.
 For example, a sibling actor's color could be used as a constraint input source.
@@ -93,7 +93,7 @@ For example, a sibling actor's color could be used as a constraint input source.
 Dali::ConstraintSource source( Dali::Source( anotherHandle, Dali::Actor::Property::COLOR ) );
 @endcode
 
-<h2 class="pg">The Constraint Function</h2>
+<h1 class="pg">The Constraint Function</h1>
 
 The signature of the constraint function is:
 
@@ -124,9 +124,9 @@ const Dali::Vector3& parentPosition( inputs[2]->GetVector3() );
 const Dali::Vector3& parentSize( inputs[3]->GetVector3() );
 @endcode
 
-<h2 class="pg">Creating a Constraint</h2>
+<h1 class="pg">Creating a Constraint</h1>
 
-<h3 class="pg">Using C Functions</h3>
+<h2 class="pg">Using C Functions</h2>
 
 If you do not have any data that is changed at runtime, then C functions should be used.
 For example, the color of an actor could be changed based on its position along the x-axis till a preset distance of 100, beyond which it is transparent.
@@ -163,7 +163,7 @@ void MyConstraintFunction( Dali::Vector4& current, const Dali::PropertyInputCont
 
 Please have a look at Dali::Constraint::New() for more details.
 
-<h3 class="pg">Using Functors</h3>
+<h2 class="pg">Using Functors</h2>
 
 If you need to store some data in a struct/class, then a functor can be used.
 Reusing the last example, the color of an actor is changed based on its position along the x-axis, but the distance when it is transparent is different for each applied constraint.
@@ -216,9 +216,9 @@ MyFunctor could then be used with another constraint with a different distance.
 Please have a look at Dali::Constraint::New(Handle, Property::Index, const T&) for more details.
 
 Instead of using the default functor, another method can be declared in the class or struct and used as the constraint function.
-Please have a look at appropriate Dali::Constraint::New() method for more details.
+Please have a look at the appropriate Dali::Constraint::New() method for more details.
 
-<h2 class="pg">Removing Constraints</h2>
+<h1 class="pg">Removing Constraints</h1>
 
 The actor's constraints can later be removed in several ways:
 
diff --git a/docs/content/shared-javascript-and-cpp-documentation/resources.md b/docs/content/shared-javascript-and-cpp-documentation/resources.md
new file mode 100644
index 0000000..50ca99b
--- /dev/null
+++ b/docs/content/shared-javascript-and-cpp-documentation/resources.md
@@ -0,0 +1,62 @@
+<!--
+/**-->
+# Resources {#resoources}
+
+## Resource Image {#resource-image}
+
+A resource image is an image that is loaded using a file path or a URL.
+
+To create a resource image:
+~~~{.cpp}
+Dali::ResourceImage image = Dali::ResourceImage::New( "/my-path/my-image.png" );
+~~~
+Which can then be used with actors (e.g. ImageActor).
+
+Resources are loaded in separate threads.
+The application can connect to the Dali::ResourceImage::LoadingFinishedSignal() to get notified when the image has loaded.
+
+By default, resource images start loading immediately and the data is released only when the ResourceImage handle is destroyed.
+To optimise an application's memory footprint, the application can ask resources to be only loaded when actually required and
+their data to be released automatically when they are no longer being used (not being used by Actors).
+~~~{.cpp}
+Dali::ResourceImage image = Dali::ResourceImage::New( "/my-path/my-image.png", Dali::ResourceImage::ON_DEMAND, Dali::Image::UNUSED );
+~~~
+If Dali::Image::UNUSED is used, then when the ResourceImage is used again, the resource data is reloaded automatically.
+
+If the application requires the image dimensions immediately, then they can be retrieved synchronously:
+~~~{.cpp}
+Dali::ImageDimensions dimensions = Dali::ResourceImage::GetImageSize( "/my-path/my-image.png" );
+~~~
+This is a disk read which can be slow and will block the event thread, so should only be used if absolutely necessary.
+
+## 9-Patch Image {#resource-9-patch}
+
+DALi has support for 9-patch images.
+These are stretchable, repeatable images which are reduced to their smallest size.
+Essentially, an image is sliced up into 9 squares and the four corners do not change size at all.
+The other 5 segments are stretched (or repeated) to allow the whole image to scale appropriately.
+
+DALi has inbuilt support for *.9.png, *.9.jpg etc. images as well.
+More information about these images can be found here: http://developer.android.com/tools/help/draw9patch.html
+
+The following is an example of a *.9.png image:
+![ ](resource/9-patch.png)
+
+Zoomed in, the red section shows the part that will be repeated.
+The four corners areas remain static.
+The one pixel border will also be stripped out.
+![ ](resource/9-patch-zoomed.png)
+
+And if the image is given a 200 by 200 size, it will look like the following:
+![ ](resource/9-patch-full.png)
+
+## Buffer Image {#resource-buffer}
+
+A BufferImage represents an image resource in the form of a pixel buffer data that can be provided by the application developer.
+The application can then write to this buffer as required and the image is updated on the screen.
+
+~~~{.cpp}
+Dali::BufferImage image = Dali::BufferImage::New( 200, 200 ); // Creates a 200 by 200 pixel buffer with a color-depth of 32-bits (with alpha)
+~~~
+
+*/