S60 Platform: Camera Example with AutoFocus Support v2.2
--------------------------------------------------------

This C++ application implements the basic features of the built-in camera using the 
On-board Camera API classes MCameraObserver and CCamera (supported from S60 2nd 
Edition onwards). The example demonstrates view finding, zooming, shooting a 
still image, and saving it. Images are either captured in bitmap format and
then converted to JPEG format, or directly in EXIF JPEG format (if supported 
by camera hardware).

AutoFocus can also be controlled if supported by camera. AutoFocus support is
enabled by linking against an AF extension library - the required binaries for 
the library are in this package.

From S60 3rd Edition, FP2 onwards, the AF extension library cannot be used because of the compatibility break. CCamera::CCameraAdvancedSettings class should be used instead to control the AutoFocus (not implemented in the example).

The updated application has been manually tested against Symbian Signed test cases 
and many improvements have been made to ensure better quality.

PREREQUISITES
-------------------------------------------------------------------------------

- Symbian OS key concepts


IMPORTANT FILES/CLASSES
--------------------------------------------------------------------------------

CameraCaptureEngine.h           | The main engine class. Owns an instance of 
                                | CCamera and implements the required observer 
                                | interface class MCameraObserver. The engine 
                                | class is also an active object - asynchronous
                                | requests are used for internal state changes.
                                |
                                | Also implements the MCamAutoFocusObserver
                                | interface, and owns a CCamAutoFocus object for
                                | controlling AutoFocus (if supported by the device.
                       

CameraAppController.h           | A controller class for the engine. This class 
                                | is also responsible for playing sounds - 
                                | the shutter sound when capturing an image, 
                                | and the AF in-focus notification beep.

CameraAppView.h                 | The landscape (standard) view class.

CameraAppBaseContainer.h        | A container class for the view.


Important Symbian C++ classes:  MCameraObserver and CCamera (from ECam.h)

AutoFocus Extension classes:    MCamAutoFocusObserver and CCamAutoFocus
                                (from ccamautofocus.h)

REQUIRED CAPABILITIES
-------------------------------------------------------------------------------

UserEnvironment
(SwEvent is required to capture events from the camera shutter key)


KNOWN ISSUES
--------------------------------------------------------------------------------

Some known issues have been detected. Some of them occur because of different 
versions of the built-in camera. This example is optimized to work with cameras supporting 
autofocus. Note that some issues may require optimization and different builds for 
better support in different devices.

- In the S60 3rd Edition SDK emulator, camera hardware is not available. Thus 
  the application cannot be fully tested on the S60 3rd Edition emulator.

- The viewfinder is set to landscape position in S60 3rd Edition device and newer 
  devices. There are some known exceptions and support for them is provided by 
  listing them in the cameraappappui.cpp file. Note that possible other S60 3rd Edition   
  devices with the viewfinder in portrait orientation may behave incorrectly.

- In some S60 3rd Edition devices, the camera shutter key cannot be used for
  capturing images, as it is reserved for the system camera application. 
  Devices that support AutoFocus use a different key code for the shutter
  key. Events from this key can be captured if the application has SwEvent
  capability (developer certificate required).  Note that in the Nokia E90 Communicator, 
  the camera key works without SwEvent capability and developer certificate. This 
  is presumably because the system camera of the device cannot be started via this 
  key so it is not reserved for the camera application.

- As a workaround to support switching between two displays in the Nokia E90 Communicator, 
  the CameraCaptureEngine is always reset deleted and re-initialized when the cover is 
  closed/opened or when the application is sent to background/foreground. The impact 
  of this is that the application works slowly in some situations.
  Note: The preinstalled Camera application of the Nokia E90 Communicator can 
  only be used on the cover display.
  
- When capturing directly in EXIF JPEG format, post-exposure view is not
  implemented (the viewfinder simply stops while the image is being saved).
  
- The AutoFocus API may return an incorrect focus range (CCamAutoFocus::FocusRange())
  after initialization if a non-default range was set in a previous session.
  A workaround is to always set the focus range to normal after initializing
  the AutoFocus object.

- AutoFocus functionality does not work in AF-enabled devices based on S60 3rd 
  Edition, Feature Pack 2 or newer (these devices use a different library for AutoFocus).

- Some focus range modes are not supported by all devices with an AF-capable 
  camera. For example, the Nokia N73 does not support the 'portrait' range,
  while the Nokia N95 does.
  
- Pixel size for the captured images is currently determined by simply selecting
  the second index from the list of supported capture sizes (see 
  CCamera::PrepareImageCaptureL()). For most devices, this is the 2nd largest
  capture size supported, however, there are some exceptions. The engine class 
  contains an (unused) method GetImageSizeIndexL(), which can be used for a
  more sophisticated capture size selection.
  
- The current solution to determine whether there is enough free space available
  when taking a picture is a simple restriction that prevents taking a
  picture with less than 500 kB of storage memory available. A somewhat better
  fix would be to reset the state of the application in case the device runs
  completely out of memory.
  
- In the Nokia N90, the Help application cannot be brought to the foreground while
  viewfinder is active.

- Help files does not copy into the right place in emulator environment but works in the device.

RUNNING THE EXAMPLE
--------------------------------------------------------------------------------

Launch the CameraApp application on your device. A screen displaying a view
finder in landscape (standard) mode will appear and the application is ready for 
use.

The operations of the application are controlled using the actions found in the 
Options menu and by using the scroller key:

- Selection key, or
  Options->Snap, or
  Camera shutter key*:     Capture an image and save it to the images folder
  
* Requires SwEvent capability and signing against a trusted certificate.
  The self-signed .sis package in the \sis folder does not have this capability.
  
- Options->Go to Gallery: Open the Media Gallery application to view images
                          
- Up arrow key:            Zoom in 
- Down arrow key:          Zoom out


AutoFocus functionality:

- Press the camera key halfway down to focus the camera. When the camera is
  in focus, a short beep is played.
  
- Options->Focus Range: Change the focus range [normal|macro|portrait|inifinity]
  Note that some devices do not support all focus range modes.

After the image has been captured, it will be saved in the default Images folder
on the device. The resulting file name is hard-coded with "CamAppXX.jpg", where
"XX" is a number automatically generated by the sample code.

The user can now either view the image using Media Gallery or capture a new
image by pressing the Selection key again or from Options->New image.


BUILD & INSTALLATION INSTRUCTIONS
--------------------------------------------------------------------------------

- Extract the contents of the AutoFocus library package to the root folder 
  (EPOCROOT) of your SDK installation path.

    autofocus_extension_library_s60_3rd_ed.zip      // for S60 3rd Edition SDKs


Mobile device (S60 3rd Edition)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Make sure the paths in .pkg files match those on your system.

2. Compile the example:

    cd group
    bldmake bldfiles
    abld reallyclean gcce
    abld build gcce urel

3. Make the sis:

    cd sis
    createsis create CameraApp_S60_3_0_v_2_2_0.pkg
    
4. Install the signed .sis file to an S60 3rd Edition device.
   - If you get a "Certificate error" during installation of a self-signed 
     package, check that App.Manager -> Settings -> Software Installation is 
     set to "All."


Emulator (WINSCW)
~~~~~~~~~~~~~~~~~

1. Compile the example:

    cd group
    bldmake bldfiles
    abld reallyclean winscw
    abld build winscw udeb

2. Start the emulator.


COMPATIBILITY
--------------------------------------------------------------------------------

S60 3rd Edition, Feature Pack 1
S60 3rd Edition

Tested on: Nokia 6290, Nokia E61i, Nokia E70, Nokia E90 Communicator, Nokia N82, Nokia N95.

Developed and tested with:
S60 3rd Edition SDK for Symbian OS, for C++, Maintenance Release

VERSION HISTORY
--------------------------------------------------------------------------------

2.2 Context-sensitive Help, About dialog, and Backup & Restore support implemented.
    Manually tested against Symbian Signed test cases to improve quality.
    Nokia E90 Communicator support improved (Known Issues section).    
    Lots of minor bugs fixed.
    S60 2nd Edition support removed from source code.

2.1 Added support for AutoFocus, using the AF extension library.
    Added support for capturing images in EXIF JPEG format.
    References to unsupported MCameraObserver2 (and related classes) removed.

2.0 Support for S60 3rd Edition added.
  
  Changes to the mechanism used to play a snap sound while capturing an image 
  (the required Camera1a_2_8kHz.wav file is no longer automatically present 
  in newer devices, and the file is delivered in the installation package).

1.0 First release.


EVALUATE THIS RESOURCE
--------------------------------------------------------------------------------

Please spare a moment to help us improve documentation quality and recognize the examples 
you find most valuable, by rating this resource at http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=2f492479-ac8c-4c3e-aa90-cc883e190d83/S60_Platform_Camera_Example_with_AutoFocus_Support_v2_2_en.zip.