qt-everywhere-src-5.14.1/qtbase/src/platformheaders/nativecontexts/qwglnativecontext.qdoc

/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
  \class QWGLNativeContext
  \inmodule QtPlatformHeaders
  \since 5.4

  \brief A class encapsulating a WGL context on Windows with desktop OpenGL (opengl32.dll).

  \note There is no binary compatibility guarantee for this class,
  meaning that an application using it is only guaranteed to work with the Qt
  version it was developed against.

  QWGLNativeContext is a value class that can be passed to
  QOpenGLContext::setNativeHandle(). When creating a QOpenGLContext with the
  native handle set, no new context will get created. Instead, the provided
  handles are used, without taking ownership. This allows wrapping a context
  created by an external framework or rendering engine. The typical usage will
  be similar to the following snippet:

  \code
      #include <QtPlatformSupport/QWGLNativeContext>
      ...create and retrieve the WGL context and the corresponding window...
      QOpenGLContext *context = new QOpenGLContext;
      QWGLNativeContext nativeContext(hglrc, hwnd);
      context->setNativeHandle(QVariant::fromValue(nativeContext));
      context->create();
      ...
  \endcode

  The window is needed because the its pixel format will be queried. When the
  adoption is successful, QOpenGLContext::format() will return a QSurfaceFormat
  describing this pixel format.

  It is recommended to restrict the usage of QOpenGLContexts created this way.
  Various platform-specific behavior and issues may prevent such contexts to be
  made current with windows (surfaces) created by Qt due to non-matching pixel
  formats for example. A potentially safer solution is to use the wrapped
  context only to set up sharing and perform Qt-based rendering offscreen,
  using a separate, dedicated QOpenGLContext. The resulting textures are then
  accessible in the foreign context too.

  \code
      ...like above...
      QOpenGLContext *qtcontext = new QOpenGLContext;
      qtcontext->setShareContext(context);
      qtcontext->setFormat(context->format());
      qtcontext->create();
      ...use qtcontext for rendering with Qt...
  \endcode

  In addition to being used with QOpenGLContext::setNativeHandle(), this class
  is used also to retrieve the native context handle, that is, a HGLRC value,
  from a QOpenGLContext. Calling QOpenGLContext::nativeHandle() returns a
  QVariant which, on Windows with opengl32.dll at least, will contain a
  QWGLNativeContext:

  \code
      QVariant nativeHandle = context->nativeHandle();
      if (!nativeHandle.isNull() && nativeHandle.canConvert<QWGLNativeContext>()) {
          QWGLNativeContext nativeContext = nativeHandle.value<QWGLNativeContext>();
          HGLRC hglrc = nativeContext.context();
          ...
      }
  \endcode

  \sa QOpenGLContext::setNativeHandle(), QOpenGLContext::nativeHandle()
 */

/*!
  \fn HGLRC QWGLNativeContext::context() const

  \return the WGL context.
 */

/*!
  \fn HWND QWGLNativeContext::window() const

  \note The window handle is not available when the QWGLNativeContext is
  queried from a regular, non-adopted QOpenGLContext using
  QOpenGLContext::nativeHandle(). This is because the \e windows platform
  plugin creates WGL contexts using a dummy window that is not available
  afterwards. Instead, the native window handle (HWND) is queriable from a
  QWindow via QPlatformNativeInterface::nativeResourceForWindow() using the \e
  "handle" resource key. Note however that the window will not have its pixel
  format set until it is first associated with a context via
  QOpenGLContext::makeCurrent().

  \return handle for the window for which the context was created.
 */

/*!
  \fn QWGLNativeContext::QWGLNativeContext()

  Construct a new instance with no handles.
 */

/*!
  \fn QWGLNativeContext::QWGLNativeContext(HGLRC ctx, HWND wnd)

  Constructs a new instance with the provided \a ctx context handle and \a wnd window handle.

  \note The window specified by \a wnd must have its pixel format set to a
  format compatible with the context's. If no SetPixelFormat() call was made on
  any device context belonging to the window, adopting the context will fail.
 */