The Tor Browser: comparison gfx/layers/client/TextureClient.h

--1:000000000000
+:3ddbb33ab111
+/* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+//  * 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 MOZILLA_GFX_TEXTURECLIENT_H
+#define MOZILLA_GFX_TEXTURECLIENT_H
+#include <stddef.h>                     // for size_t
+#include <stdint.h>                     // for uint32_t, uint8_t, uint64_t
+#include "GLContextTypes.h"             // for GLContext (ptr only), etc
+#include "GLTextureImage.h"             // for TextureImage
+#include "ImageTypes.h"                 // for StereoMode
+#include "mozilla/Assertions.h"         // for MOZ_ASSERT, etc
+#include "mozilla/Attributes.h"         // for MOZ_OVERRIDE
+#include "mozilla/RefPtr.h"             // for RefPtr, RefCounted
+#include "mozilla/gfx/2D.h"             // for DrawTarget
+#include "mozilla/gfx/Point.h"          // for IntSize
+#include "mozilla/gfx/Types.h"          // for SurfaceFormat
+#include "mozilla/layers/FenceUtils.h"  // for FenceHandle
+#include "mozilla/ipc/Shmem.h"          // for Shmem
+#include "mozilla/layers/AtomicRefCountedWithFinalize.h"
+#include "mozilla/layers/CompositorTypes.h"  // for TextureFlags, etc
+#include "mozilla/layers/LayersSurfaces.h"  // for SurfaceDescriptor
+#include "mozilla/layers/PTextureChild.h" // for PTextureChild
+#include "mozilla/mozalloc.h"           // for operator delete
+#include "nsAutoPtr.h"                  // for nsRefPtr
+#include "nsCOMPtr.h"                   // for already_AddRefed
+#include "nsISupportsImpl.h"            // for TextureImage::AddRef, etc
+class gfxReusableSurfaceWrapper;
+class gfxImageSurface;
+namespace mozilla {
+namespace layers {
+class ContentClient;
+class CompositableForwarder;
+class ISurfaceAllocator;
+class CompositableClient;
+class PlanarYCbCrImage;
+class PlanarYCbCrData;
+class Image;
+class PTextureChild;
+class TextureChild;
+class BufferTextureClient;
+class TextureClient;
+/**
+* TextureClient is the abstraction that allows us to share data between the
+* content and the compositor side.
+*/
+enum TextureAllocationFlags {
+ALLOC_DEFAULT = 0,
+ALLOC_CLEAR_BUFFER = 1
+};
+/**
+* Interface for TextureClients that can be updated using YCbCr data.
+*/
+class TextureClientYCbCr
+{
+public:
+/**
+* Copy aData into this texture client.
+*
+* This must never be called on a TextureClient that is not sucessfully locked.
+*/
+virtual bool UpdateYCbCr(const PlanarYCbCrData& aData) = 0;
+/**
+* Allocates for a given surface size, taking into account the pixel format
+* which is part of the state of the TextureClient.
+*
+* Does not clear the surface, since we consider that the surface
+* be painted entirely with opaque content.
+*/
+virtual bool AllocateForYCbCr(gfx::IntSize aYSize,
+gfx::IntSize aCbCrSize,
+StereoMode aStereoMode) = 0;
+};
+/**
+* Holds the shared data of a TextureClient, to be destroyed later.
+*
+* TextureClient's destructor initiates the destruction sequence of the
+* texture client/host pair. If the shared data is to be deallocated on the
+* host side, there is nothing to do.
+* On the other hand, if the client data must be deallocated on the client
+* side, the CompositableClient will ask the TextureClient to drop its shared
+* data in the form of a TextureClientData object. This data will be kept alive
+* until the host side confirms that it is not using the data anymore and that
+* it is completely safe to deallocate the shared data.
+*
+* See:
+*  - The PTexture IPDL protocol
+*  - CompositableChild in TextureClient.cpp
+*/
+class TextureClientData {
+public:
+virtual void DeallocateSharedData(ISurfaceAllocator* allocator) = 0;
+virtual ~TextureClientData() {}
+};
+/**
+* TextureClient is a thin abstraction over texture data that need to be shared
+* between the content process and the compositor process. It is the
+* content-side half of a TextureClient/TextureHost pair. A corresponding
+* TextureHost lives on the compositor-side.
+*
+* TextureClient's primary purpose is to present texture data in a way that is
+* understood by the IPC system. There are two ways to use it:
+* - Use it to serialize image data that is not IPC-friendly (most likely
+* involving a copy into shared memory)
+* - preallocate it and paint directly into it, which avoids copy but requires
+* the painting code to be aware of TextureClient (or at least the underlying
+* shared memory).
+*
+* There is always one and only one TextureClient per TextureHost, and the
+* TextureClient/Host pair only owns one buffer of image data through its
+* lifetime. This means that the lifetime of the underlying shared data
+* matches the lifetime of the TextureClient/Host pair. It also means
+* TextureClient/Host do not implement double buffering, which is the
+* responsibility of the compositable (which would use two Texture pairs).
+* In order to send several different buffers to the compositor side, use
+* several TextureClients.
+*/
+class TextureClient
+: public AtomicRefCountedWithFinalize<TextureClient>
+{
+public:
+TextureClient(TextureFlags aFlags = TEXTURE_FLAGS_DEFAULT);
+virtual ~TextureClient();
+static TemporaryRef<BufferTextureClient>
+CreateBufferTextureClient(ISurfaceAllocator* aAllocator,
+gfx::SurfaceFormat aFormat,
+TextureFlags aTextureFlags,
+gfx::BackendType aMoz2dBackend);
+static TemporaryRef<TextureClient>
+CreateTextureClientForDrawing(ISurfaceAllocator* aAllocator,
+gfx::SurfaceFormat aFormat,
+TextureFlags aTextureFlags,
+gfx::BackendType aMoz2dBackend,
+const gfx::IntSize& aSizeHint);
+virtual TextureClientYCbCr* AsTextureClientYCbCr() { return nullptr; }
+/**
+* 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() {}
+virtual bool IsLocked() const = 0;
+virtual bool CanExposeDrawTarget() const { return false; }
+/**
+* Returns a DrawTarget to draw into the TextureClient.
+*
+* This must never be called on a TextureClient that is not sucessfully locked.
+* When called several times within one Lock/Unlock pair, this method should
+* return the same DrawTarget.
+* The DrawTarget is automatically flushed by the TextureClient when the latter
+* is unlocked, and the DrawTarget that will be returned within the next
+* lock/unlock pair may or may not be the same object.
+* Do not keep references to the DrawTarget outside of the lock/unlock pair.
+*
+* This is typically used as follows:
+*
+* if (!texture->Lock(OPEN_READ_WRITE)) {
+*   return false;
+* }
+* {
+*   // Restrict this code's scope to ensure all references to dt are gone
+*   // when Unlock is called.
+*   RefPtr<DrawTarget> dt = texture->GetAsDrawTarget();
+*   // use the draw target ...
+* }
+* texture->Unlock();
+*
+*/
+virtual TemporaryRef<gfx::DrawTarget> GetAsDrawTarget() { return nullptr; }
+// TextureClients that can expose a DrawTarget should override this method.
+virtual gfx::SurfaceFormat GetFormat() const
+{
+return gfx::SurfaceFormat::UNKNOWN;
+}
+/**
+* Allocates for a given surface size, taking into account the pixel format
+* which is part of the state of the TextureClient.
+*
+* Does not clear the surface by default, clearing the surface can be done
+* by passing the CLEAR_BUFFER flag.
+*
+* TextureClients that can expose a DrawTarget should override this method.
+*/
+virtual bool AllocateForSurface(gfx::IntSize aSize,
+TextureAllocationFlags flags = ALLOC_DEFAULT)
+{
+return false;
+}
+/**
+* Copies a rectangle from this texture client to a position in aTarget.
+* It is assumed that the necessary locks are in place; so this should at
+* least have a read lock and aTarget should at least have a write lock.
+*/
+virtual bool CopyToTextureClient(TextureClient* aTarget,
+const gfx::IntRect* aRect,
+const gfx::IntPoint* aPoint);
+/**
+* Returns true if this texture has a lock/unlock mechanism.
+* 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; }
+/**
+* Indicates whether the TextureClient implementation is backed by an
+* in-memory buffer. The consequence of this is that locking the
+* TextureClient does not contend with locking the texture on the host side.
+*/
+virtual bool HasInternalBuffer() const = 0;
+/**
+* Allocate and deallocate a TextureChild actor.
+*
+* TextureChild is an implementation detail of TextureClient that is not
+* exposed to the rest of the code base. CreateIPDLActor and DestroyIPDLActor
+* are for use with the managing IPDL protocols only (so that they can
+* implement AllocPextureChild and DeallocPTextureChild).
+*/
+static PTextureChild* CreateIPDLActor();
+static bool DestroyIPDLActor(PTextureChild* actor);
+/**
+* Get the TextureClient corresponding to the actor passed in parameter.
+*/
+static TextureClient* AsTextureClient(PTextureChild* actor);
+virtual bool IsAllocated() const = 0;
+virtual gfx::IntSize GetSize() const = 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; }
+/**
+* valid only for TEXTURE_RECYCLE TextureClient.
+* When called this texture client will grab a strong reference and release
+* it once the compositor notifies that it is done with the texture.
+* NOTE: In this stage the texture client can no longer be used by the
+* client in a transaction.
+*/
+void WaitForCompositorRecycle();
+/**
+* After being shared with the compositor side, an immutable texture is never
+* modified, it can only be read. It is safe to not Lock/Unlock immutable
+* textures.
+*/
+bool IsImmutable() const { return mFlags & TEXTURE_IMMUTABLE; }
+void MarkImmutable() { AddFlags(TEXTURE_IMMUTABLE); }
+bool IsSharedWithCompositor() const { return mShared; }
+bool ShouldDeallocateInDestructor() const;
+/**
+* If this method returns false users of TextureClient are not allowed
+* to access the shared data.
+*/
+bool IsValid() const { return mValid; }
+/**
+* Create and init the TextureChild/Parent IPDL actor pair.
+*
+* Should be called only once per TextureClient.
+*/
+bool InitIPDLActor(CompositableForwarder* aForwarder);
+/**
+* Return a pointer to the IPDLActor.
+*
+* This is to be used with IPDL messages only. Do not store the returned
+* pointer.
+*/
+PTextureChild* GetIPDLActor();
+/**
+* Triggers the destruction of the shared data and the corresponding TextureHost.
+*
+* If the texture flags contain TEXTURE_DEALLOCATE_CLIENT, the destruction
+* will be synchronously coordinated with the compositor side, otherwise it
+* will be done asynchronously.
+*/
+void ForceRemove();
+virtual void SetReleaseFenceHandle(FenceHandle aReleaseFenceHandle) {}
+const FenceHandle& GetReleaseFenceHandle() const
+{
+return mReleaseFenceHandle;
+}
+/**
+* Wait until the current buffer is no longer being read.
+*
+* Platform support is necessary. gonk JB supports this function.
+*/
+virtual void WaitReleaseFence() {}
+private:
+/**
+* Called once, just before the destructor.
+*
+* Here goes the shut-down code that uses virtual methods.
+* Must only be called by Release().
+*/
+void Finalize();
+friend class AtomicRefCountedWithFinalize<TextureClient>;
+protected:
+/**
+* An invalid TextureClient cannot provide access to its shared data
+* anymore. This usually means it will soon be destroyed.
+*/
+void MarkInvalid() { mValid = false; }
+/**
+* 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;
+/**
+* Should only be called *once* per texture, in TextureClient::InitIPDLActor.
+* Some texture implementations rely on the fact that the descriptor will be
+* deserialized.
+* Calling ToSurfaceDescriptor again after it has already returned true,
+* or never constructing a TextureHost with aDescriptor may result in a memory
+* leak (see CairoTextureClientD3D9 for example).
+*/
+virtual bool ToSurfaceDescriptor(SurfaceDescriptor& aDescriptor) = 0;
+void AddFlags(TextureFlags  aFlags)
+{
+MOZ_ASSERT(!IsSharedWithCompositor());
+mFlags |= aFlags;
+}
+RefPtr<TextureChild> mActor;
+TextureFlags mFlags;
+bool mShared;
+bool mValid;
+FenceHandle mReleaseFenceHandle;
+friend class TextureChild;
+friend void TestTextureClientSurface(TextureClient*, gfxImageSurface*);
+friend void TestTextureClientYCbCr(TextureClient*, PlanarYCbCrData&);
+};
+/**
+* TextureClient that wraps a random access buffer such as a Shmem or raw memory.
+* This class must be inherited to implement the memory allocation and access bits.
+* (see ShmemTextureClient and MemoryTextureClient)
+*/
+class BufferTextureClient : public TextureClient
+, public TextureClientYCbCr
+{
+public:
+BufferTextureClient(ISurfaceAllocator* aAllocator, gfx::SurfaceFormat aFormat,
+gfx::BackendType aBackend, TextureFlags aFlags);
+virtual ~BufferTextureClient();
+virtual bool IsAllocated() const = 0;
+virtual uint8_t* GetBuffer() const = 0;
+virtual gfx::IntSize GetSize() const { return mSize; }
+virtual bool Lock(OpenMode aMode) MOZ_OVERRIDE;
+virtual void Unlock() MOZ_OVERRIDE;
+virtual bool IsLocked() const MOZ_OVERRIDE { return mLocked; }
+virtual bool CanExposeDrawTarget() const MOZ_OVERRIDE { return true; }
+virtual TemporaryRef<gfx::DrawTarget> GetAsDrawTarget() MOZ_OVERRIDE;
+virtual bool AllocateForSurface(gfx::IntSize aSize,
+TextureAllocationFlags aFlags = ALLOC_DEFAULT) MOZ_OVERRIDE;
+// TextureClientYCbCr
+virtual TextureClientYCbCr* AsTextureClientYCbCr() MOZ_OVERRIDE { return this; }
+virtual bool UpdateYCbCr(const PlanarYCbCrData& aData) MOZ_OVERRIDE;
+virtual bool AllocateForYCbCr(gfx::IntSize aYSize,
+gfx::IntSize aCbCrSize,
+StereoMode aStereoMode) MOZ_OVERRIDE;
+virtual gfx::SurfaceFormat GetFormat() const MOZ_OVERRIDE { return mFormat; }
+// XXX - Bug 908196 - Make Allocate(uint32_t) and GetBufferSize() protected.
+// these two methods should only be called by methods of BufferTextureClient
+// that are overridden in GrallocTextureClient (which does not implement the
+// two methods below)
+virtual bool Allocate(uint32_t aSize) = 0;
+virtual size_t GetBufferSize() const = 0;
+virtual bool HasInternalBuffer() const MOZ_OVERRIDE { return true; }
+ISurfaceAllocator* GetAllocator() const;
+protected:
+RefPtr<gfx::DrawTarget> mDrawTarget;
+RefPtr<ISurfaceAllocator> mAllocator;
+gfx::SurfaceFormat mFormat;
+gfx::IntSize mSize;
+gfx::BackendType mBackend;
+OpenMode mOpenMode;
+bool mUsingFallbackDrawTarget;
+bool mLocked;
+};
+/**
+* TextureClient that wraps shared memory.
+* the corresponding texture on the host side is ShmemTextureHost.
+*/
+class ShmemTextureClient : public BufferTextureClient
+{
+public:
+ShmemTextureClient(ISurfaceAllocator* aAllocator, gfx::SurfaceFormat aFormat,
+gfx::BackendType aBackend, TextureFlags aFlags);
+~ShmemTextureClient();
+virtual bool ToSurfaceDescriptor(SurfaceDescriptor& aDescriptor) MOZ_OVERRIDE;
+virtual bool Allocate(uint32_t aSize) MOZ_OVERRIDE;
+virtual uint8_t* GetBuffer() const MOZ_OVERRIDE;
+virtual size_t GetBufferSize() const MOZ_OVERRIDE;
+virtual bool IsAllocated() const MOZ_OVERRIDE { return mAllocated; }
+virtual TextureClientData* DropTextureData() MOZ_OVERRIDE;
+virtual bool HasInternalBuffer() const MOZ_OVERRIDE { return true; }
+mozilla::ipc::Shmem& GetShmem() { return mShmem; }
+protected:
+mozilla::ipc::Shmem mShmem;
+bool mAllocated;
+};
+/**
+* TextureClient that wraps raw memory.
+* The corresponding texture on the host side is MemoryTextureHost.
+* Can obviously not be used in a cross process setup.
+*/
+class MemoryTextureClient : public BufferTextureClient
+{
+public:
+MemoryTextureClient(ISurfaceAllocator* aAllocator, gfx::SurfaceFormat aFormat,
+gfx::BackendType aBackend, TextureFlags aFlags);
+~MemoryTextureClient();
+virtual bool ToSurfaceDescriptor(SurfaceDescriptor& aDescriptor) MOZ_OVERRIDE;
+virtual bool Allocate(uint32_t aSize) MOZ_OVERRIDE;
+virtual uint8_t* GetBuffer() const MOZ_OVERRIDE { return mBuffer; }
+virtual size_t GetBufferSize() const MOZ_OVERRIDE { return mBufSize; }
+virtual bool IsAllocated() const MOZ_OVERRIDE { return mBuffer != nullptr; }
+virtual bool HasInternalBuffer() const MOZ_OVERRIDE { return true; }
+virtual TextureClientData* DropTextureData() MOZ_OVERRIDE;
+protected:
+uint8_t* mBuffer;
+size_t mBufSize;
+};
+struct TextureClientAutoUnlock
+{
+TextureClient* mTexture;
+TextureClientAutoUnlock(TextureClient* aTexture)
+: mTexture(aTexture) {}
+~TextureClientAutoUnlock()
+{
+mTexture->Unlock();
+}
+};
+}
+}
+#endif

The Tor Browser / file comparison

comparison: gfx/layers/client/TextureClient.h

gfx/layers/client/TextureClient.h