inc/FGrpGlPlayer.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        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 @n
 105          *                                      The version must be 1(OpenGL-ES 1.x) or 2(OpenGL-ES 2.x).
 106          * @param[in]   pControl        A pointer of the target control @n
 107          *                                      Only Tizen::Ui::Controls::Frame and Tizen::Ui::Controls::Form are allowed as the target control.
 108          * @exception   E_SUCCESS       The method is successful.
 109          * @exception   E_INVALID_ARG   Either the @c pControl is not Form or Frame, or
 110          *                                                      the @c version is not @c EGL_CONTEXT_CLIENT_VERSION_1_X or @c EGL_CONTEXT_CLIENT_VERSION_2_X.
 111          * @exception   E_INVALID_OPERATION     The operation has failed, because of the duplicate call of Construct().
 112          *
 113          */
 114         result Construct(EglContextClientVersion version, Tizen::Ui::Control* pControl);
 115
 116         /**
 117          * Starts the %GlPlayer, and initializes 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 @c 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 the IGlRenderer::Pause() method 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 the IGlRenderer::Resume() method 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 the IGlRenderer::Pause() method which is implemented by developers.
 165          *
 166          * @remarks Before starting to reset the EGL status, this method 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 @c 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]   pEglConfigList  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. For detailed description, refer  <a href="http://www.khronos.org/opengles/documentation/opengles1_0/html/eglChooseConfig.html">here</a>.
 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]   pRenderer       %IGlRenderer defines how to render the scene.
 246          * @exception   E_SUCCESS       The method is successful.
 247          * @exception   E_INVALID_OPERATION     Fail to perform the IGlRenderer::InitializeGl() method 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() method is called. On the other hand, the previous %IGlRenderer of %GlPlayer is detached after calling the overrided %IGlRenderer::TerminateGL() method.
 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_