From 37cac00b5ec3f26cb1acd74378940643bb49019a Mon Sep 17 00:00:00 2001 From: Nicolas Silva Date: Mon, 30 Sep 2013 14:42:47 +0200 Subject: [PATCH] Bug 921512 - Add a bit of documentation to layers. r=bjacob --- gfx/layers/CompositorTypes.h | 1 - gfx/layers/client/CompositableClient.h | 21 +++++++++- gfx/layers/client/TextureClient.h | 51 ++++++++++++++++++------- gfx/layers/composite/CompositableHost.h | 8 ++++ 4 files changed, 65 insertions(+), 16 deletions(-) diff --git a/gfx/layers/CompositorTypes.h b/gfx/layers/CompositorTypes.h index 227f541dd2ed..651ad124a08f 100644 --- a/gfx/layers/CompositorTypes.h +++ b/gfx/layers/CompositorTypes.h @@ -48,7 +48,6 @@ const TextureFlags TEXTURE_COMPONENT_ALPHA = 1 << 5; // (for example, with GL), a BGRA shader should be used. const TextureFlags TEXTURE_RB_SWAPPED = 1 << 6; -// A texture host that supports tiling const TextureFlags TEXTURE_FRONT = 1 << 12; // A texture host on white for component alpha const TextureFlags TEXTURE_ON_WHITE = 1 << 13; diff --git a/gfx/layers/client/CompositableClient.h b/gfx/layers/client/CompositableClient.h index daf06ecd7d80..bd2c17d7ebf9 100644 --- a/gfx/layers/client/CompositableClient.h +++ b/gfx/layers/client/CompositableClient.h @@ -115,8 +115,11 @@ public: /** * This identifier is what lets us attach async compositables with a shadow - * layer. It is not used if the compositable is used with the regulat shadow + * layer. It is not used if the compositable is used with the regular shadow * layer forwarder. + * + * If this returns zero, it means the compositable is not async (it is used + * on the main thread). */ uint64_t GetAsyncID() const; @@ -141,8 +144,24 @@ public: */ virtual void OnDetach() {} + /** + * When texture deallocation must happen on the client side, we need to first + * ensure that the compositor has already let go of the data in order + * to safely deallocate it. + * + * This is implemented by registering a callback to postpone deallocation or + * recycling of the shared data. + * + * This hook is called when the compositor notifies the client that it is not + * holding any more references to the shared data so that this compositable + * can run the corresponding callback. + */ void OnReplyTextureRemoved(uint64_t aTextureID); + /** + * Run all he registered callbacks (see the comment for OnReplyTextureRemoved). + * Only call this if you know what you are doing. + */ void FlushTexturesToRemoveCallbacks(); protected: struct TextureIDAndFlags { diff --git a/gfx/layers/client/TextureClient.h b/gfx/layers/client/TextureClient.h index 1c6b798f23c3..2e0d0e5d2a20 100644 --- a/gfx/layers/client/TextureClient.h +++ b/gfx/layers/client/TextureClient.h @@ -124,12 +124,13 @@ public: virtual TextureClientSurface* AsTextureClientSurface() { return nullptr; } virtual TextureClientYCbCr* AsTextureClientYCbCr() { return nullptr; } - virtual void MarkUnused() {} - - virtual bool Lock(OpenMode aMode) - { - return IsValid(); - } + /** + * Locks the shared data, allowing the caller to get access to it. + * + * Please always lock/unlock when accessing the shared data. + * If Lock() returns false, you should not attempt to access the shared data. + */ + virtual bool Lock(OpenMode aMode) { return IsValid(); } virtual void Unlock() {} @@ -138,11 +139,18 @@ public: * Textures that do not implement locking should be immutable or should * use immediate uploads (see TextureFlags in CompositorTypes.h) */ - virtual bool ImplementsLocking() const - { - return false; - } + virtual bool ImplementsLocking() const { return false; } + /** + * Sets this texture's ID. + * + * This ID is used to match a texture client with his corresponding TextureHost. + * Only the CompositableClient should be allowed to set or clear the ID. + * Zero is always an invalid ID. + * For a given compositableClient, there can never be more than one texture + * client with the same non-zero ID. + * Texture clients from different compositables may have the same ID. + */ void SetID(uint64_t aID) { MOZ_ASSERT(mID == 0 && aID != 0); @@ -155,10 +163,7 @@ public: mID = 0; } - uint64_t GetID() const - { - return mID; - } + uint64_t GetID() const { return mID; } virtual bool IsAllocated() const = 0; @@ -166,8 +171,22 @@ public: virtual gfx::IntSize GetSize() const = 0; + /** + * Drop the shared data into a TextureClientData object and mark this + * TextureClient as invalid. + * + * The TextureClient must not hold any reference to the shared data + * after this method has been called. + * The TextureClientData is owned by the caller. + */ virtual TextureClientData* DropTextureData() = 0; + /** + * TextureFlags contain important information about various aspects + * of the texture, like how its liferime is managed, and how it + * should be displayed. + * See TextureFlags in CompositorTypes.h. + */ TextureFlags GetFlags() const { return mFlags; } /** @@ -189,6 +208,10 @@ public: */ bool IsValid() const { return mValid; } + /** + * An invalid TextureClient cannot provide access to its shared data + * anymore. This usually means it will soon be destroyed. + */ void MarkInvalid() { mValid = false; } protected: diff --git a/gfx/layers/composite/CompositableHost.h b/gfx/layers/composite/CompositableHost.h index 5c5bc7de999a..af1eeae563b1 100644 --- a/gfx/layers/composite/CompositableHost.h +++ b/gfx/layers/composite/CompositableHost.h @@ -303,6 +303,14 @@ protected: class CompositableParentManager; +/** + * IPDL actor used by CompositableHost to match with its corresponding + * CompositableClient on the content side. + * + * CompositableParent is owned by the IPDL system. It's deletion is triggered + * by either the CompositableChild's deletion, or by the IPDL communication + * goind down. + */ class CompositableParent : public PCompositableParent { public: