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 OverlayRegionSample.h
 113 #include <FGraphics.h>
 114 #include <FMedia.h>
 115 #include <FUi.h>
 116
 117 class OverlayRegionSample
 118         : public Tizen::Ui::Controls::Form
 119         , public Tizen::Media::IPlayerEventListener
 120 {
 121 public:
 122         OverlayRegionSample(void)
 123         : __pPlayer(null)
 124         , __pOverlayRegion(null)
 125         , __pOverlayPanel(null){}
 126
 127         bool Initialize(void);
 128         virtual result OnInitializing(void);
 129         virtual result OnTerminating(void);
 130
 131         // IPlayerEventListener
 132         virtual void OnPlayerOpened(result r);
 133         virtual void OnPlayerEndOfClip(void);
 134         virtual void OnPlayerSeekCompleted(result r);
 135         virtual void OnPlayerBuffering(int percent);
 136         virtual void OnPlayerErrorOccurred(const Tizen::Media::PlayerErrorReason r);
 137         virtual void OnPlayerInterrupted(void);
 138         virtual void OnPlayerReleased(void);
 139
 140 private:
 141         Tizen::Media::Player* __pPlayer;
 142         Tizen::Ui::Controls::OverlayRegion*__pOverlayRegion;
 143         Tizen::Ui::Controls::Panel* __pOverlayPanel;
 144 };
 145  *      @endcode
 146  *
 147  *      @code
 148 //Sample code for OverlayRegionSample.cpp
 149 #include <FApp.h>
 150
 151 #include "OverlayRegionSample.h"
 152
 153 using namespace Tizen::App;
 154 using namespace Tizen::Base;
 155 using namespace Tizen::Graphics;
 156 using namespace Tizen::Media;
 157 using namespace Tizen::Ui::Controls;
 158
 159 bool
 160 OverlayRegionSample::Initialize(void)
 161 {
 162         Construct(FORM_STYLE_NORMAL);
 163         return true;
 164 }
 165
 166 result
 167 OverlayRegionSample::OnInitializing(void)
 168 {
 169         result r = E_SUCCESS;
 170
 171         // Sets an overlay region area
 172         int widthVideo = 480;
 173         int HeightVideo = 320;
 174         int positionX = (GetClientAreaBounds().width - 480) / 2;
 175         int positionY = (GetClientAreaBounds().width - 480) / 2;
 176         Rectangle overlayRectangle(positionX, positionY, widthVideo, HeightVideo);
 177
 178         // Gets an overlay region
 179         __pOverlayRegion = GetOverlayRegionN(overlayRectangle,  OVERLAY_REGION_TYPE_NORMAL);
 180
 181         // Gets buffer information
 182         BufferInfo bufferInfo;
 183         __pOverlayRegion->GetBackgroundBufferInfo(bufferInfo);
 184
 185         // Gets a video file path
 186         String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"tizen.mp4";
 187
 188         // Creates an instance of Player
 189         __pPlayer = new Player();
 190         __pPlayer->Construct(*this, &bufferInfo);
 191         __pPlayer->SetLooping(true);
 192         __pPlayer->OpenFile(videoFilePath);
 193         __pPlayer->Play();
 194
 195         // Creates an instance of Panel which is overlaid with overlay region
 196         __pOverlayPanel = new Panel();
 197         __pOverlayPanel->Construct(overlayRectangle);
 198         AddControl(*__pOverlayPanel);
 199
 200         // Creates instaces of Button and Label and adds controls to the panel
 201         Label* pLabel = new Label();
 202         pLabel->Construct(Rectangle(0, 0, 400, 80),L"OverlayRegion Sample");
 203         pLabel->SetTextColor(Color::GetColor(COLOR_ID_RED));
 204         __pOverlayPanel->AddControl(*pLabel);
 205
 206         Button* pButton = new Button();
 207         pButton->Construct(Rectangle(widthVideo - 200, HeightVideo - 100, 180, 80),L"BUTTON");
 208         __pOverlayPanel->AddControl(*pButton);
 209
 210         Invalidate(true);
 211
 212         return r;
 213 }
 214
 215 result
 216 OverlayRegionSample::OnTerminating(void)
 217 {
 218         result r = E_SUCCESS;
 219
 220         // Deallocates controls
 221         delete __pPlayer;
 222         delete __pOverlayRegion;
 223
 224         return r;
 225 }
 226
 227 // IPlayerEventListener implementation
 228 void
 229 OverlayRegionSample::OnPlayerOpened(result r)
 230 {
 231         // ....
 232 }
 233
 234 void
 235 OverlayRegionSample::OnPlayerEndOfClip(void)
 236 {
 237         // ....
 238 }
 239
 240 void
 241 OverlayRegionSample::OnPlayerSeekCompleted(result r)
 242 {
 243         // ....
 244 }
 245
 246 void
 247 OverlayRegionSample::OnPlayerBuffering(int percent)
 248 {
 249         // ....
 250 }
 251
 252 void
 253 OverlayRegionSample::OnPlayerErrorOccurred(const PlayerErrorReason r)
 254 {
 255         // ....
 256 }
 257
 258 void
 259 OverlayRegionSample::OnPlayerInterrupted(void)
 260 {
 261         // ....
 262 }
 263
 264 void
 265 OverlayRegionSample::OnPlayerReleased(void)
 266 {
 267         // ....
 268 }
 269  * @endcode
 270  */
 271 class _OSP_EXPORT_ OverlayRegion
 272         : public Tizen::Base::Object
 273 {
 274 public:
 275         /**
 276          * This is the destructor for this class.
 277          * This destructor overrides Tizen::Base::Object::~Object().
 278          *
 279          * @since       2.0
 280          */
 281         virtual ~OverlayRegion(void);
 282
 283         /**
 284          * Gets the position and size of the overlay region.
 285          *
 286          * @since               2.0
 287          *
 288          * @return              An instance of Rectangle that represents the position of the top-left corner, the width, and the height of the overlay region
 289          * @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
 290          *                      point is relative to the top-left corner of the parent form.
 291          *
 292          */
 293         Tizen::Graphics::Rectangle GetBounds(void) const;
 294
 295         /**
 296          * Gets the position and size of the overlay region.
 297          *
 298          * @since               2.1
 299          *
 300          * @return              An instance of FloatRectangle that represents the position of the top-left corner, the width, and the height of the overlay region
 301          * @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
 302          *                      point is relative to the top-left corner of the parent form.
 303          *
 304          */
 305         Tizen::Graphics::FloatRectangle GetBoundsF(void) const;
 306
 307         /**
 308          * Gets the position and size of the overlay region.
 309          *
 310          * @since               2.0
 311          *
 312          * @param[out]  x               The x position of the top-left corner of the overlay region
 313          * @param[out]  y               The y position of the top-left corner of the overlay region
 314          * @param[out]  width   The width of the rectangular region
 315          * @param[out]  height  The height of the rectangular region
 316          * @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
 317          *                      point is relative to the top-left corner of the parent form.
 318          *
 319          */
 320         void GetBounds(int& x, int& y, int& width, int& height) const;
 321
 322         /**
 323          * Gets the position and size of the overlay region.
 324          *
 325          * @since               2.1
 326          *
 327          * @param[out]  x               The x position of the top-left corner of the overlay region
 328          * @param[out]  y               The y position of the top-left corner of the overlay region
 329          * @param[out]  width   The width of the rectangular region
 330          * @param[out]  height  The height of the rectangular region
 331          * @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
 332          *                      point is relative to the top-left corner of the parent form.
 333          *
 334          */
 335         void GetBounds(float& x, float& y, float& width, float& height) const;
 336
 337         /**
 338          * Sets the input buffer. @n
 339          * Due to the hardware accelerated rendering, there are limitations for an input buffer. The input buffer has the same restriction regarding its size as
 340          * the overlay region and it can be checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). If the specified condition is not satisfied,
 341          * 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
 342          * region bounds without keeping the ratio of input.
 343          *
 344          * @since               2.0
 345          *
 346          * @return              An error code
 347          * @param[in]   srcBuffer                               The source buffer
 348          * @param[in]   srcDim                                  The source dimension
 349          * @param[in]   srcFormat                               The pixel format of buffer data
 350          * @exception   E_SUCCESS                               The method is successful.
 351          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 352          * @exception   E_UNSUPPORTED_FORMAT    The specified pixel format is not supported.
 353          * @exception   E_INVALID_OPERATION     The current state of the instance prohibits the execution of the specified operation.
 354          * @exception   E_SYSTEM                                A system error has occurred.
 355          */
 356         result SetInputBuffer(const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, OverlayRegionBufferPixelFormat srcFormat);
 357
 358         /**
 359          * Gets the information related to the background buffer.
 360          *
 361          * @since               2.0
 362          *
 363          * @return              An error code
 364          * @param[out]  info                                    The information of the input buffer
 365          * @exception   E_SUCCESS                               The method is successful.
 366          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 367          * @exception   E_SYSTEM                                A system error has occurred.
 368          * @remarks This method provides the buffer information, except the pointer of a color buffer. Therefore, info.pPixels is always assigned as @c null.
 369          */
 370         result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
 371
 372         /**
 373          * Shows the overlay region on the screen.
 374          *
 375          * @since               2.0
 376          *
 377          * @return              An error code
 378          * @exception   E_SUCCESS                               The method is successful.
 379          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation, that is, this control cannot be displayed.
 380          * @exception   E_SYSTEM                                A system error has occurred.
 381          */
 382         result Show(void);
 383
 384         /**
 385          * Evaluates and returns the valid position and size that are closest to the specified bounds.
 386          *
 387          * @since                                                                       2.0
 388          *
 389          * @return              @c true if the evaluation process does not meet an error, @n
 390          *                              else @c false
 391          * @param[in]           option                                  The option for evaluating the bounds of the overlay region
 392          * @param[in, out]      rect                                    An instance of %Rectangle that represents the validated bounds of %OverlayRegion @n
 393          *                                                                                      The width and height of the input rectangle must be greater than @c 0.
 394          * @param[out]          modified                                A boolean flag that indicates whether the specified @c rectangle is modified
 395          * @exception           E_SUCCESS                               The method is successful.
 396          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
 397          * @exception           E_UNSUPPORTED_OPTION    A specified input parameter is not supported.
 398          * @exception           E_SYSTEM                                A system error has occurred.
 399          * @remarks Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 400          * The hardware capability for an overlay region is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). @n
 401          *                      If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. In
 402          *                      such cases, GetOverlayRegionN() will return E_INVALID_ARG. @n
 403          *          To prevent this kind of problem, the application must use the OverlayRegion::EvaluateBounds() method to get a validated bounds that can be
 404          *                      used as the input bounds of the GetOverlayRegionN() method.
 405          * @remarks The specific error code can be accessed using the GetLastResult() method.
 406          */
 407         static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
 408
 409         /**
 410          * Evaluates and returns the valid position and size that are closest to the specified bounds.
 411          *
 412          * @since                                                                       2.1
 413          *
 414          * @return              @c true if the evaluation process does not meet an error, @n
 415          *                              else @c false
 416          * @param[in]           option                                  The option for evaluating the bounds of the overlay region
 417          * @param[in, out]      rect                                    An instance of %FloatRectangle that represents the validated bounds of %OverlayRegion @n
 418          *                                                                                      The width and height of the input rectangle must be greater than @c 0.
 419          * @param[out]          modified                                A boolean flag that indicates whether the specified @c rectangle is modified
 420          * @exception           E_SUCCESS                               The method is successful.
 421          * @exception           E_INVALID_ARG                   A specified input parameter is invalid.
 422          * @exception           E_UNSUPPORTED_OPTION    A specified input parameter is not supported.
 423          * @exception           E_SYSTEM                                A system error has occurred.
 424          * @remarks Due to the hardware accelerated rendering, there are limitations for an overlay region. @n
 425          * The hardware capability for an overlay region is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount(). @n
 426          *                      If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay region. In
 427          *                      such cases, GetOverlayRegionNF() will return E_INVALID_ARG. @n
 428          *          To prevent this kind of problem, the application must use the OverlayRegion::EvaluateBoundsF() method to get a validated bounds that can be
 429          *                      used as the input bounds of the GetOverlayRegionNF() method.
 430          * @remarks The specific error code can be accessed using the GetLastResult() method.
 431          */
 432         static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
 433
 434         /**
 435          * Gets the value of the width. @n
 436          * Only a multiple of this value can be allowed as the width of an overlay region.
 437          *
 438          * @since               2.0
 439          *
 440          * @return              The value of width
 441          * @exception   E_SUCCESS       The method is successful.
 442          * @exception   E_SYSTEM        A system error has occurred.
 443          * @remarks The specific error code can be accessed using the GetLastResult() method.
 444          */
 445         static int GetWidthUnit(void);
 446
 447         /**
 448          * Gets the value of the height. @n
 449          * Only a multiple of this value can be allowed as the height of an overlay region.
 450          *
 451          * @since               2.0
 452          *
 453          * @return              The value of the height
 454          * @exception   E_SUCCESS       The method is successful.
 455          * @exception   E_SYSTEM        A system error has occurred.
 456          * @remarks The specific error code can be accessed using the GetLastResult() method.
 457          */
 458         static int GetHeightUnit(void);
 459
 460         /**
 461          * Gets the maximum count of overlay regions that can be used simultaneously per application.
 462          *
 463          * @since               2.0
 464          *
 465          * @return              The maximum count of overlay regions that can be used simultaneously per application
 466          * @exception   E_SUCCESS       The method is successful.
 467          * @exception   E_SYSTEM        A system error has occurred.
 468          * @remarks The specific error code can be accessed using the GetLastResult() method.
 469          */
 470         static int GetMaxCount(void);
 471
 472         /**
 473          * Gets the BufferPixelFormat list for the %OverlayRegion class. @n
 474          * Each list item has a Tizen::UI::Controls::OverlayRegionBufferPixelFormat value.
 475          *
 476          * @since 2.0
 477          *
 478          * @return              A list of the pixel formats supported by the %OverlayRegion class, @n
 479          *                              else @c null if no pixel format is supported or an exception occurs
 480          * @exception   E_SUCCESS                               The method is successful.
 481          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 482          * @remark              The specific error code can be accessed using the GetLastResult() method. @n
 483          *                              The return value and each item in the list must be deleted by the caller. @n
 484          *                              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
 485          */
 486         static Tizen::Base::Collection::IListT< OverlayRegionBufferPixelFormat >* GetSupportedBufferPixelFormatListN(void);
 487
 488 private:
 489         //
 490         // This default constructor is intentionally declared as private so that only the platform can create an instance.
 491         //
 492         // @since               2.0
 493         //
 494         OverlayRegion(void);
 495
 496         //
 497         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 498         //
 499         OverlayRegion(const OverlayRegion& rhs);
 500
 501         //
 502         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 503         //
 504         OverlayRegion& operator =(const OverlayRegion& rhs);
 505
 506 private:
 507         class _OverlayRegionImpl * __pOverlayRegionImpl;
 508
 509         friend class _OverlayRegionImpl;
 510
 511 }; // OverlayRegion
 512
 513 }}} // Tizen::Ui::Controls
 514
 515 #endif // _FUI_CTRL_OVERLAY_CONTROL_H_