Add some comments.

class IDisplayEventConnection;

class IMemoryHeap;

/*

 * This class defines the Binder IPC interface for accessing various

 * SurfaceFlinger features.

 */

class ISurfaceComposer: public IInterface {

public:

    DECLARE_META_INTERFACE(SurfaceComposer);

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

/*

 * This is a small wrapper around SurfaceTextureClient that provides some

 * helper classes for Binder interaction.

 * This is a small wrapper around SurfaceTextureClient.

 *

 * TODO: rename to SurfaceJniHelper.  May want to move SurfaceInfo and

 * the associated lock() / unlockAndPost() calls to STC.

 * TODO: rename and/or merge with STC.

 */

class Surface : public SurfaceTextureClient

{

class Surface;

/*

 * An implementation of ANativeWindow that also behaves as the producer

 * side of a BufferQueue.

 * An implementation of ANativeWindow that feeds graphics buffers into 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 GLConsumer.

 * SurfaceTextureClient.  STC then forwards the buffers through Binder IPC

 * to the BufferQueue's producer interface, providing the new frame to a

 * consumer such as GLConsumer.

 *

 * TODO: rename to Surface.  The existing Surface class wraps STC with

 * some Binder goodies, which most users of Surface class don't care about.

 * TODO: rename to Surface after merging or renaming the existing Surface

 * class.

 */

class SurfaceTextureClient

    : public ANativeObjectBase<ANativeWindow, SurfaceTextureClient, RefBase>

sp<ISurface> Layer::createSurface()

{

    /*

     * This class provides an implementation of BnSurface (the "native" or

     * "remote" side of the Binder IPC interface ISurface), and mixes in

     * LayerCleaner to ensure that mFlinger->onLayerDestroyed() is called for

     * this layer when the BSurface is destroyed.

     *

     * The idea is to provide a handle to the Layer through ISurface that

     * is cleaned up automatically when the last reference to the ISurface

     * goes away.  (The references will be held on the "proxy" side, while

     * the Layer exists on the "native" side.)

     *

     * The Layer has a reference to an instance of SurfaceFlinger's variant

     * of GLConsumer, which holds a reference to the BufferQueue.  The

     * getSurfaceTexture() call returns a Binder interface reference for

     * the producer interface of the buffer queue associated with the Layer.

     */

    class BSurface : public BnSurface, public LayerCleaner {

        wp<const Layer> mOwner;

        virtual sp<IGraphicBufferProducer> getSurfaceTexture() const {

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

/*

 * The Layer class is essentially a LayerBase combined with a BufferQueue.

 * A new BufferQueue and a new SurfaceFlingerConsumer are created when the

 * Layer is first referenced.

 *

 * This also implements onFrameAvailable(), which notifies SurfaceFlinger

 * that new data has arrived.

 */

class Layer : public LayerBaseClient,

              public SurfaceFlingerConsumer::FrameAvailableListener

{

    virtual void clearStats();

private:

    friend class SurfaceTextureLayer;

    // Creates an instance of ISurface for this Layer.

    virtual sp<ISurface> createSurface();

    uint32_t getEffectiveUsage(uint32_t usage) const;

    bool isCropped() const;

    Rect computeBufferCrop() const;