HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
glContext.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_GLF_GL_CONTEXT_H
25 #define PXR_IMAGING_GLF_GL_CONTEXT_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/glf/api.h"
29 #include "pxr/base/arch/threads.h"
30 
31 #include <memory>
32 
34 
35 
36 typedef std::shared_ptr<class GlfGLContext> GlfGLContextSharedPtr;
37 
38 /// \class GlfGLContext
39 ///
40 /// Provides window system independent access to GL contexts.
41 ///
42 /// All OpenGL operation occurs within a current GL Context. The GL
43 /// contexts used by an application are allocated and managed by the window
44 /// system interface layer, i.e. Qt, GLUT, GLX, etc.
45 ///
46 /// This class provides a way for lower-level OpenGL framework code to
47 /// get useful information about the GL contexts in use by the application.
48 ///
49 /// This mechanism depends on the application code registering callbacks to
50 /// provide access to its GL contexts.
51 ///
53 {
54 public:
55  GLF_API
56  virtual ~GlfGLContext();
57 
58  // Disallow copies
59  GlfGLContext(const GlfGLContext&) = delete;
60  GlfGLContext& operator=(const GlfGLContext&) = delete;
61 
62  /// Returns an instance for the current GL context.
63  GLF_API
65 
66  /// Returns an instance for the shared GL context.
67  GLF_API
69 
70  /// Makes \p context current if valid, otherwise makes no context current.
71  GLF_API
72  static void MakeCurrent(const GlfGLContextSharedPtr& context);
73 
74  /// Returns \c true if \a context1 and \a context2 are sharing.
75  GLF_API
76  static bool AreSharing(GlfGLContextSharedPtr const & context1,
77  GlfGLContextSharedPtr const & context2);
78 
79  /// Returns whether this interface has been initialized.
80  GLF_API
81  static bool IsInitialized();
82 
83  /// Returns \c true if this context is current.
84  GLF_API
85  bool IsCurrent() const;
86 
87 private:
88  /// Makes this context current.
89  ///
90  /// If the context is not valid this does nothing.
91  void MakeCurrent();
92 
93 public:
94  /// Makes no context current.
95  GLF_API
96  static void DoneCurrent();
97 
98  /// Returns \c true if this context is sharing with \a otherContext.
99  GLF_API
100  bool IsSharing(GlfGLContextSharedPtr const & otherContext);
101 
102  /// Returns \c true if this context is valid.
103  virtual bool IsValid() const = 0;
104 
105  /// Creates a new GlfContext that shares GL resources with this context.
106  /// The purpose of this function is to be able to create a new GL context
107  /// on a second thread that shares with the context on the main-thread.
108  /// If the GlfContext implementation does not support sharing contexts
109  /// null is returned. Example usage:
110  /// Main-thread:
111  /// RegisterGLContextCallbacks();
112  /// GlfGLContext::MakeCurrent(...);
113  /// Second-thread:
114  /// s = GetCurrentGLContext();
115  /// c = s->CreateSharingContext();
116  virtual GlfGLContextSharedPtr CreateSharingContext() {return nullptr;}
117 
118 protected:
119  GLF_API
120  GlfGLContext();
121 
122  /// Makes this context current.
123  virtual void _MakeCurrent() = 0;
124 
125  /// Returns \c true if this context is sharing with \a rhs.
126  virtual bool _IsSharing(const GlfGLContextSharedPtr& rhs) const = 0;
127 
128  /// Returns \c true if this context is equal to \p rhs.
129  virtual bool _IsEqual(const GlfGLContextSharedPtr& rhs) const = 0;
130 };
131 
132 /// \class GlfGLContextScopeHolder
133 ///
134 /// Helper class to make a GL context current.
135 ///
136 /// It is often useful to wrap a dynamic GL resource with a class interface.
137 ///
138 /// In addition to providing API to make it more convenient to use the
139 /// underlying GL resource, the lifetime of the underlying resource can
140 /// be tied to the lifetime of a wrapper object instance, e.g. allocate
141 /// the GL resource during construction, delete the GL resource during
142 /// destruction.
143 ///
144 /// While the construction and use of these kinds of wrapper objects is
145 /// usually pretty safe and straightforward, it can be more difficult to
146 /// manage destruction. Specifically, it can be hard to guarantee that
147 /// a suitable GL context is current at the time that a wrapper object
148 /// instance is destroyed. If a suitable context is not current, then
149 /// it will not be possible to delete the underlying resource, which
150 /// may cause the resource to remain allocated, which will then result
151 /// in a resource leak.
152 ///
153 /// Typically, these GL resources are allocated from contexts which are
154 /// sharing the GL resources. In which case it is sufficient for any one
155 /// one of the sharing contexts to be current in order to be able to safely
156 /// delete the GL resource from the destructor of a wrapper object.
157 ///
158 /// GlfGLContext and GlfGLContextScopeHolder can help.
159 ///
160 /// When GlfGLContext has been initialized, i.e. when suitable context
161 /// callbacks have been registered, we can use GlfGLContext to make
162 /// a GL context current.
163 ///
164 /// GlfGLContextScopeHolder does this automatically for the duration
165 /// of a code block.
166 ///
167 /// The underlying calls to make GL contexts current can be moderately
168 /// expensive. So, this mechanism should be used carefully.
169 ///
171 {
172 public:
173  /// Make the given context current and restore the current context
174  /// when this object is destroyed.
175  GLF_API
176  explicit GlfGLContextScopeHolder(const GlfGLContextSharedPtr& newContext);
177 
178  GLF_API
180 
181  GlfGLContextScopeHolder(const GlfGLContextScopeHolder&) = delete;
182  GlfGLContextScopeHolder& operator=(const GlfGLContextScopeHolder) = delete;
183 
184 protected:
185  GLF_API
186  void _MakeNewContextCurrent();
187  GLF_API
188  void _RestoreOldContext();
189 
190 private:
191  GlfGLContextSharedPtr _newContext;
192  GlfGLContextSharedPtr _oldContext;
193 };
194 
195 /// \class GlfSharedGLContextScopeHolder
196 ///
197 /// Helper class to make the shared GL context current.
198 ///
199 /// Example:
200 ///
201 /// \code
202 /// class MyTexture {
203 /// public:
204 /// MyTexture() : _textureId(0) {
205 /// // allocate from the shared context pool.
206 /// GlfSharedGLContextScopeHolder sharedContextScopeHolder;
207 /// glGenTextures(1, &_textureId);
208 /// }
209 ///
210 /// ~MyTexture() {
211 /// // delete from the shared context pool.
212 /// GlfSharedGLContextScopeHolder sharedContextScopeHolder;
213 /// glDeleteTextures(1, &_texureId);
214 /// _textureId = 0;
215 /// }
216 ///
217 /// // The caller is responsible for making sure that a suitable
218 /// // GL context is current before calling other methods.
219 ///
220 /// void Bind() {
221 /// glBindTexture(GL_TEXTURE_2D, _textureId);
222 /// }
223 ///
224 /// void Unbind() {
225 /// glBindTexture(GL_TEXTURE_2D, 0);
226 /// }
227 ///
228 /// ...
229 ///
230 /// private:
231 /// GLuint _textureId;
232 ///
233 /// };
234 /// \endcode
235 ///
237 {
238 public:
240  GlfGLContextScopeHolder(_GetSharedContext())
241  {
242  // Do nothing
243  }
244 
245 private:
246  static GlfGLContextSharedPtr _GetSharedContext()
247  {
250  }
251  return GlfGLContextSharedPtr();
252  }
253 };
254 
255 #define API_GLF_HAS_ANY_GL_CONTEXT_SCOPE_HOLDER 1
256 
257 /// \class GlfAnyGLContextScopeHolder
258 ///
259 /// Helper class to make the shared GL context current if there is no
260 /// valid current context.
261 ///
262 /// Example:
263 ///
264 /// \code
265 /// class MyTexture {
266 /// public:
267 /// MyTexture() : _textureId(0) {
268 /// // Ensure we have valid GL context to allocate
269 /// GlfAnyGLContextScopeHolder anyContextScopeHolder;
270 /// glGenTextures(1, &_textureId);
271 /// }
272 ///
273 /// ~MyTexture() {
274 /// // Ensure we have valid GL context to delete
275 /// GlfAnyGLContextScopeHolder anyContextScopeHolder;
276 /// glDeleteTextures(1, &_texureId);
277 /// _textureId = 0;
278 /// }
279 ///
280 /// // The caller is responsible for making sure that a suitable
281 /// // GL context is current before calling other methods.
282 ///
283 /// void Bind() {
284 /// glBindTexture(GL_TEXTURE_2D, _textureId);
285 /// }
286 ///
287 /// void Unbind() {
288 /// glBindTexture(GL_TEXTURE_2D, 0);
289 /// }
290 ///
291 /// ...
292 ///
293 /// private:
294 /// GLuint _textureId;
295 ///
296 /// };
297 /// \endcode
298 ///
300 {
301 public:
303  GlfGLContextScopeHolder(_GetAnyContext())
304  {
305  // Do nothing
306  }
307 
308 private:
309  static GlfGLContextSharedPtr _GetAnyContext()
310  {
312  GlfGLContextSharedPtr const current =
314  if (!(current && current->IsValid())) {
316  }
317  }
318  return GlfGLContextSharedPtr();
319  }
320 };
321 
322 /// \class GlfGLContextRegistrationInterface
323 ///
324 /// Interface for registering a GlfGLContext system.
325 ///
326 /// If you subclass GlfGLContext you should subclass this type and
327 /// instantiate an instance on the heap. It will be cleaned up
328 /// automatically.
330 {
331 public:
332  GLF_API
334 
335  // Disallow copies
337  const GlfGLContextRegistrationInterface&) = delete;
339  const GlfGLContextRegistrationInterface&) = delete;
340 
341  /// If this GLContext system supports a shared context this should
342  /// return it. This will be called at most once.
343  virtual GlfGLContextSharedPtr GetShared() = 0;
344 
345  /// Whatever your GLContext system thinks is the current GL context
346  /// may not really be the current context if another system has since
347  /// changed the context. This method should return what it thinks is
348  /// the current context. If it thinks there is no current context it
349  /// should return \c NULL.
350  virtual GlfGLContextSharedPtr GetCurrent() = 0;
351 
352 protected:
353  GLF_API
355 };
356 
357 
359 
360 #endif
GlfGLContext & operator=(const GlfGLContext &)=delete
static GLF_API bool IsInitialized()
Returns whether this interface has been initialized.
#define GLF_API
Definition: api.h:40
GLF_API GlfGLContext()
virtual void _MakeCurrent()=0
Makes this context current.
static GLF_API void DoneCurrent()
Makes no context current.
static GLF_API GlfGLContextSharedPtr GetSharedGLContext()
Returns an instance for the shared GL context.
virtual GLF_API ~GlfGLContext()
GLF_API void _MakeNewContextCurrent()
virtual bool IsValid() const =0
Returns true if this context is valid.
GlfGLContextScopeHolder & operator=(const GlfGLContextScopeHolder)=delete
virtual bool _IsEqual(const GlfGLContextSharedPtr &rhs) const =0
Returns true if this context is equal to rhs.
GLF_API bool IsCurrent() const
Returns true if this context is current.
GLF_API bool IsSharing(GlfGLContextSharedPtr const &otherContext)
Returns true if this context is sharing with otherContext.
virtual GLF_API ~GlfGLContextRegistrationInterface()
PXR_NAMESPACE_OPEN_SCOPE ARCH_API bool ArchIsMainThread()
std::shared_ptr< class GlfGLContext > GlfGLContextSharedPtr
Definition: drawTarget.h:50
virtual GlfGLContextSharedPtr CreateSharingContext()
Definition: glContext.h:116
static GLF_API bool AreSharing(GlfGLContextSharedPtr const &context1, GlfGLContextSharedPtr const &context2)
Returns true if context1 and context2 are sharing.
static GLF_API void MakeCurrent(const GlfGLContextSharedPtr &context)
Makes context current if valid, otherwise makes no context current.
GLF_API void _RestoreOldContext()
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1375
GLF_API GlfGLContextScopeHolder(const GlfGLContextSharedPtr &newContext)
PXR_NAMESPACE_OPEN_SCOPE typedef std::shared_ptr< class GlfGLContext > GlfGLContextSharedPtr
Definition: glContext.h:36
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
GlfGLContextRegistrationInterface & operator=(const GlfGLContextRegistrationInterface &)=delete
virtual bool _IsSharing(const GlfGLContextSharedPtr &rhs) const =0
Returns true if this context is sharing with rhs.
static GLF_API GlfGLContextSharedPtr GetCurrentGLContext()
Returns an instance for the current GL context.
virtual GlfGLContextSharedPtr GetShared()=0
GLF_API ~GlfGLContextScopeHolder()
virtual GlfGLContextSharedPtr GetCurrent()=0