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 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 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.
85 * @enum OverlayRegionEvaluationOption
87 * Defines the option for evaluating the bounds of an overlay region.
91 enum OverlayRegionEvaluationOption
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 */
101 * @class OverlayRegion
102 * @brief This class is an implementation of an %OverlayRegion.
106 * @final This class is not intended for extension.
108 * The %OverlayRegion class displays a region of an overlay surface, which is used to play back a video or show the camera preview.
110 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_overlay_region.htm">OverlayRegion</a>.
112 * The following example demonstrates how to use the %OverlayRegion class.
114 //Sample code for OverlayRegionSampleForm.h
115 #include <FGraphics.h>
119 class OverlayRegionSampleForm
120 : public Tizen::Ui::Controls::Form
121 , public Tizen::Media::IPlayerEventListener
124 OverlayRegionSampleForm(void);
125 virtual ~OverlayRegionSampleForm(void);
127 bool Initialize(void);
128 virtual result OnInitializing(void);
129 virtual result OnTerminating(void);
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);
141 Tizen::Ui::Controls::Panel* __pOverlayRegionSamplePanel;
142 Tizen::Ui::Controls::OverlayRegion*__pOverlayRegion;
143 Tizen::Media::Player* __pPlayer;
148 //Sample code for OverlayRegionSampleForm.cpp
150 #include "OverlayRegionSampleForm.h"
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;
158 OverlayRegionSampleForm::OverlayRegionSampleForm(void)
159 : __pOverlayRegionSamplePanel(null)
160 , __pOverlayRegion(null)
165 OverlayRegionSampleForm::~OverlayRegionSampleForm(void)
170 OverlayRegionSampleForm::Initialize(void)
172 Construct(FORM_STYLE_NORMAL);
177 OverlayRegionSampleForm::OnInitializing(void)
179 result r = E_SUCCESS;
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);
188 // Evaluates bounds of overlay region
189 bool modified = false;
190 OverlayRegion::EvaluateBounds(OVERLAY_REGION_EVALUATION_OPTION_GREATER_THAN, overlayRectangle, modified);
192 // Gets an overlay region
193 __pOverlayRegion = GetOverlayRegionN(overlayRectangle, OVERLAY_REGION_TYPE_NORMAL);
195 // Gets buffer information
196 BufferInfo bufferInfo;
197 __pOverlayRegion->GetBackgroundBufferInfo(bufferInfo);
199 // Gets a video file path
200 String videoFilePath = App::GetInstance()->GetAppResourcePath() + L"tizen.mp4";
202 // Creates an instance of Player
203 __pPlayer = new Player();
204 __pPlayer->Construct(*this, &bufferInfo);
205 __pPlayer->SetLooping(true);
206 __pPlayer->OpenFile(videoFilePath);
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));
215 Button* pButton = new Button();
216 pButton->Construct(Rectangle(positionX + widthVideo - 200, positionX + HeightVideo - 100, 180, 80),L"BUTTON");
223 OverlayRegionSampleForm::OnTerminating(void)
225 result r = E_SUCCESS;
227 // Deallocates controls
230 r = __pPlayer->Close();
237 // IPlayerEventListener implementation
239 OverlayRegionSampleForm::OnPlayerOpened(result r)
245 OverlayRegionSampleForm::OnPlayerEndOfClip(void)
251 OverlayRegionSampleForm::OnPlayerSeekCompleted(result r)
257 OverlayRegionSampleForm::OnPlayerBuffering(int percent)
263 OverlayRegionSampleForm::OnPlayerErrorOccurred(const PlayerErrorReason r)
269 OverlayRegionSampleForm::OnPlayerInterrupted(void)
275 OverlayRegionSampleForm::OnPlayerReleased(void)
281 class _OSP_EXPORT_ OverlayRegion
282 : public Tizen::Base::Object
286 * This is the destructor for this class.
287 * This destructor overrides Tizen::Base::Object::~Object().
291 virtual ~OverlayRegion(void);
294 * Gets the position and size of the overlay region.
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.
304 Tizen::Graphics::Rectangle GetBounds(void) const;
307 * Gets the position and size of the overlay region.
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.
317 Tizen::Graphics::FloatRectangle GetBoundsF(void) const;
320 * Gets the position and size of the overlay region.
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.
332 void GetBounds(int& x, int& y, int& width, int& height) const;
335 * Gets the position and size of the overlay region.
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.
347 void GetBounds(float& x, float& y, float& width, float& height) const;
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.
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.
369 result SetInputBuffer(const Tizen::Base::ByteBuffer& srcBuffer, const Tizen::Graphics::Dimension& srcDim, OverlayRegionBufferPixelFormat srcFormat);
372 * Gets the information related to the background buffer.
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.
383 result GetBackgroundBufferInfo(Tizen::Graphics::BufferInfo& info) const;
386 * Shows the overlay region on the screen.
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.
399 * Evaluates and returns the valid position and size that are closest to the specified bounds.
403 * @return @c true if the evaluation process does not meet an error, @n
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.
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.
422 static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::Rectangle& rect, bool& modified);
425 * Evaluates and returns the valid position and size that are closest to the specified bounds.
429 * @return @c true if the evaluation process does not meet an error, @n
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.
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.
447 static bool EvaluateBounds(OverlayRegionEvaluationOption option, Tizen::Graphics::FloatRectangle& rect, bool& modified);
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.
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.
460 static int GetWidthUnit(void);
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.
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.
473 static int GetHeightUnit(void);
476 * Gets the maximum count of overlay regions that can be used simultaneously per application.
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.
485 static int GetMaxCount(void);
488 * Gets the BufferPixelFormat list for the %OverlayRegion class. @n
489 * Each list item has a Tizen::UI::Controls::OverlayRegionBufferPixelFormat value.
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.
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.
503 static Tizen::Base::Collection::IListT< OverlayRegionBufferPixelFormat >* GetSupportedBufferPixelFormatListN(void);
507 // This default constructor is intentionally declared as private so that only the platform can create an instance.
514 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
516 OverlayRegion(const OverlayRegion& rhs);
519 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
521 OverlayRegion& operator =(const OverlayRegion& rhs);
524 class _OverlayRegionImpl * __pOverlayRegionImpl;
526 friend class _OverlayRegionImpl;
530 }}} // Tizen::Ui::Controls
532 #endif // _FUI_CTRL_OVERLAY_CONTROL_H_