Updated Control background with a section about renderers.
Updated ImageActor section.
Added ImageView section.
Updated ShaderEffects section.
Change-Id: Ib3df5abf69e789311d58b95a115caddc3b6ab63c
+ [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)
</td>
</table>
+@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:
+<table border=0 cellpadding=10><tr>
+<td>
+\image html BackgroundBorder.png
+</td>
+</table>
+
*
*/
* section.
*
* <h2 class="pg">Style</h2>
- * The Actor can render an image in two different ways.<br>
+ * The Actor can render an image in only as a quad. Use ImageView for nine-patch/n-patch image rendering.<br>
* -# STYLE_QUAD: A simple flat quad style for rendering images.<br>
- * -# 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.<br>
- *
- * @code
- * // default : ImageActor::STYLE_QUAD
- * myImageActor.SetStyle (Dali::ImageActor::STYLE_NINE_PATCH);
- * @endcode
- *
- *
- * <h2 class="pg">Border</h2>
- * The border is used in the ImageActor::STYLE_NINE_PATCH. It defines the border values of the image for stretching.<br>
- *
- * @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.
*
* <h2 class="pg">Pixel area</h2>
* 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.
--- /dev/null
+/*! \page image-view Image Views
+ *
+ *
+ * <h1 class="pg">Overview</h1>
+ * The Dali::Toolkit::ImageView inherits from Dali::Toolkit::Control and provide means to display resources like Images on the stage.<br>
+ *
+ * - <b>ImageView:</b> 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.<br>
+ *
+ * <h1 class="pg">Image View</h1>
+ *
+ * <h2 class="pg">Construction</h2>
+ * The Image View is constructed by passing a Dali::Image object or by a url path.<br>
+ *
+ * <h3 class="pg">Loading from a url path</h3>
+ * 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.<br>
+ * 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
+ *
+ * <h3 class="pg">Loading from a Image handle</h3>
+ * 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
+ *
+ * <h3 class="pg">The IMAGE property</h3>
+ * 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.
+ *
+ * <h3 class="pg">Renderers</h3>
+ * 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
+
+ * <h3 class="pg">Resizing at Load Time</h3>
+ * 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:
+ * <ol>
+ * <li> "shrinkToFit" Full-screen image display: Limit loaded image resolution to device resolution but show all of image.
+ * <li> "scaleToFill" Thumbnail gallery grid: Limit loaded image resolution to screen tile, filling whole tile but losing a few pixels to match the tile shape.
+ * <li> "fitWidth" Image columns: Limit loaded image resolution to column.
+ * <li> "fitHeight" Image rows: Limit loaded image resolution to row height.
+ * </ol>
+ *
+ * The dali-demo project contains a full example under
+ * <code>examples/image-scaling-and-filtering</code>
+ * and a specific sampling mode example under
+ * <code>examples/image-scaling-irregular-grid</code>.
+ *
+ * There are more details on this topic in the
+ * \link resourceimagescaling Rescaling Images \endlink
+ * section.
+ *
+ * <h2 class="pg">Style</h2>
+ * 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.<br>
+ * @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
+ *
+ * <h2 class="pg">Changing the image</h2>
+ * The Image View can be changed by calling Dali::Toolkit::ImageView::SetImage methods or by changing the IMAGE property.
+ * @code
+ * myImageActor.SetImage( newImage );
+ * @endcode
+ *
+ */
/*! \page shader-intro Shader Effects
*
-
-<h2 class="pg">Introduction</h2>
-
-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.
-
-
-<br>
-<br>
-<h2 class="pg">Custom Shader Effects</h2>
-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
-
+ *
+ * <h2 class="pg">Introduction</h2>
+ *
+ * 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.
+ *
+ * <br>
+ * <br>
+ * <h2 class="pg">Custom Shader Effects</h2>
+ * 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
+ *
*
*/
projects / platform / core / uifw / dali-toolkit.git / commitdiff
