dali/public-api/capture/capture.h

   1 #ifndef DALI_CAPTURE_H
   2 #define DALI_CAPTURE_H
   3
   4 /*
   5  * Copyright (c) 2018 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL HEADERS
  22 #include <dali/public-api/actors/actor.h>
  23 #include <dali/public-api/signals/dali-signal.h>
  24 #include <dali/public-api/actors/camera-actor.h>
  25
  26 namespace Dali
  27 {
  28
  29 /**
  30  * @addtogroup dali_adaptor_framework
  31  * @{
  32  */
  33
  34 namespace Internal DALI_INTERNAL
  35 {
  36 namespace Adaptor
  37 {
  38 class Capture;
  39 }
  40 }
  41
  42 /**
  43  * @brief Capture snapshots the current scene and save as a file.
  44  *
  45  * @SINCE_1_3_4
  46  *
  47  * Applications should follow the example below to create capture :
  48  *
  49  * @code
  50  * Capture capture = Capture::New();
  51  * @endcode
  52  *
  53  * If required, you can also connect class member function to a signal :
  54  *
  55  * @code
  56  * capture.FinishedSignal().Connect(this, &CaptureSceneExample::OnCaptureFinished);
  57  * @endcode
  58  *
  59  * At the connected class member function, you can know whether capture finish state.
  60  *
  61  * @code
  62  * void CaptureSceneExample::OnCaptureFinished( Capture capture, Capture::FinishState state )
  63  * {
  64  *   if ( state == Capture::FinishState::SUCCEEDED )
  65  *   {
  66  *     // Do something
  67  *   }
  68  *   else
  69  *   {
  70  *     // Do something
  71  *   }
  72  * }
  73  * @endcode
  74  */
  75 class DALI_ADAPTOR_API Capture : public BaseHandle
  76 {
  77
  78 public:
  79
  80   /**
  81    * @brief The enumerations used for checking capture success
  82    * @SINCE_1_3_4
  83    */
  84   enum class FinishState
  85   {
  86     SUCCEEDED, ///< Succeeded in saving the result after capture
  87     FAILED     ///< Failed to capture by time out or to save the result
  88   };
  89
  90   /**
  91    * @brief Typedef for finished signals sent by this class.
  92    *
  93    * @SINCE_1_3_4
  94    */
  95   typedef Signal< void ( Capture, Capture::FinishState ) > CaptureFinishedSignalType;
  96
  97   /**
  98    * @brief Create an uninitialized Capture; this can be initialized with Actor::New().
  99    *
 100    * @SINCE_1_3_4
 101    *
 102    * Calling member functions with an uninitialized Dali::Object is not allowed.
 103    */
 104   Capture();
 105
 106   /**
 107    * @brief Create an initialized Capture.
 108    *
 109    * @SINCE_1_3_4
 110    *
 111    * @return A handle to a newly allocated Dali resource.
 112    * @note Projection mode of default cameraActor is Dali::Camera::PERSPECTIVE_PROJECTION
 113    */
 114   static Capture New();
 115
 116   /**
 117    * @brief Create an initialized Capture.
 118    *
 119    * @SINCE_1_3_4
 120    *
 121    * @param[in] cameraActor An initialized CameraActor.
 122    * @return A handle to a newly allocated Dali resource.
 123    */
 124   static Capture New( Dali::CameraActor cameraActor );
 125
 126   /**
 127    * @brief Downcast an Object handle to Capture handle.
 128    *
 129    * @SINCE_1_3_4
 130    *
 131    * If handle points to a Capture object the downcast produces valid
 132    * handle. If not the returned handle is left uninitialized.
 133    *
 134    * @param[in] handle to An object.
 135    * @return handle to a Capture object or an uninitialized handle.
 136    */
 137   static Capture DownCast( BaseHandle handle );
 138
 139   /**
 140    * @brief Dali::Actor is intended as a base class.
 141    *
 142    * @SINCE_1_3_4
 143    *
 144    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 145    */
 146   ~Capture();
 147
 148   /**
 149    * @brief This copy constructor is required for (smart) pointer semantics.
 150    *
 151    * @SINCE_1_3_4
 152    *
 153    * @param[in] copy A reference to the copied handle.
 154    */
 155   Capture( const Capture& copy );
 156
 157   /**
 158    * @brief This assignment operator is required for (smart) pointer semantics.
 159    *
 160    * @SINCE_1_3_4
 161    *
 162    * @param[in] rhs  A reference to the copied handle.
 163    * @return A reference to this.
 164    */
 165   Capture& operator=( const Capture& rhs );
 166
 167   /**
 168    * @brief Start capture and save the image as a file.
 169    *
 170    * @SINCE_1_3_4
 171    *
 172    * @param[in] source source actor to be used for capture.
 173    * @param[in] size captured size.
 174    * @param[in] path image file path to be saved as a file.
 175    * @param[in] clearColor background color of captured scene
 176    */
 177   void Start( Actor source, const Vector2& size, const std::string &path, const Vector4& clearColor );
 178
 179   /**
 180    * @brief Start capture and save the image as a file.
 181    *
 182    * @SINCE_1_3_4
 183    *
 184    * @param[in] source source actor to be used for capture.
 185    * @param[in] size captured size.
 186    * @param[in] path image file path to be saved as a file.
 187    * @note Clear color is transparent.
 188    */
 189   void Start( Actor source, const Vector2& size, const std::string &path );
 190
 191   /**
 192    * @brief Get finished signal.
 193    *
 194    * @SINCE_1_3_4
 195    *
 196    * @return finished signal instance.
 197    */
 198   CaptureFinishedSignalType& FinishedSignal();
 199
 200 public: // Not intended for application developers
 201   /// @cond internal
 202   /**
 203    * @brief This constructor is used by New() methods.
 204    *
 205    * @SINCE_1_3_4
 206    *
 207    * @param[in] internal A pointer to a newly allocated Dali resource.
 208    */
 209   explicit DALI_INTERNAL Capture( Internal::Adaptor::Capture* internal );
 210   /// @endcond
 211 };
 212
 213 /**
 214  * @}
 215  */
 216
 217 } // namespace Dali
 218
 219 #endif // DALI_CAPTURE_H