1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 /* This Source Code Form is subject to the terms of the Mozilla Public
3 * License, v. 2.0. If a copy of the MPL was not distributed with this
4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #ifndef WEBGLOBJECTMODEL_H_
7 #define WEBGLOBJECTMODEL_H_
9 #include "nsCycleCollectionNoteChild.h"
10 #include "nsICanvasRenderingContextInternal.h"
11 #include "WebGLTypes.h"
18 /* Each WebGL object class WebGLFoo wants to:
19 * - inherit WebGLRefCountedObject<WebGLFoo>
20 * - implement a Delete() method
21 * - have its destructor call DeleteOnce()
23 * This base class provides two features to WebGL object types:
24 * 1. support for OpenGL object reference counting
25 * 2. support for OpenGL deletion statuses
27 ***** 1. OpenGL object reference counting *****
29 * WebGL objects such as WebGLTexture's really have two different refcounts:
30 * the XPCOM refcount, that is directly exposed to JavaScript, and the OpenGL
33 * For example, when in JavaScript one does: var newname = existingTexture;
34 * that increments the XPCOM refcount, but doesn't affect the OpenGL refcount.
35 * When one attaches the texture to a framebuffer object, that does increment
36 * its OpenGL refcount (and also its XPCOM refcount, to prevent the regular
37 * XPCOM refcounting mechanism from destroying objects prematurely).
39 * The actual OpenGL refcount is opaque to us (it's internal to the OpenGL
40 * implementation) but is affects the WebGL semantics that we have to implement:
41 * for example, a WebGLTexture that is attached to a WebGLFramebuffer must not
42 * be actually deleted, even if deleteTexture has been called on it, and even
43 * if JavaScript doesn't have references to it anymore. We can't just rely on
44 * OpenGL to keep alive the underlying OpenGL texture for us, for a variety of
45 * reasons, most importantly: we'd need to know when OpenGL objects are actually
46 * deleted, and OpenGL doesn't notify us about that, so we would have to query
47 * status very often with glIsXxx calls which isn't practical.
49 * This means that we have to keep track of the OpenGL refcount ourselves,
50 * in addition to the XPCOM refcount.
52 * This class implements such a refcount, see the mWebGLRefCnt
53 * member. In order to avoid name clashes (with regular XPCOM refcounting)
54 * in the derived class, we prefix members with 'WebGL', whence the names
55 * WebGLAddRef, WebGLRelease, etc.
57 * In practice, WebGLAddRef and WebGLRelease are only called from the
60 ***** 2. OpenGL deletion statuses *****
62 * In OpenGL, an object can go through 3 different deletion statuses during its
63 * lifetime, which correspond to the 3 enum values for DeletionStatus in this class:
64 * - the Default status, which it has from its creation to when the
65 * suitable glDeleteXxx function is called on it;
66 * - the DeleteRequested status, which is has from when the suitable glDeleteXxx
67 * function is called on it to when it is no longer referenced by other OpenGL
68 * objects. For example, a texture that is attached to a non-current FBO
69 * will enter that status when glDeleteTexture is called on it. For objects
70 * with that status, GL_DELETE_STATUS queries return true, but glIsXxx
71 * functions still return true.
72 * - the Deleted status, which is the status of objects on which the
73 * suitable glDeleteXxx function has been called, and that are not referenced
74 * by other OpenGL objects.
76 * This state is stored in the mDeletionStatus member of this class.
78 * When the GL refcount hits zero, if the status is DeleteRequested then we call
79 * the Delete() method on the derived class and the status becomes Deleted. This is
80 * what the MaybeDelete() function does.
82 * The DeleteOnce() function implemented here is a helper to ensure that we don't
83 * call Delete() twice on the same object. Since the derived class' destructor
84 * needs to call DeleteOnce() which calls Delete(), we can't allow either to be
85 * virtual. Strictly speaking, we could let them be virtual if the derived class
86 * were final, but that would be impossible to enforce and would lead to strange
87 * bugs if it were subclassed.
89 * This WebGLRefCountedObject class takes the Derived type
90 * as template parameter, as a means to allow DeleteOnce to call Delete()
91 * on the Derived class, without either method being virtual. This is a common
92 * C++ pattern known as the "curiously recursive template pattern (CRTP)".
94 template<typename Derived
>
95 class WebGLRefCountedObject
98 enum DeletionStatus
{ Default
, DeleteRequested
, Deleted
};
100 WebGLRefCountedObject()
101 : mDeletionStatus(Default
)
104 ~WebGLRefCountedObject() {
105 MOZ_ASSERT(mWebGLRefCnt
== 0, "destroying WebGL object still referenced by other WebGL objects");
106 MOZ_ASSERT(mDeletionStatus
== Deleted
, "Derived class destructor must call DeleteOnce()");
109 // called by WebGLRefPtr
114 // called by WebGLRefPtr
115 void WebGLRelease() {
116 MOZ_ASSERT(mWebGLRefCnt
> 0, "releasing WebGL object with WebGL refcnt already zero");
121 // this is the function that WebGL.deleteXxx() functions want to call
122 void RequestDelete() {
123 if (mDeletionStatus
== Default
)
124 mDeletionStatus
= DeleteRequested
;
128 bool IsDeleted() const {
129 return mDeletionStatus
== Deleted
;
132 bool IsDeleteRequested() const {
133 return mDeletionStatus
!= Default
;
137 if (mDeletionStatus
!= Deleted
) {
138 static_cast<Derived
*>(this)->Delete();
139 mDeletionStatus
= Deleted
;
145 if (mWebGLRefCnt
== 0 &&
146 mDeletionStatus
== DeleteRequested
)
153 nsAutoRefCnt mWebGLRefCnt
;
154 DeletionStatus mDeletionStatus
;
157 /* This WebGLRefPtr class is meant to be used for references between WebGL objects.
158 * For example, a WebGLProgram holds WebGLRefPtr's to the WebGLShader's attached
161 * Why the need for a separate refptr class? The only special thing that WebGLRefPtr
162 * does is that it increments and decrements the WebGL refcount of
163 * WebGLRefCountedObject's, in addition to incrementing and decrementing the
164 * usual XPCOM refcount.
166 * This means that by using a WebGLRefPtr instead of a nsRefPtr, you ensure that
167 * the WebGL refcount is incremented, which means that the object will be kept
168 * alive by this reference even if the matching webgl.deleteXxx() function is
179 WebGLRefPtr(const WebGLRefPtr
<T
>& aSmartPtr
)
180 : mRawPtr(aSmartPtr
.mRawPtr
)
182 AddRefOnPtr(mRawPtr
);
185 explicit WebGLRefPtr(T
* aRawPtr
)
188 AddRefOnPtr(mRawPtr
);
196 operator=(const WebGLRefPtr
<T
>& rhs
)
198 assign_with_AddRef(rhs
.mRawPtr
);
205 assign_with_AddRef(rhs
);
210 return static_cast<T
*>(mRawPtr
);
213 operator T
*() const {
217 T
* operator->() const {
218 MOZ_ASSERT(mRawPtr
!= 0, "You can't dereference a nullptr WebGLRefPtr with operator->()!");
222 T
& operator*() const {
223 MOZ_ASSERT(mRawPtr
!= 0, "You can't dereference a nullptr WebGLRefPtr with operator*()!");
229 static void AddRefOnPtr(T
* rawPtr
) {
231 rawPtr
->WebGLAddRef();
236 static void ReleasePtr(T
* rawPtr
) {
238 rawPtr
->WebGLRelease(); // must be done first before Release(), as Release() might actually destroy the object
243 void assign_with_AddRef(T
* rawPtr
) {
245 assign_assuming_AddRef(rawPtr
);
248 void assign_assuming_AddRef(T
* newPtr
) {
258 // This class is a mixin for objects that are tied to a specific
259 // context (which is to say, all of them). They provide initialization
260 // as well as comparison with the current context.
261 class WebGLContextBoundObject
264 explicit WebGLContextBoundObject(WebGLContext
* context
);
266 bool IsCompatibleWithContext(WebGLContext
*other
);
268 WebGLContext
*Context() const { return mContext
; }
271 WebGLContext
*mContext
;
272 uint32_t mContextGeneration
;
275 // this class is a mixin for GL objects that have dimensions
276 // that we need to track.
277 class WebGLRectangleObject
280 WebGLRectangleObject()
281 : mWidth(0), mHeight(0) { }
283 WebGLRectangleObject(GLsizei width
, GLsizei height
)
284 : mWidth(width
), mHeight(height
) { }
286 GLsizei
Width() const { return mWidth
; }
287 void width(GLsizei value
) { mWidth
= value
; }
289 GLsizei
Height() const { return mHeight
; }
290 void height(GLsizei value
) { mHeight
= value
; }
292 void setDimensions(GLsizei width
, GLsizei height
) {
297 void setDimensions(WebGLRectangleObject
*rect
) {
299 mWidth
= rect
->Width();
300 mHeight
= rect
->Height();
307 bool HasSameDimensionsAs(const WebGLRectangleObject
& other
) const {
308 return Width() == other
.Width() && Height() == other
.Height();
316 }// namespace mozilla
318 template <typename T
>
320 ImplCycleCollectionUnlink(mozilla::WebGLRefPtr
<T
>& aField
)
325 template <typename T
>
327 ImplCycleCollectionTraverse(nsCycleCollectionTraversalCallback
& aCallback
,
328 mozilla::WebGLRefPtr
<T
>& aField
,
332 CycleCollectionNoteChild(aCallback
, aField
.get(), aName
, aFlags
);