inc/FMediaICameraEventListener.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file        FMediaICameraEventListener.h
  20  * @brief       This is the header file for the %ICameraEventListener interface.
  21  *
  22  * This header file contains the declarations of the %ICameraEventListener interface.
  23  */
  24
  25 #ifndef _FMEDIA_ICAMERA_EVENT_LISTENER_H_
  26 #define _FMEDIA_ICAMERA_EVENT_LISTENER_H_
  27
  28 #include <FBase.h>
  29 #include <FMediaCameraTypes.h>
  30
  31 namespace Tizen { namespace Media
  32 {
  33
  34 /**
  35  * @interface   ICameraEventListener
  36  * @brief               This interface provides a listener that receives events associated with %Camera.
  37  *
  38  * @since               2.0
  39  *
  40  * The %ICameraEventListener interface specifies the methods used to notify the status of the camera and its events.
  41  * The camera engine works asynchronously. Therefore, it is important to implement this listener
  42  * to ensure the smooth performance of the camera.
  43  *
  44  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/capturing_still_images.htm">Capturing Still Images</a>.
  45  */
  46 class _OSP_EXPORT_ ICameraEventListener
  47         : virtual public Tizen::Base::Runtime::IEventListener
  48 {
  49
  50 public:
  51    /**
  52         * This polymorphic destructor should be overridden if required. @n
  53         * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  54         *
  55         * @since                2.0
  56         */
  57         virtual ~ICameraEventListener(void) {}
  58
  59    /**
  60         * Called when the Camera::SetAutoFocus() method is completed.
  61         *
  62         * @since                2.0
  63         *
  64         * @param[in]     completeCondition       The condition of auto focus completion @n
  65         *                                                                                Set to @c true if it succeeds, @n
  66         *                                                                                else @c false.
  67         */
  68         virtual void OnCameraAutoFocused(bool completeCondition) = 0;
  69
  70    /**
  71         * Called when the Camera::StartPreview() method is completed. @n
  72         * Notifies the application periodically, at the speed of the camera's frame rate,
  73         * once the %Camera::StartPreview() method is called, so as to receive the preview data.
  74         *
  75         * @since                2.0
  76         *
  77         * @param[in]    previewedData                    The displayed image data in the viewfinder @n
  78         *                                                                                The previewed data format is same as the format
  79         *                                                                            set by Camera::SetPreviewFormat().
  80         * @param[in]    r                                                The cause of the error
  81         * @exception     E_SUCCESS                               The method is successful.
  82         * @exception     E_INVALID_DATA                  The Tizen::Base::ByteBuffer contains invalid data.
  83         * @remarks
  84         *                               - This method is called only if the @c previewedData flag of Camera::StartPreview() is @c true.
  85         *                               - This method can be delayed or dropped depending on the system performance.
  86         *   @see            Camera::GetPreviewFormat()
  87         *
  88         * The camera rotation can differ according to the physical design. @n
  89         * For keeping compatibility between the targets, the application must check the hardware camera rotation.
  90         * Based on this information, the application can rotate the preview data.
  91         *
  92         * The following example demonstrates how to use the %OnCameraPreviewed() method to rotate the preview data in the portrait mode.
  93         *
  94         * @code
  95         * #include <FMedia.h>
  96         *
  97         * using namespace Tizen::Base;
  98         * using namespace Tizen::Media;
  99         * using namespace Tizen::Graphics;
 100         *
 101         * class MyCamera
 102         * : public Tizen::Media::ICameraEventListener
 103         * {
 104         * protected:
 105         *    virtual void OnCameraPreviewed(Tizen::Base::ByteBuffer& previewedData, result r) {
 106         * // Rotates the preview data to use it
 107         *     int rotation = (int)CAMERA_ROTATION_NONE;
 108         *     MediaCapability::GetValue(CAMERA_SECONDARY_ROTATION, rotation);
 109         *
 110         *     ByteBuffer rotatedData;
 111         *     rotatedData.Construct(previewedData.GetLimit());
 112         *
 113         *     switch ((CameraRotation) rotation)
 114         *     {
 115         *             case CAMERA_ROTATION_90:
 116         *                     ImageUtil::Rotate(previewedData, rotatedData,
 117         *                                 Dimension(__previewWidth, __previewHeight), IMAGE_ROTATION_90, MEDIA_PIXEL_FORMAT_YUV420P);
 118         *                     break;
 119         *
 120         *             case CAMERA_ROTATION_180:
 121         *                     ImageUtil::Rotate(previewedData, rotatedData,
 122         *                                 Dimension(__previewWidth, __previewHeight), IMAGE_ROTATION_180, MEDIA_PIXEL_FORMAT_YUV420P);
 123         *                     break;
 124         *
 125         *             case CAMERA_ROTATION_270:
 126         *                     ImageUtil::Rotate(previewedData, rotatedData,
 127         *                                 Dimension(__previewWidth, __previewHeight), IMAGE_ROTATION_270, MEDIA_PIXEL_FORMAT_YUV420P);
 128         *                     break;
 129         *
 130         *             default:
 131         *                     break;
 132         *     }
 133         * }
 134         *
 135         * private:
 136         * int __previewWidth;
 137         * int __previewHeight;
 138         * };
 139         // Normally Camera::SetFlip(CAMERA_FLIP_VERTICAL) is used when using the front camera.
 140         // Remember that the OverlayRegion method rotates the visible region internally corresponding to the form's orientation.
 141         // An application does not need to rotate the visible region explicitly.
 142         // However, the preview data itself is not rotated. If an application wants to rotate the preview data, the data must be rotated like above.
 143         // The width and height changes according to the degree of rotation.
 144         * @endcode
 145         */
 146         virtual void OnCameraPreviewed(Tizen::Base::ByteBuffer& previewedData, result r) = 0;
 147
 148    /**
 149         * Called when the %Camera::Capture() method is completed.
 150         *
 151         * @since                2.0
 152         *
 153         * @param[in]     capturedData                   The image data captured by the camera @n
 154         *                                                                               The captured data format is the same as the format
 155         *                                                                           set by Camera::SetCaptureFormat().
 156         * @param[in]     r                                              The cause of the error
 157         * @exception     E_SUCCESS                              The method is successful.
 158         * @exception     E_INVALID_DATA                 The Tizen::Base::ByteBuffer contains invalid data.
 159         * @see                  Camera::Capture()
 160     * @see               Camera::GetCaptureFormat()
 161         */
 162         virtual void OnCameraCaptured(Tizen::Base::ByteBuffer& capturedData, result r) = 0;
 163
 164    /**
 165         * Called when an error occurs in Camera.
 166         *
 167         * @since                2.0
 168         *
 169         * @param[in]    r               The camera error @n
 170         *                                               This is one of the ::CameraErrorReason values.
 171         * @remarks
 172         *                               - The @c CAMERA_ERROR_DEVICE_FAILED error occurs when the camera device
 173         *                               has a problem, such as damaged shape or hardware malfunction.
 174         *                               - The @c CAMERA_ERROR_DEVICE_INTERRUPTED error occurs when the camera
 175         *                               device is interrupted by another request, such as an incoming
 176         *                               video telephony call.
 177         *                               - In this method, the application calls the Camera::PowerOff()
 178         *                               method to reset the camera device.
 179         */
 180         virtual void OnCameraErrorOccurred(CameraErrorReason r) = 0;
 181
 182 protected:
 183         //
 184         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 185         //
 186         // This method is reserved and may change its name at any time without prior notice.
 187         //
 188         // @since               2.0
 189         //
 190         virtual void ICameraEventListener_Reserved1(void) {}
 191
 192         //
 193         // This method is for internal use only. Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 194         //
 195         // This method is reserved and may change its name at any time without prior notice.
 196         //
 197         // @since               2.0
 198         //
 199         virtual void ICameraEventListener_Reserved2(void) {}
 200
 201 };
 202
 203 }}// Tizen::Media
 204
 205 #endif