--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-6C8507F7-FE70-5654-91B5-53E356CFF67C.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,21 @@
+<?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 xml:lang="en" id="GUID-6C8507F7-FE70-5654-91B5-53E356CFF67C"><title>Controlling Pre-Image Capture </title><shortdesc>This document explains how to configure the camera before using it for still image capture. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p>The PreImageCaptureControl API allows the client to retrieve the following information: </p> <ul><li id="GUID-2616F9E0-C6C5-5C1F-9060-28755FAA2A6F"><p>Direct snapshot support </p> </li> <li id="GUID-16A74E2A-31AB-5C64-98B2-7328D4E374EF"><p>Embedded still capture setting support </p> </li> <li id="GUID-7F870485-D5E9-5667-80AC-7C95588F5893"><p>Direct saving support </p> </li> <li id="GUID-F6BDB588-3003-5CD0-9232-B39CC8218F4D"><p>Image format and pixel aspect ratio supported for a given resolution </p> </li> <li id="GUID-D2BDBB39-7726-5762-8F9D-E68D7D19B2DB"><p>Maximum memory size setting support </p> </li> <li id="GUID-93CCFA89-2C29-5029-BD4F-A36650C191F6"><p>Maximum memory size currently used in camera </p> </li> </ul> <p>This new API creates a new set of camera configuration with improved speed. The new camera configuration is created, when there is an on-going still image capture based on previous configuration. </p> <p><b>Introduction</b> </p> <p>This classes provide the necessary framework to control the image operations and settings prior to image capture. An observer class is associated with this class so that client may be notified of various relevant activities. This API provides replacement for few image capture related methods in class <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita"><apiname>Ccamera</apiname></xref>. </p> <p><b>Required Background</b> </p> <p>This is an extension API associated with <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita"><apiname>Ccamera</apiname></xref> class. To create an object of the extension API facade class, a client application would need to provide a valid <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita"><apiname>Ccamera</apiname></xref> reference as a parameter for the factory method. </p> <p>Clients use <xref href="GUID-94C66CB9-328A-3275-B5A9-198EC6D0DD30.dita"><apiname>New2L</apiname></xref> or <xref href="GUID-14200C39-1435-31B0-9768-363BD3D4331E.dita"><apiname>NewDuplicate2L</apiname></xref> method to create camera object. So, clients that uses <xref href="GUID-E6F013A6-6413-3691-A70D-0289916ACD8A.dita"><apiname>NewL</apiname></xref> or <xref href="GUID-0DB8D81E-AEC1-364B-B404-996B35B449FD.dita"><apiname>NewDuplicateL</apiname></xref> will not be able to create instance of this extension. This prepares the clients to receive unrecognized enum or ids that can be included in future. </p> </section> <section id="GUID-3905D703-E2DD-50B4-A48C-DE84E504B5FB"><title>Using PreImageCaptureControl</title> <p>Licensee should provide concrete implementation for <xref href="GUID-AB548D66-4418-30B3-B81D-619CED81EBBA.dita"><apiname>MCameraPreImageCaptureControl</apiname></xref> class. Configuring the camera before using it for still image capture includes the following steps: </p> <ol id="GUID-2C0AEE23-FF96-5A62-A9CB-8DA762FFAD8B"><li id="GUID-ECF691D5-3036-5F12-B4F2-2BA37627A262"><p>Use <xref href="GUID-9435F878-B639-3C9E-905A-AFF5C7A30F20.dita#GUID-9435F878-B639-3C9E-905A-AFF5C7A30F20/GUID-7F386328-78F2-33AE-87D8-FFCD2AAEFB20"><apiname>CcameraPreImageCaptureControl::NewL()</apiname></xref> factory method to create a class pointer. </p> <p>This maps the exported call to an internal object of class <xref href="GUID-90E10EF6-5B7E-3A0B-B1FA-293D19A2B346.dita"><apiname>CCameraPreImageCaptureControl</apiname></xref> that provides the functionality. </p> </li> <li id="GUID-94A29911-4762-5673-8805-70273331F2DF"><p>Get this pointer using a call to <xref href="GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E.dita#GUID-4E8A5141-5E4A-322A-9892-8DC49D04986E/GUID-1F537D7D-5451-3834-869D-3092A4773B83"><apiname>Ccamera::CustomInterface()</apiname></xref> with UID value <xref href="GUID-5F12DF77-CD66-3445-ACF5-FD3FF815FFF6.dita"><apiname>KECamMCameraPreImageCaptureControlUid</apiname></xref>. </p> </li> <li id="GUID-3F8D8B5D-2E66-5102-B38A-971A06B009CF"><p>Use pointer to the <xref href="GUID-AB548D66-4418-30B3-B81D-619CED81EBBA.dita"><apiname>MCameraPreImageCaptureControl</apiname></xref> derived class to initialize <xref href="GUID-90E10EF6-5B7E-3A0B-B1FA-293D19A2B346.dita#GUID-90E10EF6-5B7E-3A0B-B1FA-293D19A2B346/GUID-A4766124-D4BC-3086-8511-2D3ABC817FAA"><apiname>CCameraPreImageCaptureControl::iImpl</apiname></xref> during the second phase construction of the class <xref href="GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4.dita#GUID-021C509B-C821-3401-B2F4-DE7F52BB16D4/GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58"><apiname>CCamera::CCameraPreImageCaptureControl</apiname></xref>. </p> </li> <li id="GUID-E6406691-7048-5878-8E28-F613AC43C195"><p>Use <xref href="GUID-CC3E371F-3037-3F7C-ACFF-DCC24972F0B7.dita"><apiname>MpreImageCaptureControlObserver</apiname></xref> that contains call-back to provide instance of image capture class object after successfully preparing the image parameters. </p> </li> <li id="GUID-36D7701C-E01A-5CED-9B89-700599B4F448"><p>Check if camera can provide capture event notification to the client using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-34F7459D-BC5A-3EE3-8344-F38A53065A37"><apiname>CCamera::CCameraPreImageCaptureControl::GetCaptureEventSupportInfoL</apiname></xref> method. If capture event notification is supported, ECam implementation will use <xref href="GUID-897443E9-1596-3488-AFE1-32D02F74ED62.dita"><apiname>KUidECamEventImageCaptureEvent</apiname></xref> event to notify the clients that the image has been exposed to the camera sensor. </p> </li> <li id="GUID-74F86194-32FD-54D4-A892-DBF61D481726"><p>Clients can decide whether to play a capture sound. </p> </li> <li id="GUID-C22097F6-8BD9-5059-BE1C-72361F46DF4D"><p>Client retrieves the information about direct snapshot support, embedded still capture setting support and direct saving support from the camera, and filled the desired <xref href="GUID-F9C915AA-2CF8-39A0-99B6-C8C16D20DAE5.dita"><apiname>TPrepareImageParameters</apiname></xref> to issue <xref href="GUID-D9BF1588-CF37-3D1E-AD6B-9CF7D1540C6D.dita"><apiname>PrepareImageCapture</apiname></xref> call. </p> </li> <li id="GUID-41DF8F68-1C90-5B82-9157-3E6B182F1E86"><p>Implementation sets up and allocates memory for image capture operation. It creates a new <xref href="GUID-992BCFCD-9F06-35A5-B166-3058F650E360.dita"><apiname>CCameraImageCapture</apiname></xref> object using the prepare image parameters passed by the client. </p> </li> <li id="GUID-7D926D6F-9413-5CEE-BB25-7D22523CCDDC"><p>The callback <xref href="GUID-901FB5EB-70A9-39AA-9052-436E8FC0C0EA.dita#GUID-901FB5EB-70A9-39AA-9052-436E8FC0C0EA/GUID-BE06517A-0C7D-3F20-BE4C-00F424C30147"><apiname>MPreImageCaptureControlObserver::PrepareImageComplete</apiname></xref> passes the ownership of the <xref href="GUID-992BCFCD-9F06-35A5-B166-3058F650E360.dita"><apiname>CCameraImageCapture</apiname></xref> object to the client. </p> </li> </ol> <p> <b>Note</b>: </p> <ul><li id="GUID-9477A161-E0B5-598D-BF38-868882FB4084"><p>Client should provide implementation of <xref href="GUID-CC3E371F-3037-3F7C-ACFF-DCC24972F0B7.dita"><apiname>MpreImageCaptureControlObserver</apiname></xref> class. </p> </li> <li id="GUID-DD66113F-BAA1-5E61-A5C5-F0AD44FA2C62"><p>Licensees should provide a concrete implementation of <xref href="GUID-146FDB43-52C2-3951-8231-57B40F06A355.dita"><apiname>McameraPreImageCaptureControl</apiname></xref> interface class. </p> </li> </ul> <p>The following example code snippets illustrates the use of <b>PreImageCaptureControl</b> classes. </p> <codeblock id="GUID-725BEAC3-EB75-5792-AA27-A26F6F5D36F1" xml:space="preserve">CCamera* camera; 
+Use MCameraObserver2* observer2; 
+Use camera = CCamera::New2L(*observer2, 0);
+
+CCamera::CCameraPreImageCaptureControl* preImgCapture = CCamera::CCameraPreImageCaptureControl::NewL(*camera, MPreImageCaptureControlObserver* preImageCaptureControlObserver));
+
+CCamera::CCameraPreImageCaptureControl::TPrepareImageParameters prepareImageParameters;
+MCaptureImageObserver*     captureImageObserver ;
+preImgCapture-&gt;PrepareImageCapture(prepareImageParameters, *captureImageObserver);</codeblock> <p><b>Setting Maximum Memory Size</b> </p> <p>To set maximum memory size for a JPEG still image do the following: </p> <ul><li id="GUID-258A56BE-D440-53EA-B12E-04DDE7FDB707"><p>Check if memory size is set to maximum using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-4B42D484-8C0A-361C-9145-1F4A4A396832"><apiname>CCamera::CCameraPreImageCaptureControl::GetImageMaxMemorySizeSettingSupportInfoL</apiname></xref> method. </p> </li> <li id="GUID-6D61C9AA-A45F-586C-BA93-1C97370278B3"><p>Get the maximum memory size in KB using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-C4958029-1126-3D5B-A0BB-8E1495DE0223"><apiname>CCamera::CCameraPreImageCaptureControl::GetImageMaxMemorySizeL</apiname></xref> method. </p> </li> <li id="GUID-3C8B1F34-2B35-5F65-AFC9-625F31E17C2B"><p>Use <xref href="GUID-55213352-BFFB-3D59-A617-0CDC8B57FF75.dita#GUID-55213352-BFFB-3D59-A617-0CDC8B57FF75/GUID-DC71D0C3-35A0-3510-8D9A-EB73FD35DA52"><apiname>CCamera::CCameraPreImageCaptureControl::TPrepareImageParameters::
+                  iImageMaxMemorySize</apiname></xref> method to get the maximum memory size in kilo bytes. If client has no specific preference or if this setting is not supported, it will be <xref href="GUID-446F413C-BF0D-3B2B-A81C-03A30B4F5E09.dita"><apiname>KECamNoSpecificMaxMemorySize</apiname></xref>. The maximum memory size will take preference over JPEG quality if it is not sufficient to achieve the desired quality. </p> </li> </ul> <p><b>Providing image file saving support</b> </p> <p>To save the still images do the following steps: </p> <ul><li id="GUID-E3DB2442-4E4F-5713-AAA1-14E23AEAA565"><p>Get the settings supported for embedded still captures using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-EB7C9C95-E254-3F1F-BEAD-7019A9CEA6AF"><apiname>CCamera::CCameraPreImageCaptureControl::GetSupportedEmbeddedStillCaptureSettingsL</apiname></xref> method. </p> </li> <li id="GUID-CEEB6340-ADFB-546D-ABE0-6FDA67958D77"><p>Get the information about the direct saving state supported by the camera using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-32811F5C-2715-353F-8029-BAFDAAA311C5"><apiname>CCamera::CCameraPreImageCaptureControl::GetSupportedDirectSavingTypeL</apiname></xref> method. If supported, still images are saved in files instead of providing it to clients through <xref href="GUID-5E8EC5D5-E826-3024-B546-60A72CC55091.dita"><apiname>MCameraImageBuffer</apiname></xref> callback. </p> </li> <li id="GUID-5AE9512F-213D-5E6F-92E4-983367D74AE5"><p>Get the direct saving type currently used using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-1177F449-919D-331D-8266-9E0636A9F49C"><apiname>CCamera::CCameraPreImageCaptureControl::GetDirectSavingTypeL</apiname></xref> method. Enum value <xref href="GUID-3418EE4E-6EAF-3501-ADC4-0AEB36BC813F.dita"><apiname>TDirectSavingType</apiname></xref> will represent the direct saving type used by the camera. </p> </li> <li id="GUID-80926C68-7EE2-57E4-91A0-2DC7F633B6C4"><p>Set the required type of direct saving option specified by its state using <xref href="GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58.dita#GUID-7B13335C-10A9-38D2-AE12-A50ECCF7EA58/GUID-43AB5D15-D417-3E8E-8E8C-26EF2FA61C37"><apiname>CCamera::CCameraPreImageCaptureControl::SetDirectSavingTypeL</apiname></xref> method. </p> </li> </ul> <p> <b>Note</b>: Before capturing still images by direct saving option, clients need to provide the filename. </p> </section> <section><title>See also</title> <p><xref href="GUID-BFDDCE4E-FE4F-5815-9D0B-A0967EA53B11.dita">Controlling Still-image Capture</xref> </p> <p><xref href="GUID-3C3BBE1F-D7A2-5021-830B-78084334C883.dita">Controlling Captured Image</xref>  </p> </section> </conbody></concept>
\ No newline at end of file