1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/widget/gonk/nativewindow/GonkConsumerBaseKK.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,240 @@
1.4 +/*
1.5 + * Copyright (C) 2010 The Android Open Source Project
1.6 + * Copyright (C) 2013 Mozilla Foundation
1.7 + *
1.8 + * Licensed under the Apache License, Version 2.0 (the "License");
1.9 + * you may not use this file except in compliance with the License.
1.10 + * You may obtain a copy of the License at
1.11 + *
1.12 + * http://www.apache.org/licenses/LICENSE-2.0
1.13 + *
1.14 + * Unless required by applicable law or agreed to in writing, software
1.15 + * distributed under the License is distributed on an "AS IS" BASIS,
1.16 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1.17 + * See the License for the specific language governing permissions and
1.18 + * limitations under the License.
1.19 + */
1.20 +
1.21 +#ifndef NATIVEWINDOW_GONKCONSUMERBASE_KK_H
1.22 +#define NATIVEWINDOW_GONKCONSUMERBASE_KK_H
1.23 +
1.24 +#include <ui/GraphicBuffer.h>
1.25 +
1.26 +#include <utils/String8.h>
1.27 +#include <utils/Vector.h>
1.28 +#include <utils/threads.h>
1.29 +#include <gui/IConsumerListener.h>
1.30 +
1.31 +#include "GonkBufferQueueKK.h"
1.32 +
1.33 +namespace android {
1.34 +// ----------------------------------------------------------------------------
1.35 +
1.36 +class String8;
1.37 +
1.38 +// GonkConsumerBase is a base class for GonkBufferQueue consumer end-points. It
1.39 +// handles common tasks like management of the connection to the GonkBufferQueue
1.40 +// and the buffer pool.
1.41 +class GonkConsumerBase : public virtual RefBase,
1.42 + protected ConsumerListener {
1.43 +public:
1.44 + struct FrameAvailableListener : public virtual RefBase {
1.45 + // onFrameAvailable() is called each time an additional frame becomes
1.46 + // available for consumption. This means that frames that are queued
1.47 + // while in asynchronous mode only trigger the callback if no previous
1.48 + // frames are pending. Frames queued while in synchronous mode always
1.49 + // trigger the callback.
1.50 + //
1.51 + // This is called without any lock held and can be called concurrently
1.52 + // by multiple threads.
1.53 + virtual void onFrameAvailable() = 0;
1.54 + };
1.55 +
1.56 + virtual ~GonkConsumerBase();
1.57 +
1.58 + // abandon frees all the buffers and puts the GonkConsumerBase into the
1.59 + // 'abandoned' state. Once put in this state the GonkConsumerBase can never
1.60 + // leave it. When in the 'abandoned' state, all methods of the
1.61 + // IGraphicBufferProducer interface will fail with the NO_INIT error.
1.62 + //
1.63 + // Note that while calling this method causes all the buffers to be freed
1.64 + // from the perspective of the the GonkConsumerBase, if there are additional
1.65 + // references on the buffers (e.g. if a buffer is referenced by a client
1.66 + // or by OpenGL ES as a texture) then those buffer will remain allocated.
1.67 + void abandon();
1.68 +
1.69 + // set the name of the GonkConsumerBase that will be used to identify it in
1.70 + // log messages.
1.71 + void setName(const String8& name);
1.72 +
1.73 + // getBufferQueue returns the GonkBufferQueue object to which this
1.74 + // GonkConsumerBase is connected.
1.75 + sp<GonkBufferQueue> getBufferQueue() const;
1.76 +
1.77 + // dump writes the current state to a string. Child classes should add
1.78 + // their state to the dump by overriding the dumpLocked method, which is
1.79 + // called by these methods after locking the mutex.
1.80 + void dump(String8& result) const;
1.81 + void dump(String8& result, const char* prefix) const;
1.82 +
1.83 + // setFrameAvailableListener sets the listener object that will be notified
1.84 + // when a new frame becomes available.
1.85 + void setFrameAvailableListener(const wp<FrameAvailableListener>& listener);
1.86 +
1.87 +private:
1.88 + GonkConsumerBase(const GonkConsumerBase&);
1.89 + void operator=(const GonkConsumerBase&);
1.90 +
1.91 +protected:
1.92 +
1.93 + // GonkConsumerBase constructs a new GonkConsumerBase object to consume image
1.94 + // buffers from the given GonkBufferQueue.
1.95 + GonkConsumerBase(const sp<GonkBufferQueue>& bufferQueue, bool controlledByApp = false);
1.96 +
1.97 + // onLastStrongRef gets called by RefBase just before the dtor of the most
1.98 + // derived class. It is used to clean up the buffers so that GonkConsumerBase
1.99 + // can coordinate the clean-up by calling into virtual methods implemented
1.100 + // by the derived classes. This would not be possible from the
1.101 + // ConsuemrBase dtor because by the time that gets called the derived
1.102 + // classes have already been destructed.
1.103 + //
1.104 + // This methods should not need to be overridden by derived classes, but
1.105 + // if they are overridden the GonkConsumerBase implementation must be called
1.106 + // from the derived class.
1.107 + virtual void onLastStrongRef(const void* id);
1.108 +
1.109 + // Implementation of the GonkBufferQueue::ConsumerListener interface. These
1.110 + // calls are used to notify the GonkConsumerBase of asynchronous events in the
1.111 + // GonkBufferQueue. These methods should not need to be overridden by derived
1.112 + // classes, but if they are overridden the GonkConsumerBase implementation
1.113 + // must be called from the derived class.
1.114 + virtual void onFrameAvailable();
1.115 + virtual void onBuffersReleased();
1.116 +
1.117 + // freeBufferLocked frees up the given buffer slot. If the slot has been
1.118 + // initialized this will release the reference to the GraphicBuffer in that
1.119 + // slot. Otherwise it has no effect.
1.120 + //
1.121 + // Derived classes should override this method to clean up any state they
1.122 + // keep per slot. If it is overridden, the derived class's implementation
1.123 + // must call GonkConsumerBase::freeBufferLocked.
1.124 + //
1.125 + // This method must be called with mMutex locked.
1.126 + virtual void freeBufferLocked(int slotIndex);
1.127 +
1.128 + // abandonLocked puts the GonkBufferQueue into the abandoned state, causing
1.129 + // all future operations on it to fail. This method rather than the public
1.130 + // abandon method should be overridden by child classes to add abandon-
1.131 + // time behavior.
1.132 + //
1.133 + // Derived classes should override this method to clean up any object
1.134 + // state they keep (as opposed to per-slot state). If it is overridden,
1.135 + // the derived class's implementation must call GonkConsumerBase::abandonLocked.
1.136 + //
1.137 + // This method must be called with mMutex locked.
1.138 + virtual void abandonLocked();
1.139 +
1.140 + // dumpLocked dumps the current state of the GonkConsumerBase object to the
1.141 + // result string. Each line is prefixed with the string pointed to by the
1.142 + // prefix argument. The buffer argument points to a buffer that may be
1.143 + // used for intermediate formatting data, and the size of that buffer is
1.144 + // indicated by the size argument.
1.145 + //
1.146 + // Derived classes should override this method to dump their internal
1.147 + // state. If this method is overridden the derived class's implementation
1.148 + // should call GonkConsumerBase::dumpLocked.
1.149 + //
1.150 + // This method must be called with mMutex locked.
1.151 + virtual void dumpLocked(String8& result, const char* prefix) const;
1.152 +
1.153 + // acquireBufferLocked fetches the next buffer from the GonkBufferQueue and
1.154 + // updates the buffer slot for the buffer returned.
1.155 + //
1.156 + // Derived classes should override this method to perform any
1.157 + // initialization that must take place the first time a buffer is assigned
1.158 + // to a slot. If it is overridden the derived class's implementation must
1.159 + // call GonkConsumerBase::acquireBufferLocked.
1.160 + virtual status_t acquireBufferLocked(IGonkGraphicBufferConsumer::BufferItem *item,
1.161 + nsecs_t presentWhen);
1.162 +
1.163 + // releaseBufferLocked relinquishes control over a buffer, returning that
1.164 + // control to the GonkBufferQueue.
1.165 + //
1.166 + // Derived classes should override this method to perform any cleanup that
1.167 + // must take place when a buffer is released back to the GonkBufferQueue. If
1.168 + // it is overridden the derived class's implementation must call
1.169 + // GonkConsumerBase::releaseBufferLocked.
1.170 + virtual status_t releaseBufferLocked(int slot, const sp<GraphicBuffer> graphicBuffer);
1.171 +
1.172 + // returns true iff the slot still has the graphicBuffer in it.
1.173 + bool stillTracking(int slot, const sp<GraphicBuffer> graphicBuffer);
1.174 +
1.175 + // addReleaseFence* adds the sync points associated with a fence to the set
1.176 + // of sync points that must be reached before the buffer in the given slot
1.177 + // may be used after the slot has been released. This should be called by
1.178 + // derived classes each time some asynchronous work is kicked off that
1.179 + // references the buffer.
1.180 + status_t addReleaseFence(int slot,
1.181 + const sp<GraphicBuffer> graphicBuffer, const sp<Fence>& fence);
1.182 + status_t addReleaseFenceLocked(int slot,
1.183 + const sp<GraphicBuffer> graphicBuffer, const sp<Fence>& fence);
1.184 +
1.185 + // Slot contains the information and object references that
1.186 + // GonkConsumerBase maintains about a GonkBufferQueue buffer slot.
1.187 + struct Slot {
1.188 + // mGraphicBuffer is the Gralloc buffer store in the slot or NULL if
1.189 + // no Gralloc buffer is in the slot.
1.190 + sp<GraphicBuffer> mGraphicBuffer;
1.191 +
1.192 + // mFence is a fence which will signal when the buffer associated with
1.193 + // this buffer slot is no longer being used by the consumer and can be
1.194 + // overwritten. The buffer can be dequeued before the fence signals;
1.195 + // the producer is responsible for delaying writes until it signals.
1.196 + sp<Fence> mFence;
1.197 +
1.198 + // the frame number of the last acquired frame for this slot
1.199 + uint64_t mFrameNumber;
1.200 + };
1.201 +
1.202 + // mSlots stores the buffers that have been allocated by the GonkBufferQueue
1.203 + // for each buffer slot. It is initialized to null pointers, and gets
1.204 + // filled in with the result of GonkBufferQueue::acquire when the
1.205 + // client dequeues a buffer from a
1.206 + // slot that has not yet been used. The buffer allocated to a slot will also
1.207 + // be replaced if the requested buffer usage or geometry differs from that
1.208 + // of the buffer allocated to a slot.
1.209 + Slot mSlots[GonkBufferQueue::NUM_BUFFER_SLOTS];
1.210 +
1.211 + // mAbandoned indicates that the GonkBufferQueue will no longer be used to
1.212 + // consume images buffers pushed to it using the IGraphicBufferProducer
1.213 + // interface. It is initialized to false, and set to true in the abandon
1.214 + // method. A GonkBufferQueue that has been abandoned will return the NO_INIT
1.215 + // error from all IGonkConsumerBase methods capable of returning an error.
1.216 + bool mAbandoned;
1.217 +
1.218 + // mName is a string used to identify the GonkConsumerBase in log messages.
1.219 + // It can be set by the setName method.
1.220 + String8 mName;
1.221 +
1.222 + // mFrameAvailableListener is the listener object that will be called when a
1.223 + // new frame becomes available. If it is not NULL it will be called from
1.224 + // queueBuffer.
1.225 + wp<FrameAvailableListener> mFrameAvailableListener;
1.226 +
1.227 + // The GonkConsumerBase has-a GonkBufferQueue and is responsible for creating this object
1.228 + // if none is supplied
1.229 + sp<GonkBufferQueue> mConsumer;
1.230 +
1.231 + // mMutex is the mutex used to prevent concurrent access to the member
1.232 + // variables of GonkConsumerBase objects. It must be locked whenever the
1.233 + // member variables are accessed or when any of the *Locked methods are
1.234 + // called.
1.235 + //
1.236 + // This mutex is intended to be locked by derived classes.
1.237 + mutable Mutex mMutex;
1.238 +};
1.239 +
1.240 +// ----------------------------------------------------------------------------
1.241 +}; // namespace android
1.242 +
1.243 +#endif // NATIVEWINDOW_GONKCONSUMERBASE_H
