The Tor Browser: comparison gfx/layers/Compositor.h

--1:000000000000
+:84f0e9cf4215
+/* -*- 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 / file comparison

comparison: gfx/layers/Compositor.h

gfx/layers/Compositor.h