inc/FUiCtrlOverlayRegion.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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        FUiCtrlOverlayRegion.h
  20  * @brief   This is the header file for the %OverlayRegion class.
  21  *
  22  * This header file contains the declarations of the %OverlayRegion class.
  23  */
  24
  25 #ifndef _FUI_CTRL_OVERLAY_REGION_H_
  26 #define _FUI_CTRL_OVERLAY_REGION_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseColArrayListT.h>
  30
  31 namespace Tizen { namespace Base
  32 {
  33 class ByteBuffer;
  34 }} // Tizen::Base
  35
  36 namespace Tizen { namespace Graphics
  37 {
  38 class Point;
  39 class Dimension;
  40 class Rectangle;
  41 class FloatRectangle;
  42 class BufferInfo;
  43 }} // Tizen::Graphics
  44
  45 namespace Tizen { namespace Ui { namespace Controls
  46 {
  47
  48 /**
  49  * @enum OverlayRegionBufferPixelFormat
  50  *
  51  * Defines the pixel formats.
  52  *
  53  * @since       2.0
  54  */
  55 enum OverlayRegionBufferPixelFormat
  56 {
  57         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_ARGB8888 = 1,        /**< The ARGB8888 pixel format */
  58         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_RGB565,          /**< The RGB565 pixel format */
  59         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_YCbCr420_PLANAR, /**< The 8-bit Y plane followed by the 8-bit 2x2 subsampled U and V planes */
  60         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_NV12,                /**< The NV12 pixel format */
  61         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_UYVY,                /**< The UYVY pixel format */
  62         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_MAX,              // This enum value is for internal use only. Using this enum value can cause behavioral, security-related, and consistency-related issues in the application.
  63         OVERLAY_REGION_BUFFER_PIXEL_FORMAT_MIN = 0         // This enum value is for internal use only. Using this enum value can cause behavioral, security-related, and consistency-related issues in the application.
  64 };
  65
  66 /**
  67  * @enum OverlayRegionType
  68  *
  69  * Defines the type of an overlay region.
  70  *
  71  * @since       2.0
  72  */
  73 enum OverlayRegionType
  74 {
  75         OVERLAY_REGION_TYPE_PRIMARY_CAMERA = 1,                 /**< The primary camera type @n
  76                                                                             An overlay region displays the auto-rotated primary camera input that comes from Camera. */
  77         OVERLAY_REGION_TYPE_SECONDARY_CAMERA,               /**< The secondary camera type @n
  78                                                                             An overlay region displays the auto-rotated and mirrored secondary camera input that comes from Camera. */
  79         OVERLAY_REGION_TYPE_NORMAL,                         /**< The normal type @n
  80                                                                             An overlay region displays the user input as it is. */
  81         OVERLAY_REGION_TYPE_MAX,                             // This enum value is for internal use only. Using this enum value can cause behavioral, security-related, and consistency-related issues in the application.
  82         OVERLAY_REGION_TYPE_MIN = 0                          // This enum value is for internal use only. Using this enum value can cause behavioral, security-related, and consistency-related issues in the application.
  83 };
  84
  85 /**
  86  * @enum OverlayRegionEvaluationOption
  87  *
  88  * Defines the option for evaluating the bounds of an overlay region.
  89  *
  90  * @since       2.0
  91  */
  92 enum OverlayRegionEvaluationOption
  93 {
  94         OVERLAY_REGION_EVALUATION_OPTION_GREATER_THAN,  /**< The option evaluating the overlay region bounds and finding the minimum bounds greater than the input bounds */
  95         OVERLAY_REGION_EVALUATION_OPTION_LESS_THAN,     /**< The option evaluating the overlay region bounds and finding the maximum bounds smaller than input bounds */
  96 };
  97
  98
  99 /**
 100  * @class       OverlayRegion
 101  * @brief       This class is an implementation of an %OverlayRegion.
 102  *
 103  * @since       2.0
 104  *
 105  * @final       This class is not intended for extension.
 106  *
 107  * The %OverlayRegion class displays a region of an overlay surface, which is used to play back a video or show the camera preview.
 108  * @n
 109  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_overlay_region.htm">OverlayRegion</a>.
 110  *
 111  * @code
 112 //Sample code for OverlayRegionSampleForm.h
 113 #include <FGraphics.h>
 114 #include <FMedia.h>
 115 #include <FUi.h>
 116
 117 class OverlayRegionSampleForm
 118         : public Tizen::Ui::Controls::Form
 119         , public Tizen::Media::IPlayerEventListener
 120 {
 121 public:
 122         OverlayRegionSampleForm(void);
 123         virtual ~OverlayRegionSampleForm(void);
 124
 125         bool Initialize(void);
 126         virtual result OnInitializing(void);
 127         virtual result OnTerminating(void);
 128
 129         // IPlayerEventListener
 130         virtual void OnPlayerOpened(result r);
 131         virtual void OnPlayerEndOfClip(void);
 132         virtual void OnPlayerSeekCompleted(result r);
 133         virtual void OnPlayerBuffering(int percent);
 134         virtual void OnPlayerErrorOccurred(const Tizen::Media::PlayerErrorReason r);
 135         virtual void OnPlayerInterrupted(void);
 136         virtual void OnPlayerReleased(void);
 137
 138 private:
 139         Tizen::Ui::Controls::Panel* __pOverlayRegionSamplePanel;
 140         Tizen::Ui::Controls::OverlayRegion*__pOverlayRegion;
 141         Tizen::Media::Player* __pPlayer;
 142 };
 143  *      @endcode
 144  *
 145  *      @code
 146 //Sample code for OverlayRegionSampleForm.cpp
 147 #include <FApp.h>
 148 #include "OverlayRegionSampleForm.h"
 149
 150 using namespace Tizen::App;
 151 using namespace Tizen::Base;
 152 using namespace Tizen::Graphics;
 153 using namespace Tizen::Media;
 154 using namespace Tizen::Ui::Controls;
 155
 156 OverlayRegionSampleForm::OverlayRegionSampleForm(void)
 157         : __pOverlayRegionSamplePanel(null)
 158         , __pOverlayRegion(null)
 159         , __pPlayer(null)
 160 {
 161 }
 162
 163 OverlayRegionSampleForm::~OverlayRegionSampleForm(void)
 164 {
 165 }
 166
 167 bool
 168 OverlayRegionSampleForm::Initialize(void)
 169 {
 170         Construct(FORM_STYLE_NORMAL);
 171         return true;
 172 }
 173
 174 result
 175 OverlayRegionSampleForm::OnInitializing(void)
 176 {
 177         result r = E_SUCCESS;
 178
 179         // Sets an overlay region area
 180         int widthVideo = 480;
 181         int HeightVideo = 320;
 182         int positionX = (GetClientAreaBounds().width - 480) / 2;
 183         int positionY = (GetClientAreaBounds().width - 480) / 2;
 184         Rectangle overlayRectangle(positionX, positionY, widthVideo, HeightVideo);
 185
 186         // Evaluates bounds of overlay region
 187         bool modified = false;
 188         OverlayRegion::EvaluateBounds(OVERLAY_REGION_EVALUATION_OPTION_GREATER_THAN, overlayRectangle, modified);
 189
 190         // Gets an overlay region
 191         __pOverlayRegion = GetOverlayRegionN(overlayRectangle, OVERLAY_REGION_TYPE_NORMAL);
 192
 193         // Gets buffer information
 194         BufferInfo bufferInfo;
 195         __pOverlayRegion->GetBackgroundBufferInfo(bufferInfo);
 196
 197         // Gets a video file path
 198         String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"tizen.mp4";
 199
 200         // Creates an instance of Player
 201         __pPlayer = new Player();
 202         __pPlayer->Construct(*this, &bufferInfo);
 203         __pPlayer->SetLooping(true);
 204         __pPlayer->OpenFile(videoFilePath);
 205         __pPlayer->Play();
 206
 207         // Creates instaces of Button and Label and adds controls to the panel
 208         Label* pLabel = new Label();
 209         pLabel->Construct(Rectangle(positionX, positionY, 400, 80),L"OverlayRegion Sample");
 210         pLabel->SetTextColor(Color::GetColor(COLOR_ID_RED));
 211         AddControl(*pLabel);
 212
 213         Button* pButton = new Button();
 214         pButton->Construct(Rectangle(positionX + widthVideo - 200, positionX + HeightVideo - 100, 180, 80),L"BUTTON");
 215         AddControl(*pButton);
 216
 217         return r;
 218 }
 219
 220 result
 221 OverlayRegionSampleForm::OnTerminating(void)
 222 {
 223         result r = E_SUCCESS;
 224
 225         // Deallocates controls
 226         if (__pPlayer)
 227         {
 228                 r = __pPlayer->Close();
 229                 delete __pPlayer;
 230         }
 231
 232         return r;
 233 }
 234
 235 // IPlayerEventListener implementation
 236 void
 237 OverlayRegionSampleForm::OnPlayerOpened(result r)
 238 {
 239         // ....
 240 }
 241
 242 void
 243 OverlayRegionSampleForm::OnPlayerEndOfClip(void)
 244 {
 245         // ....
 246 }
 247
 248 void
 249 OverlayRegionSampleForm::OnPlayerSeekCompleted(result r)
 250 {
 251         // ....
 252 }
 253
 254 void
 255 OverlayRegionSampleForm::OnPlayerBuffering(int percent)
 256 {
 257         // ....
 258 }
 259
 260 void
 261 OverlayRegionSampleForm::OnPlayerErrorOccurred(const PlayerErrorReason r)
 262 {
 263         // ....
 264 }
 265
 266 void
 267 OverlayRegionSampleForm::OnPlayerInterrupted(void)
 268 {
 269         // ....
 270 }
 271
 272 void
 273 OverlayRegionSampleForm::OnPlayerReleased(void)
 274 {
 275         // ....
 276 }
 277  * @endcode
 278  */
 279 class _OSP_EXPORT_ OverlayRegion
 280         : public Tizen::Base::Object
 281 {
 282 public:
 283         /**
 284          * This is the destructor for this class.
 285          * This destructor overrides Tizen::Base::Object::~Object().
 286          *
 287          * @since       2.0
 288          */
 289         virtual ~OverlayRegion(void);
 290
 291         /**
 292          * Gets the position and size of the overlay region.
 293          *
 294          * @since               2.0
 295          *
 296          * @return              An instance of Rectangle that represents the position of the top-left corner, the width, and the height of the overlay region
 297          * @remarks     The shape of an overlay region is rectangular, which is defined by the top-left point, and the width or height. The position of the top-left
 298          *                      point is relative to the top-left corner of the parent form.
 299          *
 300          */
 301         Tizen::Graphics::Rectangle GetBounds(void) const;
 302
 303         /**
 304          * Gets the position and size of the overlay region.
 305          *
 306          * @since               2.1
 307          *
 308          * @return              An instance of FloatRectangle that represents the position of the top-left corner, the width, and the height of the overlay region
 309          * @remarks     The shape of an overlay region is rectangular, which is defined by the top-left point, and the width or height. The position of the top-left
 310          *                      point is relative to the top-left corner of the parent form.
 311          *
 312          */
 313         Tizen::Graphics::FloatRectangle GetBoundsF(void) const;
 314
 315         /**
 316          * Gets the position and size of the overlay region.
 317          *
 318          * @since               2.0
 319          *
 320          * @param[out]  x               The x position of the top-left corner of the overlay region
 321          * @param[out]  y               The y position of the top-left corner of the overlay region
 322          * @param[out]  width   The width of the rectangular region
 323          * @param[out]  height  The height of the rectangular region
 324          * @remarks     The shape of an overlay region is rectangular, which is defined by the top-left point, and the width or height. The position of the top-left
 325          *                      point is relative to the top-left corner of the parent form.
 326          *
 327          */
 328         void GetBounds(int& x, int& y, int& width, int& height) const;
 329
 330         /**
 331          * Gets the position and size of the overlay region.
 332          *
 333          * @since               2.1
 334          *
 335          * @param[out]  x               The x position of the top-left corner of the overlay region
 336          * @param[out]  y               The y position of the top-left corner of the overlay region
 337          * @param[out]  width   The width of the rectangular region
 338          * @param[out]  height  The height of the rectangular region
 339          * @remarks     The shape of an overlay region is rectangular, which is defined by the top-left point, and the width or height. The position of the top-left
 340          *                      point is relative to the top-left corner of the parent form.
 341          *
 342          */
 343         void GetBounds(float& x, float& y, float& width, float& height) const;
 344
 345         /**
 346          * Sets the input buffer. @n
 347          * Due to the hardware accelerated rendering, there are limitations for an input buffer. The input buffer has the same restriction regarding its size as
 348          * the overlay region and it can be checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). If the specified condition is not satisfied,
 349          * the E_INVALID_ARG exception is returned. If an input buffer does not fit to the bounds of the overlay region, it will be scaled up or down to the overlay
 350          * region bounds without keeping the ratio of input.
 351          *
 352          * @since               2.0
 353          *
 354          * @return              An error code
 355          * @param[in]   srcBuffer                               The source buffer
 356          * @param[in]   srcDim                                  The source dimension
 357          * @param[in]   srcFormat                               The pixel format of buffer data
 358          * @exception   E_SUCCESS                               The method is successful.
 359          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 360          * @exception   E_UNSUPPORTED_FORMAT    The specified pixel format is not supported.
 361          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 362          * @exception   E_SYSTEM                                A system error has occurred.
 363          */
 364         result SetInputBuffer(const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, OverlayRegionBufferPixelFormat srcFormat);
 365
 366         /**
 367          * Gets the information related to the background buffer.
 368          *
 369          * @since               2.0
 370          *
 371          * @return              An error code
 372          * @param[out]  info                                    The information of the input buffer
 373          * @exception   E_SUCCESS                               The method is successful.
 374          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 375          * @exception   E_SYSTEM                                A system error has occurred.
 376          * @remarks This method provides the buffer information, except the pointer of a color buffer. Therefore, info.pPixels is always assigned as @c null.
 377          */
 378         result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
 379
 380         /**
 381          * Shows the overlay region on the screen.
 382          *
 383          * @since               2.0
 384          *
 385          * @return              An error code
 386          * @exception   E_SUCCESS                               The method is successful.
 387          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, that is, this control cannot be displayed.
 388          * @exception   E_SYSTEM                                A system error has occurred.
 389          */
 390         result Show(void);
 391
 392         /**
 393          * Evaluates and returns the valid position and size that are closest to the specified bounds.
 394          *
 395          * @since                                                                       2.0
 396          *
 397          * @return              @c true if the evaluation process does not meet an error, @n
 398          *                              else @c false
 399          * @param[in]           option                                  The option for evaluating the bounds of the overlay region
 400          * @param[in, out]      rect                                    An instance of %Rectangle that represents the validated bounds of %OverlayRegion @n
 401          *                                                                                      The width and height of the input rectangle must be greater than @c 0.
 402          * @param[out]          modified                                A boolean flag that indicates whether the specified @c rectangle is modified
 403          * @exception           E_SUCCESS                               The method is successful.
 404          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
 405          * @exception           E_UNSUPPORTED_OPTION    A specified input parameter is not supported.
 406          * @exception           E_SYSTEM                                A system error has occurred.
 407          * @remarks Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 408          * The hardware capability for an overlay region is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). @n
 409          *                      If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. In
 410          *                      such cases, GetOverlayRegionN() will return E_INVALID_ARG. @n
 411          *          To prevent this kind of problem, the application must use the OverlayRegion::EvaluateBounds() method to get a validated bounds that can be
 412          *                      used as the input bounds of the GetOverlayRegionN() method.
 413          * @remarks The specific error code can be accessed using the GetLastResult() method.
 414          */
 415         static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
 416
 417         /**
 418          * Evaluates and returns the valid position and size that are closest to the specified bounds.
 419          *
 420          * @since                                                                       2.1
 421          *
 422          * @return              @c true if the evaluation process does not meet an error, @n
 423          *                              else @c false
 424          * @param[in]           option                                  The option for evaluating the bounds of the overlay region
 425          * @param[in, out]      rect                                    An instance of %FloatRectangle that represents the validated bounds of %OverlayRegion @n
 426          *                                                                                      The width and height of the input rectangle must be greater than @c 0.
 427          * @param[out]          modified                                A boolean flag that indicates whether the specified @c rectangle is modified
 428          * @exception           E_SUCCESS                               The method is successful.
 429          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
 430          * @exception           E_UNSUPPORTED_OPTION    A specified input parameter is not supported.
 431          * @exception           E_SYSTEM                                A system error has occurred.
 432          * @remarks Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 433          * The hardware capability for an overlay region is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). @n
 434          *                      If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. In
 435          *                      such cases, GetOverlayRegionNF() will return E_INVALID_ARG. @n
 436          *          To prevent this kind of problem, the application must use the OverlayRegion::EvaluateBoundsF() method to get a validated bounds that can be
 437          *                      used as the input bounds of the GetOverlayRegionNF() method.
 438          * @remarks The specific error code can be accessed using the GetLastResult() method.
 439          */
 440         static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
 441
 442         /**
 443          * Gets the value of the width. @n
 444          * Only a multiple of this value can be allowed as the width of an overlay region.
 445          *
 446          * @since               2.0
 447          *
 448          * @return              The value of width
 449          * @exception   E_SUCCESS       The method is successful.
 450          * @exception   E_SYSTEM        A system error has occurred.
 451          * @remarks The specific error code can be accessed using the GetLastResult() method.
 452          */
 453         static int GetWidthUnit(void);
 454
 455         /**
 456          * Gets the value of the height. @n
 457          * Only a multiple of this value can be allowed as the height of an overlay region.
 458          *
 459          * @since               2.0
 460          *
 461          * @return              The value of the height
 462          * @exception   E_SUCCESS       The method is successful.
 463          * @exception   E_SYSTEM        A system error has occurred.
 464          * @remarks The specific error code can be accessed using the GetLastResult() method.
 465          */
 466         static int GetHeightUnit(void);
 467
 468         /**
 469          * Gets the maximum count of overlay regions that can be used simultaneously per application.
 470          *
 471          * @since               2.0
 472          *
 473          * @return              The maximum count of overlay regions that can be used simultaneously per application
 474          * @exception   E_SUCCESS       The method is successful.
 475          * @exception   E_SYSTEM        A system error has occurred.
 476          * @remarks The specific error code can be accessed using the GetLastResult() method.
 477          */
 478         static int GetMaxCount(void);
 479
 480         /**
 481          * Gets the BufferPixelFormat list for the %OverlayRegion class. @n
 482          * Each list item has a Tizen::UI::Controls::OverlayRegionBufferPixelFormat value.
 483          *
 484          * @since 2.0
 485          *
 486          * @return              A list of the pixel formats supported by the %OverlayRegion class, @n
 487          *                              else @c null if no pixel format is supported or an exception occurs
 488          * @exception   E_SUCCESS                               The method is successful.
 489          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 490          * @remark              The specific error code can be accessed using the GetLastResult() method. @n
 491          *                              The return value and each item in the list must be deleted by the caller. @n
 492          *                              The format list can vary depending on the device. After checking the supported formats using this API, it's better to use a proper pixel format. @n
 493          */
 494         static Tizen::Base::Collection::IListT< OverlayRegionBufferPixelFormat >* GetSupportedBufferPixelFormatListN(void);
 495
 496 private:
 497         //
 498         // This default constructor is intentionally declared as private so that only the platform can create an instance.
 499         //
 500         // @since               2.0
 501         //
 502         OverlayRegion(void);
 503
 504         //
 505         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 506         //
 507         OverlayRegion(const OverlayRegion& rhs);
 508
 509         //
 510         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 511         //
 512         OverlayRegion& operator =(const OverlayRegion& rhs);
 513
 514 private:
 515         class _OverlayRegionImpl * __pOverlayRegionImpl;
 516
 517         friend class _OverlayRegionImpl;
 518
 519 }; // OverlayRegion
 520
 521 }}} // Tizen::Ui::Controls
 522
 523 #endif // _FUI_CTRL_OVERLAY_CONTROL_H_