inc/FGrpGlPlayer.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        FGrpGlPlayer.h
  20  * @brief       This is the header file for the %GlPlayer class.
  21  *
  22  * This header file contains the declarations of the %GlPlayer class.
  23  *
  24  */
  25
  26 #ifndef _FGRP_GL_PLAYER_H_
  27 #define _FGRP_GL_PLAYER_H_
  28
  29 #include <FBaseObject.h>
  30
  31 #include <eglplatform.h>
  32
  33 namespace Tizen { namespace Ui
  34 {
  35 class Control;
  36 } }
  37
  38 namespace Tizen { namespace Graphics { namespace Opengl
  39 {
  40
  41 class IGlRenderer;
  42
  43 /**
  44  * @enum        EglContextClientVersion
  45  *
  46  * Defines the Egl Context Client version of the player.
  47  *
  48  * @since 2.0
  49  *
  50  */
  51 enum EglContextClientVersion
  52 {
  53         EGL_CONTEXT_CLIENT_VERSION_1_X,         /**< The version is 1.x */
  54         EGL_CONTEXT_CLIENT_VERSION_2_X          /**< The version is 2.x */
  55 };
  56
  57 /**
  58  * @enum        EglAttributesPreset
  59  *
  60  * Defines the preset of EGL attributes and configurations.
  61  *
  62  * @since 2.0
  63  *
  64  */
  65 enum EglAttributesPreset
  66 {
  67         EGL_ATTRIBUTES_PRESET_DONT_CARE,        /**< Preset Don't care */
  68         EGL_ATTRIBUTES_PRESET_RGB565,           /**< Preset RGB565 */
  69         EGL_ATTRIBUTES_PRESET_ARGB8888          /**< Preset ARGB8888 */
  70 };
  71
  72 /**
  73  * @class       GlPlayer
  74  * @brief       This class provides a simple template for rendering 3D objects with OpenGL-ES APIs
  75  * @since 2.0
  76  * @final       This class is not intended for extension.
  77  *
  78  */
  79 class _OSP_EXPORT_ GlPlayer
  80         : public Tizen::Base::Object
  81 {
  82 public:
  83         /**
  84          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  85          *
  86          * @since 2.0
  87          *
  88          */
  89         GlPlayer(void);
  90
  91         /**
  92          * This destructor overrides Tizen::Base::Object::~Object(void).
  93          *
  94          * @since 2.0
  95          *
  96          */
  97         virtual ~GlPlayer(void);
  98
  99         /**
 100          * Initializes this instance of %GlPlayer.
 101          *
 102          * @since 2.0
 103          * @return      An error code
 104          * @param[in]   version EGL Context Client Version.
 105          * @param[in]   control Target control
 106          * @exception   E_SUCCESS       The method is successful.
 107          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 108          * @exception   E_INVALID_OPERATION     The operation has failed, because of the duplicate call of Construct().
 109          *
 110          * @remarks Currently, version must be 1(OpenGL-ES 1.x) or 2(OpenGL-ES 2.x)
 111          * @remarks Currently, only Tizen::Ui::Controls::Frame and Tizen::Ui::Controls::Form are allowed as the target control, therefore, when the input Target control is not Form or Frame then E_INVALID_ARG exception is occurred.
 112          *
 113          */
 114         result Construct(EglContextClientVersion version, Tizen::Ui::Control* pControl);
 115
 116         /**
 117          * Start the %GlPlayer, and initialzie EGL status.
 118          *
 119          * @since 2.0
 120          * @return      An error code
 121          * @exception   E_SUCCESS       The method is successful.
 122          * @exception   E_SYSTEM        Player cannot be started properly due to a severe system error.
 123          * @exception   E_INVALID_STATE The state of player is not suitable for start. For example, it is not allowable to start player when its state is pause.
 124          * @exception   E_OPENGL_ERROR  There occurs an EGL error during performing EGL function.
 125          *
 126          * @remarks     In the case that this returns E_OPENGL_ERROR exception, developers can use eglGetError() to query which EGL error is raised.
 127          *
 128          */
 129         result Start(void);
 130
 131         /**
 132          * Pause the %GlPlayer.
 133          *
 134          * @since 2.0
 135          * @return      An error code
 136          * @exception   E_SUCCESS       The method is successful.
 137          * @exception   E_SYSTEM        Player cannot be paused properly due to a severe system error.
 138          * @exception   E_INVALID_OPERATION     Fail to perform IGlRenderer::Pause function which is implemented by developers.
 139          * @exception   E_INVALID_STATE The state of player is not suitable for pause. For example, it is not allowable to pause player when it does not start after the initialization yet.
 140          *
 141          */
 142         result Pause(void);
 143
 144         /**
 145          * Resume the %GlPlayer.
 146          *
 147          * @since 2.0
 148          * @return      An error code
 149          * @exception   E_SUCCESS       The method is successful.
 150          * @exception   E_SYSTEM        Player cannot be resumed properly due to a severe system error.
 151          * @exception   E_INVALID_OPERATION     Fail to perform IGlRenderer::Resume function which is implemented by developers.
 152          * @exception   E_INVALID_STATE The state of player is not suitable for resume. For example, it is not allowable to resume player when its state is stop.
 153          *
 154          */
 155         result Resume(void);
 156
 157         /**
 158          * Stop the %GlPlayer, and reset the EGL status.
 159          *
 160          * @since 2.0
 161          * @return      An error code
 162          * @exception   E_SUCCESS       The method is successful.
 163          * @exception   E_SYSTEM        Player cannot be stopped properly due to a severe system error.
 164          * @exception   E_INVALID_OPERATION     Fail to perform IGlRenderer::Pause function which is implemented by developers.
 165          *
 166          * @remarks Before starting to reset the EGL status, this function calls IGlRenderer::Pause() to prevent unexpected behavior.
 167          *
 168          */
 169         result Stop(void);
 170
 171         /**
 172          * Redraw the scene.
 173          *
 174          * @since 2.0
 175          * @return      An error code
 176          * @exception   E_SUCCESS       The method is successful.
 177          * @exception   E_OPENGL_ERROR  There occurs an EGL error during performing EGL function.
 178          * @exception   E_INVALID_STATE The state of player is invalid and fails to pause properly.
 179          *
 180          * @remarks     In the case that this returns E_OPENGL_ERROR exception, developers can use eglGetError() to query which EGL error is raised.
 181          *
 182          */
 183         result Redraw(void);
 184
 185         /**
 186          * Set the FPS(frames per second) of the player.
 187          *
 188          * @since 2.0
 189          * @param[in]   fps     frames per second
 190          *
 191          * @remarks When you give negative integer for fps, then the %GlPlayer try to draw frames as fast as possible.
 192          *
 193          */
 194         void SetFps(int fps);
 195
 196         /**
 197          * Set the configuration list of EGL Attributes to initialize the EGL system.
 198          *
 199          * @since 2.0
 200          * @return      An error code
 201          * @param[in]   eglConfigList   a list of EGL attributes and their values.
 202          * @exception   E_SUCCESS       The method is successful.
 203          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 204          *
 205          * @remarks %GlPlayer initializes the EGL status with the given EGL attributes, which means that system does not guarantees to set EGL configurations with the given attributes but prefers them.
 206          * @remarks     The format of eglConfigList is the same with the attribute list as the second input parameter of eglChooseConfig function. To know about the detailed description, refer the reference page of eglChooseConfig: http://www.khronos.org/opengles/documentation/opengles1_0/html/eglChooseConfig.html
 207          *
 208          */
 209         result SetEglAttributeList(const EGLint* pEglConfigList);
 210
 211         /**
 212          * Set EGL configuration with the given preset.
 213          *
 214          * @since 2.0
 215          * @return              An error code
 216          * @param[in]   preset  Preset for attributes.
 217          * @exception   E_SUCCESS       The method is successful.
 218          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 219          *
 220          * @remarks %GlPlayer initializes the EGL status with the given EGL attributes, which means that system does not guarantees to set EGL configurations with the given attributes but prefers them.
 221          *
 222          */
 223         result SetEglAttributePreset(EglAttributesPreset preset);
 224
 225         /**
 226          * Set EGL configuration for the given Attribute with the given value.
 227          *
 228          * @since 2.0
 229          * @return              An error code
 230          * @param[in]   key     EGL attribute
 231          * @param[in]   value   Value for the attribute
 232          * @exception   E_SUCCESS       The method is successful.
 233          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 234          *
 235          * @remarks %GlPlayer initializes the EGL status with the given EGL attributes, which means that system does not guarantees to set EGL configurations with the given attributes but prefers them.
 236          *
 237          */
 238         result SetEglAttribute(EGLint key, EGLint value);
 239
 240         /**
 241          * Set the Renderer which implements %IGlRenderer interface.
 242          *
 243          * @since 2.0
 244          * @return              An error code
 245          * @param[in]   renderer        %IGlRenderer defines how to render the scene.
 246          * @exception   E_SUCCESS       The method is successful.
 247          * @exception   E_INVALID_OPERATION     Fail to perform IGlRenderer::InitializeGl function which is implemented by developers.
 248          * @see %IGlRenderer
 249          *
 250          * @remarks If %GlPlayer already has a renderer, then the previous renderer is replaced by the new one.
 251          * @remarks If input parameter is null, then the current renderer of %GlPlayer is detached and %GlPlayer does nothing.
 252          * @remarks When the %IGlRenderer is replaced with the input, the GL status have to be initialized for the input %IGlRenderer. For such purpose, when the input %IGlRenderer is attached, the overrided IGlRenderer::InitializedGl() function is called. On the other hands, the previous %IGlRenderer of %GlPlayer is detached after calling the overrided %IGlRenderer::TerminateGL() function.
 253          *
 254          */
 255         result SetIGlRenderer(IGlRenderer* pRenderer);
 256
 257 private:
 258         /*
 259          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 260          *
 261          * @since 2.0
 262          */
 263         GlPlayer(const GlPlayer& rhs);
 264
 265         /*
 266          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 267          *
 268          * @since 2.0
 269          */
 270         GlPlayer& operator =(const GlPlayer& rhs);
 271
 272         friend class _GlPlayerImpl;
 273         class _GlPlayerImpl* __pImpl;
 274
 275 }; // GlPlayer
 276
 277 }}} // Tizen::Graphics::Opengl
 278
 279 #endif //_FGRP_GL_PLAYER_H_