--- a/Symbian3/PDK/Source/GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,323 +1,323 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"Eclipse Public License v1.0" which accompanies this distribution,
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
- Nokia Corporation - initial contribution.
-Contributors:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF" xml:lang="en"><title>Adding
-Effects And Filters Guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>This document gives you more information about the image effects and filters. </p>
-<section><title>Purpose</title> <p>The purpose of this guide is to show you
-how to implement different image effects and filters using Image Processor. </p> <p><b>Introduction</b> </p> <p>Adding effects to an image with Image Processor
-is very simple. </p> <p>Effects are applied in the order they are inserted
-in a image. <b>Note:</b> The result from rendering an image can be different
-depending on the order the effects are applied to an image. </p> <p>The code
-example below shows an implementation in the order: crop, mirror, and 90 degree
-rotation. </p> <codeblock id="GUID-041412C5-BD03-56C2-A5A8-162C5058A243" xml:space="preserve">
-
-// Get TInputInfo interface
-TInputInfo* inputInfo = imageProcessor->InputInfoL();
-// Get the input image size
-TSize inputSize = inputInfo->SizeL();
-
-// Define crop region
-TRect cropRegion(inputSize.iWidth / 4, inputSize.iHeight / 4, inputSize.iWidth / 2, inputSize.iHeight /2);
-
-// Apply crop
-imageProcessor->SetInputRectL(cropRegion);
-
-// Get TEffect interface for Mirror Left To Right effect.
-// Note. All effects can be handled via generic TEffect interface. For more advanced functionality
-// the interface pointer must be cast to a derived effect interfece.
-TEffect* effect = imageProcessor->EffectL(KEffectMirrorLeftToRightUid);
-
-// Standard sequence of function calls to apply any effect.
-// The effect must be started with BeginL() and finished with EndL() functions calls.
-effect->BeginL();
-effect->EndL();
-
-// As non-standard effect geometrical operation can be used via derived interface only.
-TGeometricalOperation* operation = static_cast<TGeometricalOperation*>(imageProcessor->EffectL(KGeometricalOperationUid));
-operation->BeginL();
-operation->SetOperationL(ImageProcessor::CImgProcessor::EOperationRotate270);
-operation->EndL();
-
-</codeblock> </section>
-<section><title>Undo</title> <p>Image Processor has a built-in undo mechanism,
-which removes the last added effect or operation on the undo stack. Parameter
-changes are not added to the undo stack. There is an unlimited number of undo
-steps and you can check if an undo operation is possible. </p> <p>The code
-example below shows the implementation the <codeph>ImageProcessor::CImageProcessor::UndoL()</codeph> function: </p> <codeblock id="GUID-80FD0739-851C-57F8-AEF0-4BB6B8634355" xml:space="preserve">
-
-TEffectRotation* rotationEffect = static_cast<TEffectRotation*>(imageProcessor->EffectL(KEffectRotationUid));
-rotationEffect->BeginL();
-rotationEffect->SetRotationL(ImageProcessor::TEffectRotation::ERotationScaleModeFitInside, 45.0f);
-rotationEffect->EndL();
-
-// Check if we can undo last applied effect
-if (imageProcessor->CanUndoL())
-{
- // Undo the effect
- imageProcessor->UndoL();
-}
-
-</codeblock> </section>
-<section><title>Adjustable generic effects </title> <p>Those imaging effects
-that have variable strengths or settings to choose from are called adjustable
-generic effects. These effects each have three related functions: </p> <ul>
-<li id="GUID-51F7D507-5788-5120-AC0B-9E599FEE66A2"><p>The <xref href="GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB.dita#GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB/GUID-406C6996-EEA8-3404-B0EF-3FC2EDC021D2"><apiname>ImageProcessor::TEffect::BeginL()</apiname></xref> function
-is used to initiate the adjustable generic effect. </p> <p>Any function calls
-from Image Processor operations are disabled until the <codeph>EndL()</codeph> function
-is called. For example when you try to apply another effect, this cause a
-leave <codeph>KErrNotReady</codeph>. </p> <p>For example, if you want to invoke
-an <codeph>UndoL()</codeph> call, Image Processor operations are blocked between <codeph>BeginL()</codeph> and
-thecorresponding <codeph>EndL()</codeph> call. An UndoL() call can be invoked
-after an <codeph>EndL()</codeph> call. This will cancel the effects applied
-between the last <codeph>BeginL()</codeph> and <codeph>EndL()</codeph> calls. </p> </li>
-<li id="GUID-A194B271-CE29-54F1-BFD6-134CE9CC8923"><p>The <xref href="GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB.dita#GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB/GUID-1588C652-4105-366D-82EF-74EB582D2339"><apiname>ImageProcessor::TEffect::SetLevelL()</apiname></xref> function
-is used to set the parameters of the current adjustable effect. </p> <p>For
-example, when you want to change the parameters of the effect, you must call
-the <codeph>ImageProcessor::TEffect::SetLevelL()</codeph> function to set
-the parameters of the current adjustable effect. </p> </li>
-<li id="GUID-AB2A6C70-8AAA-5916-BEE2-682EBC260E49"><p>The <xref href="GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB.dita#GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB/GUID-C0A7EEA7-A5B3-3441-8148-29B2B306CB81"><apiname>ImageProcessor::TEffect::EndL()</apiname></xref> function
-is used to end the current adjustable effect. </p> <p>For example, when you
-are satisfied with the result of the effect, you must call <codeph>ImageProcessor::TEffect::EndL()</codeph> to
-complete the current adjustable effect. </p> <p> <b>Note:</b> If you are not
-satisfied with the result of the effect, you must call the <codeph>EndL()</codeph> function
-of the current generic effect followed by a call to the <codeph>UndoL()</codeph> function. </p> </li>
-</ul> <p>The code example below shows how to use an adjustable begin-end effect: </p> <codeblock id="GUID-7B09C5D7-D48D-550E-8116-5CB6811BF1A6" xml:space="preserve">
-
-// Get sharpness effect
-TEffect* effect=imageProcessor->EffectL(KEffectSharpnessUid);
-
-// Apply default level of Sharpness
-effect->BeginL();
-effect->EndL();
-
-</codeblock> </section>
-<section><title>Working with preview </title> <p>Most mobile imaging applications
-render full-resolution images twice: </p> <ol id="GUID-61808DC4-7C6F-5371-BFD2-AB7275EF9717">
-<li id="GUID-F11B0934-3D84-5F3A-88C7-C38A25CDA2F4"><p>for a preview on the
-screen </p> </li>
-<li id="GUID-23DA4BE1-B256-5B39-BE6C-E97232EF8BA0"><p>for the rendering of
-the output image. </p> </li>
-</ol> <p>To make the render operation into a simple function, you must call
-the <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495"><apiname>ImageProcessor::TPreview</apiname></xref> function. </p> <p>The <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495"><apiname>ImageProcessor::TPreview</apiname></xref> function
-is an interface that describes the preview identified by the preview ID. The
-interface is initialized by specifying an output Symbian bitmap or pixel buffer
-(image frame) by calling <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-38670F92-962C-31D5-9642-9F3F9BE42B30"><apiname>ImageProcessor::TPreview::SetOutput()</apiname></xref>. </p> <p>You
-can use the preview for the zoom and pan effects: </p> <codeblock id="GUID-862C5EB5-4E2C-51E2-AF8E-65F6C5785B3B" xml:space="preserve">
-
-void TPreview::SetZoomL(TReal32 aZoom);
-void TPreview::SetPanL(TReal32 aPanX, TReal32 aPanY);
-TReal32 TPreview::ZoomL() const;
-void TPreview::PanL(TReal32& aPanX, TReal32& aPanY) const;
-
-</codeblock> <p>The <codeph>TReal32</codeph> of pan effect ranges from -1.0
-to 1.0 and the <codeph>TReal32</codeph> of zoom effect ranges from 1.0x to <codeph>TReal32</codeph> maximum
-value. </p> <p> <b>Note:</b> The zoom and pan effects only affect the preview.
-When rendering the original image, these changes are ignored. </p> </section>
-<section><title>Changing the input </title> <p>The source image can be changed
-by calling the <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-0448A658-7DD6-3767-82FC-1EE64B1CBEE3"><apiname>ImageProcessor::CImgProcessor::SetInputL()</apiname></xref> function
-without creating a new Image Processor instance. <codeph>ImageProcessor::CImgProcessor::SetInputL()</codeph> can
-be used when displaying thumbnails or when choosing between different overlay
-graphics. The image source can freely be switched between file, buffer, bitmap
-and a background colour. </p> <p>The code example below illustrates the chain
-of effects applied to a number of images and rendered to screen. </p> <codeblock id="GUID-2D54E9BB-20FE-5F02-A00E-71AAD089FBF0" xml:space="preserve">
-
- // Get white balance effect
- effect = imageProcessor->EffectL(KEffectWhiteBalanceUid);
-
- // Apply default white balance
- effect->BeginL();
- effect->EndL();
-
- // Go through the images and render the preview for each of them
- for (TInt i = 0; i < 4; i++)
- {
- imageProcessor->SetInputL(*filenames[i]);
- preview->RenderL();
- }
-
-</codeblock> </section>
-<section><title>Image information </title> <p>Image Processor has functionality
-to get information about the source image. This information can be used for
-display in a file browser or to verify the correct capabilities that are available
-for a specific processing task. </p> <p>First, a pointer to <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-E1B6400E-1A36-368A-AAC7-CDDE3ED656A2"><apiname>ImageProcessor::TInputInfo()</apiname></xref> interface
-must be obtained from the active Image Processor instance. To extract the
-information, the following functions are called: </p> <codeblock id="GUID-C940E27B-4FCE-5C9A-B39A-4C04C9BD6591" xml:space="preserve">
-
-TSize TInputInfo::SizeL() const;
-void TInputInfo::FormatL(TUid& aFormat, TUid& aSubFormat) const;
-TDisplayMode TInputInfo::DisplayModeL() const;
-TUid TInputInfo::ImageFrameFormatL() const;
-TUid TInputInfo::SamplingL() const;
-TUint32 TInputInfo::BitsPerPixelL() const;
-TBool TInputInfo::IsProgressiveL() const;
-TBool TInputInfo::IsInterlacedL() const;
-TBool TInputInfo::HasAlphaL() const;
-
-</codeblock> </section>
-<section><title>Coordinates and areas </title> <p>Image Processor uses a number
-of different coordinate systems to cope with the translation from the preview
-image to the input image. </p> <p>In this section the following concepts are
-introduced: </p> <ul>
-<li id="GUID-B9B0ED22-9EAC-50B3-9987-6BDE1C2D5513"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-4CB4BD23-85CD-5239-96C4-936BC46EE745"> Input images</xref> </p> </li>
-<li id="GUID-4E83AAF6-9820-5D28-9B7B-38E8F4F709DD"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-F956698F-28B3-5CFB-9ABC-E4C69688B284"> Geometry and orientation effects</xref> </p> </li>
-<li id="GUID-07F10586-079D-58BA-9B6D-B9A00372BAF2"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-43A6D850-367B-5A57-8CAA-03113298ED07"> Previews</xref> </p> </li>
-<li id="GUID-367CA050-A363-5D93-B99E-711B180EAA7C"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-BB35B339-CFB6-54CB-9D20-308EEB82225F">Preview canvases</xref> </p> </li>
-<li id="GUID-F59E4119-8111-51BF-98EA-799E52DC870E"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-1187E33F-1EA4-57A0-BC12-1810A48CF61B">Zoom and pan settings</xref> </p> </li>
-<li id="GUID-C14A7AFA-6F20-5313-99CA-7887D5A3895F"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-7DA27E76-C144-5784-9748-2839766B9A52">Overlay images</xref> </p> </li>
-</ul> <p id="GUID-4CB4BD23-85CD-5239-96C4-936BC46EE745"><b>Input images</b> </p> <p>A
-coordinate system is the region within which a given set of coordinates are
-relevant. In many scenarios, you will need to provide coordinate information
-to Image Processor. This information is ambiguous without additional handling
-to make the coordinates apply to a specific coordinate system. </p> <p>An
-area defines the dimensions of a region. Image data can change form and scale
-during the editing session, which means that a set of areas with different
-dimensions can exist throughout the chain of operations. </p> <p>All imaging
-sessions use a source image as a base. The source image represents the source
-coordinate system and the source area. The source coordinate system is not
-public since it has no relevance to the user. The source coordinate system
-starts at the top left corner of the source image and expands downwards along
-the y-axis and to the right along the x-axis. The source area size is public,
-however, and can be queried through the <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-1D0573C2-611F-3527-9C0B-8E668A208133"><apiname>ImageProcessor::CImgProcessor::CurrentSizeL() </apiname></xref> function. </p> <p id="GUID-F956698F-28B3-5CFB-9ABC-E4C69688B284"><b>Geometry and orientation
-effects</b> </p> <p>Applying geometry effects and orientation effects to an
-input image is usually a chain process. When all effects have been applied,
-the resulting image may differ in geometry from the original source image.
-Hence, the resulting image defines a new area called the current area and
-a new coordinate system called the current coordinate system. Both of these
-are public and can be queried through the Image Processor. The current coordinate
-system starts at the top left corner of the image and expands downwards along
-the y-axis and to the right along the x-axis. </p> <p id="GUID-43A6D850-367B-5A57-8CAA-03113298ED07"><b>Previews</b> </p> <p>You
-can make use of one or more previews when processing an image. A preview defines
-the region on which the image is shown. A preview introduces the preview area
-and the preview coordinate system, both of which are public. The preview coordinate
-system starts at the top left corner of the screen and expands downwards along
-y-axis and to the right along x-axis. </p> <p>Use <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-AF30A4A2-736E-3256-8C14-31368F0A24E3"><apiname>ImageProcessor::TPreview::PreviewToCurrentCoordL()</apiname></xref> to
-perform coordinate conversion and <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-CB6994A3-4355-3D67-85BB-8690F37EE0DD"><apiname>ImageProcessor::TPreview::SizeL()</apiname></xref> to
-get the size of the preview area. </p> <p>To convert between preview coordinates
-and current coordinates use the <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-C38A0CD8-061F-383F-9C0F-06E153FAD477"><apiname>ImageProcessor::TPreview::PreviewToCurrentCoordL(const
- TPoint&)</apiname></xref> function. To convert between canvas coordinates
-to current coordinates use the <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-481BCBAC-20B9-3134-A20B-EEEFE92C1C22"><apiname>ImageProcessor::TPreview::CanvasToCurrentCoordL()</apiname></xref> function. </p> <p>It
-can be useful to know the current size of the session image, that is, the
-size of the image after any effects and cropping have been applied, by using
-the <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-1D0573C2-611F-3527-9C0B-8E668A208133"><apiname>ImageProcessor::CImgProcessor::CurrentSizeL()</apiname></xref> function. </p> <p id="GUID-BB35B339-CFB6-54CB-9D20-308EEB82225F"><b>Preview canvases</b> </p> <p>Each
-preview contains a sub-region called the canvas. When the resulting image
-is scaled to fit the preview area, while preserving aspect ratio, the actual
-image data will not cover the entire screen and the areas outside the image
-are filled with a background colour. The area containing the image data is
-always referred to as the canvas. A canvas introduces the canvas area and
-the canvas coordinate system, both of which are public. The canvas coordinate
-system starts at the top left corner of the canvas and expands downwards along
-the y-axis and to the right along the x-axis. </p> <p>Use the <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-481BCBAC-20B9-3134-A20B-EEEFE92C1C22"><apiname>ImageProcessor::TPreview::CanvasToCurrentCoordL()</apiname></xref> to
-perform coordinate conversion and<xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-A69588CB-8BF2-3FA9-806A-216CA460E912"><apiname>ImageProcessor::TPreview::CanvasAreaL()</apiname></xref> function
-to return the size and location of the canvas area. </p> <p id="GUID-1187E33F-1EA4-57A0-BC12-1810A48CF61B"><b> Zoom and Pan settings</b> </p> <p>Zoom
-and Pan settings do not introduce their own areas or coordinate systems. In
-this regard, Zoom and pan are equivalent to a preview. </p> <p id="GUID-7DA27E76-C144-5784-9748-2839766B9A52"><b>Overlay images</b> </p> <p>Overlay
-images define their own overlay coordinate system and overlay area. The coordinate
-system of an overlay image is public. The overlay coordinate system and overlay
-are rarely used since they are not treated as separate objects once they are
-applied to the source image. The overlay is treated as part of the original
-image data after insertion. </p> <p>However, the coordinate system of an overlay
-image is relevant for defining its anchor point to the source image. The overlay
-area can be queried from Image Processor instances that expose overlay operations.
-The overlay coordinate system starts at the centre of the overlay image and
-expands to the left along the negative side of the y-axis, upwards along the
-negative side of the x-axis, to the right along the x-axis and downwards along
-the y-axis. </p> </section>
-<section><title>Applying overlay and border effects</title> <p>It is possible
-to add borders (frames) and overlays to your input image. For example, you
-might want to add a logo to an image or add a pair of sunglasses to a picture.
-To use a border effect, call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-EF0B943B-C58D-39AD-AAA3-ABEE11033A8C"><apiname>ImageProcessor::CImgProcessor::EffectL(KEffectBorderUid)</apiname></xref>. </p> <p>Border
-images are images with alpha channels. The border is automatically stretched
-to fit the input image. </p> <p>To use overlay effect, call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-08855134-3A4C-3BE5-B817-73342FFD5CCE"><apiname>ImageProcessor::CImgProcessor::OverlayL()</apiname></xref>. </p> <p>There
-are two ways to insert an overlay to an image, either from a file or from
-memory. If you load the overlay from a file, both PNG and JPEG are accepted,
-but you will only have the transparency option if you use a PNG image. The
-overlay is managed through the interface <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-95D515E0-F751-3703-8FD1-80F9B8870E16"><apiname>ImageProcessor::TOverlay</apiname></xref>. </p> <p>You
-can specify the position, the scale, and the angle of the overlay. The position
-must be given in current coordinates. The scale ranges from 0.0 to infinity,
-where 1.0 represent no scaling. The angle ranges from 0.0 degrees to 360.0
-degrees. To begin inserting the overlay the <xref href="GUID-95D515E0-F751-3703-8FD1-80F9B8870E16.dita#GUID-95D515E0-F751-3703-8FD1-80F9B8870E16/GUID-E1255D4A-714D-31A8-9E5E-CCBFF477E2F4"><apiname>ImageProcessor::TOverlay::BeginL()</apiname></xref> function
-must be called. The code example below illustrates the scale effect and the
-angle of the overlay effect. </p> <p>When the overlay is in place you must
-call <xref href="GUID-95D515E0-F751-3703-8FD1-80F9B8870E16.dita#GUID-95D515E0-F751-3703-8FD1-80F9B8870E16/GUID-B3250D2E-CBCB-357C-82CA-7A7B35045CAE"><apiname>ImageProcessor::TOverlay::EndL()</apiname></xref> to conclude the overlay. </p> <p>The
-code examples below describe some common scenarios: </p> <ul>
-<li id="GUID-A2AA2186-067D-571C-AC58-14E97050ED49"><p>You want to insert an
-overlay image in the centre of the image you see on the screen. The scale
-is set to 1.0 and the angle is set to 0 degrees. It is crucial to distinguish
-between canvas coordinates and current coordinates. </p> </li>
-<li id="GUID-24318F41-42F7-5297-B022-6914FB78B381"><p>After the overlay is
-started you want to double its size, rotate it 45 degrees clockwise, and move
-it down ten screen pixels. </p> </li>
-</ul> <codeblock id="GUID-A558142D-8C96-5DB8-B2AF-277C645BE47D" xml:space="preserve">
-
- TPoint overlayPosition(0,0);
-
- // Get preview canvas rectangle
- TRect canvasArea = preview->CanvasAreaL();
-
- // Set overlay position to the center of the preview canvas area
- overlayPosition.iX = (canvasArea.iBr.iX - canvasArea.iTl.iX) / 2;
- overlayPosition.iY = (canvasArea.iBr.iY - canvasArea.iTl.iY) / 2;
-
- // Convert the preview canvas coordinates to the input current coordinates
- TPoint tmp(0, 0);
- preview->CanvasToCurrentCoordL(overlayPosition, tmp);
- overlayPosition = tmp;
-
- // Get TOverlay interface
- TOverlay* overlay = imageProcessor->OverlayL();
-
- // Begin the overlay with a overlay file
- overlay->SetInputL(KInputOverlayFileName, KImageTypePNGUid);
- overlay->BeginL();
-
- // Set overlay with 1.0 x/y scale (un-scaled), position at the center of the preview canvas, 0.0 angle (no rotation)
- overlay->SetL(1.0f, 1.0f, overlayPosition, 0.0f);
-
- // we can check what this looks like by rendering to the preview
- preview->RenderL();
-
- // We can then double the size of the overlaid, rotate it 45 degrees clockwise
- // and move it down ten screen pixels.
- TReal32 overlayScaleX = 0.0f;
- TReal32 overlayScaleY = 0.0f;
- overlay->GetScaleL(overlayScaleX, overlayScaleY);
-
- overlayScaleX *= 2.0f;
- overlayScaleY *= 2.0f;
-
- TReal32 overlayAngle = overlay->AngleL();
-
- // Rotate the overlay 45 degrees
- overlayAngle += 45.0f;
- if (overlayAngle >= 360.0f)
- {
- overlayAngle = overlayAngle - 360.0f;
- }
-
- // Move down the position of the overlay 10 screen pixels
- overlayPosition = overlay->PositionL();
- overlayPosition.iY += 10;
-
- // Set overlay with new parameters
- overlay->SetL(overlayScaleX, overlayScaleY, overlayPosition, overlayAngle);
-
- // Apply overlay parameters and finish with overlay
- overlay->EndL();
-
- preview->RenderL();
-
-</codeblock> </section>
-
-<example><p/></example>
-<section><title>See also</title> <p><xref href="GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita">JPEG
-Image Transform Extension Guide</xref> </p> </section>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF" xml:lang="en"><title>Adding
+Effects And Filters Guide</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This document gives you more information about the image effects and filters. </p>
+<section><title>Purpose</title> <p>The purpose of this guide is to show you
+how to implement different image effects and filters using Image Processor. </p> <p><b>Introduction</b> </p> <p>Adding effects to an image with Image Processor
+is very simple. </p> <p>Effects are applied in the order they are inserted
+in a image. <b>Note:</b> The result from rendering an image can be different
+depending on the order the effects are applied to an image. </p> <p>The code
+example below shows an implementation in the order: crop, mirror, and 90 degree
+rotation. </p> <codeblock id="GUID-041412C5-BD03-56C2-A5A8-162C5058A243" xml:space="preserve">
+
+// Get TInputInfo interface
+TInputInfo* inputInfo = imageProcessor->InputInfoL();
+// Get the input image size
+TSize inputSize = inputInfo->SizeL();
+
+// Define crop region
+TRect cropRegion(inputSize.iWidth / 4, inputSize.iHeight / 4, inputSize.iWidth / 2, inputSize.iHeight /2);
+
+// Apply crop
+imageProcessor->SetInputRectL(cropRegion);
+
+// Get TEffect interface for Mirror Left To Right effect.
+// Note. All effects can be handled via generic TEffect interface. For more advanced functionality
+// the interface pointer must be cast to a derived effect interfece.
+TEffect* effect = imageProcessor->EffectL(KEffectMirrorLeftToRightUid);
+
+// Standard sequence of function calls to apply any effect.
+// The effect must be started with BeginL() and finished with EndL() functions calls.
+effect->BeginL();
+effect->EndL();
+
+// As non-standard effect geometrical operation can be used via derived interface only.
+TGeometricalOperation* operation = static_cast<TGeometricalOperation*>(imageProcessor->EffectL(KGeometricalOperationUid));
+operation->BeginL();
+operation->SetOperationL(ImageProcessor::CImgProcessor::EOperationRotate270);
+operation->EndL();
+
+</codeblock> </section>
+<section><title>Undo</title> <p>Image Processor has a built-in undo mechanism,
+which removes the last added effect or operation on the undo stack. Parameter
+changes are not added to the undo stack. There is an unlimited number of undo
+steps and you can check if an undo operation is possible. </p> <p>The code
+example below shows the implementation the <codeph>ImageProcessor::CImageProcessor::UndoL()</codeph> function: </p> <codeblock id="GUID-80FD0739-851C-57F8-AEF0-4BB6B8634355" xml:space="preserve">
+
+TEffectRotation* rotationEffect = static_cast<TEffectRotation*>(imageProcessor->EffectL(KEffectRotationUid));
+rotationEffect->BeginL();
+rotationEffect->SetRotationL(ImageProcessor::TEffectRotation::ERotationScaleModeFitInside, 45.0f);
+rotationEffect->EndL();
+
+// Check if we can undo last applied effect
+if (imageProcessor->CanUndoL())
+{
+ // Undo the effect
+ imageProcessor->UndoL();
+}
+
+</codeblock> </section>
+<section><title>Adjustable generic effects </title> <p>Those imaging effects
+that have variable strengths or settings to choose from are called adjustable
+generic effects. These effects each have three related functions: </p> <ul>
+<li id="GUID-51F7D507-5788-5120-AC0B-9E599FEE66A2"><p>The <xref href="GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB.dita#GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB/GUID-406C6996-EEA8-3404-B0EF-3FC2EDC021D2"><apiname>ImageProcessor::TEffect::BeginL()</apiname></xref> function
+is used to initiate the adjustable generic effect. </p> <p>Any function calls
+from Image Processor operations are disabled until the <codeph>EndL()</codeph> function
+is called. For example when you try to apply another effect, this cause a
+leave <codeph>KErrNotReady</codeph>. </p> <p>For example, if you want to invoke
+an <codeph>UndoL()</codeph> call, Image Processor operations are blocked between <codeph>BeginL()</codeph> and
+thecorresponding <codeph>EndL()</codeph> call. An UndoL() call can be invoked
+after an <codeph>EndL()</codeph> call. This will cancel the effects applied
+between the last <codeph>BeginL()</codeph> and <codeph>EndL()</codeph> calls. </p> </li>
+<li id="GUID-A194B271-CE29-54F1-BFD6-134CE9CC8923"><p>The <xref href="GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB.dita#GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB/GUID-1588C652-4105-366D-82EF-74EB582D2339"><apiname>ImageProcessor::TEffect::SetLevelL()</apiname></xref> function
+is used to set the parameters of the current adjustable effect. </p> <p>For
+example, when you want to change the parameters of the effect, you must call
+the <codeph>ImageProcessor::TEffect::SetLevelL()</codeph> function to set
+the parameters of the current adjustable effect. </p> </li>
+<li id="GUID-AB2A6C70-8AAA-5916-BEE2-682EBC260E49"><p>The <xref href="GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB.dita#GUID-5DD1A7CA-B0F8-3769-9D53-4541BDC2C3FB/GUID-C0A7EEA7-A5B3-3441-8148-29B2B306CB81"><apiname>ImageProcessor::TEffect::EndL()</apiname></xref> function
+is used to end the current adjustable effect. </p> <p>For example, when you
+are satisfied with the result of the effect, you must call <codeph>ImageProcessor::TEffect::EndL()</codeph> to
+complete the current adjustable effect. </p> <p> <b>Note:</b> If you are not
+satisfied with the result of the effect, you must call the <codeph>EndL()</codeph> function
+of the current generic effect followed by a call to the <codeph>UndoL()</codeph> function. </p> </li>
+</ul> <p>The code example below shows how to use an adjustable begin-end effect: </p> <codeblock id="GUID-7B09C5D7-D48D-550E-8116-5CB6811BF1A6" xml:space="preserve">
+
+// Get sharpness effect
+TEffect* effect=imageProcessor->EffectL(KEffectSharpnessUid);
+
+// Apply default level of Sharpness
+effect->BeginL();
+effect->EndL();
+
+</codeblock> </section>
+<section><title>Working with preview </title> <p>Most mobile imaging applications
+render full-resolution images twice: </p> <ol id="GUID-61808DC4-7C6F-5371-BFD2-AB7275EF9717">
+<li id="GUID-F11B0934-3D84-5F3A-88C7-C38A25CDA2F4"><p>for a preview on the
+screen </p> </li>
+<li id="GUID-23DA4BE1-B256-5B39-BE6C-E97232EF8BA0"><p>for the rendering of
+the output image. </p> </li>
+</ol> <p>To make the render operation into a simple function, you must call
+the <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495"><apiname>ImageProcessor::TPreview</apiname></xref> function. </p> <p>The <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495"><apiname>ImageProcessor::TPreview</apiname></xref> function
+is an interface that describes the preview identified by the preview ID. The
+interface is initialized by specifying an output Symbian bitmap or pixel buffer
+(image frame) by calling <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-38670F92-962C-31D5-9642-9F3F9BE42B30"><apiname>ImageProcessor::TPreview::SetOutput()</apiname></xref>. </p> <p>You
+can use the preview for the zoom and pan effects: </p> <codeblock id="GUID-862C5EB5-4E2C-51E2-AF8E-65F6C5785B3B" xml:space="preserve">
+
+void TPreview::SetZoomL(TReal32 aZoom);
+void TPreview::SetPanL(TReal32 aPanX, TReal32 aPanY);
+TReal32 TPreview::ZoomL() const;
+void TPreview::PanL(TReal32& aPanX, TReal32& aPanY) const;
+
+</codeblock> <p>The <codeph>TReal32</codeph> of pan effect ranges from -1.0
+to 1.0 and the <codeph>TReal32</codeph> of zoom effect ranges from 1.0x to <codeph>TReal32</codeph> maximum
+value. </p> <p> <b>Note:</b> The zoom and pan effects only affect the preview.
+When rendering the original image, these changes are ignored. </p> </section>
+<section><title>Changing the input </title> <p>The source image can be changed
+by calling the <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-0448A658-7DD6-3767-82FC-1EE64B1CBEE3"><apiname>ImageProcessor::CImgProcessor::SetInputL()</apiname></xref> function
+without creating a new Image Processor instance. <codeph>ImageProcessor::CImgProcessor::SetInputL()</codeph> can
+be used when displaying thumbnails or when choosing between different overlay
+graphics. The image source can freely be switched between file, buffer, bitmap
+and a background colour. </p> <p>The code example below illustrates the chain
+of effects applied to a number of images and rendered to screen. </p> <codeblock id="GUID-2D54E9BB-20FE-5F02-A00E-71AAD089FBF0" xml:space="preserve">
+
+ // Get white balance effect
+ effect = imageProcessor->EffectL(KEffectWhiteBalanceUid);
+
+ // Apply default white balance
+ effect->BeginL();
+ effect->EndL();
+
+ // Go through the images and render the preview for each of them
+ for (TInt i = 0; i < 4; i++)
+ {
+ imageProcessor->SetInputL(*filenames[i]);
+ preview->RenderL();
+ }
+
+</codeblock> </section>
+<section><title>Image information </title> <p>Image Processor has functionality
+to get information about the source image. This information can be used for
+display in a file browser or to verify the correct capabilities that are available
+for a specific processing task. </p> <p>First, a pointer to <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-E1B6400E-1A36-368A-AAC7-CDDE3ED656A2"><apiname>ImageProcessor::TInputInfo()</apiname></xref> interface
+must be obtained from the active Image Processor instance. To extract the
+information, the following functions are called: </p> <codeblock id="GUID-C940E27B-4FCE-5C9A-B39A-4C04C9BD6591" xml:space="preserve">
+
+TSize TInputInfo::SizeL() const;
+void TInputInfo::FormatL(TUid& aFormat, TUid& aSubFormat) const;
+TDisplayMode TInputInfo::DisplayModeL() const;
+TUid TInputInfo::ImageFrameFormatL() const;
+TUid TInputInfo::SamplingL() const;
+TUint32 TInputInfo::BitsPerPixelL() const;
+TBool TInputInfo::IsProgressiveL() const;
+TBool TInputInfo::IsInterlacedL() const;
+TBool TInputInfo::HasAlphaL() const;
+
+</codeblock> </section>
+<section><title>Coordinates and areas </title> <p>Image Processor uses a number
+of different coordinate systems to cope with the translation from the preview
+image to the input image. </p> <p>In this section the following concepts are
+introduced: </p> <ul>
+<li id="GUID-B9B0ED22-9EAC-50B3-9987-6BDE1C2D5513"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-4CB4BD23-85CD-5239-96C4-936BC46EE745"> Input images</xref> </p> </li>
+<li id="GUID-4E83AAF6-9820-5D28-9B7B-38E8F4F709DD"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-F956698F-28B3-5CFB-9ABC-E4C69688B284"> Geometry and orientation effects</xref> </p> </li>
+<li id="GUID-07F10586-079D-58BA-9B6D-B9A00372BAF2"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-43A6D850-367B-5A57-8CAA-03113298ED07"> Previews</xref> </p> </li>
+<li id="GUID-367CA050-A363-5D93-B99E-711B180EAA7C"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-BB35B339-CFB6-54CB-9D20-308EEB82225F">Preview canvases</xref> </p> </li>
+<li id="GUID-F59E4119-8111-51BF-98EA-799E52DC870E"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-1187E33F-1EA4-57A0-BC12-1810A48CF61B">Zoom and pan settings</xref> </p> </li>
+<li id="GUID-C14A7AFA-6F20-5313-99CA-7887D5A3895F"><p><xref href="GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF.dita#GUID-F221B15F-B5DE-516F-8FB0-75C1971DB3AF/GUID-7DA27E76-C144-5784-9748-2839766B9A52">Overlay images</xref> </p> </li>
+</ul> <p id="GUID-4CB4BD23-85CD-5239-96C4-936BC46EE745"><b>Input images</b> </p> <p>A
+coordinate system is the region within which a given set of coordinates are
+relevant. In many scenarios, you will need to provide coordinate information
+to Image Processor. This information is ambiguous without additional handling
+to make the coordinates apply to a specific coordinate system. </p> <p>An
+area defines the dimensions of a region. Image data can change form and scale
+during the editing session, which means that a set of areas with different
+dimensions can exist throughout the chain of operations. </p> <p>All imaging
+sessions use a source image as a base. The source image represents the source
+coordinate system and the source area. The source coordinate system is not
+public since it has no relevance to the user. The source coordinate system
+starts at the top left corner of the source image and expands downwards along
+the y-axis and to the right along the x-axis. The source area size is public,
+however, and can be queried through the <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-1D0573C2-611F-3527-9C0B-8E668A208133"><apiname>ImageProcessor::CImgProcessor::CurrentSizeL() </apiname></xref> function. </p> <p id="GUID-F956698F-28B3-5CFB-9ABC-E4C69688B284"><b>Geometry and orientation
+effects</b> </p> <p>Applying geometry effects and orientation effects to an
+input image is usually a chain process. When all effects have been applied,
+the resulting image may differ in geometry from the original source image.
+Hence, the resulting image defines a new area called the current area and
+a new coordinate system called the current coordinate system. Both of these
+are public and can be queried through the Image Processor. The current coordinate
+system starts at the top left corner of the image and expands downwards along
+the y-axis and to the right along the x-axis. </p> <p id="GUID-43A6D850-367B-5A57-8CAA-03113298ED07"><b>Previews</b> </p> <p>You
+can make use of one or more previews when processing an image. A preview defines
+the region on which the image is shown. A preview introduces the preview area
+and the preview coordinate system, both of which are public. The preview coordinate
+system starts at the top left corner of the screen and expands downwards along
+y-axis and to the right along x-axis. </p> <p>Use <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-AF30A4A2-736E-3256-8C14-31368F0A24E3"><apiname>ImageProcessor::TPreview::PreviewToCurrentCoordL()</apiname></xref> to
+perform coordinate conversion and <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-CB6994A3-4355-3D67-85BB-8690F37EE0DD"><apiname>ImageProcessor::TPreview::SizeL()</apiname></xref> to
+get the size of the preview area. </p> <p>To convert between preview coordinates
+and current coordinates use the <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-C38A0CD8-061F-383F-9C0F-06E153FAD477"><apiname>ImageProcessor::TPreview::PreviewToCurrentCoordL(const
+ TPoint&)</apiname></xref> function. To convert between canvas coordinates
+to current coordinates use the <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-481BCBAC-20B9-3134-A20B-EEEFE92C1C22"><apiname>ImageProcessor::TPreview::CanvasToCurrentCoordL()</apiname></xref> function. </p> <p>It
+can be useful to know the current size of the session image, that is, the
+size of the image after any effects and cropping have been applied, by using
+the <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-1D0573C2-611F-3527-9C0B-8E668A208133"><apiname>ImageProcessor::CImgProcessor::CurrentSizeL()</apiname></xref> function. </p> <p id="GUID-BB35B339-CFB6-54CB-9D20-308EEB82225F"><b>Preview canvases</b> </p> <p>Each
+preview contains a sub-region called the canvas. When the resulting image
+is scaled to fit the preview area, while preserving aspect ratio, the actual
+image data will not cover the entire screen and the areas outside the image
+are filled with a background colour. The area containing the image data is
+always referred to as the canvas. A canvas introduces the canvas area and
+the canvas coordinate system, both of which are public. The canvas coordinate
+system starts at the top left corner of the canvas and expands downwards along
+the y-axis and to the right along the x-axis. </p> <p>Use the <xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-481BCBAC-20B9-3134-A20B-EEEFE92C1C22"><apiname>ImageProcessor::TPreview::CanvasToCurrentCoordL()</apiname></xref> to
+perform coordinate conversion and<xref href="GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495.dita#GUID-9CBD93A5-1916-31C4-A974-213FCD7A5495/GUID-A69588CB-8BF2-3FA9-806A-216CA460E912"><apiname>ImageProcessor::TPreview::CanvasAreaL()</apiname></xref> function
+to return the size and location of the canvas area. </p> <p id="GUID-1187E33F-1EA4-57A0-BC12-1810A48CF61B"><b> Zoom and Pan settings</b> </p> <p>Zoom
+and Pan settings do not introduce their own areas or coordinate systems. In
+this regard, Zoom and pan are equivalent to a preview. </p> <p id="GUID-7DA27E76-C144-5784-9748-2839766B9A52"><b>Overlay images</b> </p> <p>Overlay
+images define their own overlay coordinate system and overlay area. The coordinate
+system of an overlay image is public. The overlay coordinate system and overlay
+are rarely used since they are not treated as separate objects once they are
+applied to the source image. The overlay is treated as part of the original
+image data after insertion. </p> <p>However, the coordinate system of an overlay
+image is relevant for defining its anchor point to the source image. The overlay
+area can be queried from Image Processor instances that expose overlay operations.
+The overlay coordinate system starts at the centre of the overlay image and
+expands to the left along the negative side of the y-axis, upwards along the
+negative side of the x-axis, to the right along the x-axis and downwards along
+the y-axis. </p> </section>
+<section><title>Applying overlay and border effects</title> <p>It is possible
+to add borders (frames) and overlays to your input image. For example, you
+might want to add a logo to an image or add a pair of sunglasses to a picture.
+To use a border effect, call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-EF0B943B-C58D-39AD-AAA3-ABEE11033A8C"><apiname>ImageProcessor::CImgProcessor::EffectL(KEffectBorderUid)</apiname></xref>. </p> <p>Border
+images are images with alpha channels. The border is automatically stretched
+to fit the input image. </p> <p>To use overlay effect, call <xref href="GUID-13E30312-DD05-3581-9A59-C3569A981657.dita#GUID-13E30312-DD05-3581-9A59-C3569A981657/GUID-08855134-3A4C-3BE5-B817-73342FFD5CCE"><apiname>ImageProcessor::CImgProcessor::OverlayL()</apiname></xref>. </p> <p>There
+are two ways to insert an overlay to an image, either from a file or from
+memory. If you load the overlay from a file, both PNG and JPEG are accepted,
+but you will only have the transparency option if you use a PNG image. The
+overlay is managed through the interface <xref href="GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7.dita#GUID-9E5136D1-B8BE-3CE4-9A20-39D672E31EC7/GUID-95D515E0-F751-3703-8FD1-80F9B8870E16"><apiname>ImageProcessor::TOverlay</apiname></xref>. </p> <p>You
+can specify the position, the scale, and the angle of the overlay. The position
+must be given in current coordinates. The scale ranges from 0.0 to infinity,
+where 1.0 represent no scaling. The angle ranges from 0.0 degrees to 360.0
+degrees. To begin inserting the overlay the <xref href="GUID-95D515E0-F751-3703-8FD1-80F9B8870E16.dita#GUID-95D515E0-F751-3703-8FD1-80F9B8870E16/GUID-E1255D4A-714D-31A8-9E5E-CCBFF477E2F4"><apiname>ImageProcessor::TOverlay::BeginL()</apiname></xref> function
+must be called. The code example below illustrates the scale effect and the
+angle of the overlay effect. </p> <p>When the overlay is in place you must
+call <xref href="GUID-95D515E0-F751-3703-8FD1-80F9B8870E16.dita#GUID-95D515E0-F751-3703-8FD1-80F9B8870E16/GUID-B3250D2E-CBCB-357C-82CA-7A7B35045CAE"><apiname>ImageProcessor::TOverlay::EndL()</apiname></xref> to conclude the overlay. </p> <p>The
+code examples below describe some common scenarios: </p> <ul>
+<li id="GUID-A2AA2186-067D-571C-AC58-14E97050ED49"><p>You want to insert an
+overlay image in the centre of the image you see on the screen. The scale
+is set to 1.0 and the angle is set to 0 degrees. It is crucial to distinguish
+between canvas coordinates and current coordinates. </p> </li>
+<li id="GUID-24318F41-42F7-5297-B022-6914FB78B381"><p>After the overlay is
+started you want to double its size, rotate it 45 degrees clockwise, and move
+it down ten screen pixels. </p> </li>
+</ul> <codeblock id="GUID-A558142D-8C96-5DB8-B2AF-277C645BE47D" xml:space="preserve">
+
+ TPoint overlayPosition(0,0);
+
+ // Get preview canvas rectangle
+ TRect canvasArea = preview->CanvasAreaL();
+
+ // Set overlay position to the center of the preview canvas area
+ overlayPosition.iX = (canvasArea.iBr.iX - canvasArea.iTl.iX) / 2;
+ overlayPosition.iY = (canvasArea.iBr.iY - canvasArea.iTl.iY) / 2;
+
+ // Convert the preview canvas coordinates to the input current coordinates
+ TPoint tmp(0, 0);
+ preview->CanvasToCurrentCoordL(overlayPosition, tmp);
+ overlayPosition = tmp;
+
+ // Get TOverlay interface
+ TOverlay* overlay = imageProcessor->OverlayL();
+
+ // Begin the overlay with a overlay file
+ overlay->SetInputL(KInputOverlayFileName, KImageTypePNGUid);
+ overlay->BeginL();
+
+ // Set overlay with 1.0 x/y scale (un-scaled), position at the center of the preview canvas, 0.0 angle (no rotation)
+ overlay->SetL(1.0f, 1.0f, overlayPosition, 0.0f);
+
+ // we can check what this looks like by rendering to the preview
+ preview->RenderL();
+
+ // We can then double the size of the overlaid, rotate it 45 degrees clockwise
+ // and move it down ten screen pixels.
+ TReal32 overlayScaleX = 0.0f;
+ TReal32 overlayScaleY = 0.0f;
+ overlay->GetScaleL(overlayScaleX, overlayScaleY);
+
+ overlayScaleX *= 2.0f;
+ overlayScaleY *= 2.0f;
+
+ TReal32 overlayAngle = overlay->AngleL();
+
+ // Rotate the overlay 45 degrees
+ overlayAngle += 45.0f;
+ if (overlayAngle >= 360.0f)
+ {
+ overlayAngle = overlayAngle - 360.0f;
+ }
+
+ // Move down the position of the overlay 10 screen pixels
+ overlayPosition = overlay->PositionL();
+ overlayPosition.iY += 10;
+
+ // Set overlay with new parameters
+ overlay->SetL(overlayScaleX, overlayScaleY, overlayPosition, overlayAngle);
+
+ // Apply overlay parameters and finish with overlay
+ overlay->EndL();
+
+ preview->RenderL();
+
+</codeblock> </section>
+
+<example><p/></example>
+<section><title>See also</title> <p><xref href="GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita">JPEG
+Image Transform Extension Guide</xref> </p> </section>
</conbody></concept>
\ No newline at end of file