CpuConsumer.h revision e41b318bc4708e1dee9364e73215ff0d51fb76a1
1/* 2 * Copyright (C) 2012 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17#ifndef ANDROID_GUI_CPUCONSUMER_H 18#define ANDROID_GUI_CPUCONSUMER_H 19 20#include <gui/BufferQueue.h> 21 22#include <ui/GraphicBuffer.h> 23 24#include <utils/String8.h> 25#include <utils/Vector.h> 26#include <utils/threads.h> 27 28#define ANDROID_GRAPHICS_CPUCONSUMER_JNI_ID "mCpuConsumer" 29 30namespace android { 31 32/** 33 * CpuConsumer is a BufferQueue consumer endpoint that allows direct CPU 34 * access to the underlying gralloc buffers provided by BufferQueue. Multiple 35 * buffers may be acquired by it at once, to be used concurrently by the 36 * CpuConsumer owner. Sets gralloc usage flags to be software-read-only. 37 * This queue is synchronous by default. 38 */ 39 40class CpuConsumer: public virtual RefBase, 41 protected BufferQueue::ConsumerListener 42{ 43 public: 44 struct FrameAvailableListener : public virtual RefBase { 45 // onFrameAvailable() is called each time an additional frame becomes 46 // available for consumption. A new frame queued will always trigger the 47 // callback, whether the queue is empty or not. 48 // 49 // This is called without any lock held and can be called concurrently 50 // by multiple threads. 51 virtual void onFrameAvailable() = 0; 52 }; 53 54 struct LockedBuffer { 55 uint8_t *data; 56 uint32_t width; 57 uint32_t height; 58 PixelFormat format; 59 uint32_t stride; 60 Rect crop; 61 uint32_t transform; 62 uint32_t scalingMode; 63 int64_t timestamp; 64 uint64_t frameNumber; 65 }; 66 67 // Create a new CPU consumer. The maxLockedBuffers parameter specifies 68 // how many buffers can be locked for user access at the same time. 69 CpuConsumer(uint32_t maxLockedBuffers); 70 71 virtual ~CpuConsumer(); 72 73 // set the name of the CpuConsumer that will be used to identify it in 74 // log messages. 75 void setName(const String8& name); 76 77 // Gets the next graphics buffer from the producer and locks it for CPU use, 78 // filling out the passed-in locked buffer structure with the native pointer 79 // and metadata. Returns BAD_VALUE if no new buffer is available, and 80 // INVALID_OPERATION if the maximum number of buffers is already locked. 81 // 82 // Only a fixed number of buffers can be locked at a time, determined by the 83 // construction-time maxLockedBuffers parameter. If INVALID_OPERATION is 84 // returned by lockNextBuffer, then old buffers must be returned to the queue 85 // by calling unlockBuffer before more buffers can be acquired. 86 status_t lockNextBuffer(LockedBuffer *nativeBuffer); 87 88 // Returns a locked buffer to the queue, allowing it to be reused. Since 89 // only a fixed number of buffers may be locked at a time, old buffers must 90 // be released by calling unlockBuffer to ensure new buffers can be acquired by 91 // lockNextBuffer. 92 status_t unlockBuffer(const LockedBuffer &nativeBuffer); 93 94 // setFrameAvailableListener sets the listener object that will be notified 95 // when a new frame becomes available. 96 void setFrameAvailableListener(const sp<FrameAvailableListener>& listener); 97 98 sp<ISurfaceTexture> getProducerInterface() const { return mBufferQueue; } 99 protected: 100 101 // Implementation of the BufferQueue::ConsumerListener interface. These 102 // calls are used to notify the CpuConsumer of asynchronous events in the 103 // BufferQueue. 104 virtual void onFrameAvailable(); 105 virtual void onBuffersReleased(); 106 107 private: 108 // Free local buffer state 109 status_t freeBufferLocked(int buf); 110 111 // Maximum number of buffers that can be locked at a time 112 uint32_t mMaxLockedBuffers; 113 114 // mName is a string used to identify the SurfaceTexture in log messages. 115 // It can be set by the setName method. 116 String8 mName; 117 118 // mFrameAvailableListener is the listener object that will be called when a 119 // new frame becomes available. If it is not NULL it will be called from 120 // queueBuffer. 121 sp<FrameAvailableListener> mFrameAvailableListener; 122 123 // Underlying buffer queue 124 sp<BufferQueue> mBufferQueue; 125 126 // Array for caching buffers from the buffer queue 127 sp<GraphicBuffer> mBufferSlot[BufferQueue::NUM_BUFFER_SLOTS]; 128 // Array for tracking pointers passed to the consumer, matching the 129 // mBufferSlot indexing 130 void *mBufferPointers[BufferQueue::NUM_BUFFER_SLOTS]; 131 // Count of currently locked buffers 132 uint32_t mCurrentLockedBuffers; 133 134 // mMutex is the mutex used to prevent concurrent access to the member 135 // variables of CpuConsumer objects. It must be locked whenever the 136 // member variables are accessed. 137 mutable Mutex mMutex; 138}; 139 140} // namespace android 141 142#endif // ANDROID_GUI_CPUCONSUMER_H 143