From 0273adbf0bc202eda2ca579ae0773464ea9c701f Mon Sep 17 00:00:00 2001
From: Andy McFadden <fadden@android.com>
Date: Wed, 12 Dec 2012 17:10:08 -0800
Subject: [PATCH] Added some comments

Added a quick intro section at the top of the class.  Also noted
the proposed new name for the class.

Change-Id: I3f79663527544aa4e910db0e5a1374b54d16ba2f
---
 include/gui/ISurfaceTexture.h      | 16 ++++++++++++++++
 include/gui/Surface.h              |  7 +++++++
 include/gui/SurfaceTexture.h       | 15 +++++++++++++++
 include/gui/SurfaceTextureClient.h | 15 +++++++++++++++
 4 files changed, 53 insertions(+)

diff --git a/include/gui/ISurfaceTexture.h b/include/gui/ISurfaceTexture.h
index ae7c5c226..58345a028 100644
--- a/include/gui/ISurfaceTexture.h
+++ b/include/gui/ISurfaceTexture.h
@@ -34,6 +34,22 @@ namespace android {
 
 class SurfaceTextureClient;
 
+/*
+ * This class defines an interface that is implemented by classes that
+ * produce buffers of graphics data.  For example, a class that decodes
+ * video for playback might use this to provide frames.  This is
+ * typically done indirectly, through SurfaceTextureClient.
+ *
+ * The underlying mechanism is a BufferQueue.  In normal operation, the
+ * producer calls dequeueBuffer() to get an empty buffer, fills it with
+ * data, then calls queueBuffer() to make it available to the consumer.
+ *
+ * The BnSurfaceTexture and BpSurfaceTexture classes provide the Binder
+ * IPC implementation.
+ *
+ * TODO: rename to IGraphicBufferProducer (IBufferProducer?
+ * IBufferQueueProducer?)
+ */
 class ISurfaceTexture : public IInterface
 {
 public:
diff --git a/include/gui/Surface.h b/include/gui/Surface.h
index 2288fe775..f3455b5d6 100644
--- a/include/gui/Surface.h
+++ b/include/gui/Surface.h
@@ -106,6 +106,13 @@ private:
     
 // ---------------------------------------------------------------------------
 
+/*
+ * This is a small wrapper around SurfaceTextureClient that provides some
+ * helper classes for Binder interaction.
+ *
+ * TODO: rename to SurfaceJniHelper.  May want to move SurfaceInfo and
+ * the associated lock() / unlockAndPost() calls to STC.
+ */
 class Surface : public SurfaceTextureClient
 {
 public:
diff --git a/include/gui/SurfaceTexture.h b/include/gui/SurfaceTexture.h
index ae5d57ac9..50efb7385 100644
--- a/include/gui/SurfaceTexture.h
+++ b/include/gui/SurfaceTexture.h
@@ -42,6 +42,21 @@ namespace android {
 
 class String8;
 
+/*
+ * SurfaceTexture consumes buffers of graphics data from a BufferQueue,
+ * and makes them available to OpenGL as a texture.
+ *
+ * A typical usage pattern is to set up the SurfaceTexture with the
+ * desired options, and call updateTexImage() when a new frame is desired.
+ * If a new frame is available, the texture will be updated.  If not,
+ * the previous contents are retained.
+ *
+ * By default, the texture is attached to the GL_TEXTURE_EXTERNAL_OES
+ * texture target, in the EGL context of the first thread that calls
+ * updateTexImage().
+ *
+ * TODO: rename to GLConsumer (OpenGLConsumer?)
+ */
 class SurfaceTexture : public ConsumerBase {
 public:
     typedef ConsumerBase::FrameAvailableListener FrameAvailableListener;
diff --git a/include/gui/SurfaceTextureClient.h b/include/gui/SurfaceTextureClient.h
index 56d861a46..a582975e1 100644
--- a/include/gui/SurfaceTextureClient.h
+++ b/include/gui/SurfaceTextureClient.h
@@ -34,6 +34,21 @@ namespace android {
 
 class Surface;
 
+/*
+ * An implementation of ANativeWindow that also behaves as the producer
+ * side of a BufferQueue.
+ *
+ * This is typically used by programs that want to render frames through
+ * some means (maybe OpenGL, a software renderer, or a hardware decoder)
+ * and have the frames they create forwarded to SurfaceFlinger for
+ * compositing.  For example, a video decoder could render a frame and call
+ * eglSwapBuffers(), which invokes ANativeWindow callbacks defined by
+ * SurfaceTextureClient.  STC then acts as the BufferQueue producer,
+ * providing the new frame to a consumer such as SurfaceTexture.
+ *
+ * TODO: rename to Surface.  The existing Surface class wraps STC with
+ * some Binder goodies, which most users of Surface class don't care about.
+ */
 class SurfaceTextureClient
     : public ANativeObjectBase<ANativeWindow, SurfaceTextureClient, RefBase>
 {