Update comments for ContentClient (
bug 1409871 part 13, r=nical)
This could be a part of the previous commit, but I omitted it to keep the size
down. Just some updates to comments and documentation.
MozReview-Commit-ID: HkCOSIQhBNv
--- a/gfx/layers/basic/BasicPaintedLayer.h
+++ b/gfx/layers/basic/BasicPaintedLayer.h
@@ -2,17 +2,17 @@
* 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 GFX_BASICPAINTEDLAYER_H
#define GFX_BASICPAINTEDLAYER_H
#include "Layers.h" // for PaintedLayer, LayerManager, etc
-#include "RotatedBuffer.h" // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h" // for RotatedBuffer, etc
#include "BasicImplData.h" // for BasicImplData
#include "BasicLayers.h" // for BasicLayerManager
#include "gfxPoint.h" // for gfxPoint
#include "mozilla/RefPtr.h" // for RefPtr
#include "mozilla/gfx/BasePoint.h" // for BasePoint
#include "mozilla/layers/ContentClient.h" // for ContentClientBasic
#include "mozilla/mozalloc.h" // for operator delete
#include "nsDebug.h" // for NS_ASSERTION
--- a/gfx/layers/client/ClientPaintedLayer.h
+++ b/gfx/layers/client/ClientPaintedLayer.h
@@ -3,17 +3,17 @@
* 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 GFX_CLIENTPAINTEDLAYER_H
#define GFX_CLIENTPAINTEDLAYER_H
#include "ClientLayerManager.h" // for ClientLayerManager, etc
#include "Layers.h" // for PaintedLayer, etc
-#include "RotatedBuffer.h" // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h" // for RotatedBuffer, etc
#include "mozilla/Attributes.h" // for override
#include "mozilla/RefPtr.h" // for RefPtr
#include "mozilla/layers/ContentClient.h" // for ContentClient
#include "mozilla/mozalloc.h" // for operator delete
#include "nsDebug.h" // for NS_ASSERTION
#include "nsISupportsImpl.h" // for MOZ_COUNT_CTOR, etc
#include "nsRegion.h" // for nsIntRegion
#include "mozilla/layers/PLayerTransaction.h" // for PaintedLayerAttributes
--- a/gfx/layers/client/ContentClient.cpp
+++ b/gfx/layers/client/ContentClient.cpp
@@ -143,18 +143,17 @@ ContentClient::BeginPaintBuffer(PaintedL
dest.mValidRegion);
if (result.mRegionToDraw.IsEmpty())
return result;
if (mBuffer) {
if (mBuffer->Lock(LockMode())) {
// Do not modify result.mRegionToDraw or result.mContentType after this call.
- // Do not modify mBufferRect, mBufferRotation, or mDidSelfCopy,
- // or call CreateBuffer before this call.
+ // Do not modify the back buffer's bufferRect, bufferRotation, or didSelfCopy.
FinalizeFrame(result.mRegionToDraw);
} else {
// Abandon everything and redraw it all. Ideally we'd reallocate and copy
// the old to the new and then call FinalizeFrame on the new buffer so that
// we only need to draw the latest bits, but we need a big refactor to support
// that ordering.
result.mRegionToDraw = dest.mNeededRegion;
dest.mCanReuseBuffer = false;
--- a/gfx/layers/client/ContentClient.h
+++ b/gfx/layers/client/ContentClient.h
@@ -2,17 +2,17 @@
* 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_CONTENTCLIENT_H
#define MOZILLA_GFX_CONTENTCLIENT_H
#include <stdint.h> // for uint32_t
-#include "RotatedBuffer.h" // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h" // for RotatedBuffer, etc
#include "gfxTypes.h"
#include "gfxPlatform.h" // for gfxPlatform
#include "mozilla/Assertions.h" // for MOZ_CRASH
#include "mozilla/Attributes.h" // for override
#include "mozilla/RefPtr.h" // for RefPtr, already_AddRefed
#include "mozilla/gfx/Point.h" // for IntSize
#include "mozilla/layers/CompositableClient.h" // for CompositableClient
#include "mozilla/layers/CompositableForwarder.h"
@@ -38,45 +38,27 @@ class DrawTarget;
namespace layers {
class PaintedLayer;
class CapturedPaintState;
/**
* A compositable client for PaintedLayers. These are different to Image/Canvas
* clients due to sending a valid region across IPC and because we do a lot more
- * optimisation work, encapsualted in RotatedContentBuffers.
+ * optimisation work, encapsulated in RotatedBuffers.
*
* We use content clients for OMTC and non-OMTC, basic rendering so that
* BasicPaintedLayer has only one interface to deal with. We support single and
* double buffered flavours. For tiled layers, we do not use a ContentClient
* although we do have a ContentHost, and we do use texture clients and texture
* hosts.
*
* The interface presented by ContentClient is used by the BasicPaintedLayer
* methods - PaintThebes, which is the same for MT and OMTC, and PaintBuffer
- * which is different (the OMTC one does a little more). The 'buffer' in the
- * names of a lot of these method is actually the TextureClient. But, 'buffer'
- * for the RotatedContentBuffer (as in SetBuffer) means a gfxSurface. See the
- * comments for SetBuffer and SetBufferProvider in RotatedContentBuffer. To keep
- * these mapped buffers alive, we store a pointer in mOldTextures if the
- * RotatedContentBuffer's surface is not the one from our texture client, once we
- * are done painting we unmap the surface/texture client and don't need to keep
- * it alive anymore, so we clear mOldTextures.
- *
- * The sequence for painting is: call BeginPaint on the content client;
- * call BeginPaintBuffer on the content client. That will initialise the buffer
- * for painting, by calling RotatedContentBuffer::BeginPaint (usually) which
- * will call back to ContentClient::FinalizeFrame to finalize update of the
- * buffers before drawing (i.e., it finalizes the previous frame). Then call
- * BorrowDrawTargetForPainting to get a DrawTarget to paint into. Then paint.
- * Then return that DrawTarget using ReturnDrawTarget.
- * Call EndPaint on the content client;
- *
- * SwapBuffers is called in response to the transaction reply from the compositor.
+ * which is different (the OMTC one does a little more).
*/
class ContentClient : public CompositableClient
{
public:
typedef gfxContentType ContentType;
/**
* Creates, configures, and returns a new content client. If necessary, a
@@ -108,17 +90,17 @@ public:
virtual void PrintInfo(std::stringstream& aStream, const char* aPrefix);
virtual void Clear();
/**
* This is returned by BeginPaint. The caller should draw into mTarget.
* mRegionToDraw must be drawn. mRegionToInvalidate has been invalidated
- * by RotatedContentBuffer and must be redrawn on the screen.
+ * by ContentClient and must be redrawn on the screen.
* mRegionToInvalidate is set when the buffer has changed from
* opaque to transparent or vice versa, since the details of rendering can
* depend on the buffer type.
*/
struct PaintState {
PaintState()
: mRegionToDraw()
, mRegionToInvalidate()
@@ -220,37 +202,53 @@ protected:
nsIntRegion mValidRegion;
gfx::IntRect mBufferRect;
SurfaceMode mBufferMode;
gfxContentType mBufferContentType;
bool mCanReuseBuffer;
bool mCanKeepBufferContents;
};
+ /**
+ * Decide whether we can keep our current buffer and its contents,
+ * and return a struct containing the regions to paint, invalidate,
+ * the new buffer rect, surface mode, and content type.
+ */
BufferDecision CalculateBufferForPaint(PaintedLayer* aLayer,
uint32_t aFlags);
/**
- * Return the buffer's content type. Requires a valid buffer or
- * buffer provider.
+ * Return the buffer's content type. Requires a valid buffer.
*/
gfxContentType BufferContentType();
+ /**
+ * Returns whether the specified size is adequate for the current
+ * buffer and buffer size policy.
+ */
bool BufferSizeOkFor(const gfx::IntSize& aSize);
+ /**
+ * Returns what open mode to use on texture clients. Ignored when
+ * using basic content clients.
+ */
OpenMode LockMode() const;
/**
* Any actions that should be performed at the last moment before we begin
* rendering the next frame. I.e., after we calculate what we will draw,
* but before we rotate the buffer and possibly create new buffers.
* aRegionToDraw is the region which is guaranteed to be overwritten when
* drawing the next frame.
*/
virtual void FinalizeFrame(const nsIntRegion& aRegionToDraw) {}
+ /**
+ * Create a new rotated buffer for the specified content type, buffer rect,
+ * and buffer flags.
+ */
virtual RefPtr<RotatedBuffer> CreateBuffer(gfxContentType aType,
const gfx::IntRect& aRect,
uint32_t aFlags) = 0;
RefPtr<RotatedBuffer> mBuffer;
BufferSizePolicy mBufferSizePolicy;
bool mInAsyncPaint;
};
@@ -282,31 +280,30 @@ protected:
const gfx::IntRect& aRect,
uint32_t aFlags) override;
private:
gfx::BackendType mBackend;
};
/**
- * A ContentClient backed by a RotatedContentBuffer.
+ * A ContentClient backed by a RemoteRotatedBuffer.
*
* When using a ContentClientRemoteBuffer, SurfaceDescriptors are created on
* the rendering side and destroyed on the compositing side. They are only
* passed from one side to the other when the TextureClient/Hosts are created.
* *Ownership* of the SurfaceDescriptor moves from the rendering side to the
* compositing side with the create message (send from CreateBuffer) which
* tells the compositor that TextureClients have been created and that the
* compositor should assign the corresponding TextureHosts to our corresponding
* ContentHost.
*
* If the size or type of our buffer(s) change(s), then we simply destroy and
* create them.
*/
-// Version using new texture clients
class ContentClientRemoteBuffer : public ContentClient
{
public:
explicit ContentClientRemoteBuffer(CompositableForwarder* aForwarder)
: ContentClient(aForwarder, ContainsVisibleBounds)
, mIsNewBuffer(false)
{}
@@ -314,42 +311,36 @@ public:
const char* aPrefix="",
bool aDumpHtml=false,
TextureDumpMode aCompress=TextureDumpMode::Compress) override;
virtual RefPtr<CapturedPaintState> BorrowDrawTargetForRecording(PaintState& aPaintState,
RotatedBuffer::DrawIterator* aIter,
bool aSetTransform) override;
- /**
- * Begin/End Paint map a gfxASurface from the texture client
- * into the buffer of RotatedBuffer. The surface is only
- * valid when the texture client is locked, so is mapped out
- * of RotatedContentBuffer when we are done painting.
- * None of the underlying buffer attributes (rect, rotation)
- * are affected by mapping/unmapping.
- */
virtual void BeginPaint() override;
virtual void BeginAsyncPaint() override;
virtual void EndPaint(nsTArray<ReadbackProcessor::Update>* aReadbackUpdates = nullptr) override;
virtual void Updated(const nsIntRegion& aRegionToDraw,
const nsIntRegion& aVisibleRegion);
virtual TextureFlags ExtraTextureFlags() const
{
return TextureFlags::IMMEDIATE_UPLOAD;
}
protected:
virtual nsIntRegion GetUpdatedRegion(const nsIntRegion& aRegionToDraw,
const nsIntRegion& aVisibleRegion);
- // Ensure we have a valid back buffer if we have a valid front buffer (i.e.
- // if a backbuffer has been created.)
+ /**
+ * Ensure we have a valid back buffer if we have a valid front buffer (i.e.
+ * if a backbuffer has been created.)
+ */
virtual void EnsureBackBufferIfFrontBuffer() {}
virtual RefPtr<RotatedBuffer> CreateBuffer(gfxContentType aType,
const gfx::IntRect& aRect,
uint32_t aFlags) override;
RefPtr<RotatedBuffer> CreateBufferInternal(const gfx::IntRect& aRect,
gfx::SurfaceFormat aFormat,
@@ -359,25 +350,23 @@ protected:
{
return static_cast<RemoteRotatedBuffer*>(mBuffer.get());
}
bool mIsNewBuffer;
};
/**
- * A double buffered ContentClient. mTextureClient is the back buffer, which
- * we draw into. mFrontClient is the front buffer which we may read from, but
- * not write to, when the compositor does not have the 'soft' lock. We can write
- * into mTextureClient at any time.
+ * A double buffered ContentClientRemoteBuffer. mBuffer is the back buffer, which
+ * we draw into. mFrontBuffer is the front buffer which we may read from, but
+ * not write to, when the compositor does not have the 'soft' lock.
*
* The ContentHost keeps a reference to both corresponding texture hosts, in
* response to our UpdateTextureRegion message, the compositor swaps its
- * references. In response to the compositor's reply we swap our references
- * (in SwapBuffers).
+ * references.
*/
class ContentClientDoubleBuffered : public ContentClientRemoteBuffer
{
public:
explicit ContentClientDoubleBuffered(CompositableForwarder* aFwd)
: ContentClientRemoteBuffer(aFwd)
, mFrontAndBackBufferDiffer(false)
{}
@@ -411,22 +400,22 @@ public:
private:
RefPtr<RemoteRotatedBuffer> mFrontBuffer;
nsIntRegion mFrontUpdatedRegion;
bool mFrontAndBackBufferDiffer;
};
/**
- * A single buffered ContentClient. We have a single TextureClient/Host
- * which we update and then send a message to the compositor that we are
- * done updating. It is not safe for the compositor to use the corresponding
- * TextureHost's memory directly, it must upload it to video memory of some
- * kind. We are free to modify the TextureClient once we receive reply from
- * the compositor.
+ * A single buffered ContentClientRemoteBuffer. We have a single
+ * TextureClient/Host which we update and then send a message to the
+ * compositor that we are done updating. It is not safe for the compositor
+ * to use the corresponding TextureHost's memory directly, it must upload
+ * it to video memory of some kind. We are free to modify the TextureClient
+ * once we receive reply from the compositor.
*/
class ContentClientSingleBuffered : public ContentClientRemoteBuffer
{
public:
explicit ContentClientSingleBuffered(CompositableForwarder* aFwd)
: ContentClientRemoteBuffer(aFwd)
{
}
--- a/gfx/layers/composite/ContentHost.h
+++ b/gfx/layers/composite/ContentHost.h
@@ -5,17 +5,17 @@
#ifndef GFX_CONTENTHOST_H
#define GFX_CONTENTHOST_H
#include <stdint.h> // for uint32_t
#include <stdio.h> // for FILE
#include "mozilla-config.h" // for MOZ_DUMP_PAINTING
#include "CompositableHost.h" // for CompositableHost, etc
-#include "RotatedBuffer.h" // for RotatedContentBuffer, etc
+#include "RotatedBuffer.h" // for RotatedBuffer, etc
#include "mozilla/Attributes.h" // for override
#include "mozilla/RefPtr.h" // for RefPtr
#include "mozilla/gfx/BasePoint.h" // for BasePoint
#include "mozilla/gfx/MatrixFwd.h" // for Matrix4x4
#include "mozilla/gfx/Point.h" // for Point
#include "mozilla/gfx/Polygon.h" // for Polygon
#include "mozilla/gfx/Rect.h" // for Rect
#include "mozilla/gfx/Types.h" // for SamplingFilter