gecko-dev/gfx/layers/client/CompositableClient.h

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set ts=8 sts=2 et sw=2 tw=80: */
/* 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_BUFFERCLIENT_H
#define MOZILLA_GFX_BUFFERCLIENT_H

#include <stdint.h>              // for uint64_t
#include <vector>                // for vector
#include <map>                   // for map
#include "mozilla/Assertions.h"  // for MOZ_CRASH
#include "mozilla/RefPtr.h"      // for already_AddRefed, RefCounted
#include "mozilla/gfx/Types.h"   // for SurfaceFormat
#include "mozilla/layers/CompositorTypes.h"
#include "mozilla/layers/LayersTypes.h"    // for LayersBackend, TextureDumpMode
#include "mozilla/layers/TextureClient.h"  // for TextureClient
#include "mozilla/webrender/WebRenderTypes.h"  // for RenderRoot
#include "nsISupportsImpl.h"                   // for MOZ_COUNT_CTOR, etc

namespace mozilla {
namespace layers {

class CompositableClient;
class ImageBridgeChild;
class ImageContainer;
class CompositableForwarder;
class CompositableChild;
class TextureClientRecycleAllocator;
class ContentClientRemoteBuffer;

/**
 * CompositableClient manages the texture-specific logic for composite layers,
 * independently of the layer. It is the content side of a CompositableClient/
 * CompositableHost pair.
 *
 * CompositableClient's purpose is to send texture data to the compositor side
 * along with any extra information about how the texture is to be composited.
 * Things like opacity or transformation belong to layer and not compositable.
 *
 * Since Compositables are independent of layers it is possible to create one,
 * connect it to the compositor side, and start sending images to it. This alone
 * is arguably not very useful, but it means that as long as a shadow layer can
 * do the proper magic to find a reference to the right CompositableHost on the
 * Compositor side, a Compositable client can be used outside of the main
 * shadow layer forwarder machinery that is used on the main thread.
 *
 * The first step is to create a Compositable client and call Connect().
 * Connect() creates the underlying IPDL actor (see CompositableChild) and the
 * corresponding CompositableHost on the other side.
 *
 * To do in-transaction texture transfer (the default), call
 * ShadowLayerForwarder::Attach(CompositableClient*, ShadowableLayer*). This
 * will let the LayerComposite on the compositor side know which
 * CompositableHost to use for compositing.
 *
 * To do async texture transfer (like async-video), the CompositableClient
 * should be created with a different CompositableForwarder (like
 * ImageBridgeChild) and attachment is done with
 * CompositableForwarder::AttachAsyncCompositable that takes an identifier
 * instead of a CompositableChild, since the CompositableClient is not managed
 * by this layer forwarder (the matching uses a global map on the compositor
 * side, see CompositableMap in ImageBridgeParent.cpp)
 *
 * Subclasses: Painted layers use ContentClients, ImageLayers use ImageClients,
 * Canvas layers use CanvasClients (but ImageHosts). We have a different
 * subclass where we have a different way of interfacing with the textures - in
 * terms of drawing into the compositable and/or passing its contents to the
 * compostior.
 */
class CompositableClient {
 protected:
  virtual ~CompositableClient();

 public:
  NS_INLINE_DECL_THREADSAFE_REFCOUNTING(CompositableClient)

  explicit CompositableClient(CompositableForwarder* aForwarder,
                              TextureFlags aFlags = TextureFlags::NO_FLAGS);

  virtual void Dump(std::stringstream& aStream, const char* aPrefix = "",
                    bool aDumpHtml = false,
                    TextureDumpMode aCompress = TextureDumpMode::Compress){};

  virtual TextureInfo GetTextureInfo() const = 0;

  LayersBackend GetCompositorBackendType() const;

  already_AddRefed<TextureClient> CreateBufferTextureClient(
      gfx::SurfaceFormat aFormat, gfx::IntSize aSize,
      gfx::BackendType aMoz2dBackend = gfx::BackendType::NONE,
      TextureFlags aFlags = TextureFlags::DEFAULT);

  already_AddRefed<TextureClient> CreateTextureClientForDrawing(
      gfx::SurfaceFormat aFormat, gfx::IntSize aSize, BackendSelector aSelector,
      TextureFlags aTextureFlags,
      TextureAllocationFlags aAllocFlags = ALLOC_DEFAULT);

  already_AddRefed<TextureClient> CreateTextureClientFromSurface(
      gfx::SourceSurface* aSurface, BackendSelector aSelector,
      TextureFlags aTextureFlags,
      TextureAllocationFlags aAllocFlags = ALLOC_DEFAULT);

  /**
   * Establishes the connection with compositor side through IPDL
   */
  virtual bool Connect(ImageContainer* aImageContainer = nullptr);

  void Destroy();

  bool IsConnected() const;

  CompositableForwarder* GetForwarder() const { return mForwarder; }

  /**
   * This identifier is what lets us attach async compositables with a shadow
   * layer. It is not used if the compositable is used with the regular shadow
   * layer forwarder.
   *
   * If this returns empty, it means the compositable is not async (it is used
   * on the main thread).
   */
  CompositableHandle GetAsyncHandle() const;

  /**
   * Handle for IPDL communication.
   */
  CompositableHandle GetIPCHandle() const { return mHandle; }

  /**
   * Tells the Compositor to create a TextureHost for this TextureClient.
   */
  virtual bool AddTextureClient(TextureClient* aClient);

  /**
   * A hook for the when the Compositable is detached from it's layer.
   */
  virtual void OnDetach() {}

  /**
   * Clear any resources that are not immediately necessary. This may be called
   * in low-memory conditions.
   */
  virtual void ClearCachedResources();

  /**
   * Shrink memory usage.
   * Called when "memory-pressure" is observed.
   */
  virtual void HandleMemoryPressure();

  /**
   * Should be called when deataching a TextureClient from a Compositable,
   * because some platforms need to do some extra book keeping when this
   * happens.
   *
   * See AutoRemoveTexture to automatically invoke this at the end of a scope.
   */
  virtual void RemoveTexture(TextureClient* aTexture,
                             const Maybe<wr::RenderRoot>& aRenderRoot);

  void InitIPDL(const CompositableHandle& aHandle);

  TextureFlags GetTextureFlags() const { return mTextureFlags; }

  TextureClientRecycleAllocator* GetTextureClientRecycler();

  bool HasTextureClientRecycler() { return !!mTextureClientRecycler; }

  static void DumpTextureClient(std::stringstream& aStream,
                                TextureClient* aTexture,
                                TextureDumpMode aCompress);

 protected:
  RefPtr<CompositableForwarder> mForwarder;
  // Some layers may want to enforce some flags to all their textures
  // (like disallowing tiling)
  TextureFlags mTextureFlags;
  RefPtr<TextureClientRecycleAllocator> mTextureClientRecycler;

  CompositableHandle mHandle;
  bool mIsAsync;

  friend class CompositableChild;
};

/**
 * Helper to call RemoveTexture at the end of a scope.
 */
struct AutoRemoveTexture {
  AutoRemoveTexture(CompositableClient* aCompositable,
                    wr::RenderRoot aRenderRoot,
                    TextureClient* aTexture = nullptr)
      : mTexture(aTexture),
        mCompositable(aCompositable),
        mRenderRoot(aRenderRoot) {}

  ~AutoRemoveTexture();

  RefPtr<TextureClient> mTexture;

 private:
  CompositableClient* mCompositable;
  wr::RenderRoot mRenderRoot;
};

}  // namespace layers
}  // namespace mozilla

#endif