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 public:
172  /// Make the given context current and restore the current context
173  /// when this object is destroyed.
174  GLF_API
175  explicit GlfGLContextScopeHolder(const GlfGLContextSharedPtr& newContext);
176 
177  GLF_API
179 
180  GlfGLContextScopeHolder(const GlfGLContextScopeHolder&) = delete;
181  GlfGLContextScopeHolder& operator=(const GlfGLContextScopeHolder) = delete;
182 
183 protected:
184  GLF_API
185  void _MakeNewContextCurrent();
186  GLF_API
187  void _RestoreOldContext();
188 
189 private:
190  GlfGLContextSharedPtr _newContext;
191  GlfGLContextSharedPtr _oldContext;
192 };
193 
194 /// \class GlfSharedGLContextScopeHolder
195 ///
196 /// Helper class to make the shared GL context current.
197 ///
198 /// Example:
199 ///
200 /// \code
201 /// class MyTexture {
202 /// public:
203 /// MyTexture() : _textureId(0) {
204 /// // allocate from the shared context pool.
205 /// GlfSharedGLContextScopeHolder sharedContextScopeHolder;
206 /// glGenTextures(1, &_textureId);
207 /// }
208 ///
209 /// ~MyTexture() {
210 /// // delete from the shared context pool.
211 /// GlfSharedGLContextScopeHolder sharedContextScopeHolder;
212 /// glDeleteTextures(1, &_texureId);
213 /// _textureId = 0;
214 /// }
215 ///
216 /// // The caller is responsible for making sure that a suitable
217 /// // GL context is current before calling other methods.
218 ///
219 /// void Bind() {
220 /// glBindTexture(GL_TEXTURE_2D, _textureId);
221 /// }
222 ///
223 /// void Unbind() {
224 /// glBindTexture(GL_TEXTURE_2D, 0);
225 /// }
226 ///
227 /// ...
228 ///
229 /// private:
230 /// GLuint _textureId;
231 ///
232 /// };
233 /// \endcode
234 ///
236 public:
238  GlfGLContextScopeHolder(_GetSharedContext())
239  {
240  // Do nothing
241  }
242 
243 private:
244  static GlfGLContextSharedPtr _GetSharedContext()
245  {
248  }
249  return GlfGLContextSharedPtr();
250  }
251 };
252 
253 /// \class GlfGLContextRegistrationInterface
254 ///
255 /// Interface for registering a GlfGLContext system.
256 ///
257 /// If you subclass GlfGLContext you should subclass this type and
258 /// instantiate an instance on the heap. It will be cleaned up
259 /// automatically.
261 {
262 public:
263  GLF_API
265 
266  // Disallow copies
268  const GlfGLContextRegistrationInterface&) = delete;
270  const GlfGLContextRegistrationInterface&) = delete;
271 
272  /// If this GLContext system supports a shared context this should
273  /// return it. This will be called at most once.
274  virtual GlfGLContextSharedPtr GetShared() = 0;
275 
276  /// Whatever your GLContext system thinks is the current GL context
277  /// may not really be the current context if another system has since
278  /// changed the context. This method should return what it thinks is
279  /// the current context. If it thinks there is no current context it
280  /// should return \c NULL.
281  virtual GlfGLContextSharedPtr GetCurrent() = 0;
282 
283 protected:
284  GLF_API
286 };
287 
288 
290 
291 #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:51
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:1346
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