Merge "Added some comments"

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:

// ---------------------------------------------------------------------------

/*

 * 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:

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;

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>

{