|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223" xml:lang="en"><title>JPEG |
|
13 Image Transform Extension Guide</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This document introduces you to the JPEG image transform extensions. </p> |
|
15 <section id="GUID-3333CA2A-EF84-5E7B-B9BE-8FF00523897F-GENID-1-8-1-18-1-1-5-1-6-1-12-1-4-1-3-1-3-1-3-1-2-2"><title>Purpose</title> <p>The |
|
16 Image Transform framework supports standard extensions for advanced JPEG functions. </p> <p>The |
|
17 functions are, </p> <ul> |
|
18 <li id="GUID-5AEE7F00-B5AE-5D17-8280-BB86E1C3F309"><p><xref href="GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita#GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223/GUID-3F1A77BC-C5C3-5A3D-B823-7310B97D449A">Orientation</xref> (Rotation and Mirror over horizontal and vertical Axis) </p> </li> |
|
19 <li id="GUID-48438448-064A-5FE4-96D4-769336CFC50E"><p><xref href="GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita#GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223/GUID-3132C68A-4A30-51FD-9259-9425E3E5B5AE">Overlay</xref> </p> </li> |
|
20 <li id="GUID-03E14C2D-A7D9-532F-9E3A-BB8A38770929"><p><xref href="GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223.dita#GUID-8E794D5A-9C83-54EB-AD5A-6A74BB155223/GUID-AAD925E2-9450-5ADC-B2D2-FF106392FC4C"> Squeeze</xref> </p> </li> |
|
21 </ul> </section> |
|
22 <section id="GUID-3F1A77BC-C5C3-5A3D-B823-7310B97D449A"><title>Orientation</title> <p>The |
|
23 COrientationTransformExtension extension to CImageTransform allows you to |
|
24 rotate in steps of 90 degrees or to mirror a JPEG file either from file or |
|
25 memory. </p> <p>When you require an Image Transform plugin which supports |
|
26 the Orientation extension, call <xref href="GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4.dita#GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4/GUID-141A948E-6070-335D-B0B2-1F4AD283EC1A"><apiname>CImageTransform::SetTransformationsL()</apiname></xref> or <xref href="GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4.dita#GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4/GUID-429C3968-9EB4-3B6E-85FF-13244E4505D2"><apiname>CImageTransform::EOrientation()</apiname></xref>. |
|
27 The client must get the COrientationTransformExtension extension and use this |
|
28 to set up the required transformation: </p> <codeblock id="GUID-12531AE6-3383-50F3-8D89-629010D967E1" xml:space="preserve"> |
|
29 |
|
30 IMPORT_C void COrientationTransformExtension::SetOrientationL(TOrientation aOrientation); |
|
31 |
|
32 </codeblock> <p>The orientation changes supported by the <xref href="GUID-593AD11D-3CE7-39E7-B5FE-EDEDABE8D936.dita"><apiname>COrientationTransformExtension</apiname></xref> are, </p> <ul> |
|
33 <li id="GUID-E3056EBA-DC74-5D99-95D5-3016AEAADA4A"><p>90 degree clockwise </p> </li> |
|
34 <li id="GUID-9E607A83-0846-56FC-95D4-CD7250934EC0"><p>180 degree clockwise </p> </li> |
|
35 <li id="GUID-27A48EA1-7774-5DA8-9FCB-201965A9EA59"><p>270 degree clockwise </p> </li> |
|
36 <li id="GUID-53B7C705-D2EE-5729-BE74-91291D7F30C5"><p>mirroring over the vertical |
|
37 axis </p> </li> |
|
38 <li id="GUID-D7806048-D30A-5D77-BA5E-1F581E76D5CC"><p>mirroring over the horizontal |
|
39 axis </p> </li> |
|
40 <li id="GUID-88EDAE03-DB13-5BF9-BAE8-60C20065D114"><p>transpose over the main |
|
41 diagonal </p> </li> |
|
42 <li id="GUID-8E508BFF-714C-58B4-A0BB-82B6507FC7EA"><p>transpose over the minor |
|
43 diagonal. </p> </li> |
|
44 </ul> <p>In the example function below a JPEG image is rotated by 90 degrees: </p> <codeblock id="GUID-9C13D4D9-1772-5FC1-A294-F0B52A5EFFA2" xml:space="preserve"> |
|
45 |
|
46 // Create the image transform |
|
47 CImageTransform* imageTransform = CImageTransform::NewL(iFs); |
|
48 CleanupStack::PushL(imageTransform); |
|
49 |
|
50 // Setup the image transform |
|
51 imageTransform->SetSourceFilenameL(aSrcFileName); |
|
52 imageTransform->SetDestFilenameL(aDestFileName); |
|
53 imageTransform->SetTransformationsL(CImageTransform::EOrientation); |
|
54 imageTransform->SetupL(); |
|
55 |
|
56 // Get the extension plugin supporting orientation |
|
57 TUid lRotateUid = {KUidOrientationTransformExtension }; |
|
58 TInt err = KErrNone; |
|
59 COrientationTransformExtension* lRotateExt = static_cast<COrientationTransformExtension*> |
|
60 (imageTransform->Extension(lRotateUid, err)); |
|
61 |
|
62 // Check here whether the plugin supports this extension or not set the orientation on |
|
63 // the plugin |
|
64 lRotateExt->SetOrientationL(COrientationTransformExtension::ERotation90DegreesClockwise); |
|
65 |
|
66 // Perform the transformation |
|
67 imageTransform->Transform(aStatus); |
|
68 |
|
69 // CImageTransform::Transform() is an asynchronous function |
|
70 // and the result of the transformation would be known in the |
|
71 // RunL() function of the active object associated with the aStatus |
|
72 |
|
73 </codeblock> <p>The image rotation can be performed in the compressed domain |
|
74 allowing a transformation of the image. Benefits of speed and memory usage |
|
75 can be obtained dependent on the implementation of the plugin. </p> </section> |
|
76 <section id="GUID-3132C68A-4A30-51FD-9259-9425E3E5B5AE"><title>Overlay</title> <p> <xref href="GUID-83EA2789-C3FE-383A-B81F-E9E362FE4283.dita"><apiname>COverlayTransformExtension</apiname></xref> extension |
|
77 to Image Transform framework allows lossless overlay or blend of images. Examples |
|
78 of the use of <xref href="GUID-83EA2789-C3FE-383A-B81F-E9E362FE4283.dita"><apiname>COverlayTransformExtension</apiname></xref> include adding |
|
79 timestamp or place-stamp, some text or inserting a company logo. The images |
|
80 below show an example of overlay functionality: </p> <fig id="GUID-BA901C57-D744-5353-8B25-2195EA084016"> |
|
81 <image href="GUID-E09CA978-2599-50F9-AF6D-077AD7D5CA6F_d0e309541_href.jpg" placement="inline"/> |
|
82 </fig> <p>The image overlay transformation can, depending on its implementation, |
|
83 be very fast eliminating the need to decode the whole image making it very |
|
84 useful, for example a camera application. The types of image that can be overlaid |
|
85 onto the main JPEG image can be discovered through the extension. It is also |
|
86 possible to overlay a <codeph>CFbsBitmap</codeph>. If you need transparency, |
|
87 then you have to choose an image format supporting a transparency channel |
|
88 such as PNG. </p> <p>When you require an Image Transform plugin which supports |
|
89 the Overlay extension, call <xref href="GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4.dita#GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4/GUID-141A948E-6070-335D-B0B2-1F4AD283EC1A"><apiname>CImageTransform::SetTransformationsL()</apiname></xref> or <xref href="GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4.dita#GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4/GUID-198CAB14-A6CB-3D51-9404-C4DED1DCF215"><apiname>CImageTransform::EOverlay()</apiname></xref>. |
|
90 The client must get the COverlayTransformExtension extension and use this |
|
91 to set up the required transformation. The client can control the desired |
|
92 position for overlay, and the transparency for image. The example below show |
|
93 the successful setup for <xref href="GUID-83EA2789-C3FE-383A-B81F-E9E362FE4283.dita"><apiname>COverlayTransformExtension</apiname></xref> with |
|
94 the JPEG image overlaid by an image at (0,0) position co-ordinates: </p> <codeblock id="GUID-648E2DC3-9BA2-59D3-88DA-3E9C31BC3F18" xml:space="preserve"> |
|
95 |
|
96 // Create the image transform |
|
97 CImageTransform* imageTransform = CImageTransform::NewL(iFs); |
|
98 CleanupStack::PushL(imageTransform); |
|
99 |
|
100 // Setup the image transform |
|
101 imageTransform->SetSourceFilenameL(aSrcFileName); |
|
102 imageTransform->SetDestFilenameL(aDestFileName); |
|
103 imageTransform->SetTransformationsL(CImageTransform::EOverlay); |
|
104 imageTransform->SetupL(); |
|
105 |
|
106 // Get the extension plugin supporting overlay |
|
107 TUid lOverlayUid = {KUidOverlayTransformExtension }; |
|
108 TInt err = KErrNone; |
|
109 COverlayTransformExtension * lOverlayExt = static_cast< COverlayTransformExtension *> |
|
110 (imageTransform->Extension(lOverlayUid, err)); |
|
111 |
|
112 // Check here whether the plugin supports this extension or not Set the position on |
|
113 // the plugin |
|
114 lOverlayExt->Position(TPoint(0,0)); |
|
115 |
|
116 // Set the overlay file and its type |
|
117 lOverlayExt->SetOverlayFileL(aOverlayFileName, KImageTypeJPGUid); |
|
118 |
|
119 // Perform the transformation |
|
120 imageTransform->Transform(aStatus); |
|
121 |
|
122 // CImageTransform::Transform() is an asynchronous function |
|
123 // and the result of the transformation would be known in the |
|
124 // RunL() function of the active object associated with the aStatus |
|
125 |
|
126 </codeblock> </section> |
|
127 <section id="GUID-AAD925E2-9450-5ADC-B2D2-FF106392FC4C"><title>Squeeze</title> <p>The <xref href="GUID-1B022316-410D-328C-AFB2-E3A339E1609B.dita"><apiname>CSqueezeTransformExtension()</apiname></xref> extension |
|
128 to the Image Transform framework allows, </p> <ul> |
|
129 <li id="GUID-485ED69C-7895-5B8F-B2DC-D8A165F74D59"><p>Auto-resize </p> </li> |
|
130 <li id="GUID-8DDD9BE0-F079-5F6F-B4D7-26DC45170BEC"><p>Squeeze. </p> </li> |
|
131 </ul> <p>A auto-resize adjusts the image size and encoding quality to achieve |
|
132 a desired file size. If the file size requirement has not been met, then you |
|
133 can use squeeze to compress the image even further. The JPEG squeeze module |
|
134 is a convenient tool when creating MMS. </p> <p>When you require an Image |
|
135 Transform plugin which supports the Squeeze extension, call <xref href="GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4.dita#GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4/GUID-141A948E-6070-335D-B0B2-1F4AD283EC1A"><apiname>CImageTransform::SetTransformationsL()</apiname></xref> or <xref href="GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4.dita#GUID-37B0C02C-F518-3ADD-8828-90FD6B3E9DE4/GUID-FC837A02-243D-3A5B-A81D-63802678F6C6"><apiname>CImageTransform::ESqueeze()</apiname></xref>. </p> <p>Squeezing an image can be accomplished through: </p> <codeblock id="GUID-12A6E7C4-8627-5ACC-8692-64F247FB518D" xml:space="preserve"> |
|
136 |
|
137 IMPORT_C void CSqueezeTransformExtension::SetDestSizeInBytes(TUint aMaxDestDataSize ) ; |
|
138 |
|
139 </codeblock> <p>Or </p> <codeblock id="GUID-97A7CE4F-A227-51EE-B8E6-CC04C5A2491A" xml:space="preserve"> |
|
140 IMPORT_C void SetAdvancedSqueezeModeL(TAdvancedSqueezeParams* aSqueezeAutoResizeParams ) ; |
|
141 </codeblock> <p>In the latter case can be made through the use of <xref href="GUID-4372B86B-111B-3B9E-838A-511D247846D4.dita#GUID-4372B86B-111B-3B9E-838A-511D247846D4/GUID-15AB4D19-1FDE-3D29-AED2-7776E3E08C10"><apiname>TAdvancedSqueezeParams::TAutoResizeAction</apiname></xref>. |
|
142 The enumeration to do auto resize are, </p> <ul> |
|
143 <li id="GUID-3240A4EE-6904-536C-BA05-5995738CE048"><p> <xref href="GUID-DAEB147E-2A50-30F5-85C8-863DC8C21AF7.dita"><apiname> |
|
144 EAutoResizeActionPreserveSourceEncodingQuality</apiname></xref> for preserving |
|
145 the source encoding quality while shrinking the width and height of the image </p> </li> |
|
146 <li id="GUID-B29AE145-B946-59CD-879E-6F77F0E48563"><p> <xref href="GUID-EAF60EAB-3E65-34AE-BD3F-C32BA331BCEE.dita"><apiname> EAutoResizeActionPrioritizeLargeImageSize</apiname></xref> for |
|
147 preserving the maxImageSize while lowering the encoding quality </p> </li> |
|
148 <li id="GUID-2B98FA22-2853-5DB0-B9A2-7B2BC6080522"><p> <xref href="GUID-EAF42079-109B-36E7-940F-C10C10743E31.dita"><apiname>EAutoResizeActionResizePrioritizeHighEncodingQuality</apiname></xref> for |
|
149 preserving the highest possible encoding quality while shrinking the width |
|
150 and height of the image </p> </li> |
|
151 <li id="GUID-3848F63C-D0CF-5888-BC68-127AA29DFE81"><p> <xref href="GUID-D8807BBD-5EAE-3BBE-B408-5841D7554287.dita"><apiname>EAutoResizeActionMiddleCourse</apiname></xref> for |
|
152 simultaneously lower the encoding quality and shrink the width and height |
|
153 of the image. </p> </li> |
|
154 </ul> <p>These settings are used by the auto resize to determine size and |
|
155 encoding quality for the new image file. </p> <p>The JPEG squeeze enblaes |
|
156 images to be set to a enblaes pre-defined size. This is useful if storage |
|
157 size is critical or if there are limitations when sending images i.e. MMS |
|
158 file size. The dimensions of the image are preserved; the JPEG compression |
|
159 ratio being changed to maintain the image size. </p> <p> <b>Note:</b> The |
|
160 JPEG squeeze functionality must be used with care. Drastically decreasing |
|
161 file size will result in poor image quality. </p> <p>In the below example, |
|
162 the JPEG image is squeezed to get a file size less than the specified maxium |
|
163 size: </p> <codeblock id="GUID-9E529BC6-0042-5EBE-A5AE-8F2ADAA8E4D8" xml:space="preserve"> |
|
164 |
|
165 // Create the image transform |
|
166 CImageTransform* imageTransform = CImageTransform::NewL(iFs); |
|
167 CleanupStack::PushL(imageTransform); |
|
168 // Setup the image transform |
|
169 imageTransform->SetSourceFilenameL(aSrcFileName); |
|
170 imageTransform->SetDestFilenameL(aDestFileName); |
|
171 imageTransform->SetTransformationsL(CImageTransform::ESqueeze); |
|
172 imageTransform->SetupL(); |
|
173 // Get the extension plugin supporting squeeze |
|
174 TUid lSqueezeUid = {KUidSqueezeTransformExtension }; |
|
175 TInt err = KErrNone; |
|
176 CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> |
|
177 (imageTransform->Extension(lSqueezeUid, err)); |
|
178 // Check here whether the plugin supports this extension or not |
|
179 // Set the max dest size in bytes |
|
180 lSqueezeExt-> SetDestSizeInBytes(aMaxSizeInBytes); |
|
181 // Perform the transformation |
|
182 imageTransform->Transform(aStatus); |
|
183 // CImageTransform::Transform() is an asynchronous function |
|
184 // and the result of the transformation would be known in the |
|
185 // RunL() function of the active object associated with the aStatus |
|
186 |
|
187 </codeblock> <p>The example code below show how the JPEG squeeze image is |
|
188 used to make an image fulfill the MMS ‘Image Rich’ class constraints, i.e. |
|
189 file size less than 100k bytes and image size no more than 640*480 pixels. </p> <codeblock id="GUID-C04CB828-3307-5079-91CD-BEA7A15F0215" xml:space="preserve"> |
|
190 |
|
191 // Create the image transform |
|
192 CImageTransform* imageTransform = CImageTransform::NewL(iFs); |
|
193 CleanupStack::PushL(imageTransform); |
|
194 // Setup the image transform |
|
195 imageTransform->SetSourceFilenameL(aSrcFileName); |
|
196 imageTransform->SetDestFilenameL(aDestFileName); |
|
197 imageTransform->SetTransformationsL(CImageTransform::ESqueeze); |
|
198 imageTransform->SetupL(); |
|
199 // Get the extension plugin supporting squeeze |
|
200 TUid lSqueezeUid = {KUidSqueezeTransformExtension }; |
|
201 TInt err = KErrNone; |
|
202 CSqueezeTransformExtension * lSqueezeExt = static_cast< CSqueezeTransformExtension*> |
|
203 (imageTransform->Extension(lSqueezeUid, err)); |
|
204 TInt res = KErrNone; |
|
205 TInt newSize = 0; |
|
206 TAdvancedSqueezeParams info ; |
|
207 |
|
208 // MMS Image Rich |
|
209 info.iMaxDestSizeInBytes = 100000; |
|
210 info.iMaxImageSize.iWidth = 640; |
|
211 info.iMaxImageSize.iHeight = 480; |
|
212 info.iMinImageSize. iWidth = 160; |
|
213 info.iMinImageSize. iHeight = 120; |
|
214 info.iResizeAction = EAutoResizeActionPrioritizeLargeImageSize; |
|
215 info.iMinEncodingQuality = 0.5f; |
|
216 info.iSamplingUid = KUidSamplingColor420; |
|
217 lSqueezeExt->SetAdvancedSqueezeModeL(&info); |
|
218 // Perform the transformation |
|
219 imageTransform->Transform(aStatus); |
|
220 // CImageTransform::Transform() is an asynchronous function |
|
221 // and the result of the transformation would be known in the |
|
222 // RunL() function of the active object associated with the aStatus |
|
223 |
|
224 </codeblock> </section> |
|
225 |
|
226 </conbody></concept> |