2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0/
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 FUiCtrlOverlayPanel.h
20 * @brief This is the header file for the %OverlayPanel class.
22 * This header file contains the declarations of the %OverlayPanel class.
25 #ifndef _FUI_CTRL_OVERLAY_PANEL_H_
26 #define _FUI_CTRL_OVERLAY_PANEL_H_
28 #include <FBaseTypes.h>
29 #include <FGrpCanvas.h>
30 #include <FUiCtrlPanel.h>
32 namespace Tizen { namespace Ui { namespace Controls
36 * @enum OverlayPanelEvaluationOption
38 * Defines the option for evaluating the bounds of an overlay panel.
42 enum OverlayPanelEvaluationOption
44 OVERLAY_PANEL_EVAL_OPT_GREATER_THAN, /**< The option evaluating the overlay panel bounds and finding the minimum
45 bounds greater than the input bounds */
46 OVERLAY_PANEL_EVAL_OPT_LESS_THAN /**< The option evaluating the overlay panel bounds and finding the maximum
47 bounds smaller than input bounds */
52 * @brief This class is an implementation of %OverlayPanel.
56 * @remarks The %OverlayPanel control can only be attached to a %Form control by using Tizen::Ui::Container::AddControl method, because of its native
57 * characteristics. Since %OverlayPanel inherits a Panel control, it can be used as a container if needed.
59 * The %OverlayPanel class is an implementation of the %OverlayPanel control.
60 * The %OverlayPanel is a special type of panel which is used to specify area where the developer
61 * can playback video or camera preview. It is called an overlay because it is possible to overlay
62 * other graphics and controls on top of the panel.
63 * The %OverlayPanel consists of two layers, the foreground panel and background buffer which supports
64 * H/W accelerated rendering. Due to the hardware accelerated nature, there is a limitation with an
65 * %OverlayPanel. The Form that houses an %OverlayPanel can only have a black, opaque background.
66 * The overlay panel can manipulate the rotation and the size of input buffer.
68 * The following example demonstrates how to use the %OverlayPanel class.
71 //Sample code for OverlayPanelSampleForm.h
76 class OverlayPanelSampleForm
77 : public Tizen::Ui::Controls::Form
78 , public Tizen::Ui::IActionEventListener
79 , public Tizen::Media::IPlayerEventListener
82 OverlayPanelSampleForm(void);
83 virtual ~OverlayPanelSampleForm(void);
85 bool Initialize(void);
86 virtual result OnInitializing(void);
87 virtual result OnTerminating(void);
88 virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
90 // IPlayerEventListener
91 virtual void OnPlayerOpened(result r);
92 virtual void OnPlayerEndOfClip(void);
93 virtual void OnPlayerSeekCompleted(result r);
94 virtual void OnPlayerBuffering(int percent);
95 virtual void OnPlayerErrorOccurred(const Tizen::Media::PlayerErrorReason r);
96 virtual void OnPlayerInterrupted(void);
97 virtual void OnPlayerReleased(void);
100 static const int ID_BUTTON_OK = 101;
102 Tizen::Media::Player* __pPlayer;
103 Tizen::Ui::Controls::OverlayPanel* __pOverlayPanel;
108 //Sample code for OverlayPanelSampleForm.cpp
110 #include "OverlayPanelSampleForm.h"
112 using namespace Tizen::App;
113 using namespace Tizen::Base;
114 using namespace Tizen::Graphics;
115 using namespace Tizen::Media;
116 using namespace Tizen::Ui::Controls;
118 OverlayPanelSampleForm::OverlayPanelSampleForm(void)
122 OverlayPanelSampleForm::~OverlayPanelSampleForm(void)
127 OverlayPanelSampleForm::Initialize(void)
129 Construct(FORM_STYLE_NORMAL);
134 OverlayPanelSampleForm::OnInitializing(void)
136 // Set bounds of overlay panel
137 Rectangle overlayPanelBounds(10, 10, GetClientAreaBounds().width - 20, 500);
140 bool isModifiedBounds = false;
141 result r = OverlayPanel::EvaluateBounds(OVERLAY_PANEL_EVAL_OPT_GREATER_THAN, overlayPanelBounds, isModifiedBounds);
143 // Creates an instance of overlay panel
144 __pOverlayPanel = new OverlayPanel();
145 __pOverlayPanel->Construct(overlayPanelBounds);
146 AddControl(__pOverlayPanel);
148 // Gets a background buffer info
149 BufferInfo bufferinfo;
150 __pOverlayPanel->GetBackgroundBufferInfo(bufferinfo);
152 // Gets a video file path (/res/video.mp4)
153 String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"video.mp4";
155 // Creates an instance of Player
156 __pPlayer = new Player();
157 __pPlayer->Construct(*this, &bufferinfo);
158 __pPlayer->OpenFile(videoFilePath);
161 // Creates an instance of Button
162 Button *pButton = new Button();
163 pButton->Construct(Rectangle(10, 10, 300, 100));
164 pButton->SetText(L"Resize & Rotate");
165 pButton->SetActionId(ID_BUTTON_OK);
166 pButton->AddActionEventListener(*this);
167 __pOverlayPanel->AddControl(pButton);
173 OverlayPanelSampleForm::OnTerminating(void)
175 result r = E_SUCCESS;
177 // Deallocates controls
188 OverlayPanelSampleForm::OnActionPerformed(const Tizen::Ui::Control& source, int actionId)
194 //Modify renderer size & Rotate renderer
195 __pOverlayPanel->SetRenderSize(Dimension(400, 400));
196 __pOverlayPanel->SetRendererRotation(OverlayPanel::ROTATION_270);
204 // IPlayerEventListener implementation
206 OverlayPanelSampleForm::OnPlayerOpened(result r)
212 OverlayPanelSampleForm::OnPlayerEndOfClip(void)
218 OverlayPanelSampleForm::OnPlayerSeekCompleted(result r)
224 OverlayPanelSampleForm::OnPlayerBuffering(int percent)
230 OverlayPanelSampleForm::OnPlayerErrorOccurred(const PlayerErrorReason r)
236 OverlayPanelSampleForm::OnPlayerInterrupted(void)
242 OverlayPanelSampleForm::OnPlayerReleased(void)
249 class _OSP_EXPORT_ OverlayPanel
250 : public Tizen::Ui::Controls::Panel
256 * Defines the various rotation options.
262 ROTATION_NONE, /**< No rotation*/
263 ROTATION_90, /**< The 90 degree rotation */
264 ROTATION_180, /**< The 180 degree rotation */
265 ROTATION_270, /**< The 270 degree rotation */
266 ROTATION_NONE_LR, /**< The horizontal mirroring */
267 ROTATION_NONE_UD, /**< The vertical mirroring */
268 ROTATION_90_LR, /**< The 90 degree rotation with horizontal mirroring */
269 ROTATION_90_UD, /**< The 90 degree rotation with vertical mirroring */
270 ROTATION_180_LR, /**< The 180 degree rotation with horizontal mirroring */
271 ROTATION_180_UD, /**< The 180 degree rotation with vertical mirroring */
272 ROTATION_270_LR, /**< The 270 degree rotation with horizontal mirroring */
273 ROTATION_270_UD, /**< The 270 degree rotation with vertical mirroring */
278 * @enum BufferPixelFormat
280 * Defines the pixel formats.
284 enum BufferPixelFormat
286 BUFFER_PIXEL_FORMAT_ARGB8888, /**< The ARGB8888 pixel format */
287 BUFFER_PIXEL_FORMAT_RGB565, /**< The RGB565 pixel format */
288 BUFFER_PIXEL_FORMAT_YCbCr420_PLANAR, /**< The 8 bit Y plane followed by 8 bit 2 X 2 subsampled U and V planes */
289 BUFFER_PIXEL_FORMAT_NV12, /**< The NV12 pixel format */
290 BUFFER_PIXEL_FORMAT_UYVY /**< The UYVY pixel format */
294 * This is the default constructor for this class. @n
295 * The object is not fully constructed after this constructor is called. @n
296 * For full construction, the %Construct() method must be called right after calling this constructor.
303 * This destructor overrides Tizen::Base::Object::~Object().
307 virtual ~OverlayPanel(void);
310 * Initializes this instance of %OverlayPanel at the specified rectangle.
314 * @return An error code
315 * @param[in] rect The location and size of the %OverlayPanel control @n
316 * The maximum size is equal to screen size. for example 720 x 1280 on a HD screen, or 480 x 800 on a
318 * @exception E_SUCCESS The method is successful.
319 * @exception E_INVALID_ARG A specified input parameter @c is invalid.
320 * @exception E_SYSTEM A system error has occurred.
322 * - The size of the control must be within the range defined by the minimum size and the maximum size.
323 * - To guarantee the size of the render buffer equal to the size of the %OverlayPanel after constructed, checks bounds of
324 * @c rect using EvaluateBounds() method before calling this method.
325 * - Do not use %OverlayPanel in combination with %OverlayRegion. If used, %OverlayPanel may not work as expected.
326 * @see %Tizen::Ui::Container
328 result Construct(const Tizen::Graphics::Rectangle& rect);
331 * Initializes this instance of %OverlayPanel at the specified rectangle.
335 * @return An error code
336 * @param[in] rect The location and size of the %OverlayPanel control @n
337 * The maximum size is equal to screen size. for example 720 x 1280 on a HD screen, or 480 x 800 on a
339 * @exception E_SUCCESS The method is successful.
340 * @exception E_INVALID_ARG A specified input parameter @c is invalid.
341 * @exception E_SYSTEM A system error has occurred.
343 * - The size of the control must be within the range defined by the minimum size and the maximum size.
344 * - To guarantee the size of the render buffer equal to the size of the %OverlayPanel after constructed, checks bounds of
345 * @c rect using EvaluateBounds() method before calling this method.
346 * - Do not use %OverlayPanel in combination with %OverlayRegion. If used, %OverlayPanel may not work as expected.
347 * @see %Tizen::Ui::Container
349 result Construct(const Tizen::Graphics::FloatRectangle& rect);
352 * Sets the rotation of the input buffer. @n
356 * @param[in] rotation The rotation
358 void SetRendererRotation(OverlayPanel::Rotation rotation);
362 * Changes the size of the displayed renderer.
364 * @brief <i> [Deprecated] </i>
365 * @deprecated This method is deprecated. Instead of using this class, use the %OverlayRegion class, that supports video playback and
369 * @param[in] dim The dimension of the window to draw
373 void SetRendererSize(Tizen::Graphics::Dimension& dim);
376 * Changes the size of the displayed renderer.
380 * @return An error code
381 * @param[in] dim The dimension of the window to draw
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_INVALID_ARG A specified input parameter is invalid.
384 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
386 * - A %OverlayPanel becomes displayable only after it has been added to a form.
387 * - If you want to resize window to draw render buffer, calls this function after the %OverlayPanel is added to a %Form control
389 * OverlayPanel* pOverlayPanel = new OverlayPanel();
390 * pOverlayPanel->Construct(Rectangle(100, 250, 300, 300));
391 * AddControl(pOverlayPanel);
394 * result r = pOverlayPanel->SetRenderSize(Dimension(300, 200));
398 result SetRenderSize(const Tizen::Graphics::Dimension& dim);
401 * Changes the size of the displayed renderer.
405 * @return An error code
406 * @param[in] dim The dimension of the window to draw
407 * @exception E_SUCCESS The method is successful.
408 * @exception E_INVALID_ARG A specified input parameter is invalid.
409 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
411 * - A %OverlayPanel becomes displayable only after it has been added to a form.
412 * - If you want to resize window to draw render buffer, calls this function after the %OverlayPanel is added to a %Form control
414 * OverlayPanel* pOverlayPanel = new OverlayPanel();
415 * pOverlayPanel->Construct(FloatRectangle(100.0, 250.0, 300.0, 300.0));
416 * AddControl(pOverlayPanel);
419 * result r = pOverlayPanel->SetRenderSize(FloatDimension(300.0, 200.0));
423 result SetRenderSize(const Tizen::Graphics::FloatDimension& dim);
426 * Sets the input buffer.
430 * @param[in] destDim The dimension of the window to draw
431 * @param[in] srcBuffer The source buffer
432 * @param[in] srcDim The source dimension
433 * @param[in] srcFormat The pixel format of buffer data
434 * @exception E_SUCCESS The method is successful.
435 * @exception E_INVALID_ARG A specified input parameter is invalid.
436 * @exception E_SYSTEM A system error has occurred.
437 * @exception E_UNSUPPORTED_FORMAT The specified pixel format is not supported.
438 * @remarks Control::Invalidate() methods must be called to properly display the input buffer.
440 result SetInputBuffer(const Tizen::Graphics::Dimension& destDim, const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, BufferPixelFormat srcFormat);
443 * Sets the input buffer.
447 * @param[in] destDim The dimension of the window to draw
448 * @param[in] srcBuffer The source buffer
449 * @param[in] srcDim The source dimension
450 * @param[in] srcFormat The pixel format of buffer data
451 * @exception E_SUCCESS The method is successful.
452 * @exception E_INVALID_ARG A specified input parameter is invalid.
453 * @exception E_SYSTEM A system error has occurred.
454 * @exception E_UNSUPPORTED_FORMAT The specified pixel format is not supported.
455 * @remarks Control::Invalidate() methods must be called to properly display the input buffer.
457 result SetInputBuffer(const Tizen::Graphics::FloatDimension& destDim, const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, BufferPixelFormat srcFormat);
460 * Gets the information of the background buffer.
464 * @return An error code
465 * @param[out] info The information of the background buffer
466 * @exception E_SUCCESS The method is successful.
467 * @exception E_OPERATION_FAILED The operation has failed.
468 * @remarks Currently, this method provides buffer information except the pointer of the RGB color buffer. @n
469 * Therefore, info.pPixels is always assigned @c null.
471 result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
475 * Sets the aspect ratio of the renderer.
477 * @brief <i> [Deprecated] </i>
478 * @deprecated This method is deprecated because the renderer aspect ratio is not guaranteed any more.
481 * @param[in] fix Set to @c true if the renderer will display the aspect ratio of the input buffer even if the renderer and input data have
482 * different aspect ratios, @n
484 * @remarks This method has no effects for hardware accelerated GL backend.
487 void SetRendererAspectRatio(bool fix);
491 * Gets the masking color of this control.
493 * @brief <i> [Deprecated] </i>
494 * @deprecated This method is deprecated because masking color does not exist on %OverlayPanel any more.
495 * @remarks Do not call this method. It is not supported.
498 * @return Always returns Tizen::Graphics::Color(0x00000000)
501 Tizen::Graphics::Color GetMaskingColor(void) const;
504 * Evaluates and returns the valid position and size that are closest to the specified bounds.
508 * @return An error code
509 * @param[in] option The option for evaluating the bounds of the overlay panel
510 * @param[in, out] rect An instance of %Tizen::Graphics::Rectangle that represents the validated bounds of %OverlayPanel @n
511 * The width and height of the input rectangle must be greater than @c 0.
512 * @param[out] modified A boolean flag that indicates whether the specified @c rectangle is modified
513 * @exception E_SUCCESS The method is successful.
514 * @exception E_INVALID_ARG The specified input parameter @c is invalid.
515 * @exception E_UNSUPPORTED_OPTION The specified input parameter @c is not supported.
516 * @exception E_OPERATION_FAILED The operation has failed.
518 * - Due to the hardware accelerated rendering, there are limitations for an overlay panel.
519 * - The hardware capability for an overlay panel is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount().
520 * - If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay
521 * panel. In such cases, Construct() will return @c E_INVALID_ARG. @n
522 * To prevent this kind of problem, the application must the this method to get a validated bounds
523 * - The specific error code can be accessed using the GetLastResult() method.
525 static result EvaluateBounds(OverlayPanelEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
528 * Evaluates and returns the valid position and size that are closest to the specified bounds.
532 * @return An error code
533 * @param[in] option The option for evaluating the bounds of the overlay panel
534 * @param[in, out] rect An instance of %Tizen::Graphics::FloatRectangle that represents the validated bounds of %OverlayPanel @n
535 * The width and height of the input float rectangle must be greater than @c 0.
536 * @param[out] modified A boolean flag that indicates whether the specified @c rectangle is modified
537 * @exception E_SUCCESS The method is successful.
538 * @exception E_INVALID_ARG The specified input parameter @c is invalid.
539 * @exception E_UNSUPPORTED_OPTION The specified input parameter @c is not supported.
540 * @exception E_OPERATION_FAILED The operation has failed.
542 * - Due to the hardware accelerated rendering, there are limitations for an overlay panel.
543 * - The hardware capability for an overlay panel is checked by using the GetWidthUnit(), GetHeightUnit() and GetMaxCount().
544 * - If the application runs on multi-screen resolutions, the specified bounds may not meet the hardware limitations of the overlay
545 * panel. In such cases, Construct() will return E_INVALID_ARG. @n
546 * To prevent this kind of problem, the application must use this method to get a validated bounds
547 * - The specific error code can be accessed using the GetLastResult() method.
549 static result EvaluateBounds(OverlayPanelEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
552 * Gets the BufferPixelFormat list for the %OverlayPanel class. @n
553 * Each list item has a Tizen::UI::Controls::OverlayPanel::BufferPixelFormat value.
558 * - A list of the pixel formats supported by the %OverlayPanel class, @n
559 * else @c null if no pixel format is supported or an exception occurs
560 * - The specific error code can be accessed using the GetLastResult() method.
561 * - The return value and each item in the list must be deleted by the caller.
562 * - The format list can vary depending on the device. After checking the supported formats using this method,
563 * it's better to use a proper pixel format.
565 static Tizen::Base::Collection::IListT<BufferPixelFormat>* GetSupportedBufferPixelFormatListN(void);
568 * Gets the width unit. @n
569 * Only a multiple of this value can be allowed as the width of an overlay panel.
573 * @return The value of width
575 static int GetWidthUnit(void);
578 * Gets the height unit. @n
579 * Only a multiple of this value can be allowed as the height of an overlay panel.
583 * @return The value of the height
585 static int GetHeightUnit(void);
588 * Gets the maximum count of overlay panel that can be used simultaneously per application.
592 * @return The maximum count of overlay panel that can be used simultaneously per application
594 static int GetMaxCount(void);
598 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
600 OverlayPanel(const OverlayPanel& rhs);
603 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
605 OverlayPanel& operator =(const OverlayPanel& rhs);
608 }}} // Tizen::Ui::Controls
610 #endif // _FUI_CTRL_OVERLAY_PANEL_H_