Mac-4.7.4/tools/qmeegographicssystemhelper/qmeegographicssystemhelper.h - platform/external/qt - Git at Google

 /****************************************************************************
 **
 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
 ** All rights reserved.
 ** Contact: Nokia Corporation (qt-info@nokia.com)
 **
 ** This file is part of the plugins of the Qt Toolkit.
 **
 ** $QT_BEGIN_LICENSE:LGPL$
 ** GNU Lesser General Public License Usage
 ** This file may be used under the terms of the GNU Lesser General Public
 ** License version 2.1 as published by the Free Software Foundation and
 ** appearing in the file LICENSE.LGPL included in the packaging of this
 ** file. Please review the following information to ensure the GNU Lesser
 ** General Public License version 2.1 requirements will be met:
 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 **
 ** In addition, as a special exception, Nokia gives you certain additional
 ** rights. These rights are described in the Nokia Qt LGPL Exception
 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 **
 ** GNU General Public License Usage
 ** Alternatively, this file may be used under the terms of the GNU General
 ** Public License version 3.0 as published by the Free Software Foundation
 ** and appearing in the file LICENSE.GPL included in the packaging of this
 ** file. Please review the following information to ensure the GNU General
 ** Public License version 3.0 requirements will be met:
 ** http://www.gnu.org/copyleft/gpl.html.
 **
 ** Other Usage
 ** Alternatively, this file may be used in accordance with the terms and
 ** conditions contained in a signed written agreement between you and Nokia.
 **
 **
 **
 **
 **
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/

 #ifndef QMEEGOGRAPHICSSYSTEMHELPER_H
 #define QMEEGOGRAPHICSSYSTEMHELPER_H

 #include <QPixmap>
 #include <QImage>
 #include "qmeegolivepixmap.h"

 class QLibrary;

 //! The base class for accressing special meego graphics system features.
 /*!
  This class is a helper class with static-only methods for accessing various
  meego graphics system functionalities. The way it works is that the helper
  dynamically calls-in to the loaded graphicssystem plugin... therefore, you're
  expected to make sure that you're indeed running with 'meego' before using any
  of the specialized methods.

  In example:

  \code
  QPixmap p;
  if (QMeeGoGraphicsSystemHelper::isRunningMeeGo()) {
     p = QMeeGoGraphicsSystemHelper::pixmapWithGLTexture(64, 64);
  } else {
     p = QPixmap(64, 64);
  }
  \endcode

  Calling any of the meego-specific features while not running meego might
  give unpredictable results. The only functions safe to call at all times are:

  \code
  QMeeGoGraphicsSystemHelper::isRunningMeeGo();
  QMeeGoGraphicsSystemHelper::runningGraphicsSystemName();
  QMeeGoGraphicsSystemHelper::switchToMeeGo();
  QMeeGoGraphicsSystemHelper::switchToRaster();
  \endcode
 */

 class Q_DECL_EXPORT QMeeGoGraphicsSystemHelper
 {
 public:
     //! Returns true if running meego.
     /*!
      Returns true if the currently active (running) system is 'meego' with OpenGL.
      This returns both true if the app was started with 'meego' or was started with
      'runtime' graphics system and the currently active system through the runtime
      switching is 'meego'.
     */
     static bool isRunningMeeGo();

     //! Returns true if running with a 'runtime' graphicssystem.
     /*!
      This function can be used in combination with ::runningGraphicsSystemName to figure out
      the existing situation.
     */
     static bool isRunningRuntime();

     //! Enables the sending of QMeeGoSwitchEvent's when the graphicssystem switches.
     /*!
       An application that wishes to start receive QMeegoSwitchEvents must call this function.
     */
     static void enableSwitchEvents();

     //! Switches to meego graphics system.
     /*!
      When running with the 'runtime' graphics system, sets the currently active
      system to 'meego'. The window surface and all the resources are automatically
      migrated to OpenGL. Will fail if the active graphics system is not 'runtime'.
      Calling this function will emit QMeeGoSwitchEvent to the top level widgets.
      If switch events are enabled, two events will be emitted for each switch --
      one before the switch (QMeeGoSwitchEvent::WillSwitch) and one after the
      switch (QMeeGoSwitchEvent::DidSwitch).
      If the switch policy is set to NoSwitch, this function has no effect.
     */
     static void switchToMeeGo();

     //! Switches to raster graphics system
     /*!
      When running with the 'runtime' graphics system, sets the currently active
      system to 'raster'. The window surface and the graphics resources (including the
      EGL shared image resources) are automatically migrated back to the CPU. All OpenGL
      resources (surface, context, cache, font cache) are automaticall anihilated.
      Calling this function will emit QMeeGoSwitchEvent to the top level widgets. If switch
      events are enabled, two events will be emitted for each switch -- one before the
      switch (QMeeGoSwitchEvent::WillSwitch) and one after the switch (QMeeGoSwitchEvent::DidSwitch).
      If the switch policy is set to NoSwitch, this function has no effect.
     */
     static void switchToRaster();

     //! Used to specify the policy for graphics system switching.
     enum SwitchPolicy {
         AutomaticSwitch,    /**< Automatic switching */
         ManualSwitch,       /**< Switching is controleld by the application */
         NoSwitch            /**< Switching is disabled completely */
     };

     //! Sets the policy of graphicssystem switching
     /*!
      By default, the switch to raster happens automatically when all windows are either
      minimized or when the last window is destroyed. This function lets the application
      change the graphicssystem switching policy to prevent the switching from happening
      automatically (that is if the application doesn't want switching at all or wishes
      to control the switching manually).
     */
     static void setSwitchPolicy(SwitchPolicy policy);

     //! Returns the name of the active graphics system
     /*!
      Returns the name of the currently active system. If running with 'runtime' graphics
      system, returns the name of the active system inside the runtime graphics system
     */
     static QString runningGraphicsSystemName();

     //! Creates a new EGL shared image.
     /*!
      Creates a new EGL shared image from the given image. The EGL shared image wraps
      a GL texture in the native format and can be easily accessed from other processes.
     */
     static Qt::HANDLE imageToEGLSharedImage(const QImage &image);

     //! Creates a QPixmap from an EGL shared image
     /*!
      Creates a new QPixmap from the given EGL shared image handle. The QPixmap can be
      used for painting like any other pixmap. The softImage should point to an alternative,
      software version of the graphical resource -- ie. obtained from theme daemon. The
      softImage can be allocated on a QSharedMemory slice for easy sharing across processes
      too. When the application is migrated ToRaster, this softImage will replace the
      contents of the sharedImage.

      It's ok to call this function too when not running 'meego' graphics system. In this
      case it'll create a QPixmap backed with a raster data (from softImage)... but when
      the system is switched back to 'meego', the QPixmap will be migrated to a EGL-shared image
      backed storage (handle).
     */
     static QPixmap pixmapFromEGLSharedImage(Qt::HANDLE handle, const QImage &softImage);

     //! Destroys an EGL shared image.
     /*!
      Destroys an EGLSharedImage previously created with an ::imageToEGLSharedImage call.
      Returns true if the image was found and the destruction was successful. Notice that
      this destroys the image for all processes using it.
     */
     static bool destroyEGLSharedImage(Qt::HANDLE handle);

     //! Updates the QPixmap backed with an EGLShared image.
     /*!
      This function re-reads the softImage that was specified when creating the pixmap with
      ::pixmapFromEGLSharedImage and updates the EGL Shared image contents. It can be used
      to share cross-proccess mutable EGLShared images.
     */
     static void updateEGLSharedImagePixmap(QPixmap *p);

     //! Create a new QPixmap with a GL texture.
     /*!
      Creates a new QPixmap which is backed by an OpenGL local texture. Drawing to this
      QPixmap will be accelerated by hardware -- unlike the normal (new QPixmap()) pixmaps,
      which are backed by a software engine and only migrated to GPU when used. Migrating those
      GL-backed pixmaps when going ToRaster is expsensive (they need to be downloaded from
      GPU to CPU) so use wisely.
     */
     static QPixmap pixmapWithGLTexture(int w, int h);

     //! Sets translucency (alpha) on the base window surface.
     /*!
      This function needs to be called *before* any widget/content is created.
      When called with true, the base window surface will be translucent and initialized
      with QGLFormat.alpha == true.

      This function is *deprecated*. Set Qt::WA_TranslucentBackground attribute
      on the top-level widget *before* you show it instead.
     */
     static void setTranslucent(bool translucent);

     //! Used to specify the mode for swapping buffers in double-buffered GL rendering.
     enum SwapMode {
         AutomaticSwap,      /**< Automatically choose netween full and partial updates (25% threshold) */
         AlwaysFullSwap,     /**< Always do a full swap even if partial updates support present */
         AlwaysPartialSwap,  /**< Always do a partial swap (if support present) no matter what threshold */
         KillSwap            /**< Do not perform buffer swapping at all (no picture) */
     };

     //! Sets the buffer swapping mode.
     /*!
      This can be only called when running with the meego graphics system.
      The KillSwap mode can be specififed to effectively block painting.

      This functionality should be used only by applications counting on a specific behavior.
      Most applications should use the default automatic behavior.
     */
     static void setSwapBehavior(SwapMode mode);
 };

 #endif
	/****************************************************************************
	**
	** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
	** All rights reserved.
	** Contact: Nokia Corporation (qt-info@nokia.com)
	**
	** This file is part of the plugins of the Qt Toolkit.
	**
	** $QT_BEGIN_LICENSE:LGPL$
	** GNU Lesser General Public License Usage
	** This file may be used under the terms of the GNU Lesser General Public
	** License version 2.1 as published by the Free Software Foundation and
	** appearing in the file LICENSE.LGPL included in the packaging of this
	** file. Please review the following information to ensure the GNU Lesser
	** General Public License version 2.1 requirements will be met:
	** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
	**
	** In addition, as a special exception, Nokia gives you certain additional
	** rights. These rights are described in the Nokia Qt LGPL Exception
	** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
	**
	** GNU General Public License Usage
	** Alternatively, this file may be used under the terms of the GNU General
	** Public License version 3.0 as published by the Free Software Foundation
	** and appearing in the file LICENSE.GPL included in the packaging of this
	** file. Please review the following information to ensure the GNU General
	** Public License version 3.0 requirements will be met:
	** http://www.gnu.org/copyleft/gpl.html.
	**
	** Other Usage
	** Alternatively, this file may be used in accordance with the terms and
	** conditions contained in a signed written agreement between you and Nokia.
	**
	**
	**
	**
	**
	** $QT_END_LICENSE$
	**
	****************************************************************************/

	#ifndef QMEEGOGRAPHICSSYSTEMHELPER_H
	#define QMEEGOGRAPHICSSYSTEMHELPER_H

	#include <QPixmap>
	#include <QImage>
	#include "qmeegolivepixmap.h"

	class QLibrary;

	//! The base class for accressing special meego graphics system features.
	/*!
	This class is a helper class with static-only methods for accessing various
	meego graphics system functionalities. The way it works is that the helper
	dynamically calls-in to the loaded graphicssystem plugin... therefore, you're
	expected to make sure that you're indeed running with 'meego' before using any
	of the specialized methods.

	In example:

	\code
	QPixmap p;
	if (QMeeGoGraphicsSystemHelper::isRunningMeeGo()) {
	p = QMeeGoGraphicsSystemHelper::pixmapWithGLTexture(64, 64);
	} else {
	p = QPixmap(64, 64);
	}
	\endcode

	Calling any of the meego-specific features while not running meego might
	give unpredictable results. The only functions safe to call at all times are:

	\code
	QMeeGoGraphicsSystemHelper::isRunningMeeGo();
	QMeeGoGraphicsSystemHelper::runningGraphicsSystemName();
	QMeeGoGraphicsSystemHelper::switchToMeeGo();
	QMeeGoGraphicsSystemHelper::switchToRaster();
	\endcode
	*/

	class Q_DECL_EXPORT QMeeGoGraphicsSystemHelper
	{
	public:
	//! Returns true if running meego.
	/*!
	Returns true if the currently active (running) system is 'meego' with OpenGL.
	This returns both true if the app was started with 'meego' or was started with
	'runtime' graphics system and the currently active system through the runtime
	switching is 'meego'.
	*/
	static bool isRunningMeeGo();

	//! Returns true if running with a 'runtime' graphicssystem.
	/*!
	This function can be used in combination with ::runningGraphicsSystemName to figure out
	the existing situation.
	*/
	static bool isRunningRuntime();

	//! Enables the sending of QMeeGoSwitchEvent's when the graphicssystem switches.
	/*!
	An application that wishes to start receive QMeegoSwitchEvents must call this function.
	*/
	static void enableSwitchEvents();

	//! Switches to meego graphics system.
	/*!
	When running with the 'runtime' graphics system, sets the currently active
	system to 'meego'. The window surface and all the resources are automatically
	migrated to OpenGL. Will fail if the active graphics system is not 'runtime'.
	Calling this function will emit QMeeGoSwitchEvent to the top level widgets.
	If switch events are enabled, two events will be emitted for each switch --
	one before the switch (QMeeGoSwitchEvent::WillSwitch) and one after the
	switch (QMeeGoSwitchEvent::DidSwitch).
	If the switch policy is set to NoSwitch, this function has no effect.
	*/
	static void switchToMeeGo();

	//! Switches to raster graphics system
	/*!
	When running with the 'runtime' graphics system, sets the currently active
	system to 'raster'. The window surface and the graphics resources (including the
	EGL shared image resources) are automatically migrated back to the CPU. All OpenGL
	resources (surface, context, cache, font cache) are automaticall anihilated.
	Calling this function will emit QMeeGoSwitchEvent to the top level widgets. If switch
	events are enabled, two events will be emitted for each switch -- one before the
	switch (QMeeGoSwitchEvent::WillSwitch) and one after the switch (QMeeGoSwitchEvent::DidSwitch).
	If the switch policy is set to NoSwitch, this function has no effect.
	*/
	static void switchToRaster();

	//! Used to specify the policy for graphics system switching.
	enum SwitchPolicy {
	AutomaticSwitch, /*< Automatic switching /
	ManualSwitch, /*< Switching is controleld by the application /
	NoSwitch /*< Switching is disabled completely /
	};

	//! Sets the policy of graphicssystem switching
	/*!
	By default, the switch to raster happens automatically when all windows are either
	minimized or when the last window is destroyed. This function lets the application
	change the graphicssystem switching policy to prevent the switching from happening
	automatically (that is if the application doesn't want switching at all or wishes
	to control the switching manually).
	*/
	static void setSwitchPolicy(SwitchPolicy policy);

	//! Returns the name of the active graphics system
	/*!
	Returns the name of the currently active system. If running with 'runtime' graphics
	system, returns the name of the active system inside the runtime graphics system
	*/
	static QString runningGraphicsSystemName();

	//! Creates a new EGL shared image.
	/*!
	Creates a new EGL shared image from the given image. The EGL shared image wraps
	a GL texture in the native format and can be easily accessed from other processes.
	*/
	static Qt::HANDLE imageToEGLSharedImage(const QImage &image);

	//! Creates a QPixmap from an EGL shared image
	/*!
	Creates a new QPixmap from the given EGL shared image handle. The QPixmap can be
	used for painting like any other pixmap. The softImage should point to an alternative,
	software version of the graphical resource -- ie. obtained from theme daemon. The
	softImage can be allocated on a QSharedMemory slice for easy sharing across processes
	too. When the application is migrated ToRaster, this softImage will replace the
	contents of the sharedImage.

	It's ok to call this function too when not running 'meego' graphics system. In this
	case it'll create a QPixmap backed with a raster data (from softImage)... but when
	the system is switched back to 'meego', the QPixmap will be migrated to a EGL-shared image
	backed storage (handle).
	*/
	static QPixmap pixmapFromEGLSharedImage(Qt::HANDLE handle, const QImage &softImage);

	//! Destroys an EGL shared image.
	/*!
	Destroys an EGLSharedImage previously created with an ::imageToEGLSharedImage call.
	Returns true if the image was found and the destruction was successful. Notice that
	this destroys the image for all processes using it.
	*/
	static bool destroyEGLSharedImage(Qt::HANDLE handle);

	//! Updates the QPixmap backed with an EGLShared image.
	/*!
	This function re-reads the softImage that was specified when creating the pixmap with
	::pixmapFromEGLSharedImage and updates the EGL Shared image contents. It can be used
	to share cross-proccess mutable EGLShared images.
	*/
	static void updateEGLSharedImagePixmap(QPixmap *p);

	//! Create a new QPixmap with a GL texture.
	/*!
	Creates a new QPixmap which is backed by an OpenGL local texture. Drawing to this
	QPixmap will be accelerated by hardware -- unlike the normal (new QPixmap()) pixmaps,
	which are backed by a software engine and only migrated to GPU when used. Migrating those
	GL-backed pixmaps when going ToRaster is expsensive (they need to be downloaded from
	GPU to CPU) so use wisely.
	*/
	static QPixmap pixmapWithGLTexture(int w, int h);

	//! Sets translucency (alpha) on the base window surface.
	/*!
	This function needs to be called before any widget/content is created.
	When called with true, the base window surface will be translucent and initialized
	with QGLFormat.alpha == true.

	This function is deprecated. Set Qt::WA_TranslucentBackground attribute
	on the top-level widget before you show it instead.
	*/
	static void setTranslucent(bool translucent);

	//! Used to specify the mode for swapping buffers in double-buffered GL rendering.
	enum SwapMode {
	AutomaticSwap, /*< Automatically choose netween full and partial updates (25% threshold) /
	AlwaysFullSwap, /*< Always do a full swap even if partial updates support present /
	AlwaysPartialSwap, /*< Always do a partial swap (if support present) no matter what threshold /
	KillSwap /*< Do not perform buffer swapping at all (no picture) /
	};

	//! Sets the buffer swapping mode.
	/*!
	This can be only called when running with the meego graphics system.
	The KillSwap mode can be specififed to effectively block painting.

	This functionality should be used only by applications counting on a specific behavior.
	Most applications should use the default automatic behavior.
	*/
	static void setSwapBehavior(SwapMode mode);
	};

	#endif