1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
/****************************************************************************
**
** 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.
*/
|
