2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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.
19 * @file FUiCtrlOverlayRegion.h
20 * @brief This is the header file for the %OverlayRegion class.
22 * This header file contains the declarations of the %OverlayRegion class.
25 #ifndef _FUI_CTRL_OVERLAY_REGION_H_
26 #define _FUI_CTRL_OVERLAY_REGION_H_
28 #include <FBaseObject.h>
29 #include <FBaseColArrayListT.h>
31 namespace Tizen { namespace Base
36 namespace Tizen { namespace Graphics
45 namespace Tizen { namespace Ui { namespace Controls
49 * @enum OverlayRegionBufferPixelFormat
51 * Defines the pixel formats.
55 enum OverlayRegionBufferPixelFormat
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.
67 * @enum OverlayRegionType
69 * Defines the type of an overlay region.
73 enum OverlayRegionType
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.
86 * @enum OverlayRegionEvaluationOption
88 * Defines the option for evaluating the bounds of an overlay region.
92 enum OverlayRegionEvaluationOption
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 */
100 * @class OverlayRegion
101 * @brief This class is an implementation of an %OverlayRegion.
105 * @final This class is not intended for extension.
107 * The %OverlayRegion class displays a region of an overlay surface, which is used to play back a video or show the camera preview.
109 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_overlay_region.htm">OverlayRegion</a>.
112 //Sample code for OverlayRegionSampleForm.h
113 #include <FGraphics.h>
117 class OverlayRegionSampleForm
118 : public Tizen::Ui::Controls::Form
119 , public Tizen::Media::IPlayerEventListener
122 OverlayRegionSampleForm(void);
123 virtual ~OverlayRegionSampleForm(void);
125 bool Initialize(void);
126 virtual result OnInitializing(void);
127 virtual result OnTerminating(void);
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);
139 Tizen::Ui::Controls::Panel* __pOverlayRegionSamplePanel;
140 Tizen::Ui::Controls::OverlayRegion*__pOverlayRegion;
141 Tizen::Media::Player* __pPlayer;
146 //Sample code for OverlayRegionSampleForm.cpp
148 #include "OverlayRegionSampleForm.h"
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;
156 OverlayRegionSampleForm::OverlayRegionSampleForm(void)
157 : __pOverlayRegionSamplePanel(null)
158 , __pOverlayRegion(null)
163 OverlayRegionSampleForm::~OverlayRegionSampleForm(void)
168 OverlayRegionSampleForm::Initialize(void)
170 Construct(FORM_STYLE_NORMAL);
175 OverlayRegionSampleForm::OnInitializing(void)
177 result r = E_SUCCESS;
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);
186 // Evaluates bounds of overlay region
187 bool modified = false;
188 OverlayRegion::EvaluateBounds(OVERLAY_REGION_EVALUATION_OPTION_GREATER_THAN, overlayRectangle, modified);
190 // Gets an overlay region
191 __pOverlayRegion = GetOverlayRegionN(overlayRectangle, OVERLAY_REGION_TYPE_NORMAL);
193 // Gets buffer information
194 BufferInfo bufferInfo;
195 __pOverlayRegion->GetBackgroundBufferInfo(bufferInfo);
197 // Gets a video file path
198 String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"tizen.mp4";
200 // Creates an instance of Player
201 __pPlayer = new Player();
202 __pPlayer->Construct(*this, &bufferInfo);
203 __pPlayer->SetLooping(true);
204 __pPlayer->OpenFile(videoFilePath);
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));
213 Button* pButton = new Button();
214 pButton->Construct(Rectangle(positionX + widthVideo - 200, positionX + HeightVideo - 100, 180, 80),L"BUTTON");
215 AddControl(*pButton);
221 OverlayRegionSampleForm::OnTerminating(void)
223 result r = E_SUCCESS;
225 // Deallocates controls
228 r = __pPlayer->Close();
235 // IPlayerEventListener implementation
237 OverlayRegionSampleForm::OnPlayerOpened(result r)
243 OverlayRegionSampleForm::OnPlayerEndOfClip(void)
249 OverlayRegionSampleForm::OnPlayerSeekCompleted(result r)
255 OverlayRegionSampleForm::OnPlayerBuffering(int percent)
261 OverlayRegionSampleForm::OnPlayerErrorOccurred(const PlayerErrorReason r)
267 OverlayRegionSampleForm::OnPlayerInterrupted(void)
273 OverlayRegionSampleForm::OnPlayerReleased(void)
279 class _OSP_EXPORT_ OverlayRegion
280 : public Tizen::Base::Object
284 * This is the destructor for this class.
285 * This destructor overrides Tizen::Base::Object::~Object().
289 virtual ~OverlayRegion(void);
292 * Gets the position and size of the overlay region.
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.
301 Tizen::Graphics::Rectangle GetBounds(void) const;
304 * Gets the position and size of the overlay region.
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.
313 Tizen::Graphics::FloatRectangle GetBoundsF(void) const;
316 * Gets the position and size of the overlay region.
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.
328 void GetBounds(int& x, int& y, int& width, int& height) const;
331 * Gets the position and size of the overlay region.
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.
343 void GetBounds(float& x, float& y, float& width, float& height) const;
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.
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.
364 result SetInputBuffer(const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, OverlayRegionBufferPixelFormat srcFormat);
367 * Gets the information related to the background buffer.
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.
378 result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
381 * Shows the overlay region on the screen.
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.
393 * Evaluates and returns the valid position and size that are closest to the specified bounds.
397 * @return @c true if the evaluation process does not meet an error, @n
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.
415 static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
418 * Evaluates and returns the valid position and size that are closest to the specified bounds.
422 * @return @c true if the evaluation process does not meet an error, @n
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.
440 static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
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.
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.
453 static int GetWidthUnit(void);
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.
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.
466 static int GetHeightUnit(void);
469 * Gets the maximum count of overlay regions that can be used simultaneously per application.
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.
478 static int GetMaxCount(void);
481 * Gets the BufferPixelFormat list for the %OverlayRegion class. @n
482 * Each list item has a Tizen::UI::Controls::OverlayRegionBufferPixelFormat value.
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
494 static Tizen::Base::Collection::IListT< OverlayRegionBufferPixelFormat >* GetSupportedBufferPixelFormatListN(void);
498 // This default constructor is intentionally declared as private so that only the platform can create an instance.
505 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
507 OverlayRegion(const OverlayRegion& rhs);
510 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
512 OverlayRegion& operator =(const OverlayRegion& rhs);
515 class _OverlayRegionImpl * __pOverlayRegionImpl;
517 friend class _OverlayRegionImpl;
521 }}} // Tizen::Ui::Controls
523 #endif // _FUI_CTRL_OVERLAY_CONTROL_H_