The Tor Browser: gfx/layers/Compositor.h@b8a032363ba2 (annotated)

gfx/layers/Compositor.h@b8a032363ba2 (annotated)

gfx/layers/Compositor.h

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* -*- 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_COMPOSITOR_H
 #define MOZILLA_GFX_COMPOSITOR_H
 #include "Units.h"                      // for ScreenPoint
 #include "mozilla/Assertions.h"         // for MOZ_ASSERT, etc
 #include "mozilla/RefPtr.h"             // for TemporaryRef, RefCounted
 #include "mozilla/gfx/Point.h"          // for IntSize, Point
 #include "mozilla/gfx/Rect.h"           // for Rect, IntRect
 #include "mozilla/gfx/Types.h"          // for Float
 #include "mozilla/layers/CompositorTypes.h"  // for DiagnosticTypes, etc
 #include "mozilla/layers/LayersTypes.h"  // for LayersBackend
 #include "nsISupportsImpl.h"            // for MOZ_COUNT_CTOR, etc
 #include "nsRegion.h"
 #include <vector>
 #include "mozilla/WidgetUtils.h"
 /**
  * Different elements of a web pages are rendered into separate "layers" before
  * they are flattened into the final image that is brought to the screen.
  * See Layers.h for more informations about layers and why we use retained
  * structures.
  * Most of the documentation for layers is directly in the source code in the
  * form of doc comments. An overview can also be found in the the wiki:
  * https://wiki.mozilla.org/Gecko:Overview#Graphics
  *
  *
  * # Main interfaces and abstractions
  *
  *  - Layer, ShadowableLayer and LayerComposite
  *    (see Layers.h and ipc/ShadowLayers.h)
  *  - CompositableClient and CompositableHost
  *    (client/CompositableClient.h composite/CompositableHost.h)
  *  - TextureClient and TextureHost
  *    (client/TextureClient.h composite/TextureHost.h)
  *  - TextureSource
  *    (composite/TextureHost.h)
  *  - Forwarders
  *    (ipc/CompositableForwarder.h ipc/ShadowLayers.h)
  *  - Compositor
  *    (this file)
  *  - IPDL protocols
  *    (.ipdl files under the gfx/layers/ipc directory)
  *
  * The *Client and Shadowable* classes are always used on the content thread.
  * Forwarders are always used on the content thread.
  * The *Host and Shadow* classes are always used on the compositor thread.
  * Compositors, TextureSource, and Effects are always used on the compositor
  * thread.
  * Most enums and constants are declared in LayersTypes.h and CompositorTypes.h.
  *
  *
  * # Texture transfer
  *
  * Most layer classes own a Compositable plus some extra information like
  * transforms and clip rects. They are platform independent.
  * Compositable classes manipulate Texture objects and are reponsible for
  * things like tiling, buffer rotation or double buffering. Compositables
  * are also platform-independent. Examples of compositable classes are:
  *  - ImageClient
  *  - CanvasClient
  *  - ContentHost
  *  - etc.
  * Texture classes (TextureClient and TextureHost) are thin abstractions over
  * platform-dependent texture memory. They are maniplulated by compositables
  * and don't know about buffer rotations and such. The purposes of TextureClient
  * and TextureHost are to synchronize, serialize and deserialize texture data.
  * TextureHosts provide access to TextureSources that are views on the
  * Texture data providing the necessary api for Compositor backend to composite
  * them.
  *
  * Compositable and Texture clients and hosts are created using factory methods.
  * They should only be created by using their constructor in exceptional
  * circumstances. The factory methods are located:
  *    TextureClient       - CompositableClient::CreateTextureClient
  *    TextureHost         - TextureHost::CreateTextureHost, which calls a
  *                          platform-specific function, e.g., CreateTextureHostOGL
  *    CompositableClient  - in the appropriate subclass, e.g.,
  *                          CanvasClient::CreateCanvasClient
  *    CompositableHost    - CompositableHost::Create
  *
  *
  * # IPDL
  *
  * If off-main-thread compositing (OMTC) is enabled, compositing is performed
  * in a dedicated thread. In some setups compositing happens in a dedicated
  * process. Documentation may refer to either the compositor thread or the
  * compositor process.
  * See explanations in ShadowLayers.h.
  *
  *
  * # Backend implementations
  *
  * Compositor backends like OpenGL or flavours of D3D live in their own directory
  * under gfx/layers/. To add a new backend, implement at least the following
  * interfaces:
  * - Compositor (ex. CompositorOGL)
  * - TextureHost (ex. SharedTextureHostOGL)
  * Depending on the type of data that needs to be serialized, you may need to
  * add specific TextureClient implementations.
  */
 class nsIWidget;
 struct nsIntSize;
 class nsIntRegion;
 namespace mozilla {
 namespace gfx {
 class Matrix;
 class Matrix4x4;
 class DrawTarget;
 }
 namespace layers {
 struct Effect;
 struct EffectChain;
 class Image;
 class ISurfaceAllocator;
 class Layer;
 class NewTextureSource;
 class DataTextureSource;
 class CompositingRenderTarget;
 class PCompositorParent;
 class LayerManagerComposite;
 enum SurfaceInitMode
 {
   INIT_MODE_NONE,
   INIT_MODE_CLEAR
 };
 /**
  * A base class for a platform-dependent helper for use by TextureHost.
  */
 class CompositorBackendSpecificData
 {
   NS_INLINE_DECL_REFCOUNTING(CompositorBackendSpecificData)
 protected:
   virtual ~CompositorBackendSpecificData() {}
 };
 /**
  * Common interface for compositor backends.
  *
  * Compositor provides a cross-platform interface to a set of operations for
  * compositing quads. Compositor knows nothing about the layer tree. It must be
  * told everything about each composited quad - contents, location, transform,
  * opacity, etc.
  *
  * In theory it should be possible for different widgets to use the same
  * compositor. In practice, we use one compositor per window.
  *
  * # Usage
  *
  * For an example of a user of Compositor, see LayerManagerComposite.
  *
  * Initialization: create a Compositor object, call Initialize().
  *
  * Destruction: destroy any resources associated with the compositor, call
  * Destroy(), delete the Compositor object.
  *
  * Composition:
  *  call BeginFrame,
  *  for each quad to be composited:
  *    call MakeCurrent if necessary (not necessary if no other context has been
  *      made current),
  *    take care of any texture upload required to composite the quad, this step
  *      is backend-dependent,
  *    construct an EffectChain for the quad,
  *    call DrawQuad,
  *  call EndFrame.
  * If the user has to stop compositing at any point before EndFrame, call
  * AbortFrame.
  * If the compositor is usually used for compositing but compositing is
  * temporarily done without the compositor, call EndFrameForExternalComposition
  * after compositing each frame so the compositor can remain internally
  * consistent.
  *
  * By default, the compositor will render to the screen, to render to a target,
  * call SetTargetContext or SetRenderTarget, the latter with a target created
  * by CreateRenderTarget or CreateRenderTargetFromSource.
  *
  * The target and viewport methods can be called before any DrawQuad call and
  * affect any subsequent DrawQuad calls.
  */
 class Compositor
 {
 protected:
   virtual ~Compositor() {}
 public:
   NS_INLINE_DECL_REFCOUNTING(Compositor)
   Compositor(PCompositorParent* aParent = nullptr)
     : mCompositorID(0)
     , mDiagnosticTypes(DIAGNOSTIC_NONE)
     , mParent(aParent)
     , mScreenRotation(ROTATION_0)
   {
   }
   virtual TemporaryRef<DataTextureSource> CreateDataTextureSource(TextureFlags aFlags = 0) = 0;
   virtual bool Initialize() = 0;
   virtual void Destroy() = 0;
   /**
    * Return true if the effect type is supported.
    *
    * By default Compositor implementations should support all effects but in
    * some rare cases it is not possible to support an effect efficiently.
    * This is the case for BasicCompositor with EffectYCbCr.
    */
   virtual bool SupportsEffect(EffectTypes aEffect) { return true; }
   /**
    * Request a texture host identifier that may be used for creating textures
    * across process or thread boundaries that are compatible with this
    * compositor.
    */
   virtual TextureFactoryIdentifier GetTextureFactoryIdentifier() = 0;
   /**
    * Properties of the compositor.
    */
   virtual bool CanUseCanvasLayerForSize(const gfx::IntSize& aSize) = 0;
   virtual int32_t GetMaxTextureSize() const = 0;
   /**
    * Set the target for rendering. Results will have been written to aTarget by
    * the time that EndFrame returns.
    *
    * If this method is not used, or we pass in nullptr, we target the compositor's
    * usual swap chain and render to the screen.
    */
   virtual void SetTargetContext(gfx::DrawTarget* aTarget) = 0;
   typedef uint32_t MakeCurrentFlags;
   static const MakeCurrentFlags ForceMakeCurrent = 0x1;
   /**
    * Make this compositor's rendering context the current context for the
    * underlying graphics API. This may be a global operation, depending on the
    * API. Our context will remain the current one until someone else changes it.
    *
    * Clients of the compositor should call this at the start of the compositing
    * process, it might be required by texture uploads etc.
    *
    * If aFlags == ForceMakeCurrent then we will (re-)set our context on the
    * underlying API even if it is already the current context.
    */
   virtual void MakeCurrent(MakeCurrentFlags aFlags = 0) = 0;
   /**
    * Creates a Surface that can be used as a rendering target by this
    * compositor.
    */
   virtual TemporaryRef<CompositingRenderTarget>
   CreateRenderTarget(const gfx::IntRect& aRect, SurfaceInitMode aInit) = 0;
   /**
    * Creates a Surface that can be used as a rendering target by this
    * compositor, and initializes the surface by copying from aSource.
    * If aSource is null, then the current screen buffer is used as source.
    *
    * aSourcePoint specifies the point in aSource to copy data from.
    */
   virtual TemporaryRef<CompositingRenderTarget>
   CreateRenderTargetFromSource(const gfx::IntRect& aRect,
                                const CompositingRenderTarget* aSource,
                                const gfx::IntPoint& aSourcePoint) = 0;
   /**
    * Sets the given surface as the target for subsequent calls to DrawQuad.
    * Passing null as aSurface sets the screen as the target.
    */
   virtual void SetRenderTarget(CompositingRenderTarget* aSurface) = 0;
   /**
    * Returns the current target for rendering. Will return null if we are
    * rendering to the screen.
    */
   virtual CompositingRenderTarget* GetCurrentRenderTarget() const = 0;
   /**
    * Mostly the compositor will pull the size from a widget and this method will
    * be ignored, but compositor implementations are free to use it if they like.
    */
   virtual void SetDestinationSurfaceSize(const gfx::IntSize& aSize) = 0;
   /**
    * Declare an offset to use when rendering layers. This will be ignored when
    * rendering to a target instead of the screen.
    */
   virtual void SetScreenRenderOffset(const ScreenPoint& aOffset) = 0;
   /**
    * Tell the compositor to draw a quad. What to do draw and how it is
    * drawn is specified by aEffectChain. aRect is the quad to draw, in user space.
    * aTransform transforms from user space to screen space. If texture coords are
    * required, these will be in the primary effect in the effect chain.
    */
   virtual void DrawQuad(const gfx::Rect& aRect, const gfx::Rect& aClipRect,
                         const EffectChain& aEffectChain,
                         gfx::Float aOpacity, const gfx::Matrix4x4 &aTransform) = 0;
   /**
    * Tell the compositor to draw lines connecting the points. Behaves like
    * DrawQuad.
    */
   virtual void DrawLines(const std::vector<gfx::Point>& aLines, const gfx::Rect& aClipRect,
                          const gfx::Color& aColor,
                          gfx::Float aOpacity, const gfx::Matrix4x4 &aTransform)
   { /* Should turn into pure virtual once implemented in D3D */ }
   /*
    * Clear aRect on current render target.
    */
   virtual void ClearRect(const gfx::Rect& aRect) { }
   /**
    * Start a new frame.
    *
    * aInvalidRect is the invalid region of the screen; it can be ignored for
    * compositors where the performance for compositing the entire window is
    * sufficient.
    *
    * aClipRectIn is the clip rect for the window in window space (optional).
    * aTransform is the transform from user space to window space.
    * aRenderBounds bounding rect for rendering, in user space.
    *
    * If aClipRectIn is null, this method sets *aClipRectOut to the clip rect
    * actually used for rendering (if aClipRectIn is non-null, we will use that
    * for the clip rect).
    *
    * If aRenderBoundsOut is non-null, it will be set to the render bounds
    * actually used by the compositor in window space. If aRenderBoundsOut
    * is returned empty, composition should be aborted.
    */
   virtual void BeginFrame(const nsIntRegion& aInvalidRegion,
                           const gfx::Rect* aClipRectIn,
                           const gfx::Matrix& aTransform,
                           const gfx::Rect& aRenderBounds,
                           gfx::Rect* aClipRectOut = nullptr,
                           gfx::Rect* aRenderBoundsOut = nullptr) = 0;
   /**
    * Flush the current frame to the screen and tidy up.
    */
   virtual void EndFrame() = 0;
   virtual void SetFBAcquireFence(Layer* aLayer) {}
   /**
    * Post-rendering stuff if the rendering is done outside of this Compositor
    * e.g., by Composer2D.
    * aTransform is the transform from user space to window space.
    */
   virtual void EndFrameForExternalComposition(const gfx::Matrix& aTransform) = 0;
   /**
    * Tidy up if BeginFrame has been called, but EndFrame won't be.
    */
   virtual void AbortFrame() = 0;
   /**
    * Setup the viewport and projection matrix for rendering to a target of the
    * given dimensions. The size and transform here will override those set in
    * BeginFrame. BeginFrame sets a size and transform for the default render
    * target, usually the screen. Calling this method prepares the compositor to
    * render using a different viewport (that is, size and transform), usually
    * associated with a new render target.
    * aWorldTransform is the transform from user space to the new viewport's
    * coordinate space.
    */
   virtual void PrepareViewport(const gfx::IntSize& aSize,
                                const gfx::Matrix& aWorldTransform) = 0;
   /**
    * Whether textures created by this compositor can receive partial updates.
    */
   virtual bool SupportsPartialTextureUpdate() = 0;
   void SetDiagnosticTypes(DiagnosticTypes aDiagnostics)
   {
     mDiagnosticTypes = aDiagnostics;
   }
   DiagnosticTypes GetDiagnosticTypes() const
   {
     return mDiagnosticTypes;
   }
   void DrawDiagnostics(DiagnosticFlags aFlags,
                        const gfx::Rect& visibleRect,
                        const gfx::Rect& aClipRect,
                        const gfx::Matrix4x4& transform,
                        uint32_t aFlashCounter = DIAGNOSTIC_FLASH_COUNTER_MAX);
   void DrawDiagnostics(DiagnosticFlags aFlags,
                        const nsIntRegion& visibleRegion,
                        const gfx::Rect& aClipRect,
                        const gfx::Matrix4x4& transform,
                        uint32_t aFlashCounter = DIAGNOSTIC_FLASH_COUNTER_MAX);
 #ifdef MOZ_DUMP_PAINTING
   virtual const char* Name() const = 0;
 #endif // MOZ_DUMP_PAINTING
   virtual LayersBackend GetBackendType() const = 0;
   /**
    * Each Compositor has a unique ID.
    * This ID is used to keep references to each Compositor in a map accessed
    * from the compositor thread only, so that async compositables can find
    * the right compositor parent and schedule compositing even if the compositor
    * changed.
    */
   uint32_t GetCompositorID() const
   {
     return mCompositorID;
   }
   void SetCompositorID(uint32_t aID)
   {
     MOZ_ASSERT(mCompositorID == 0, "The compositor ID must be set only once.");
     mCompositorID = aID;
   }
   /**
    * Notify the compositor that composition is being paused. This allows the
    * compositor to temporarily release any resources.
    * Between calling Pause and Resume, compositing may fail.
    */
   virtual void Pause() {}
   /**
    * Notify the compositor that composition is being resumed. The compositor
    * regain any resources it requires for compositing.
    * Returns true if succeeded.
    */
   virtual bool Resume() { return true; }
   /**
    * Call before rendering begins to ensure the compositor is ready to
    * composite. Returns false if rendering should be aborted.
    */
   virtual bool Ready() { return true; }
   // XXX I expect we will want to move mWidget into this class and implement
   // these methods properly.
   virtual nsIWidget* GetWidget() const { return nullptr; }
   /**
    * Debug-build assertion that can be called to ensure code is running on the
    * compositor thread.
    */
   static void AssertOnCompositorThread();
   /**
    * We enforce that there can only be one Compositor backend type off the main
    * thread at the same time. The backend type in use can be checked with this
    * static method. We need this for creating texture clients/hosts etc. when we
    * don't have a reference to a Compositor.
    *
    * This can only be used from the compositor thread!
    */
   static LayersBackend GetBackend();
   size_t GetFillRatio() {
     float fillRatio = 0;
     if (mPixelsFilled > 0 && mPixelsPerFrame > 0) {
       fillRatio = 100.0f * float(mPixelsFilled) / float(mPixelsPerFrame);
       if (fillRatio > 999.0f) {
         fillRatio = 999.0f;
       }
     }
     return fillRatio;
   }
   virtual CompositorBackendSpecificData* GetCompositorBackendSpecificData() {
     return nullptr;
   }
   ScreenRotation GetScreenRotation() const {
     return mScreenRotation;
   }
   void SetScreenRotation(ScreenRotation aRotation) {
     mScreenRotation = aRotation;
   }
   // On b2g the clip rect is in the coordinate space of the physical screen
   // independently of its rotation, while the coordinate space of the layers,
   // on the other hand, depends on the screen orientation.
   // This only applies to b2g as with other platforms, orientation is handled
   // at the OS level rather than in Gecko.
   // In addition, the clip rect needs to be offset by the rendering origin.
   // This becomes important if intermediate surfaces are used.
   gfx::Rect ClipRectInLayersCoordinates(gfx::Rect aClip) const;
 protected:
   void DrawDiagnosticsInternal(DiagnosticFlags aFlags,
                                const gfx::Rect& aVisibleRect,
                                const gfx::Rect& aClipRect,
                                const gfx::Matrix4x4& transform,
                                uint32_t aFlashCounter);
   bool ShouldDrawDiagnostics(DiagnosticFlags);
   /**
    * Set the global Compositor backend, checking that one isn't already set.
    */
   static void SetBackend(LayersBackend backend);
   uint32_t mCompositorID;
   DiagnosticTypes mDiagnosticTypes;
   PCompositorParent* mParent;
   /**
    * We keep track of the total number of pixels filled as we composite the
    * current frame. This value is an approximation and is not accurate,
    * especially in the presence of transforms.
    */
   size_t mPixelsPerFrame;
   size_t mPixelsFilled;
   ScreenRotation mScreenRotation;
   virtual gfx::IntSize GetWidgetSize() const = 0;
 private:
   static LayersBackend sBackend;
 };
 } // namespace layers
 } // namespace mozilla
 #endif /* MOZILLA_GFX_COMPOSITOR_H */

The Tor Browser / annotate

gfx/layers/Compositor.h@b8a032363ba2 (annotated)

gfx/layers/Compositor.h