inc/FUiCtrlOverlayRegion.h

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