From: Chu Hoang Date: Thu, 12 Nov 2015 13:19:00 +0000 (+0000) Subject: Updated Programming guide. X-Git-Tag: dali_1.1.11~14 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=77abc294f7cc107aa575454735a0201b9f3a254a Updated Programming guide. Updated Control background with a section about renderers. Updated ImageActor section. Added ImageView section. Updated ShaderEffects section. Change-Id: Ib3df5abf69e789311d58b95a115caddc3b6ab63c --- diff --git a/docs/content/images/background/BackgroundBorder.png b/docs/content/images/background/BackgroundBorder.png new file mode 100644 index 0000000..e580281 Binary files /dev/null and b/docs/content/images/background/BackgroundBorder.png differ diff --git a/docs/content/main.md b/docs/content/main.md index 920c5db..380828a 100644 --- a/docs/content/main.md +++ b/docs/content/main.md @@ -30,6 +30,7 @@ + [Event Handling](@ref event-system) + [Layouting](@ref size-negotiation) + [Image Actor](@ref image-actor) + + [Image View](@ref image-view) + [Animation](@ref animation) + [Basic Framework](@ref animation-basics) + [Key Frame Animations](@ref animation-key-frame) diff --git a/docs/content/programming-guide/background.h b/docs/content/programming-guide/background.h index a8dc916..132fe19 100644 --- a/docs/content/programming-guide/background.h +++ b/docs/content/programming-guide/background.h @@ -57,5 +57,24 @@ then the above image will look like: +@section background-renderer Background Renderer + +The background can be set to use a specified renderer, e.g the border renderer +@code +Property::Map renderer; +renderer.Insert("rendererType","borderRenderer"); +renderer.Insert("borderColor",COLOR::RED); +renderer.Insert("borderSize",20.f); + +control.SetProperty( Control::Property::BACKGROUND, renderer); +@endcode + +then the above image will look like: + + +
+\image html BackgroundBorder.png +
+ * */ diff --git a/docs/content/programming-guide/image-actor.h b/docs/content/programming-guide/image-actor.h index 99a42cd..b528ef1 100644 --- a/docs/content/programming-guide/image-actor.h +++ b/docs/content/programming-guide/image-actor.h @@ -60,25 +60,9 @@ * section. * *

Style

- * The Actor can render an image in two different ways.
+ * The Actor can render an image in only as a quad. Use ImageView for nine-patch/n-patch image rendering.
* -# STYLE_QUAD: A simple flat quad style for rendering images.
- * -# STYLE_NINE_PATCH: This style gives the flexibility to stretch images by dividing it into 9 sections. - * The four corners are not scaled; the four edges are scaled in one axis, and the middle is scaled in both axes.
- * - * @code - * // default : ImageActor::STYLE_QUAD - * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH); - * @endcode - * - * - *

Border

- * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.
- * - * @code - * Dali::ImageActor::Border border(0.45,0.15,0.45,0.15); - * myImageActor.SetBorder(border); - * @endcode - * + * -# STYLE_NINE_PATCH: This is deprecated as of Dali 1.1.11. * *

Pixel area

* The area of the image to be displayed by the Image Actor can be set by setting the Pixel area. Pixel area is relative to the top-left (0,0) of the image. diff --git a/docs/content/programming-guide/image-view.h b/docs/content/programming-guide/image-view.h new file mode 100644 index 0000000..886a6ab --- /dev/null +++ b/docs/content/programming-guide/image-view.h @@ -0,0 +1,113 @@ +/*! \page image-view Image Views + * + * + *

Overview

+ * The Dali::Toolkit::ImageView inherits from Dali::Toolkit::Control and provide means to display resources like Images on the stage.
+ * + * - ImageView: An actor for displaying Images. It allows the developer to display a Dali::Image object or an image from a url path on the stage.
+ * + *

Image View

+ * + *

Construction

+ * The Image View is constructed by passing a Dali::Image object or by a url path.
+ * + *

Loading from a url path

+ * Image View will load a file from a given url path. Using a url path is the prefered way of displaying an image as the Dali engine can do optimsations to + * reuse shaders and perform automatic image atlassing.
+ * This can be a path to a image file: + * @code + * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.png" ); + * @endcode + * + * A path to a nine-patch/n-patch image file: + * @code + * Dali::Toolkit::ImageView myImageView = ImageView::New( "source-image-url.9.png" ); + * @endcode + * + *

Loading from a Image handle

+ * Dali::Image is an abstract base class with multiple derived classes. + * + * @code + * Dali::Image image = BufferImage::New( 100, 100 ); + * Dali::Toolkit::ImageView myImageView = Toolkit::ImageView::New( image ); + * @endcode + * + *

The IMAGE property

+ * the IMAGE property allows you to change many aspects of the image that is renderered. + * This property can either be a string for a image url path or a Property::Map that specifies + * the image in more detail. + * + *

Renderers

+ * You can specify a specific renderer instead of using the default Image Renderer, e.g to use the Border Renderer. + * + * @code + * Property::Map renderer; + * renderer.Insert("rendererType","borderRenderer"); + * renderer.Insert("borderColor",COLOR::RED); + * renderer.Insert("borderSize",20.f); + * + * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New(); + * myImageView.SetProperty( Control::Property::IMAGE, renderer); + * @endcode + + *

Resizing at Load Time

+ * An application loading images from an external source will often want to + * display those images at a lower resolution than their native ones. + * To support this, DALi can resize an image at load time so that its + * in-memory copy uses less space and its visual quality benefits from being + * prefiltered. + * There are four algorithms which can be used to fit an image to a desired + * rectangle, a desired width or a desired height + * (see Dali::FittingMode). + * + * Here is an example doing rescaling: + * + * @code + * Property::Map imageProperty; + * imageProperty.Insert("imageUrl", "source-image-url.png"); + * imageProperty.Insert("imageFittingMode", "scaleToFill"); + * imageProperty.Insert("fitWidth", 240); + * imageProperty.Insert("fitHeight", 240); + * Dali::Toolkit::ImageView myImageView = Dali::Toolkit::ImageView::New(); + * myImageView.SetProperty( Control::Property::IMAGE, imageProperty); + + * @endcode + * + * This example sets the size and fitting mode appropriately for a large thumbnail + * during Dali::ResourceImage construction. + * In general, to enable scaling on load, pass a non-zero width or height and + * one of the four fitting modes to the Dali::ResourceImage creator function + * as shown above. + * + * The fitting modes and a suggested use-case for each are as follows: + *
    + *
  1. "shrinkToFit" Full-screen image display: Limit loaded image resolution to device resolution but show all of image. + *
  2. "scaleToFill" Thumbnail gallery grid: Limit loaded image resolution to screen tile, filling whole tile but losing a few pixels to match the tile shape. + *
  3. "fitWidth" Image columns: Limit loaded image resolution to column. + *
  4. "fitHeight" Image rows: Limit loaded image resolution to row height. + *
+ * + * The dali-demo project contains a full example under + * examples/image-scaling-and-filtering + * and a specific sampling mode example under + * examples/image-scaling-irregular-grid. + * + * There are more details on this topic in the + * \link resourceimagescaling Rescaling Images \endlink + * section. + * + *

Style

+ * The Actor can render an image in only as a quad or as a nine-patch/n-patch image. This is done by using a nine-patch filename naming scheme of ending with + * a ".9" or a ".#". There is no special treatment if the file encodes a nine-patch image or n-patch image as long as it has either ".9" or ".#" the image will be correctly loaded.
+ * @code + * Dali::Toolkit::ImageView myImageView1 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.9.png"); + * Dali::Toolkit::ImageView myImageView2 = Dali::Toolkit::ImageView::New("source-to-nine-patch-image.#.png"); + * @endcode + * + *

Changing the image

+ * The Image View can be changed by calling Dali::Toolkit::ImageView::SetImage methods or by changing the IMAGE property. + * @code + * myImageActor.SetImage( newImage ); + * @endcode + * + */ diff --git a/docs/content/programming-guide/shader-intro.h b/docs/content/programming-guide/shader-intro.h index 75fef8f..54c8909 100644 --- a/docs/content/programming-guide/shader-intro.h +++ b/docs/content/programming-guide/shader-intro.h @@ -1,35 +1,86 @@ /*! \page shader-intro Shader Effects * - -

Introduction

- -The shader effects allow the developer to apply visual deformations on the actors. -They can affect the geometry, the colors and textures of the actor. - - -
-
-

Custom Shader Effects

-The \ref Dali::ShaderEffect "ShaderEffect" lets the developers create their own shader effects by specifying the vertex and pixel shaders. - -A custom shader effect can be created like this: -@code -String myVertexShader; // This variable would contain the code for a vertex shader. -Dali::ShaderEffect myEffect = Dali::ShaderEffect::New( myVertexShader, - "" // use default pixel shader - ); -@endcode - -The value of a uniform can be set like this: -@code -// if the uniform was declared like this in the shader: uniform float myUniform; -myEffect.SetUniform( "myUniform", 0.5f ); -@endcode - -The custom shader effect can be applied to an actor like any other shader: -@code -actor.SetShaderEffect( myEffect ); -@endcode - + * + *

Introduction

+ * + * The shader effects allow the developer to apply visual deformations on Image Views. + * They can affect the geometry, the colors and textures of the Image View. + * + *
+ *
+ *

Custom Shader Effects

+ * The custom shader lets the developers create their own shader effects by specifying the vertex and pixel shaders. + * + * To set a custom shader to ImageRenderer you have to pass it through as a Property::Map + * @code + * //an example vertex shader + * const char* VERTEX_SHADER = DALI_COMPOSE_SHADER( + * attribute mediump vec2 aPosition;\n + * varying mediump vec2 vTexCoord;\n + * uniform mediump mat4 uMvpMatrix;\n + * uniform mediump vec3 uSize;\n + * \n + * void main()\n + * {\n + * mediump vec4 vertexPosition = vec4(aPosition, 0.0, 1.0);\n + * vertexPosition.xyz *= uSize;\n + * vertexPosition = uMvpMatrix * vertexPosition;\n + * \n + * vTexCoord = aPosition + vec2(0.5);\n + * gl_Position = vertexPosition;\n + * }\n + * ); + * + * //an example fragment shader + * const char* FRAGMENT_SHADER = DALI_COMPOSE_SHADER( + * varying mediump vec2 vTexCoord;\n + * uniform sampler2D sTexture;\n + * uniform lowp vec4 uColor;\n + * \n + * void main()\n + * {\n + * gl_FragColor = texture2D( sTexture, vTexCoord ) * uColor;\n + * }\n + * ); + * + * Property::Map customShader; + * + * customShader.Insert(“vertex-shader”, VERTEX_SHADER); //if this is not set then the default ImageView vertex shader will be used + * customShader.Insert(“fragment-shader”, FRAGMENT_SHADER); //if this is not set then the default ImageView fragment shader will be used + * + * Property::Map map; + * map.Insert(“shader”, customShader); + * + * ImageView imageView = ImageView::New("image-url.png") + * imageView.SetProperty(ImageView::Property::IMAGE, map); + * @endcode + * + * Optionally, you can subdivide the grid horizontally or vertically before you add it to the map but you should not do this if a quad is used. + * @code + * int X_SUB_DIVISIONS = 20; + * int Y_SUB_DIVISIONS = 20; + * customShader.Insert(“subdivide-grid-x”, X_SUB_DIVISIONS); //optional number of times to subdivide the grid horizontally, don’t add if you just want to use a quad + * customShader.Insert(“subdivide-grid-y”, Y_SUB_DIVISIONS); //optional number of times to subdivide the grid vertically, don’t add if you just want to use a quad + * + * //shader hints can be an array or a string + * optional array of shader hints + * + * Property::Array shaderHints; + * shaderHints.PushBack(“requires-self-depth-test”); + * shaderHints.PushBack(“output-is-transparent”); + * shaderHints.PushBack(“output-is-opaque”); + * shaderHints.PushBack(“modifies-geometry”); + * customShader.Insert(“hints”, shaderHints); + * + * //or optional single shader hint as a string + * //customShader.Insert(“hints”, “output-is-transparent”); + * @endcode + * + * The value of a uniform can be set on the imageView + * @code + * // if the uniform was declared like this in the shader: uniform float myUniform; + * imageView.RegisterProperty( "myUniform", 0.5f ); + * @endcode + * * */