Bug 967573 - Better document TextureClient. r=sotaro
authorNicolas Silva <nical@mozilla.com>
Tue, 04 Feb 2014 21:32:02 +0100
changeset 166816 4f3b4bbccb54a0706e19e299d3feda6f2b63bf21
parent 166815 5e355d51e30f28d2d3254312922b6eaacc4a5914
child 166817 145a831ad90ae29dc196fac657d9246406971e32
push id39291
push usernsilva@mozilla.com
push dateTue, 04 Feb 2014 20:32:15 +0000
treeherdermozilla-inbound@4f3b4bbccb54 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerssotaro
bugs967573
milestone30.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 967573 - Better document TextureClient. r=sotaro
gfx/layers/client/TextureClient.h
--- a/gfx/layers/client/TextureClient.h
+++ b/gfx/layers/client/TextureClient.h
@@ -76,16 +76,41 @@ public:
 };
 
 /**
  * Interface for TextureClients that can be updated using a DrawTarget.
  */
 class TextureClientDrawTarget
 {
 public:
+  /**
+   * 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->AsTextureClientDrawTarget()->GetAsDrawTarget();
+   *   // use the draw target ...
+   * }
+   * texture->Unlock();
+   *
+   */
   virtual TemporaryRef<gfx::DrawTarget> GetAsDrawTarget() = 0;
   virtual gfx::SurfaceFormat GetFormat() const = 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 by default, clearing the surface can be done
    * by passing the CLEAR_BUFFER flag.
@@ -95,17 +120,30 @@ public:
 };
 
 /**
  * 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.
  *
@@ -194,26 +232,16 @@ public:
 
   virtual bool IsAllocated() const = 0;
 
   virtual bool ToSurfaceDescriptor(SurfaceDescriptor& aDescriptor) = 0;
 
   virtual gfx::IntSize GetSize() const = 0;
 
   /**
-   * 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;
-
-  /**
    * 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; }
 
   /**
@@ -231,53 +259,67 @@ public:
 
   /**
    * If this method returns false users of TextureClient are not allowed
    * to access the shared data.
    */
   bool IsValid() const { return mValid; }
 
   /**
-   * An invalid TextureClient cannot provide access to its shared data
-   * anymore. This usually means it will soon be destroyed.
-   */
-  void MarkInvalid() { mValid = false; }
-
-  /**
    * 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();
 
   /**
-   * TODO[nical] doc!
+   * 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();
 
 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;
+
   void AddFlags(TextureFlags  aFlags)
   {
     MOZ_ASSERT(!IsSharedWithCompositor());
     mFlags |= aFlags;
   }
 
   RefPtr<TextureChild> mActor;
   TextureFlags mFlags;