From cf0b8c85fb0106751256dba7821f86b5ad03126c Mon Sep 17 00:00:00 2001
From: Mathias Agopian <mathias@google.com>
Date: Tue, 19 Feb 2013 18:24:40 -0800
Subject: [PATCH] get rid of Surface::getISurfaceTexture()

this was there just for legacy reasons.

Change-Id: I0a48d6e04d7efa65033f9f10c91bba557f16ae8b
---
 include/gui/Surface.h                        | 32 +++++++++++++++-----
 libs/gui/tests/SurfaceTextureClient_test.cpp |  2 +-
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/include/gui/Surface.h b/include/gui/Surface.h
index bfd5a11d0..18e57ed9e 100644
--- a/include/gui/Surface.h
+++ b/include/gui/Surface.h
@@ -50,21 +50,39 @@ class Surface
 {
 public:
 
+    /*
+     * creates a Surface from the given IGraphicBufferProducer (which concrete
+     * implementation is a BufferQueue).
+     *
+     * Surface is mainly state-less while it's disconnected, it can be
+     * viewed as a glorified IGraphicBufferProducer holder. It's therefore
+     * safe to create other Surfaces from the same IGraphicBufferProducer.
+     *
+     * However, once a Surface is connected, it'll prevent other Surfaces
+     * referring to the same IGraphicBufferProducer to become connected and
+     * therefore prevent them to be used as actual producers of buffers.
+     */
     Surface(const sp<IGraphicBufferProducer>& bufferProducer);
 
+    /* getIGraphicBufferProducer() returns the IGraphicBufferProducer this
+     * Surface was created with. Usually it's an error to use the
+     * IGraphicBufferProducer while the Surface is connected.
+     */
     sp<IGraphicBufferProducer> getIGraphicBufferProducer() const;
 
-    static status_t writeToParcel(const sp<Surface>& surface, Parcel* parcel);
-    static sp<Surface> readFromParcel(const Parcel& data);
-
+    /* convenience function to check that the given surface is non NULL as
+     * well as its IGraphicBufferProducer */
     static bool isValid(const sp<Surface>& surface) {
         return surface != NULL && surface->getIGraphicBufferProducer() != NULL;
     }
 
-    // FIXME: temporary for source compatibility...
-    sp<IGraphicBufferProducer> getISurfaceTexture() const {
-        return getIGraphicBufferProducer();
-    }
+    /* writes the given Surface into a Parcel */
+    static status_t writeToParcel(const sp<Surface>& surface, Parcel* parcel);
+
+    /* constructs a Surface from a Parcel. see Surface::writeToParcel()
+     * and SurfaceControl::writeToParcel() */
+    static sp<Surface> readFromParcel(const Parcel& data);
+
 
 protected:
     Surface();
diff --git a/libs/gui/tests/SurfaceTextureClient_test.cpp b/libs/gui/tests/SurfaceTextureClient_test.cpp
index 58ae1708e..24b60f1af 100644
--- a/libs/gui/tests/SurfaceTextureClient_test.cpp
+++ b/libs/gui/tests/SurfaceTextureClient_test.cpp
@@ -112,7 +112,7 @@ protected:
 };
 
 TEST_F(SurfaceTextureClientTest, GetISurfaceTextureIsNotNull) {
-    sp<IGraphicBufferProducer> ist(mSTC->getISurfaceTexture());
+    sp<IGraphicBufferProducer> ist(mSTC->getIGraphicBufferProducer());
     ASSERT_TRUE(ist != NULL);
 }