/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ #ifndef WEBGLOBJECTMODEL_H_ #define WEBGLOBJECTMODEL_H_ #include "mozilla/WeakPtr.h" #include "nsCycleCollectionNoteChild.h" #include "WebGLTypes.h" namespace mozilla { template<typename> class LinkedList; class WebGLContext; //// // This class is a mixin for objects that are tied to a specific // context (which is to say, all of them). They provide initialization // as well as comparison with the current context. class WebGLContextBoundObject { public: const WeakPtr<WebGLContext> mContext; private: const uint32_t mContextGeneration; public: explicit WebGLContextBoundObject(WebGLContext* webgl); bool IsCompatibleWithContext(const WebGLContext* other) const; }; //// class WebGLDeletableObject : public WebGLContextBoundObject { template<typename> friend class WebGLRefCountedObject; private: enum DeletionStatus { Default, DeleteRequested, Deleted }; DeletionStatus mDeletionStatus; //// explicit WebGLDeletableObject(WebGLContext* webgl) : WebGLContextBoundObject(webgl) , mDeletionStatus(Default) { } ~WebGLDeletableObject() { MOZ_ASSERT(mDeletionStatus == Deleted, "Derived class destructor must call DeleteOnce()."); } public: bool IsDeleted() const { return mDeletionStatus == Deleted; } bool IsDeleteRequested() const { return mDeletionStatus != Default; } }; /* Each WebGL object class WebGLFoo wants to: * - inherit WebGLRefCountedObject<WebGLFoo> * - implement a Delete() method * - have its destructor call DeleteOnce() * * This base class provides two features to WebGL object types: * 1. support for OpenGL object reference counting * 2. support for OpenGL deletion statuses * ***** 1. OpenGL object reference counting ***** * * WebGL objects such as WebGLTexture's really have two different refcounts: * the XPCOM refcount, that is directly exposed to JavaScript, and the OpenGL * refcount. * * For example, when in JavaScript one does: var newname = existingTexture; * that increments the XPCOM refcount, but doesn't affect the OpenGL refcount. * When one attaches the texture to a framebuffer object, that does increment * its OpenGL refcount (and also its XPCOM refcount, to prevent the regular * XPCOM refcounting mechanism from destroying objects prematurely). * * The actual OpenGL refcount is opaque to us (it's internal to the OpenGL * implementation) but is affects the WebGL semantics that we have to implement: * for example, a WebGLTexture that is attached to a WebGLFramebuffer must not * be actually deleted, even if deleteTexture has been called on it, and even * if JavaScript doesn't have references to it anymore. We can't just rely on * OpenGL to keep alive the underlying OpenGL texture for us, for a variety of * reasons, most importantly: we'd need to know when OpenGL objects are actually * deleted, and OpenGL doesn't notify us about that, so we would have to query * status very often with glIsXxx calls which isn't practical. * * This means that we have to keep track of the OpenGL refcount ourselves, * in addition to the XPCOM refcount. * * This class implements such a refcount, see the mWebGLRefCnt * member. In order to avoid name clashes (with regular XPCOM refcounting) * in the derived class, we prefix members with 'WebGL', whence the names * WebGLAddRef, WebGLRelease, etc. * * In practice, WebGLAddRef and WebGLRelease are only called from the * WebGLRefPtr class. * ***** 2. OpenGL deletion statuses ***** * * In OpenGL, an object can go through 3 different deletion statuses during its * lifetime, which correspond to the 3 enum values for DeletionStatus in this * class: * - the Default status, which it has from its creation to when the suitable * glDeleteXxx function is called on it; * - the DeleteRequested status, which is has from when the suitable * glDeleteXxx function is called on it to when it is no longer referenced by * other OpenGL objects. For example, a texture that is attached to a * non-current FBO will enter that status when glDeleteTexture is called on * it. For objects with that status, GL_DELETE_STATUS queries return true, * but glIsXxx functions still return true. * - the Deleted status, which is the status of objects on which the suitable * glDeleteXxx function has been called, and that are not referenced by other * OpenGL objects. * * This state is stored in the mDeletionStatus member of this class. * * When the GL refcount hits zero, if the status is DeleteRequested then we call * the Delete() method on the derived class and the status becomes Deleted. This * is what the MaybeDelete() function does. * * The DeleteOnce() function implemented here is a helper to ensure that we * don't call Delete() twice on the same object. Since the derived class's * destructor needs to call DeleteOnce() which calls Delete(), we can't allow * either to be virtual. Strictly speaking, we could let them be virtual if the * derived class were final, but that would be impossible to enforce and would * lead to strange bugs if it were subclassed. * * This WebGLRefCountedObject class takes the Derived type as template * parameter, as a means to allow DeleteOnce to call Delete() on the Derived * class, without either method being virtual. This is a common C++ pattern * known as the "curiously recursive template pattern (CRTP)". */ template<typename Derived> class WebGLRefCountedObject : public WebGLDeletableObject { friend class WebGLContext; template<typename T> friend void ClearLinkedList(LinkedList<T>& list); private: nsAutoRefCnt mWebGLRefCnt; public: explicit WebGLRefCountedObject(WebGLContext* webgl) : WebGLDeletableObject(webgl) { } ~WebGLRefCountedObject() { MOZ_ASSERT(mWebGLRefCnt == 0, "Destroying WebGL object still referenced by other WebGL" " objects."); } // called by WebGLRefPtr void WebGLAddRef() { ++mWebGLRefCnt; } // called by WebGLRefPtr void WebGLRelease() { MOZ_ASSERT(mWebGLRefCnt > 0, "Releasing WebGL object with WebGL refcnt already zero"); --mWebGLRefCnt; MaybeDelete(); } // this is the function that WebGL.deleteXxx() functions want to call void RequestDelete() { if (mDeletionStatus == Default) mDeletionStatus = DeleteRequested; MaybeDelete(); } protected: void DeleteOnce() { if (mDeletionStatus != Deleted) { static_cast<Derived*>(this)->Delete(); mDeletionStatus = Deleted; } } private: void MaybeDelete() { if (mWebGLRefCnt == 0 && mDeletionStatus == DeleteRequested) { DeleteOnce(); } } }; /* This WebGLRefPtr class is meant to be used for references between WebGL * objects. For example, a WebGLProgram holds WebGLRefPtr's to the WebGLShader's * attached to it. * * Why the need for a separate refptr class? The only special thing that * WebGLRefPtr does is that it increments and decrements the WebGL refcount of * WebGLRefCountedObject's, in addition to incrementing and decrementing the * usual XPCOM refcount. * * This means that by using a WebGLRefPtr instead of a nsRefPtr, you ensure that * the WebGL refcount is incremented, which means that the object will be kept * alive by this reference even if the matching webgl.deleteXxx() function is * called on it. */ template<typename T> class WebGLRefPtr { public: WebGLRefPtr() : mRawPtr(0) {} WebGLRefPtr(const WebGLRefPtr<T>& smartPtr) : mRawPtr(smartPtr.mRawPtr) { AddRefOnPtr(mRawPtr); } explicit WebGLRefPtr(T* rawPtr) : mRawPtr(rawPtr) { AddRefOnPtr(mRawPtr); } ~WebGLRefPtr() { ReleasePtr(mRawPtr); } WebGLRefPtr<T>& operator=(const WebGLRefPtr<T>& rhs) { assign_with_AddRef(rhs.mRawPtr); return *this; } WebGLRefPtr<T>& operator=(T* rhs) { assign_with_AddRef(rhs); return *this; } T* get() const { return static_cast<T*>(mRawPtr); } operator T*() const { return get(); } T* operator->() const MOZ_NO_ADDREF_RELEASE_ON_RETURN { MOZ_ASSERT(mRawPtr != 0, "You can't dereference a nullptr WebGLRefPtr with operator->()!"); return get(); } T& operator*() const { MOZ_ASSERT(mRawPtr != 0, "You can't dereference a nullptr WebGLRefPtr with operator*()!"); return *get(); } private: static void AddRefOnPtr(T* rawPtr) { if (rawPtr) { rawPtr->WebGLAddRef(); rawPtr->AddRef(); } } static void ReleasePtr(T* rawPtr) { if (rawPtr) { rawPtr->WebGLRelease(); // must be done first before Release(), as Release() might actually destroy the object rawPtr->Release(); } } void assign_with_AddRef(T* rawPtr) { AddRefOnPtr(rawPtr); assign_assuming_AddRef(rawPtr); } void assign_assuming_AddRef(T* newPtr) { T* oldPtr = mRawPtr; mRawPtr = newPtr; ReleasePtr(oldPtr); } protected: T* mRawPtr; }; // this class is a mixin for GL objects that have dimensions // that we need to track. class WebGLRectangleObject { public: WebGLRectangleObject() : mWidth(0) , mHeight(0) {} WebGLRectangleObject(GLsizei width, GLsizei height) : mWidth(width) , mHeight(height) {} GLsizei Width() const { return mWidth; } void width(GLsizei value) { mWidth = value; } GLsizei Height() const { return mHeight; } void height(GLsizei value) { mHeight = value; } void setDimensions(GLsizei width, GLsizei height) { mWidth = width; mHeight = height; } void setDimensions(WebGLRectangleObject* rect) { if (rect) { mWidth = rect->Width(); mHeight = rect->Height(); } else { mWidth = 0; mHeight = 0; } } bool HasSameDimensionsAs(const WebGLRectangleObject& other) const { return Width() == other.Width() && Height() == other.Height(); } protected: GLsizei mWidth; GLsizei mHeight; }; }// namespace mozilla template <typename T> inline void ImplCycleCollectionUnlink(mozilla::WebGLRefPtr<T>& field) { field = nullptr; } template <typename T> inline void ImplCycleCollectionTraverse(nsCycleCollectionTraversalCallback& callback, mozilla::WebGLRefPtr<T>& field, const char* name, uint32_t flags = 0) { CycleCollectionNoteChild(callback, field.get(), name, flags); } template <typename T> inline void ImplCycleCollectionTraverse(nsCycleCollectionTraversalCallback& callback, const mozilla::WebGLRefPtr<T>& field, const char* name, uint32_t flags = 0) { CycleCollectionNoteChild(callback, field.get(), name, flags); } #endif